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 sanity 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. ' cmd_foo() { # Implementation for the foo command. # You should sanity check $# 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.
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 sanity 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.