system_recovery
is the primary executable in the recovery system. The recovery system is a second, standalone instance of Fuchsia that runs on devices to recover the primary Fuchsia system when the primary Fuchsia system is inoperative.
You can build the recovery image using the following command:
$ fx build build/images/recovery
This command builds several recovery-*.zbi
files in obj/build/images/recovery
, which are self-contained archives of the recovery system.
After building the recovery image, you can run the image in QEMU using the following command:
$ fx run-recovery -g
The easiest way to run recovery on hardware is to boot the newly built recovery image with fastboot:
$ cat out/default/obj/build/images/recovery/recovery-eng/fuchsia.{zbi,vbmeta} > \ out/default/obj/build/images/recovery/recovery-eng/fuchsia.boot $ fastboot boot out/default/obj/build/images/recovery/recovery-eng/fuchsia.boot
Alternatively, you can netboot a device into a newly built recovery image:
$ out/default/host-tools/bootserver --board-name device-name --boot out/default/obj/build/images/recovery/recovery-eng/fuchsia.zbi
where device-name
can be found with fx list-devices
.
NB If you only have one device or have used the fx set-device
command you can omit the --board-name
argument.
After building the recovery image, you can flash it via the following commands:
fastboot erase vbmeta_a && \ fastboot erase vbmeta_b && \ fastboot flash vbmeta_r fuchsia.vbmeta && \ fastboot flash zircon_r fuchsia.zbi && \ fastboot stage /home/fuchsia/.ssh/authorized_keys oem add-staged-bootloader-file ssh.authorized_keys && \ fastboot continue
The above block will disable the A/B slots so that we default into recovery, provisions the R slot with recovery-eng, then stages the SSH authorized keys for recovery-eng to enable SSH access. The device can then be accessed via the standard ssh-based fx commands like fx shell
.
When you need to test against an Omaha server you can include arguments in a custom zircon_r.vbmeta.
$ tee out/default/recovery-omaha.props <<EOF ota_channel=stable omaha_app_id=example_product:abcdefghijklmno0123456789_userdebug omaha_url=https://clients2.google.com/service/update2/fuchsia/json EOF
out/default/host_x64/zbi --output out/default/recovery-omaha.zbi --type IMAGE_ARGS out/default/recovery-omaha.props
--key
, --algorithm
, and --public_key_metadata
need to match the args used for your board (set in boards/<board-name>.gni
as avb_key
, avb_algorithm
, and avb_atx_metadata
respectively).--include_descriptors_from_image
should point to the vbmeta file you want to add omaha args to.${FUCHSIA_DIR}/third_party/android/platform/external/avb/avbtool \ make_vbmeta_image \ --output out/default/recovery-omaha-args.vbmeta \ --key src/firmware/avb_keys/vim3/vim3-dev-key/vim3_devkey_atx_psk.pem \ --algorithm SHA512_RSA4096 \ --public_key_metadata src/firmware/avb_keys/vim3/vim3-dev-key/vim3_dev_atx_metadata.bin \ --include_descriptors_from_image out/default/obj/build/images/recovery/recovery-eng/fuchsia.vbmeta \ --prop_from_file zbi_image_args:out/default/recovery-omaha.zbi
fx fastboot flash zircon_r out/default/recovery-omaha-args.vbmeta
Build the core product with recovery:
$ fx set core.x64 --with //src/recovery $ fx build
Load the system you've just built onto your device.
Run the system recovery unit tests:
$ fx test -s 5 system_recovery_tests
Note that test_ui requires display access, so using a product other than “core” will likely cause these tests to fail.
Run the recovery integration test:
$ fx test -s 5 recovery_integration_test
TODO: Need to create end-to-end tests.