Chromium OS Docs

xBuddy for Devserver

Warning: This document is old & has moved. Please update any links:
https://chromium.googlesource.com/chromiumos/docs/+/HEAD/xbuddy.md

xBuddy (short for “cros buddy”, and “x” is a rotated cross) allows you to obtain Chromium OS images or other artifacts off Google Storage and reference locally built images. When used with devserver (or scripts that use it), it can also be used to update your Chromium OS machine to any image.

xBuddy Paths

Each xBuddy path contains four elements in the form of “location/board/version/image_type”. Each of these elements can have different values such as:

  • location (optional) - Where to get the artifact.
    • local (default) - xBuddy will attempt to find the artifact locally.
    • remote - xBuddy will search Google storage for artifacts. The exact bucket is automatically detected based on the other arguments below.
  • board (required) - Mostly self-explanatory e.g. amd64-generic or a specifc builder alias like amd64-generic-paladin or amd64-generic-paladin-tryjob.
  • version (optional) - A version string or an alias that maps to a version.
    • latest (default) - If location is local, the latest locally built image for that board. For remote, the newest image from stable channel on Google Storage.
    • latest-{canary|dev|beta|stable} - Latest build produced for the given channel.
    • latest-official - Latest available release image built for that board in Google Storage (e.g. gs://chromeos-image-archive/eve-release).
    • latest-official-{suffix} - Latest available image with that board suffix (can be anything like pre-cq, release, etc.) in Google Storage (e.g. gs://chromeos-image-archive/eve-pre-cq).
    • latest-{branch-prefix} - Latest build with given branch prefix i.e. RX-Y.Z or RX-Y or just RX -- seems broken, see line below.
    • {branch-prefix} - Latest build with given branch prefix i.e. RX-Y.X or RX-Y or just RX.
  • image_type (optional) - Any of the artifacts that devserver recognizes.
    • test (default) - A dev image (signed with dev keys) that has been modified to make testing even easier.
    • dev - Developer image (signed with dev keys). Like base but with additional dev packages.
    • base - A pristine Chrome OS image (signed with dev keys).
    • recovery - A base image (signed with dev keys) that can be flashed to a USB stick and used to recover a Chrome OS install.
    • signed - A recovery image that has been signed by Google and can be installed through autoupdate.

Exmaples

Some valid examples of xBuddy path are:

  • remote/amd64-generic/latest-canary
  • remote/amd64-generic/latest-official
  • remote/amd64-generic-paladin/R32-4830.0.0-rc1
  • remote/trybot-amd64-generic-paladin/R32-5189.0.0-b100
  • amd64-generic/latest
  • local/amd64-generic/latest/test
  • amd64-generic/latest/test

xBuddy Path Overrides

There are abbreviations for some common paths. For example, an empty path is taken to refer to the latest local build for a board.

The defaults are found in src/platform/dev/xbuddy_config.ini, and can be overridden with shadow_xbuddy_config.ini.

xBuddy Interface and Usage

Devserver RPC: xbuddy

Please see Using the Devserver for more details about the devserver.

If there is a devserver running on host ${HOST} and port ${PORT}, stage artifacts onto it using xBuddy paths by calling “xbuddy”. The path following xbuddy/ in the call URL is interpreted as an xBuddy path.

The up to date documentation can be found under the help section of devserver's index, http://${HOST}:${PORT}/doc/xbuddy

http://${HOST}:${PORT}/xbuddy/${XBUDDY_PATH}

Or download the artifact by calling:

wget http://${HOST}:${PORT}/xbuddy/${XBUDDY_PATH} -O chromiumos_test_image.bin

To get the directory name that the artifact will be found in:

http://${HOST}:${PORT}/xbuddy/${XBUDDY_PATH}?return_dir=true

Devserver RPC: xbuddy_list

If there is a devserver running, check which images are currently cached on it by calling xbuddy_list:

http://${HOST}:${PORT}/xbuddy_list

Using cros flash

To use xBuddy path with cros flash:

cros flash ${DUT_IP} xbuddy://${XBUDDY_PATH}

xbuddy:// is optional.

See cros flash page for more details.

Updating from a DUT: update_engine_client

If there is a devserver running, and you have access to the test device, update the device by calling update_engine_client with an omaha_url that contains an xBuddy path. The omaha_url is a call to devserver‘s update RPC. Documentation found under the help section of devserver’s index. http://${HOST}:${PORT}/doc/update

To update the image to the latest stable:

update_engine_client --update --omaha_url=${HOST}:${PORT}/update/

To update to a specific xBuddy artifact:

update_engine_client --update --omaha_url=${HOST}:${PORT}/update/xbuddy/{XBUDDY_PATH}

See update engine page for more details.