developer_mode.md

# Developer Mode

*** note
**Warning: This document is old & has moved.  Please update any links:**<br>
https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md
***

Production Chrome OS devices that are shipped from the factory are locked down
and will not let you make changes to the software. This page describes how to
enable developer mode and get root access to your system.

[TOC]

## Enable Developer Mode {#dev-mode}

Modern Chrome OS devices can be put into developer mode by pressing
[specific keys][debug buttons] while Chrome OS is booting:

*   [Developer mode for devices with a keyboard][keyboard developer mode]
*   [Developer mode for devices without a keyboard (tablets)][keyboardless developer mode]

*** note
**Caution:** Modifications you make to the system are not supported by Google,
may cause hardware, software or security issues and may void warranty.
***

NOTE: Putting your device into developer mode inherently makes it a little less
secure. Specifically, it makes the "verified boot" that's built-in to your
hardware a little bit more lax, allowing your hardware to run custom
(non-Google-signed) images. It also gives you access to a "root" shell.

If you’re encountering issues putting your device into Developer Mode,
it's possible that your device administrator has blocked Developer
Mode access on your device.  Please follow the link to read more
details about [blocked Developer Mode].

You can tell that you're in Developer Mode if you see one of these screens when
you turn the device on:

![developer mode 1] ![developer mode 2] ![developer mode 3] ![developer mode 4]

## Switch to Normal Mode {#normal-mode}

To restore your device to Normal Mode (i.e., disable Developer Mode), reboot
your device and perform the following action:

*   Device with keyboard: Press the `Spacebar` at the firmware screen.
*   Devices without keyboard (tablet): Use the `Volume-Up` and `Volume-Down`
    keys to select the `Enable OS Verification` option. Press the `Power` button
    to confirm.

NOTE: If you've made changes to the rootfs filesystem while in developer mode,
you may have to use the [recovery process] to restore your device to its factory
condition. However, as long as you don't crack open the case, you shouldn't be
able to do anything that can't be undone by recovery (software).

## Getting to a Command Prompt {#shell}

If you're a Linux hacker, you probably know that Google Chrome OS is built on
top of Linux and you're wondering how you can jailbreak your device so you can
get to a command prompt. It turns out: there's no need. The command prompt is
built in to your device!

NOTE: Before following these instructions, remember to put your device into
[Developer Mode](#dev-mode).

### Get the Command Prompt Through VT-2 {#vt2}

One way to get the login prompt is through something called `VT-2`, or "virtual
terminal 2". If you're a Linux user, this is probably familiar. You can get to
`VT-2` by pressing:

```
[ Ctrl ] [ Alt ] [ → ]
```

where the `[ → ]` key is the right-arrow key just above the number `3` on your
keyboard.

Once you have the login prompt, you should see a set of instructions telling you
about command-line access. By default, you can login as the `chronos` user with
no password. This includes the ability to do password-less `sudo`. The
instructions on the screen will tell you how you can set a password. They also
tell you how to disable screen dimming.

In order to get back to the browser press:

```
[ Ctrl ] [ Alt ] [ ← ]
```

where the `[ ← ]` key is the left-arrow key just above the number `1` on your
keyboard.

NOTE: The top-rows of the keyboard on a Chrome OS device are actually treated by
Linux as the keys `F1` through `F10`. Thus, the `[ → ]` key is actually `F2`
and the `[ ← ]` key is actually `F1`.

NOTE: Kernel messages show up on `VT-8`.

### Getting the Command Prompt Through "crosh" {#crosh}

An alternate way to get to a terminal prompt is to use [`crosh`]:

1.  Go through the standard Chrome OS login screen (you'll need to setup a
    network, etc) and get to the web browser. It's OK if you login as guest.
1.  Press `[ Ctrl ] [ Alt ] [ T ]` to get the [`crosh`] shell.
1.  Use the shell command to get the shell prompt. NOTE: even if you set a
    password for the chronos user, you won't need it here (though you still need
    it for sudo access)

NOTE: Entering the shell this way doesn't give you all the instructions that
[`VT-2`] does (like how to set your password). You might want to follow the
[`VT-2`] steps once just to get the instructions.

If you want to get back to the browser without killing the shell, you can use `[
Alt ] [ Tab ]`.

NOTE: You can create as many shells as you want with `[ Ctrl ] [ Alt ] [ T ]`
again and another shell will be opened. You can `[ Alt ] [ Tab ]` between them.

## Making Changes to the Filesystem {#disable-verity}

The Chromium OS rootfs is mounted read-only. In developer mode you can disable
the rootfs verification, enabling it to be modified.

*** note
**NOTE:** If you mount the root filesystem in writeable mode, even if you make
no changes, it will no longer be verifiable and you'll have to use a recovery
image to restore your system when you switch back to normal mode. Auto updates
may also fail until a full payload is downloaded.
***

To make your rootfs writable, run the following command from a shell on the
device:

```bash
(dut) $ sudo /usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification
```

Then reboot. Your rootfs will be mounted read/write.

## Specifying Command Line Flags for Chrome {#chrome-cmdline-flags}

