Documentation

<- Back to documentation

Installing CopperheadOS

CopperheadOS currently supports the following devices:

  • Nexus 9
  • Nexus 5X
  • Nexus 6P

Prerequisites

You can obtain the adb and fastboot tools from the Android SDK. Update the SDK before proceeding with installation. Avoid distribution packages for the tools unless they are up-to-date (v7.0.0_r1 or later). Please take this seriously and use an up-to-date adb/fastboot, otherwise you may end up with a corrupt OS installation. Verify that the adb/fastboot in your PATH is the up-to-date copy, not an alternate set that you may have installed elsewhere. Verified boot will detect any corruption on modern devices when the bootloader is locked and the device will prevent corrupting low-level firmware so you can always flash again, but it’s best to avoid taking unnecessary risks. There is no guarantee of compatibility with an old fastboot.

Enabling OEM unlocking

OEM unlocking needs to be enabled from within the operating system.

Enable the developer settings menu by going to Settings -> About device and pressing on the build number menu entry until developer mode is enabled.

Next, go to Settings -> Developer settings and toggle on the ‘Enable OEM unlocking’ setting.

Flashing the factory images

The initial install should be performed by flashing the factory images. This will wipe all the existing data. The factory images tarball can be downloaded from the builds page.

Verify the factory images using the GPG signature:

gpg --recv-keys 65EEFE022108E2B708CBFCF7F9E712E59AF5F22A
gpg --verify bullhead-factory-2016.05.03.18.54.15.tar.xz.sig bullhead-factory-2016.05.03.18.54.15.tar.xz

First, boot into the bootloader interface. You can do this by turning off the device and then turning it on by holding both the Volume Down and Power buttons. Alternatively, you can use adb reboot bootloader from Android.

The bootloader now needs to be unlocked to allow flashing new images:

fastboot flashing unlock

or, on older devices like the Nexus 9:

fastboot oem unlock

On the Nexus 5X and 6P, the command needs to be confirmed on the device.

Next, extract the factory images and run the script to flash them. Note that the fastboot command run by the flashing script requires a fair bit of free space in a temporary directory, which defaults to /tmp:

tar xvf bullhead-factory-2016.05.03.18.54.15.tar.xz
cd bullhead-mtc19t
./flash-all.sh

Use a different temporary directory if your /tmp doesn’t have 2GiB available:

mkdir tmp
TMPDIR=$PWD/tmp ./flash-all.sh

On the Nexus 5X and 6P, you should now proceed to locking the bootloader before using the device as locking wipes the data again.

Locking the bootloader

Locking the bootloader is important as it enables full verified boot on devices where it is supported (Nexus 5X, 6P). It also prevents using fastboot to flash, format or erase partitions. Verified boot will detect modifications to any of the OS partitions (boot, recovery, system, vendor) and in the future (Android N) it will prevent reading modified blocks unless error correction succeeds.

Reboot into the bootloader menu and set it to locked:

fastboot flashing lock

or, on older devices like the Nexus 9:

fastboot oem lock

On the Nexus 5X and 6P, the command needs to be confirmed on the device since it needs to perform a factory reset.

Unlocking the bootloader again will perform a factory reset.

OEM unlocking should be disabled again in the developer settings menu within the operating system. This prevents unlocking the bootloader without access to the owner account. CopperheadOS prevents bypassing the OEM unlocking toggle by wiping the data partition from the hidden recovery menu, unlike stock Android. You can still trigger factory resets from within the OS. Note that this means that recovering a device with a forgotten password is not possible without Copperhead doing it, which is the main purpose of this feature (anti-theft). Stock Android can be more forgiving because it’s tied to a Google account.

Verified boot

The bootloader will display a notice with the fingerprint of the verified boot key since it isn’t the built-in OEM key. Current devices attempt to use the TEE to prevent the key from being changed, but the implementation has limitations and there is some value in manually confirming it.

  • Nexus 5X fingerprint: 0AA1-7043-4D5F
  • Nexus 6P fingerprint: 965E-780B-32FC-B686

The Nexus 9 lacks verified boot support in the bootloader.

Updating

Update client

CopperheadOS checks for updates on a daily basis by default. It can be configured in Settings -> About device -> System updates.

Sideloading

Updates can also be downloaded from the downloads page and installed via recovery with adb sideloading. The zip files are signed and will be verified by the CopperheadOS recovery image.

First, boot into recovery. You can do this either by using adb reboot recovery from the operating system or selecting the Recovery option in the bootloader menu.

Next, access the recovery menu by holding down the power button and pressing the volume up button a single time.

Finally, select the “Apply update from ADB” option in the recovery menu and sideload the update with adb:

adb sideload bullhead-ota_update-2016.05.03.18.54.15.zip

Reporting bugs

Bugs (or feature requests) should be reported to the issue tracker on GitHub.