This is the homepage/documentation for the crosh, the Chromium OS shell. If you‘re on a CrOS devices right now, you should be able to launch crosh by hitting Ctrl+Alt+T. If you aren’t on CrOS, then most likely that won't do anything useful :).
Just run help to get info about available commands and discover more.
You can also use tab completion to quickly find existing commands.
It's an adventure!
This section is meant for people hacking on Chromium OS, especially when they need to modify/extend crosh.
Please do not install new modules without full security review. Any insecure code that crosh loads will be directly available to people in verified mode. That‘s an easy attack vector to run arbitrary code and mess with the user’s state. We don't want to undermine the security of CrOS!
If you are looking for reviewers, look at the [./OWNERS] file.
The main crosh script should hold the core crosh logic only. All other functions should live in appropriate module directories.
Modules that are specific to a board, or heavily specific to a package, should generally live with that board and/or package. For functions that are always available on all CrOS devices, that code should be kept in this repo.
If you're unsure, just ask on chromium-os-dev@chromium.org.
Module directories live in subdirectories under /usr/share/crosh/ on the CrOS device. This list is in order -- so modules in a later dir may override earlier ones.
extra.d/: Modules always loaded.removable.d/: Modules loaded when running on a removable device (e.g. USB).dev.d/: Modules only loaded when the device is in dev mode.Only modules using the name format ##-<name>.sh will be loaded. The leading numbers are used to control ordering and the .sh suffix is a validity check.
As an example, crosh stores its dev mode module at /usr/share/crosh/dev.d/50-crosh.sh and its removable drive module at /usr/share/crosh/removable.d/50-crosh.sh.
If you don‘t have a need for a specific number, just use 30. Don’t pick a number 50+ unless you really need to override crosh (which you rarely should).
If you don‘t have a name, just use one that matches your package’s name. We use 50-crosh.sh because the package name is crosh.
For every command, you define two variables and one function. There is no need to register the new commands anywhere as crosh will inspect its own runtime environment to discover them.
Here's how you would register a new foo command.
# A short description of arguments that this command accepts. USAGE_foo='<some args>' HELP_foo=' Extended description of this command. ' # Not required, but lets crosh detect if the foo program is available in the # current system (e.g. the package is not installed on all devices). If it # isn't available, crosh will automatically display an error message and never # call cmd_foo. EXEC_foo='/full/path/to/program' cmd_foo() ( # Implementation for the foo command. # You should validate $# and "$@" and process them first. # For invalid args, call the help function with an error message # before returning non-zero. ...foo code goes here!... )
See the design section below for more details on what and how to structure the new command.
If your crosh command simply calls out to an external program to do the processing, and that program already offers usage details, you probably don't want to have to duplicate things. You can handle this scenario by defining a help_foo function that makes the respective call.
# Set the help string so crosh can discover us automatically. HELP_foo='' cmd_foo() ( ... ) help_foo() ( /some/command --help )
Take note that we still set HELP_foo. This is needed so crosh can discover us automatically and display us in the relevant user facing lists (like the help_advanced command). We don't need to set USAGE_foo though since the help_foo function does that for us.
If a command is not yet ready for “prime time”, you might want to have it in crosh for early testing, but not have it show up in the help output where users can easily discover it (of course, the code is all public, so anyone reading the actual source can find it). Here's how you do it.
# Set the vars to pass the unittests ... USAGE_vmc='' HELP_vmc='' # ... then unset them to hide the command from "help" output. unset USAGE_vmc HELP_vmc cmd_vmc() ( ... )
If you want to replace a crosh command with some other UI (like a chrome:// page), and you want to deprecate the command gracefully by leaving behind a friendly note if people try to use it, here's the form.
# Set the vars to pass the unittests ... USAGE_storage_status='' HELP_storage_status='' # ... then unset them to hide the command from "help" output. unset USAGE_storage_status HELP_storage_status cmd_storage_status() ( # TODO: Delete this after the R## release branch. echo "Removed. See storage_info section in chrome://system" )
Make sure you add the TODO comment so people know in the future when it's OK to clean it up.
You can run ./crosh on your desktop system to get a sample shell. You can quickly test basic interactions (like argument parsing) here, or check the help output. You won't have access to the CrOS services that many crosh commands expect to talk to (via D-Bus), so those commands will fail.
If you want to load dev mode modules, you can use ./crosh --dev. It will only load local modules (./dev.d/), so if your module lives elsewhere, you can copy it here temporarily.
Similarly, if you want to load removable device modules, you can use ./crosh --removable.
The ./run_tests.sh unittest runner performs a bunch of basic style and soundness checks. Run it against your code!
The crosh shell runs in the same environment as the browser (same user/group, same Linux namespaces, etc...). So any tools you run in crosh, or information you try to acquire, must be accessible to the chronos user.
However, we rarely want crosh to actually execute tools directly. Instead, you should add D-Bus callbacks to the debugd daemon and send all requests to it. We can better control access in debugd and lock tools down. Then the only logic that exists in crosh is a D-Bus IPC call and then displays output from those programs. Discussion of debugd is out of scope here, so check out the /debugd/ directory instead.
Anyone should feel free to pick up these ideas and try to implement them :).
shell.