*   [Enable developer mode.](#dev-mode)
*   [Disable rootfs verification.](#disable-verity)
*   [Access a shell.](#shell)
*   Modify `/etc/chrome_dev.conf` (read the comments in the file for more
    details).
*   Restart the UI with:

    ```bash
    (dut) $ sudo restart ui
    ```

## Booting from USB or SD card

Chromium OS can be installed on a USB stick or SD card, for example if you
[build it yourself][Building Chromium OS]. In order to boot these, you have to
first enable booting from external storage by [opening a shell](#shell) and
running the command `crossystem deb_boot_usb=1`. (Even though this only says
USB, it will also work for SD cards.)

Afterwards, reboot the device and use the
[method appropriate for your device][debug buttons] to trigger external storage
boot when you see the developer mode boot screen.

## Running an alternative bootloader ("legacy BIOS") {#alt-firmware}

You can install an alternative bootloader that may make it easier to boot other
operating systems. This does **not** require you to disable firmware write
protection (with its associated risks).

*** note
**NOTE:** Some Chrome OS devices may ship with one or more alternative
bootloaders pre-installed. These are merely provided as examples of how to set
up the alternative bootloader feature. They are not officially supported,
usually not tested and may or may not work at all or do anything useful. The
point of the alternative bootloader feature is just to allow users to install
their own -- we may occasionally pre-install software if it is readily
available, but we are not committing to test and maintain it or to provide the
same set across all platforms.

You can also find ready-made alternative bootloaders to install on third-party
community sites such as [mrchromebox.tech]. Note that these sites are not
affiliated with Google or the Chromium OS project and we are not responsible for
any issues or damages arising from them. Use at your own risk.
***

Alternative bootloaders must be packaged as a coreboot payload and installed in
the `RW_LEGACY` section of the firmware flash. You can read out the flash and
print the contents of this section by [opening a shell](#shell) and running
```
flashrom -r /tmp/bios.bin
cbfstool /tmp/bios.bin print -r RW_LEGACY
```
If you see a file called `altfw/list` in this output, you have a 2019+ platform
that supports having more than one alternative bootloader installed at the same
time. Otherwise, you can only install a single bootloader that must be called
`payload`. In that case you may need to remove an already installed bootloader
via `cbfstool /tmp/bios.bin remove -r RW_LEGACY -n payload` to make room.

The new bootloader you want to add should be formatted as an ELF file. Make sure
that the entry point information in the file is correctly set and that it
contains code able to run in a firmware environment (i.e. no operating system
support, nothing set up other than what coreboot usually provides to its
payloads). Then add the file via
```
cbfstool /tmp/bios.bin add-payload -r RW_LEGACY -c lzma -n <your bootloader name> -f <path/to/your/bootloader.elf>
```
On an older platform make sure the name is `payload` and you're done. On a newer
platform, you can choose any name you want but you need to enter it in the
bootloader directory file. Extract this file with
```
cbfstool /tmp/bios.bin extract -r RW_LEGACY -n altfw/list -f /tmp/altfw.txt
```
and edit `/tmp/altfw.txt` with a normal text editor (e.g. `nano`). The file
contains one line per bootloader with the following values separated by
semicolons:

1.  Number of the bootloader in the developer mode menu (0 through 9)
    *   NOTE: The bootloader number 0 is always the "default" that will boot
        if `dev_default_boot=legacy` is set and the developer boot screen
        timer runs out.
1.  Name of the bootloader in CBFS (i.e. the `-n` parameter to `cbfstool`)
1.  Name of the bootloader that shall appear in the developer mode menu
1.  Comment field for more detailed description (not used by firmware)

Add a line for the bootloader you just added, save the file, then replace the
file in CBFS with the updated version via
```
cbfstool /tmp/bios.bin remove -r RW_LEGACY -n altfw/list
cbfstool /tmp/bios.bin add -r RW_LEGACY -n altfw/list -f /tmp/altfw.txt -t raw
```
You may also want to delete the `cros_allow_auto_update` file, if present. This
will prevent future Chrome OS system updates from overwriting the alternative
bootloader section after you modified it:
```
cbfstool /tmp/bios.bin remove -r RW_LEGACY -n cros_allow_auto_update
```
Finally, you must write the modified CBFS section back to the firmware flash and
tell the firmware to enable the alternative bootloader feature:
```
flashrom -w /tmp/bios.bin -i RW_LEGACY
crossystem dev_boot_legacy=1
```
Now you can reboot and use the
[method appropriate for your device][debug buttons] to run your alternative
bootloader when you see the developer mode boot screen.

<!-- Links -->

[`VT-2`]: #vt2
[Building Chromium OS]: developer_guide.md#Building-Chromium-OS
[crosh]: https://chromium.googlesource.com/chromiumos/platform2/+/HEAD/crosh
[debug buttons]: debug_buttons.md
[keyboard developer mode]: debug_buttons.md#firmware-keyboard-interface
[keyboardless developer mode]: debug_buttons.md#firmware-menu-interface
[mrchromebox.tech]: https://mrchromebox.tech
[recovery process]: https://www.google.com/chromeos/recovery
[blocked Developer Mode]: https://support.google.com/chrome/a/answer/6150653

<!-- Images -->

[developer mode 1]: ./images/developer_mode1.jpg
[developer mode 2]: ./images/developer_mode2.jpg
[developer mode 3]: ./images/developer_mode3.jpg
[developer mode 4]: ./images/developer_mode4.jpg