diff --git a/README.rst b/README.rst index 94656ce..9b38914 100644 --- a/README.rst +++ b/README.rst @@ -12,38 +12,27 @@ |MIT| |Matrix| -The meta-rauc layer provides support for integrating the RAUC update tool -into your device. +The meta-rauc Yocto/OpenEmbedded layer provides integration for +`RAUC `_, a robust and secure **update framework +for embedded Linux systems**. + +This layer integrates RAUC into Yocto builds for both **target usage (update +client)** and **host usage (bundle creation)**. -Please see the corresponding sections below for more information. For a detailed description on steps necessary to integrate RAUC into your project, refer https://rauc.readthedocs.io/en/latest/integration.html. -Dependencies -============ - -This layer depends on:: - - URI: https://github.com/openembedded/bitbake.git - branch: master - - URI: https://github.com/openembedded/openembedded-core.git - layers: meta - branch: master +Layer Dependencies +================== -For fuse-support in casync (the default):: +This layer depends on: - URI: https://github.com/openembedded/meta-openembedded.git - layers: meta-filesystems - branch: master +* `openembedded-core `_ -Patches -======= +To use the optional casync feature with FUSE, you will also need: -Please submit patches via GitHub pull request on https://github.com/rauc/meta-rauc - -Maintainer: Enrico Joerns +* ``meta-filesystems`` from `meta-openembedded `_. Migration Notes =============== @@ -58,62 +47,44 @@ configuration-specific adaptions from your ``rauc_%.bbappend`` to a ``rauc-conf.bbappend`` file. -I. Adding the rauc Layer to Your Build -====================================== - -In order to use this layer, you need to make the build system aware of -it. - -Assuming the rauc layer exists at the top-level of your -yocto build tree, you can add it to the build system by adding the -location of the rauc layer to bblayers.conf, along with any -other layers needed. e.g.:: - - BBLAYERS ?= " \ - /path/to/yocto/meta \ - /path/to/yocto/meta-poky \ - /path/to/yocto/meta-yocto-bsp \ - /path/to/yocto/meta-rauc \ - " - +Adding the RAUC Update Service to Your Device +============================================= -II. Building and Using RAUC Host Tool -===================================== +To prepare your device for using RAUC as its update handler, +at least the following steps are required: -If you intend to build and use RAUC as a host tool from your BSP, e.g. for -calling ``rauc info`` on your built bundle, simply run:: +1. Add ``rauc`` to ``DISTRO_FEATURES`` in your distro (or local) config:: - bitbake rauc-native -caddto_recipe_sysroot - oe-run-native rauc-native rauc info --keyring=/path/to/keyring.pem tmp/deploy/images//.raucb + DISTRO_FEATURES += "rauc" -If you need to execute the ``casync`` host tool manually, you can do this by running:: +2. Provide a RAUC system configuration (and keyring) in your BSP layer by + creating a ``rauc-conf.bbappend`` that fetches your custom ``system.conf`` + (and keyring) from your layer:: - bitbake casync-native -caddto_recipe_sysroot - oe-run-native casync-native casync --help + FILESEXTRAPATHS:prepend := "${THISDIR}/files:" -III. Adding the RAUC Update Service to Your Device -================================================== + The ``rauc-conf`` recipe will install these files into ``/etc/rauc/`` by + default. -To prepare your device for using RAUC as its update handler, -you have to follow at least the following steps: + For information on how to write a proper RAUC system configuration, please + refer to the RAUC user documentation [1]_. -1. Add `rauc` to `DISTRO_FEATURES` in your distro (or local) config:: +Note: If you do not use packagegroup-base, you also need to manually add +the ``rauc`` package to your systems image recipe:: - DISTRO_FEATURES += "rauc" - -2. Add a ``rauc-conf.bbappend`` in your device-specific (BSP) layer - that installs your RAUC system configuration file under - ``/etc/rauc/system.conf``. For information on how to write the RAUC - update file, please refer to the RAUC user documentation [1]_:: + IMAGE_INSTALL:append = " rauc" - FILESEXTRAPATHS:prepend := "${THISDIR}/files:" +Building a RAUC Update Bundle +============================= -3. Create a bundle recipe for your device by adding a recipe - that inherits the `bundle` class and adds all desired +1. Create a bundle recipe for your device by adding a recipe + that inherits the ``bundle`` class and adds all desired configuration:: inherit bundle + RAUC_BUNDLE_FORMAT = "verity" + RAUC_BUNDLE_SLOTS = "rootfs" RAUC_SLOT_rootfs = "my-rootfs-recipe" @@ -126,18 +97,27 @@ you have to follow at least the following steps: For a more detailed explanation on the required and available variables, read the notes in the bundle.bbclass file. -4. Build a bundle and the rootfs for your device:: +2. Build a bundle and the rootfs for your device:: bitbake my-bundle-recipe -Note: If you do not use packagegroup-base, you als need to manually add -the `rauc` package to your systems image recipe:: - IMAGE_INSTALL:append = " rauc" +Building and Using the RAUC Host Tool +===================================== +To manually build and use RAUC as a host tool from your BSP (e.g. for +calling ``rauc info`` on your built bundle), run:: -IV. Building The RAUC hawkBit Clients -===================================== + bitbake rauc-native -caddto_recipe_sysroot + oe-run-native rauc-native rauc info --keyring=/path/to/keyring.pem tmp/deploy/images//.raucb + +To manually build and use the ``casync`` host tool, run:: + + bitbake casync-native -caddto_recipe_sysroot + oe-run-native casync-native casync --help + +Building The RAUC hawkBit Client +================================ This layer offers support for ``rauc-hawkbit-updater``, a daemon that interfaces between RAUC and the hawkBit deployment server. @@ -146,10 +126,10 @@ To use ``rauc-hawkbit-updater`` in your system add to your image recipe:: IMAGE_INSTALL:append = " rauc-hawkbit-updater" -V. Configure Custom Kernel -========================== +Configure Custom Kernel +======================= -In order to use RAUC on your system, the kernel must support SquashFS and loop +To use RAUC on your system, the kernel must support SquashFS and loop mounts. For the standard yocto kernel, the meta-rauc layer provides a kernel configuration fragment that enables the config options required for this. @@ -157,8 +137,8 @@ If you build your own kernel with a full custom ``defconfig`` file, you have to make sure that the options in ``recipes-kernel/linux/linux-yocto/rauc.cfg`` are enabled in your configuration, too. -VI. Build RAUC Development Version -================================== +Build RAUC Development Version +============================== Beside the standard release version recipes, the _git variants of RAUC recipes allow to build RAUC from a master branch revision that is newer than the latest @@ -175,13 +155,21 @@ in your local.conf. Note that this has the same effect as setting ``DEFAULT_PREFERENCE = "1"`` for each recipe (target/native/nativesdk) individually. -VII. Contributing -================= +Release Cycle +============= + +We follow the Yocto Project release methodology, schedule, and stable/LTS +support timelines. +See https://docs.yoctoproject.org/ref-manual/release-process.html for more +information. + +Contributing +============ To report bugs, file a new `issue `_ on GitHub. -For fixing bugs, bumping recipes or adding new features, open a `pull request +For fixing bugs, bumping recipes, or adding new features, open a `pull request `_ on GitHub. Add a ``Signed-off-by`` line to your commits according to the @@ -191,23 +179,28 @@ Add a ``Signed-off-by`` line to your commits according to the Backporting ----------- -For backporting changes to a stable or LTS branch, two options exist: +For backporting fixes or version bumps to a stable or LTS branch, two options exist: a) drop a backport request in the original pull request b) backport on your own and create a new pull request -When doing backports on your own, make sure to include a cherry-pick note and +When doing backports on your own, make sure to include a cherry-pick/backport note and the original commit-ish in a line below the original Signed-off-by and add your own Signed-off-by below. When using git, this can be done automatically with:: git cherry-pick -xs -Note that backports will be accepted for actively maintained `poky releases +Note that backports will be accepted for `actively maintained Yocto releases `_ only! -VIII. References -================ +Maintainer(s) +------------- + +* Enrico Joerns + +References +========== .. [1] http://rauc.readthedocs.io/en/latest/