.. Integration 統合 =========== .. contents:: :local: :depth: 2 .. If you intend to prepare your platform for using RAUC as an update framework, this chapter will guide you through the required steps and show the different ways you can choose. RAUC を更新フレームワークとして使用するためにプラットフォームを準備する場合は、この章で必要な手順を説明し、選択できるさまざまな方法を示します。 .. To integrate RAUC, you first need to be able to build RAUC as both a host and a target application. The host application is needed for generating update bundles while the target application or service performs the core task of RAUC: updating you device. RAUC を統合するには、まず RAUC をホスト アプリケーションとターゲット アプリケーションの両方としてビルドできる必要があります。 ホスト アプリケーションはアップデート バンドルを生成するために必要であり、ターゲット アプリケーションまたはサービスは RAUC のコア タスクであるデバイスのアップデートを実行します。 .. In an update system, a lot of components have to play together and have to be configured appropriately to interact correctly. In principle, these are: 更新システムでは、多くのコンポーネントが一緒に動作し、正しく相互作用するように適切に構成する必要があります。 原則として、これらは次のとおりです。 * Hardware setup, devices, partitions, etc. * The bootloader * The Linux kernel * The init system * System utilities (mount, mkfs, ...) * The update tool, RAUC itself .. .. note:: When integrating RAUC into your embedded Linux system, and in general, we highly recommend using a Linux system build system like Yocto / OpenEmbedded or PTXdist that allows you to have well defined software states while easing integration of the different components involved. For information about how to integrate RAUC using these tools, refer to the sections :ref:`sec_int_yocto` or :ref:`sec_int_ptxdist`. .. note:: RAUC を組み込み Linux システムに統合する場合、一般的に、Yocto / OpenEmbedded または PTXdist などの Linux システム ビルド システムを使用することを強くお勧めします。これにより、関連するさまざまなコンポーネントの統合を容易にしながら、ソフトウェアの状態を明確に定義できます。 これらのツールを使用して RAUC を統合する方法については、:ref:`sec_int_yocto` または :ref:`sec_int_ptxdist` のセクションを参照してください。 .. _sec-int-system-config: Partitioning Your Device ------------------------ .. A basic requirement for a redundant update system is to have your storage set up properly. In a simple case, this means having two redundant partitions of equal size for an A/B setup, or a tiny and a larger partition for a recovery/A setup. 冗長更新システムの基本的な要件は、ストレージを適切にセットアップすることです。 単純なケースでは、これは、A/B セットアップ用に同じサイズの 2 つの冗長パーティションを持つこと、またはリカバリ/A セットアップ用に小さくて大きいパーティションを持つことを意味します。 .. Partitioning the storage is part of the bootstrap process and **not** in the scope of an update tool like RAUC. ストレージのパーティション分割はブートストラップ プロセスの一部であり、RAUC のような更新ツールの範囲内では **ありません**。 .. Additionally, you may also need to reserve space for your bootloader, boot state information (such as the state backend for barebox or environment partition for U-Boot), :ref:`data partition(s) ` or similar. さらに、ブートローダー、ブート状態情報 (ベアボックスの状態バックエンドや U-Boot の環境パーティションなど)、 :ref:`data partition(s) ` などのためにスペースを予約する必要がある場合もあります。 .. Since changing the partition layout is hard or even impossible to change in the field, make sure it meets both current and possible future requirements. パーティションのレイアウトを変更することは、現場で変更するのが困難または不可能であるため、現在および将来の要件の両方を満たしていることを確認してください。 SD Card ~~~~~~~ .. Partitioning your SD Card is quite easy as it can simply be done from your host system by either using a command-line or graphical tool (fdisk/cfdisk/gparted) or by writing a full SD Card image as generated by your embedded Linux build system. コマンドラインまたはグラフィカル ツール (fdisk/cfdisk/gparted) を使用するか、組み込み Linux ビルド システムによって生成された完全な SD カード イメージを書き込むことにより、ホスト システムから簡単に SD カードのパーティション分割を行うことができるため、SD カードのパーティション分割は非常に簡単です。 .. Most modern systems should use GPT for partitioning. 最新のシステムのほとんどは、パーティショニングに GPT を使用する必要があります。 eMMC ~~~~ .. In contrast to SD cards, an eMMC is fixed to your board and can not be easily pre-programmed before soldering (except for very large production batches). Accordingly, it usually needs to be set up from a Linux factory image booted from a secondary boot source such as network (e.g. TFTP), USB (e.g. Android fastboot), or other mass storage. SD カードとは対照的に、eMMC はボードに固定されており、はんだ付け前に簡単に事前プログラムすることはできません (非常に大規模な生産バッチを除く)。 したがって、通常は、ネットワーク (TFTP など)、USB (Android fastboot など)、またはその他の大容量ストレージなどのセカンダリ ブート ソースから起動された Linux ファクトリ イメージからセットアップする必要があります。 .. A useful tool for automating partitioning at runtime is `systemd-repart `_. 実行時にパーティショニングを自動化するための便利なツールは、 `systemd-repart `_ です。 .. Note that an eMMC also provides dedicated boot partitions that can be selected by setting Extended CSD registers and thus, if the SoC supports it, allows :ref:`atomic bootloader updates `. eMMC は、拡張 CSD レジスタを設定することで選択できる専用のブート パーティションも提供するため、SoC がサポートしている場合は、 `アトミック ブートローダーの更新 ` が可能になることに注意してください。 .. The eMMC specification also supports changing the operational mode of either the entire eMMC or only parts of it to better match requirements such as write endurance or data retention, e.g. by switching to pSLC mode. eMMC 仕様は、書き込み耐久性やデータ保持などの要件により適合するように、eMMC 全体またはその一部のみの動作モードの変更もサポートしています。 例えば pSLCモードへの切り替えがあります。 SSD ~~~ SSDs can be handled similarly to eMMCs, except that most do not provide boot partition or operational mode support. Note that you can still make use of atomic bootloader updates here when booting from :ref:`GPT ` (or :ref:`MBR `). NAND ~~~~ Raw NAND can either be partitioned by devicetree partitions (as a subnode of the NAND controller) or (indirectly) by using UBI, which supports creating multiple UBI volumes. Note that when using raw NAND, responsibility for bad block and NAND quirks handling is on your side (or on side of the NAND handling layer you use). Some bugs or misconfigurations will appear to work fine and only manifest as sporadic failures much later. If in doubt, using eMMC is recommended, especially for devices with normal quantity, since debugging NAND issues can be quite time-consuming. .. RAUC System Configuration RAUCのシステム構成 ------------------------- .. The system configuration file is the central configuration in RAUC that abstracts the loosely coupled storage setup, partitioning and boot strategy of your board to a coherent redundancy setup world view for RAUC. システム構成ファイルは、RAUC の中心的な構成であり、ボードの疎結合ストレージのセットアップ、パーティショニング、およびブート戦略を RAUC の一貫した冗長構成の世界観に抽象化します。 .. RAUC expects its central configuration file ``/etc/rauc/system.conf`` to describe the system it runs on in a way that all relevant information for performing updates and making decisions are given. RAUC は、その中央構成ファイル ``/etc/rauc/system.conf`` が、更新の実行と決定を行うためのすべての関連情報が提供される方法で実行されるシステムを記述することを期待しています。 .. .. note:: For a full reference of the system.conf file refer to section :ref:`sec_ref_slot_config`. .. note:: system.conf ファイルの完全なリファレンスについては、 :ref:`sec_ref_slot_config` セクションを参照してください。 .. Similar to other configuration files used by RAUC, the system configuration uses a key-value syntax (similar to those known from .ini files). RAUC で使用される他の構成ファイルと同様に、システム構成ではキーと値の構文が使用されます (.ini ファイルで知られているものと同様)。 .. Slot Configuration スロット構成 ~~~~~~~~~~~~~~~~~~ .. The most important step is to describe the slots that RAUC should use when performing updates. Which slots are required and what you have to take care of when designing your system will be covered in the chapter :ref:`sec-scenarios`. This section assumes that you have already decided on a setup and want to describe it for RAUC. 最も重要なステップは、更新の実行時に RAUC が使用するスロットを記述することです。 どのスロットが必要で、システムを設計する際に注意しなければならないことは、 :ref:`sec-scenarios` の章で説明されています。 このセクションでは、すでにセットアップを決定しており、RAUC 用に説明したいと考えていることを前提としています。 .. A slot is defined by a slot section. The naming of the section must follow a simple format: ``[slot..]`` where ** describes a class of possibly multiple redundant slots (such as ``rootfs``, ``recovery`` or ``appfs``) and *slot-index* is the index of the individual slot instance, starting with index 0. スロットは、スロット セクションによって定義されます。 セクションの名前は、次のような単純な形式に従う必要があります。 ``[slot..]`` この ** は複数の冗長スロット (``rootfs``、 ``recovery``、 ``appfs`` など) のクラスを記述し、 *slot-index* は個々のスロット インスタンスのインデックスです。 このインデックスは 0 から始まります。 .. If you have two redundant slots used for the root file system, for example, you should name your sections according to this example: たとえば、ルート ファイル システムに使用する 2 つの冗長スロットがある場合は、次の例に従ってセクションに名前を付ける必要があります。 .. code-block:: cfg [slot.rootfs.0] device = [...] [slot.rootfs.1] device = [...] .. RAUC does not have predefined class names. The only requirement is that the class names used in the system config match those you later use in the update manifests. RAUC には、定義済みのクラス名がありません。唯一の要件は、システム構成で使用されるクラス名が、後で更新マニフェストで使用するものと一致することです。 .. The mandatory settings for each slot are: 各スロットの必須設定は次のとおりです。 * the ``device`` that holds the (device) path describing *where* the slot is located, * the ``type`` that defines *how* to update the target device. If the slot is bootable, then you also need * the ``bootname`` which is the name the bootloader uses to refer to this slot device. .. _sec-slot-type: Slot Type ^^^^^^^^^ A list of slot storage types currently supported by RAUC: +----------+-------------------------------------------------------------------+-------------+ | Type | Description | Tar support | +----------+-------------------------------------------------------------------+-------------+ | raw | A partition holding no (known) file system. Only raw image copies | | | | may be performed. | | +----------+-------------------------------------------------------------------+-------------+ | ext4 | A block device holding an ext4 filesystem. | x | +----------+-------------------------------------------------------------------+-------------+ | nand | A raw NAND flash partition. | | +----------+-------------------------------------------------------------------+-------------+ | nor | A raw NOR flash partition. | | +----------+-------------------------------------------------------------------+-------------+ | ubivol | An UBI partition in NAND. | | +----------+-------------------------------------------------------------------+-------------+ | ubifs | An UBI volume containing an UBIFS in NAND. | x | +----------+-------------------------------------------------------------------+-------------+ | vfat | A block device holding a vfat filesystem. | x | +----------+-------------------------------------------------------------------+-------------+ | jffs2 | A flash memory holding a JFFS2 filesystem. | x | +----------+-------------------------------------------------------------------+-------------+ Depending on this slot storage type and the slot's :ref:`image filename ` extension, RAUC determines how to extract the image content to the target slot. While the generic filename extension ``.img`` is supported for all filesystems, it is strongly recommended to use explicit extensions (e.g. ``.vfat`` or ``.ext4``) when possible, as this allows checking during installation that the slot type is correct. Grouping Slots ^^^^^^^^^^^^^^ If multiple slots belong together in a way that they always have to be updated together with the respective other slots, you can ensure this by grouping slots. A group must always have a single bootable slot, then all other slots define a parent relationship to this bootable slot as follows: .. code-block:: cfg [slot.rootfs.0] ... [slot.appfs.0] parent = rootfs.0 ... [slot.rootfs.1] ... [slot.appfs.1] parent = rootfs.1 ... Library Dependencies -------------------- .. The minimal requirement for RAUC regardless of whether intended for the host or target side is GLib (minimum version 2.45.8) as utility library and OpenSSL (>=1.0) for signature handling. ホスト側とターゲット側のどちらを対象としているかに関係なく、RAUC の最小要件は、ユーティリティ ライブラリとしての GLib (最小バージョン 2.45.8) と署名処理用の OpenSSL (>=1.0) です。 .. note:: In order to let RAUC detect mounts correctly, GLib must be compiled with libmount support (``--enable-libmount``) and at least be 2.49.5. For network support (enabled with ``--enable-network``), additionally `libcurl` is required. This is only useful for the target service. For JSON-style support (enabled with ``--enable-json``), additionally `libjson-glib` is required. Kernel Configuration -------------------- .. The kernel used on the target device must support both loop block devices and the SquashFS file system to allow installing RAUC bundles. For the recommended ``verity`` :ref:`bundle format`, dm-verity must be supported as well. ターゲット デバイスで使用されるカーネルは、RAUC バンドルをインストールできるように、ループ ブロック デバイスと SquashFS ファイル システムの両方をサポートする必要があります。 推奨される ``verity`` :ref:`バンドル形式`では、dm-verity もサポートされている必要があります。 .. In kernel Kconfig you have to enable the following options as either built-in (``y``) or module (``m``): カーネル Kconfig では、次のオプションをビルトイン (``y``) またはモジュール (``m``) として有効にする必要があります。 .. code-block:: cfg CONFIG_MD CONFIG_BLK_DEV_DM CONFIG_BLK_DEV_LOOP CONFIG_DM_VERITY CONFIG_SQUASHFS CONFIG_CRYPTO_SHA256 .. For streaming support, you have to add ``CONFIG_BLK_DEV_NBD``. For encryption support, you have to add ``CONFIG_DM_CRYPT``. ストリーミングをサポートするには、 ``CONFIG_BLK_DEV_NBD`` を追加する必要があります。 暗号化をサポートするには、 ``CONFIG_DM_CRYPT`` を追加する必要があります。 .. note:: These drivers may also be loaded as modules. Kernel versions v5.0 to v5.7 will require the patch ``7e81f99afd91c937f0e66dc135e26c1c4f78b003`` backporting to fix a bug where the bundles cannot be mounted in a small number of cases. .. note:: On ARM SoCs, there are optimized alternative SHA256 implementations available (for example ``CONFIG_CRYPTO_SHA2_ARM_CE``, ``CRYPTO_SHA256_ARM`` or hardware accellerators such as ``CONFIG_CRYPTO_DEV_FSL_CAAM_AHASH_API``). .. _sec_ref_host_tools: Required Host Tools ------------------- To be able to generate bundles, RAUC requires at least the following host tools: * mksquashfs * unsquashfs When using the RAUC casync integration, the ``casync`` tool and ``fakeroot`` (for converting archives to directory tree indexes) must also be available. .. _sec_ref_target_tools: .. Required Target Tools --------------------- 必要なターゲット ツール --------------------- .. RAUC requires and uses a set of target tools depending on the type of supported storage and used image type. RAUC は、サポートされるストレージのタイプと使用されるイメージ タイプに応じて、一連のターゲット ツールを必要とし、使用します。 .. Mandatory tools for each setup are ``mount`` and ``umount``, either from `Busybox `_ or `util-linux `_ 各セットアップに必須のツールは、 `Busybox `_ または `util-linux `_ からの ``mount`` と ``unmount`` です。 .. Note that build systems may handle parts of these dependencies automatically, but also in this case you will have to select some of them manually as RAUC cannot fully know how you intend to use your system. ビルド システムはこれらの依存関係の一部を自動的に処理する場合があることに注意してください。 ただし、この場合も、RAUC はシステムをどのように使用するかを完全には認識できないため、一部を手動で選択する必要があります。 :NAND Flash: flash_erase & nandwrite (from `mtd-utils `_) :NOR Flash: flash_erase & flashcp (from `mtd-utils `_) :UBIFS: mkfs.ubifs (from `mtd-utils `_) :TAR archives: You may either use `GNU tar `_ or `Busybox tar `_. .. If you intend to use Busybox tar, make sure format autodetection and also the compression formats you use are enabled: Busybox tar を使用する場合は、フォーマットの自動検出と、使用する圧縮フォーマットが有効になっていることを確認してください。 * ``CONFIG_FEATURE_TAR_AUTODETECT=y`` * ``CONFIG_FEATURE_TAR_LONG_OPTIONS=y`` * select needed ``CONFIG_FEATURE_SEAMLESS_*=y`` options :ext4: mkfs.ext4 (from `e2fsprogs `_) :vfat: mkfs.vfat (from `dosfstools `_) Depending on the bootloader you use on your target, RAUC also needs the right tool to interact with it: :Barebox: barebox-state (from `dt-utils `_) :U-Boot: fw_setenv/fw_getenv (from `u-boot `_) :GRUB: grub-editenv :EFI: efibootmgr Note that for running ``rauc info`` on the target (as well as on the host), you also need to have the ``unsquashfs`` tool installed. When using the RAUC casync integration, the ``casync`` tool must also be available. .. Interfacing with the Bootloader ブートローダーとのインターフェース ------------------------------- .. RAUC provides support for interfacing with different types of bootloaders. To select the bootloader you have or intend to use on your system, set the ``bootloader`` key in the ``[system]`` section of your device's ``system.conf``. RAUC は、さまざまなタイプのブートローダーとのインターフェースをサポートします。 システムで使用する、または使用する予定のブートローダーを選択するには、デバイスの ``system.conf`` の ``[system]`` セクションに ``bootloader`` キーを設定します。 .. note:: If in doubt about choosing the right bootloader, we recommend to use `barebox `__ as it provides a dedicated boot handling framework, called `bootchooser `__. .. To let RAUC handle a bootable slot, you have to mark it as bootable in your ``system.conf`` and configure the name under which the bootloader identifies this specific slot. This is both done by setting the ``bootname`` property. RAUC が起動可能なスロットを処理できるようにするには、 ``system.conf`` で起動可能としてマークし、ブートローダーがこの特定のスロットを識別する名前を設定する必要があります。 これは、どちらも ``bootname`` プロパティを設定することによって行われます。 .. code-block:: cfg [slot.rootfs.0] ... bootname=system0 .. Amongst others, the bootname property also serves as one way to let RAUC know which slot is currently booted (running). In the following, the different options for letting RAUC detect the currently booted slot are described. 特に、bootname プロパティは、どのスロットが現在起動されている (実行されている) かを RAUC に知らせる 1 つの方法としても機能します。 以下では、現在起動されているスロットを RAUC に検出させるためのさまざまなオプションについて説明します。 .. Booted Slot Detection 起動スロット検出 ~~~~~~~~~~~~~~~~~~~~~ .. For RAUC it is quite essential to know from which slot the system is currently running. We will refer this as the *booted slot*. Only reliable detection of the *booted slot* enables RAUC to determine the set of currently inactive slots (that it can safely write to). RAUC では、システムが現在どのスロットから実行されているかを知ることが非常に重要です。 これを起動スロットと呼びます。 ブートされたスロットの確実な検出のみが、RAUC が現在非アクティブなスロットのセット (安全に書き込みできる) を決定できるようにします。 .. If possible, one should always prefer to signal the active slot explicitly from the bootloader to the userspace and RAUC. Only for cases where this explicit way is not possible or unwanted, some alternative approaches of automatically detecting the currently booted slot are implemented in RAUC. 可能であれば、アクティブなスロットをブートローダーからユーザー空間と RAUC に明示的に通知することを常に優先する必要があります。 この明示的な方法が不可能または望ましくない場合にのみ、現在起動されているスロットを自動的に検出するいくつかの代替アプローチが RAUC に実装されています。 .. A detailed list of detection mechanism follows. 検出メカニズムの詳細なリストは次のとおりです。 Identification via Kernel Commandline ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ RAUC evaluates different kernel commandline parameters in the order they are listed below. .. rubric:: ``rauc.slot=`` and ``rauc.external`` This is the generic way to explicitly set information about which slot was booted by the bootloader. For slots that are handled by a bootloader slot selection mechanism (such as A+B slots) you should specify the slot's configured ``bootname``:: rauc.slot=system0 For special cases where some slots are not handled by the slot selection mechanism (such as a 'last-resort' recovery fallback that never gets explicitly selected) you can also give the name of the slot:: rauc.slot=recovery.0 When booting from a source not configured in your system.conf (for example from a USB memory stick), you can tell rauc explicitly with the flag ``rauc.external``. This means that all slots are known to be inactive and will be valid installation targets. A possible use case for this is to use RAUC during a bootstrapping procedure to perform an initial installation. .. rubric:: ``bootchooser.active=`` This is the command-line parameter used by barebox's *bootchooser* mechanism. It will be set automatically by the bootchooser framework and does not need any manual configuration. RAUC compares this against each slot's bootname (not the slot's name as above):: bootchooser.active=system0 .. rubric:: ``root=`` If none of the above parameters is given, the ``root=`` parameter is evaluated by RAUC to gain information on the currently booted system. The ``root=`` entry contains the device from which device the kernel (or initramfs) should load the rootfs. RAUC supports parsing different variants for giving these device as listed below. :: root=/dev/sda1 root=/dev/ubi0_1 Giving the plain device name is supported, of course. .. note:: The alternative ubi rootfs format with ``root=ubi0:volname`` is currently unsupported. If you want to refer to UBI volumes via name in your ``system.conf``, check the FAQ entry :ref:`faq-udev-symlinks`. :: root=PARTLABEL=abcde root=PARTUUID=01234 root=UUID=01234 Parsing the ``PARTLABEL``, ``PARTUUID`` and ``UUID`` is supported, which allows referring to a special partition / file system without having to know the enumeration-dependent `sdX` name. RAUC converts the value to the corresponding ``/dev/disk/by-*`` symlink name and then to the actual device name. :: root=/dev/nfs RAUC automatically detects NFS boots (by checking if this parameter is set in the kernel command line). There is no extra slot configuration needed for this as RAUC assumes it is safe to update all available slots in case the currently running system comes from NFS. .. rubric:: ``systemd.verity_root_data=`` RAUC handles the ``systemd.verity_root_data=`` parameter the same as ``root=`` above. See the `systemd-veritysetup-generator documentation `_ for details. Barebox ~~~~~~~ The `Barebox `_ bootloader, which is available for many common embedded platforms, provides a dedicated boot source selection framework, called *bootchooser*, backed by an atomic and redundant storage backend, named *state*. *Barebox state* allows you to save the variables required by bootchooser with memory specific storage strategies in all common storage mediums, such as block devices, mtd (NAND/NOR), EEPROM, and UEFI variables. The *Bootchooser* framework maintains information about priority and remaining boot attempts while being configurable on how to deal with them for different strategies. To enable the Barebox bootchooser support in RAUC, select it in your system.conf: .. code-block:: cfg [system] ... bootloader=barebox Configure Barebox ^^^^^^^^^^^^^^^^^ As mentioned above, Barebox support requires you to have the *bootchooser framework* with *barebox state* backend enabled. In Barebox' Kconfig you can enable this by setting: .. code-block:: cfg CONFIG_BOOTCHOOSER=y CONFIG_STATE=y CONFIG_STATE_DRV=y To debug and interact with bootchooser and state in Barebox, you should also enable these tools: .. code-block:: cfg CONFIG_CMD_STATE=y CONFIG_CMD_BOOTCHOOSER=y Setup Barebox Bootchooser ^^^^^^^^^^^^^^^^^^^^^^^^^ The barebox bootchooser framework allows you to specify a number of redundant boot targets that should be automatically selected by an algorithm, based on status information saved for each boot target. The bootchooser itself can be used as a Barebox boot target. This is where we start by setting the barebox default boot target to `bootchooser`:: nv boot.default="bootchooser" Now, when Barebox is initialized it starts the bootchooser logic to select its real boot target. As a next step, we need to tell bootchooser which boot targets it should handle. These boot targets can have descriptive names which must not equal any of your existing boot targets, we will have a mapping for this later on. In this example we call the virtual bootchooser boot targets ``system0`` and ``system1``:: nv bootchooser.targets="system0 system1" Now connect each of these virtual boot targets to a real Barebox boot target (one of its automagical ones or custom boot scripts):: nv bootchooser.system0.boot="nand0.ubi.system0" nv bootchooser.system1.boot="nand0.ubi.system1" To configure bootchooser to store the variables in Barebox state, you need to configure the ``state_prefix``:: nv bootchooser.state_prefix="state.bootstate" Beside this very basic configuration variables, you need to set up a set of other general and slot-specific variables. .. warning:: It is highly recommended to read the full Barebox bootchooser `documentation `_ in order to know about the requirements and possibilities in fine-tuning the behavior according to your needs. Also make sure to have these ``nv`` settings in your compiled-in environment, not in your device-local environment. Setting up Barebox State for Bootchooser ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For storing its status information, the bootchooser framework requires a *barebox,state* instance to be set up with a set of variables matching the set of virtual boot targets defined. To allow loading the state information in a well-defined format both from Barebox and from the kernel, we store the state data format definition in the Barebox devicetree. Barebox fixups the information into the Linux devicetree when loading the kernel. This assures having a consistent view on the variables in Barebox and Linux. An example devicetree node for our simple redundant setup will have the following basic structure .. code-block:: DTS state { bootstate { system0 { ... }; system1 { ... }; }; }; In the state node, we set the appropriate compatible to tell the *barebox,state* driver to care for it and define where and how we want to store our data. This will look similar to this: .. code-block:: DTS state: state { magic = <0x4d433230>; compatible = "barebox,state"; backend-type = "raw"; backend = <&state_storage>; backend-stridesize = <0x40>; backend-storage-type = "circular"; #address-cells = <1>; #size-cells = <1>; [...] } where ``<&state_storage>`` is a phandle to, e.g. an EEPROM or NAND partition. .. important:: The devicetree only defines where and in which format the data will be stored. By default, no data will be stored in the deviectree itself! The rest of the variable set definition will be made in the ``bootstate`` subnode. For each virtual boot target handled by state, two uint32 variables ``remaining_attempts`` and ``priority`` need to be defined.: .. code-block:: DTS bootstate { system0 { #address-cells = <1>; #size-cells = <1>; remaining_attempts@0 { reg = <0x0 0x4>; type = "uint32"; default = <3>; }; priority@4 { reg = <0x4 0x4>; type = "uint32"; default = <20>; }; }; [...] }; .. note:: As the example shows, you must also specify some useful default variables the state driver will load in case of uninitialized backend storage. Additionally one single variable for storing information about the last chosen boot target is required: .. code-block:: DTS bootstate { [...] last_chosen@10 { reg = <0x10 0x4>; type = "uint32"; }; }; .. warning:: This example shows only a highly condensed excerpt of setting up Barebox state for bootchooser. For a full documentation on how Barebox state works and how to properly integrate it into your platform see the official Barebox State Framework `user documentation `_ as well as the corresponding `devicetree binding `_ reference! You can verify your setup by calling ``devinfo state`` from Barebox, which would print this for example: .. code-block:: sh barebox@board:/ devinfo state Parameters: bootstate.last_chosen: 2 (type: uint32) bootstate.system0.priority: 10 (type: uint32) bootstate.system0.remaining_attempts: 3 (type: uint32) bootstate.system1.priority: 20 (type: uint32) bootstate.system1.remaining_attempts: 3 (type: uint32) dirty: 0 (type: bool) save_on_shutdown: 1 (type: bool) Once you have set up bootchooser properly, you finally need to enable RAUC to interact with it. Enable Accessing Barebox State for RAUC ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For this, you need to specify which (virtual) boot target belongs to which of the RAUC slots you defined. You do this by assigning the virtual boot target name to the slots ``bootname`` property: .. code-block:: cfg [slot.rootfs.0] ... bootname=system0 [slot.rootfs.1] ... bootname=system1 For writing the bootchooser's state variables from userspace, RAUC uses the tool *barebox-state* from the `dt-utils `_ repository. .. note:: RAUC requires dt-utils version v2017.03 or later! Make sure to have this tool integrated on your target platform. You can verify your setup by calling it manually: .. code-block:: sh # barebox-state -d bootstate.system0.remaining_attempts=3 bootstate.system0.priority=10 bootstate.system1.remaining_attempts=3 bootstate.system1.priority=20 bootstate.last_chosen=2 Verify Boot Slot Detection ^^^^^^^^^^^^^^^^^^^^^^^^^^ As detecting the currently booted rootfs slot from userspace and matching it to one of the slots defined in RAUC's ``system.conf`` is not always trivial and error-prone, Barebox provides an explicit information about which slot it selected for booting adding a `bootchooser.active` key to the commandline of the kernel it boots. This key has the virtual bootchooser boot target assigned. In our case, if the bootchooser logic decided to boot `system0` the kernel commandline will contain:: bootchooser.active=system0 RAUC uses this information for detecting the active booted slot (based on the slot's `bootname` property). If the kernel commandline of your booted system contains this line, you have successfully set up bootchooser to boot your slot:: $ cat /proc/cmdline U-Boot ~~~~~~ .. To enable handling of redundant booting in U-Boot, manual scripting is required. U-Boot allows storing and modifying variables in its *Environment*. Properly configured, the environment can be accessed both from U-Boot itself as well as from Linux userspace. U-Boot also supports setting up the environment redundantly for atomic modifications. U-Boot での冗長ブートの処理を有効にするには、手動でスクリプトを作成する必要があります。 U-Boot では、その *環境* で変数を保存および変更できます。 適切に構成されていれば、U-Boot 自体と Linux ユーザー空間の両方から環境にアクセスできます。 U-Boot は、アトミックな変更のために環境を冗長に設定することもサポートしています。 .. The default RAUC U-Boot boot selection implementation requires a U-Boot boot script using specific set of variables that are persisted to the environment as stateful slot selection information. デフォルトの RAUC U-Boot ブート選択の実装には、ステートフル スロット選択情報として環境に保持される特定の変数セットを使用する U-Boot ブート スクリプトが必要です。 .. To enable U-Boot support in RAUC, select it in your system.conf: RAUC で U-Boot サポートを有効にするには、system.conf でそれを選択します。 .. code-block:: cfg [system] ... bootloader=uboot .. Set up U-Boot Boot Script for RAUC RAUC 用の U-Boot ブート スクリプトのセットアップ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. U-Boot as the bootloader needs to decide which slot (partition) to boot. For this decision it needs to read and process some state information set by RAUC or previous boot attempts. ブートローダーとしての U-Boot は、起動するスロット (パーティション) を決定する必要があります。 この決定のために、RAUC または以前のブート試行によって設定された状態情報を読み取って処理する必要があります。 .. The U-Boot bootloader interface of RAUC will rely on setting the following U-Boot environment variables: RAUC の U-Boot ブートローダー インターフェイスは、次の U-Boot 環境変数の設定に依存します。 .. :``BOOT_ORDER``: Contains a space-separated list of boot names in the order they should be tried, e.g. ``A B``. :``BOOT__LEFT``: Contains the number of remaining boot attempts to perform for the respective slot. :``BOOT_ORDER``: スペースで区切られたブート名のリストが、試される順序で含まれています。 e.g. ``A B``. :``BOOT__LEFT``: それぞれのスロットで実行する残りのブート試行回数が含まれます。 .. An example U-Boot script for handling redundant A/B boot setups is located in the ``contrib/`` folder of the RAUC source repository (``contrib/uboot.sh``). 冗長な A/B ブート設定を処理するための U-Boot スクリプトの例は、RAUC ソース リポジトリの ``contrib/`` フォルダーにあります (``contrib/uboot.sh``)。 .. .. note:: You must adapt the script's boot commands to match the requirements of your platform. .. note:: プラットフォームの要件に合わせて、スクリプトの起動コマンドを調整する必要があります。 .. You should integrate your boot selection script as ``boot.scr`` default boot script into U-Boot. ブート選択スクリプトを boot.scr デフォルト ブート スクリプトとして U-Boot に統合する必要があります。 .. For this you have to convert it to a U-boot readable default script (``boot.scr``) first:: このためには、最初に U-Boot で読み取り可能なデフォルト スクリプト (``boot.scr``) に変換する必要があります。 mkimage -A arm -T script -C none -n "Boot script" -d boot.scr If you place this on a partition next to U-Boot, it will use it as its boot script. For more details, refer the `U-Boot Scripting Capabilities `_ chapter in the U-Boot user documentation. The example script uses the names ``A`` and ``B`` as the ``bootname`` for the two different boot targets. These names need to be set in your system.conf as the ``bootname`` of the respective slots. The resulting boot attempts variables will be ``BOOT_A_LEFT`` and ``BOOT_B_LEFT``. The ``BOOT_ORDER`` variable will contain ``A B`` if ``A`` is the primary slot or ``B A`` if ``B`` is the primary slot to boot. .. note:: For minor changes in boot logic or variable names simply change the boot script and/or the RAUC system.conf ``bootname`` settings. If you want to implement a fully different behavior, you might need to modify the ``uboot_set_state()`` and ``uboot_set_primary()`` functions in ``src/bootchooser.c`` of RAUC. Setting up the (Fail-Safe) U-Boot Environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The U-Boot environment is used to store stateful boot selection information and serves as the interface between userspace and bootloader. The information stored in the environment needs to be preserved, even if the bootloader should be updated. Thus the environment should be placed outside the bootloader partition! The storage location for the environment can be controlled with ``CONFIG_ENV_IS_IN_*`` U-Boot Kconfig options like ``CONFIG_ENV_IS_IN_FAT`` or ``CONFIG_ENV_IS_IN_MMC``. You may either select a different storage than your bootloader, or a different location/partition/volume on the same storage. For fail-safe (atomic) updates of the environment, U-Boot can use redundant environments that allow to write to one copy while keeping the other as fallback if writing fails, e.g. due to sudden power cut. In order to enable redundant environment storage, you have to additionally set in your U-Boot config: .. code-block:: cfg CONFIG_SYS_REDUNDAND_ENVIRONMENT=y CONFIG_ENV_SIZE= CONFIG_ENV_OFFSET= CONFIG_ENV_OFFSET_REDUND= .. note:: Above switches refer to U-Boot >= v2020.01. Refer to U-Boot source code and README for more details on this. Enable Accessing U-Boot Environment from Userspace ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To enable reading and writing of the U-Boot environment from Linux userspace, you need to have: * U-Boot target tools ``fw_printenv`` and ``fw_setenv`` available on your devices rootfs. * Environment configuration file ``/etc/fw_env.config`` in your target root filesystem. See the corresponding `HowTo `_ section from the U-Boot documentation for more details on how to set up the environment config file for your device. .. Example: Setting up U-Boot Environment on eMMC/SD Card 例: eMMC/SD カードでの U-Boot 環境のセットアップ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. For this example we assume a simple redundancy boot partition layout with a bootloader partition and two rootfs partitions. この例では、1 つのブートローダー パーティションと 2 つの rootfs パーティションを持つ単純な冗長ブート パーティション レイアウトを想定しています。 .. Another additional partition we use exclusively for storing the environment. 環境を保存するためだけにもう 1 つの追加パーティションを使用します。 .. .. note:: It is not strictly required to have the env on an actual MBR/GPT partition, but we use this here as it better protects against accidentally overwriting relevant data of other partitions. .. note: env を実際の MBR/GPT パーティションに配置することは厳密には必須ではありませんが、他のパーティションの関連データを誤って上書きすることを防ぐため、ここではこれを使用します。 .. Partition table (excerpt with partition offsets): パーティション テーブル (パーティション オフセットを含む抜粋): .. code-block:: text /dev/mmcblk0p1 StartLBA: 8192 -> u-boot etc. /dev/mmcblk0p2 StartLBA: 114688 -> u-boot environment /dev/mmcblk0p3 StartLBA: 139264 -> rootfs A /dev/mmcblk0p4 StartLBA: 475136 -> rootfs B .. We enable redundant environment and storage in MMC (not in vfat/ext4 partition) in the u-boot config: u-boot 構成で、冗長環境と MMC (vfat/ext4 パーティションではなく) のストレージを有効にします。 .. code-block:: cfg CONFIG_SYS_REDUNDAND_ENVIRONMENT=y CONFIG_ENV_IS_IN_MMC=y .. The default should be to use mmc device 0 and HW partition 0. Since U-Boot 2020.10.0 we can set this also explicitly if required: デフォルトでは、mmc デバイス 0 と HW パーティション 0 を使用する必要があります。 U-Boot 2020.10.0 以降、必要に応じて明示的に設定することもできます。 .. code-block:: cfg CONFIG_SYS_MMC_ENV_DEV=0 CONFIG_SYS_MMC_ENV_PART=0 .. important:: With ``CONFIG_SYS_MMC_ENV_PART`` we can specify a eMMC HW partition only, not an MBR/GPT partition! HW partitions are e.g. 0=user data area, 1=boot partition. Then we must specify the env storage size and its offset relative to the currently used device. Here the device is the eMMC user data area (or SD Card). For placing the content in partition 2 now, we must calculate the offset as ``offset=hex(n sector * 512 bytes/sector)``. With ``n=114688`` (start of /dev/mmcblk0p2 according to above partition table) we get an offset of ``0x3800000``. As size we pick ``0x4000`` (16kB) here. The offset of the redundant copy must be the offset of the first copy + size of first copy. This results in: .. code-block:: cfg CONFIG_ENV_SIZE=0x4000 CONFIG_ENV_OFFSET=0x3800000 CONFIG_ENV_OFFSET_REDUND=0x3804000 Finally, we need to configure userspace to access the same location. This can be referenced directly by its partition device name (/dev/mmcblk0p2) in the ``/etc/fw_env.config``: .. code-block:: text /dev/mmcblk0p2 0x0000 0x4000 /dev/mmcblk0p2 0x4000 0x4000 GRUB ~~~~ .. code-block:: cfg [system] ... bootloader=grub To enable handling of redundant booting in GRUB, manual scripting is required. The GRUB bootloader interface of RAUC uses the GRUB environment variables ``_OK``, ``_TRY`` and ``ORDER``. An exemplary GRUB configuration for handling redundant boot setups is located in the ``contrib/`` folder of the RAUC source repository (``grub.conf``). As the GRUB shell only has limited support for scripting, this example uses only one try per enabled slot. To enable reading and writing of the GRUB environment, you need to have the tool ``grub-editenv`` available on your target. By default RAUC expects the grubenv file to be located at ``/boot/grub/grubenv``, you can specify a custom directory by passing ``grubenv=/path/to/grubenv`` in your system.conf ``[system]`` section. Make sure that the grubenv file is located outside your redundant rootfs partitions as the rootfs needs to be exchangeable without affecting the environment content. For UEFI systems, a proper location would be to place it on the EFI partition, e.g. at ``/EFI/BOOT/grubenv``. The same partition can also be used for your ``grub.cfg`` (which could be placed at ``/EFI/BOOT/grub.cfg``). Note that you then also need to manually tell GRUB where to load the grubenv from. You can do this in your ``grub.cfg`` by a adding the ``--file`` argument to your script's ``load_env`` and ``save_env`` calls, like:: load_env --file=(hd0,2)/grubenv save_env --file=(hd0,2)/grubenv A_TRY A_OK B_TRY B_OK ORDER .. _sec-efi: EFI ~~~ For x86 systems that directly boot via EFI/UEFI, RAUC supports interaction with EFI boot entries by using the `efibootmgr` tool. To enable EFI bootloader support in RAUC, write in your ``system.conf``: .. code-block:: cfg [system] ... bootloader=efi To set up a system ready for pure EFI-based redundancy boot without any further bootloader or initramfs involved, you have to create an appropriate partition layout and matching boot EFI entries. Assuming a simple A/B redundancy, you would need: * 2 redundant EFI partitions holding an EFI stub kernel (e.g. at ``EFI/LINUX/BZIMAGE.EFI``) * 2 redundant rootfs partitions To create boot entries for these, use the efibootmgr tool:: efibootmgr --create --disk /dev/sdaX --part 1 --label "system0" --loader \\EFI\\LINUX\\BZIMAGE.EFI --unicode "root=PARTUUID=" efibootmgr --create --disk /dev/sdaX --part 2 --label "system1" --loader \\EFI\\LINUX\\BZIMAGE.EFI --unicode "root=PARTUUID=" where you replace /dev/sdaX with the name of the disk you use for redundancy boot, ```` with the PARTUUID of the first rootfs partition and ```` with the PARTUUID of the second rootfs partition. You can inspect and verify your settings by running:: efibootmgr -v In your ``system.conf``, you have to list both the EFI partitions (each containing one kernel) as well as the rootfs partitions. Make the first EFI partition a child of the first rootfs partition and the second EFI partition a child of the second rootfs partition to have valid slot groups. Set the rootfs slot bootnames to those we have defined with the ``--label`` argument in the ``efibootmgr`` call above: .. code-block:: cfg [slot.efi.0] device=/dev/sdX1 type=vfat parent=rootfs.0 [slot.efi.1] device=/dev/sdX2 type=vfat parent=rootfs.1 [slot.rootfs.0] device=/dev/sdX3 type=ext4 bootname=system0 [slot.rootfs.1] device=/dev/sdX4 type=ext4 bootname=system1 .. _sec-custom-bootloader-backend: Custom ~~~~~~ If none of the previously mentioned approaches can be applied on the system, RAUC also offers the possibility to use customization scripts or applications as bootloader backend. To enable the custom bootloader backend support in RAUC, select it in your `system.conf`: .. code-block:: cfg [system] ... bootloader=custom Configure custom bootloader backend ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The custom bootloader backed based on a handler that is called to get the desired information or set the appropriate configuration of the custom bootloader environment. To register the custom bootloader backend handler, assign your handler to the ``bootloader-custom-backend`` key in section ``handlers`` in your `system.conf`: .. code-block:: cfg [handlers] ... bootloader-custom-backend=custom-bootloader-script Custom bootloader backend interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ According to :ref:`sec-boot-slot` the custom bootloader handler is called by RAUC to trigger the following actions: * get the primary slot * set the primary slot * get the boot state * set the boot state To get the primary slot, the handler is called with the argument ``get-primary``. The handler must output the current primary slot's bootname on the `stdout`, and return ``0`` on exit, if no error occurred. In case of failure, the handler must return with non-zero value. Accordingly, in order to set the primary slot, the custom bootloader handler is called with argument ``set-primary `` where ```` matches the ``bootname=`` key defined for the respective slot in your `system.conf`. If the set was successful, the handler must also return with a ``0``, otherwise the return value must be non-zero. In addition to the primary slot, RAUC must also be able to determine the boot state of a specific slot. RAUC determines the necessary boot state by calling the custom bootloader handler with the argument ``get-state ``. Whereupon the handler has to output the state ``good`` or ``bad`` to `stdout` and exit with the return value ``0``. If the state cannot be determined or another error occurs, the custom bootloader handler must exit with non-zero return value. To set the boot state to the desire slot, the handler is called with argument ``set-state ``. As already mentioned in the paragraph above, the ```` matches the ``bootname=`` key defined for the respective slot in your `system.conf`. The ```` argument corresponds to one of the following values: * ``good`` if the last start of the slot was successful or * ``bad`` if the last start of the slot failed. The return value must be ``0`` if the boot state was set successfully, or non-zero if an error occurred. .. Init System and Service Startup システムとサービスの初期化 ------------------------------- .. There are several ways to run the RAUC service on your target. The recommended way is to use a systemd-based system and allow to start RAUC via D-Bus activation. ターゲットで RAUC サービスを実行するには、いくつかの方法があります。 推奨される方法は、systemd ベースのシステムを使用し、D-Bus アクティベーションを介して RAUC を開始できるようにすることです。 .. You can start the RAUC service manually by executing:: 次のコマンドを実行して、RAUC サービスを手動で開始できます。 $ rauc service .. Keep in mind that rauc service reads the system.conf during startup and needs to be restarted for changes in the system.conf to take affect. rauc サービスは起動時に system.conf を読み取るため、system.conf の変更を有効にするには再起動する必要があることに注意してください。 .. Systemd Integration Systemd 統合 ~~~~~~~~~~~~~~~~~~~ .. When building RAUC, a default systemd ``rauc.service`` file will be generated in the ``data/`` folder. RAUC をビルドすると、デフォルトの systemd の ``rauc.service`` ファイルが ``data/`` フォルダーに生成されます。 .. Depending on your configuration ``make install`` will place this file in one of your system's service file folders. 構成に応じて、 ``make install`` はこのファイルをシステムのサービス ファイル フォルダーの 1 つに配置します。 .. It is a good idea to wait for the system to be fully started before marking it as successfully booted. In order to achieve this, a smart solution is to create a systemd service that calls ``rauc status mark-good`` and use systemd's dependency handling to assure this service will not be executed before all relevant other services came up successfully. It could look similar to this: システムが正常に起動したとマークする前に、システムが完全に起動するのを待つことをお勧めします。 これを実現するためのスマートなソリューションは、 ``rauc status mark-good`` を呼び出す systemd サービスを作成し、systemd の依存関係処理を使用して、関連する他のすべてのサービスが正常に起動する前にこのサービスが実行されないようにすることです。 これは次のようになります。 .. code-block:: cfg [Unit] Description=RAUC Good-marking Service ConditionKernelCommandLine=|bootchooser.active ConditionKernelCommandLine=|rauc.slot [Service] ExecStart=/usr/bin/rauc status mark-good [Install] WantedBy=multi-user.target D-Bus Integration ----------------- The :ref:`D-Bus ` interface RAUC provides makes it easy to integrate it into your customapplication. In order to allow sending data, make sure the D-Bus config file ``de.pengutronix.rauc.conf`` from the ``data/`` dir gets installed properly. To only start RAUC when required, using D-Bus activation is a smart solution. In order to enable D-Bus activation, properly install the D-Bus service file ``de.pengutronix.rauc.service`` from the ``data/`` dir. .. Watchdog Configuration ウォッチドッグ設定 ---------------------- .. Detecting system hangs during runtime requires to have a watchdog and to have the watchdog configured and handled properly. Systemd provides a sophisticated watchdog multiplexing and handling allowing you to configure separate timeouts and handlings for each of your services. 実行時にシステムのハングを検出するには、ウォッチドッグが必要であり、ウォッチドッグを適切に構成および処理する必要があります。 Systemd は、洗練されたウォッチドッグの多重化と処理を提供し、サービスごとに個別のタイムアウトと処理を構成できるようにします。 .. To enable it, you need at least to have these lines in your systemd configuration:: これを有効にするには、systemd 設定に少なくとも次の行が必要です。 RuntimeWatchdogSec=20 ShutdownWatchdogSec=10min .. _sec_int_yocto: Yocto ----- .. Yocto support for using RAUC is provided by the `meta-rauc `_ layer. RAUC を使用するための Yocto サポートは、 `meta-rauc `_ レイヤーによって提供されます。 .. The layer supports building RAUC both for the target as well as as a host tool. With the `bundle.bbclass `_ it provides a mechanism to specify and build bundles directly with the help of Yocto. このレイヤーは、ターゲット ツールとホスト ツールの両方で RAUC の構築をサポートします。 `bundle.bbclass `_ を使用すると、Yocto を使用して直接バンドルを指定および構築するメカニズムが提供されます。 For more information on how to use the layer, also see the layer's `README `_ file. .. note:: When using the ``block-hash-index`` adaptive mode, you may need to set ``IMAGE_ROOTFS_ALIGNMENT = "4"`` in your ``machine.conf`` to ensure that the image is padded to full 4 kiB blocks. Target System Setup ~~~~~~~~~~~~~~~~~~~ Add the `meta-rauc` layer to your setup:: git submodule add git@github.com:rauc/meta-rauc.git Add the RAUC tool to your image recipe (or package group):: IMAGE_INSTALL_append = "rauc" .. Append the RAUC recipe from your BSP layer (referred to as `meta-your-bsp` in the following) by creating a ``meta-your-bsp/recipes-core/rauc/rauc_%.bbappend`` with the following content:: 次の内容で ``meta-your-bsp/recipes-core/rauc/rauc_%.bbappend`` を作成して、BSP レイヤー (以下では `meta-your-bsp` と呼びます) から RAUC レシピを追加します。 FILESEXTRAPATHS_prepend := "${THISDIR}/files:" .. Write a ``system.conf`` for your board and place it in the folder you mentioned in the recipe (`meta-your-bsp/recipes-core/rauc/files`). This file must provide a system compatible string to identify your system type, as well as a definition of all slots in your system. By default, the system configuration will be placed in `/etc/rauc/system.conf` on your target rootfs. ボードの ``system.conf`` を作成し、レシピで言及したフォルダー (`meta-your-bsp/recipes-core/rauc/files`) に配置します。 このファイルは、システム タイプを識別するためのシステム互換文字列と、システム内のすべてのスロットの定義を提供する必要があります。 デフォルトでは、システム構成はターゲット rootfs の `/etc/rauc/system.conf`` に配置されます。 .. Also place the appropriate keyring file for your target into the directory added to ``FILESEXTRAPATHS`` above. Name it either ``ca.cert.pem`` or additionally specify the name of your custom file by setting ``RAUC_KEYRING_FILE``. If multiple keyring certificates are required on a single system, create a keyring directory containing each certificate. また、上記の ``FILESEXTRAPATHS`` に追加されたディレクトリに、ターゲットの適切なキーリング ファイルを配置します。 ``ca.cert.pem`` という名前を付けるか、 ``RAUC_KEYRING_FILE`` を設定してカスタム ファイルの名前を追加で指定します。 1 つのシステムで複数のキーリング証明書が必要な場合は、各証明書を含むキーリング ディレクトリを作成します。 .. note:: For information on how to create a testing / development key/cert/keyring, please refer to `scripts/README `_ in meta-rauc. For a reference of allowed configuration options in system.conf, see :ref:`sec_ref_slot_config`. For a more detailed instruction on how to write a system.conf, see :ref:`sec-int-system-config`. .. Using RAUC on the Host System ホストシステムでの RAUC の使用 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. The RAUC recipe allows to compile and use RAUC on your host system. Having RAUC available as a host tool is useful for debugging, testing or for creating bundles manually. For the preferred way of creating bundles automatically, see the chapter `Bundle Generation`_. In order to compile RAUC for your host system, simply run:: RAUC レシピを使用すると、ホスト システムで RAUC をコンパイルして使用できます。 RAUC をホスト ツールとして使用できるようにすると、デバッグ、テスト、または手動でバンドルを作成する場合に役立ちます。 バンドルを自動的に作成する推奨方法については、「バンドルの生成」の章を参照してください。 ホストシステム用に RAUC をコンパイルするには、次のコマンドを実行するだけです: bitbake rauc-native .. This will place a copy of the RAUC binary in ``tmp/deploy/tools`` in your current build folder. To test it, try:: これにより、現在のビルド フォルダーの ``tmp/deploy/tools`` に RAUC バイナリのコピーが配置されます。 テストするには、次を試してください。 tmp/deploy/tools/rauc --version .. Bundle Generation バンドルの生成 ~~~~~~~~~~~~~~~~~ .. Bundles can be created either manually by building and using RAUC as a native tool, or by using the ``bundle.bbclass`` that handles most of the basic steps, automatically. バンドルは、RAUC をビルドしてネイティブ ツールとして使用することによって手動で作成するか、ほとんどの基本的な手順を自動的に処理する ``bundle.bbclass`` を使用して作成できます。 .. First, create a bundle recipe in your BSP layer. A possible location for this could be ``meta-your-bsp/recipes-core/bundles/update-bundle.bb``. まず、BSP レイヤーでバンドル レシピを作成します。 これが可能な場所は、 ``meta-your-bsp/recipes-core/bundles/update-bundle.bb`` です。 .. To create your bundle you first have to inherit the bundle class:: バンドルを作成するには、最初にバンドル クラスを継承する必要があります。 inherit bundle .. To create the manifest file, you may either use the built-in class mechanism, or provide a custom manifest. マニフェスト ファイルを作成するには、組み込みのクラス メカニズムを使用するか、カスタム マニフェストを提供します。 .. For using the built-in bundle generation, you need to specify some variables: 組み込みのバンドル生成を使用するには、いくつかの変数を指定する必要があります。 .. ``RAUC_BUNDLE_COMPATIBLE`` Sets the compatible string for the bundle. This should match the compatible you specified in your ``system.conf`` or, more generally, the compatible of the target platform you intend to install this bundle on. ``RAUC_BUNDLE_COMPATIBLE`` バンドルの互換文字列を設定します。 これは、 ``system.conf`` で指定した互換性、またはより一般的には、このバンドルをインストールする予定のターゲット プラットフォームの互換性と一致する必要があります。 .. ``RAUC_BUNDLE_SLOTS`` Use this to list all slot classes for which the bundle should contain images. A value of ``"rootfs appfs"`` for example will create a manifest with images for two slot classes; rootfs and appfs. ``RAUC_BUNDLE_SLOTS`` これを使用して、バンドルにイメージを含める必要があるすべてのスロット クラスを一覧表示します。 たとえば、``"rootfs appfs"`` という値は、rootfs と appfs の 2 つのスロット クラスのイメージを含むマニフェストを作成します。 .. ``RAUC_BUNDLE_FORMAT`` Use this to choose the :ref:`sec_ref_formats` for the generated bundle. It currently defaults to ``plain``, but you should use ``verity`` if possible. ``RAUC_BUNDLE_FORMAT`` これを使用して、生成されたバンドルのバンドル形式を選択します。 現在はデフォルトで ``plain`` ですが、可能であれば ``verity`` を使用する必要があります。 .. ``RAUC_SLOT_`` For each slot class, set this to the image (recipe) name which builds the artifact you intend to place in the slot class. ``RAUC_SLOT_`` スロット クラスごとに、これをスロット クラスに配置するアーティファクトをビルドするイメージ (レシピ) 名に設定します。 .. ``RAUC_SLOT_[type]`` For each slot class, set this to the *type* of image you intend to place in this slot. Possible types are: ``image`` (default), ``kernel``, ``boot``, or ``file``. ``RAUC_SLOT_[type]`` スロット クラスごとに、このスロットに配置するイメージのタイプに設定します。 可能なタイプは、 ``image`` (デフォルト)、 ``kernel``、 ``boot``、または ``file`` です。 .. .. note:: For a full list of supported variables, refer to `classes/bundle.bbclass` in meta-rauc. .. note:: サポートされている変数の完全なリストについては、meta-rauc の `classes/bundle.bbclass` を参照してください。 .. A minimal bundle recipe, such as `core-bundle-minimal.bb` that is contained in meta-rauc will look as follows:: meta-rauc に含まれる `core-bundle-minimal.bb` などの最小バンドル レシピは次のようになります。 inherit bundle RAUC_BUNDLE_COMPATIBLE ?= "Demo Board" RAUC_BUNDLE_SLOTS ?= "rootfs" RAUC_BUNDLE_FORMAT ?= "verity" RAUC_SLOT_rootfs ?= "core-image-minimal" .. To be able to build a signed image of this, you also need to configure ``RAUC_KEY_FILE`` and ``RAUC_CERT_FILE`` to point to your key and certificate files you intend to use for signing. You may set them either from your bundle recipe or any global configuration (layer, site.conf, etc.), e.g.:: これの署名付きイメージを作成できるようにするには、署名に使用するキーと証明書ファイルを指すように ``RAUC_KEY_FILE`` と ``RAUC_CERT_FILE`` を構成する必要もあります。 バンドル レシピまたは任意のグローバル構成 (layer、site.conf など) から設定できます。例: RAUC_KEY_FILE = "${COREBASE}/meta-/files/development-1.key.pem" RAUC_CERT_FILE = "${COREBASE}/meta-/files/development-1.cert.pem" .. .. note:: For information on how to create a testing / development key/cert/keyring, please refer to `scripts/README` in meta-rauc. .. note:: テスト/開発キー/証明書/キーリングの作成方法については、meta-rauc の `script/README` を参照してください。 .. Based on this information, a call of:: この情報に基づいて、次の呼び出しが行われます。 bitbake core-bundle-minimal .. will build all required images and generate a signed RAUC bundle from this. The created bundle can be found in ``${DEPLOY_DIR_IMAGE}`` (defaults to ``tmp/deploy/images/`` in your build directory). 必要なすべてのイメージをビルドし、これから署名付き RAUC バンドルを生成します。 作成されたバンドルは ``${DEPLOY_DIR_IMAGE}`` にあります (デフォルトはビルド ディレクトリの ``tmp/deploy/images/`` です)。 .. _sec_int_ptxdist: PTXdist ------- .. note:: RAUC support in PTXdist is available since version 2017.04.0. Integration into Your RootFS Build ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable building RAUC for your target, set:: CONFIG_RAUC=y in your ptxconfig (by selecting ``RAUC`` via ``ptxdist menuconfig``). You should also customize the compatible RAUC uses for your system. To do this, set ``PTXCONF_RAUC_COMPATIBLE`` to a string that uniquely identifies your device type. The default value will be ``"${PTXCONF_PROJECT_VENDOR}\ ${PTXCONF_PROJECT}"``. Place your system configuration file in ``$(PTXDIST_PLATFORMCONFIGDIR)/projectroot/etc/rauc/system.conf`` to let the RAUC package install it into the rootfs you build. .. note:: PTXdist versions since 2020.06.0 use their `code signing infrastructure `_ for keyring creation. See PTXdist's `Managing Certificate Authority Keyrings `_ for different scenarios (refer to RAUC's :ref:`sec-ca-configuration`). Previous PTXdist versions expected the keyring in ``$(PTXDIST_PLATFORMCONFIGDIR)/projectroot/etc/rauc/ca.cert.pem``. The keyring is installed into the rootfs to ``/etc/rauc/ca.cert.pem``. If using systemd, the recipes install both the default ``systemd.service`` file for RAUC as well as a ``rauc-mark-good.service`` file. This additional good-marking-service runs after user space is brought up and notifies the underlying bootloader implementation about a successful boot of the system. This is typically used in conjunction with a boot attempts counter in the bootloader that is decremented before starting the system and reset by `rauc status mark-good` to indicate a successful system startup. .. _ptxdist-code-signing: https://www.ptxdist.org/doc/dev_code_signing.html .. _ptxdist-manage-ca-keyrings: https://www.ptxdist.org/doc/dev_code_signing.html#managing-certificate-authority-keyrings Create Update Bundles from your RootFS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable building RAUC bundles, set:: CONFIG_IMAGE_RAUC=y in your platformconfig (by using ``ptxdist platformconfig``). This adds a default image recipe for building a RAUC update bundle out of the system's rootfs. As for most image recipes, the `genimage ` tool is used to configure and generate the update bundle. PTXdist's default bundle configuration is placed in `config/images/rauc.config`. You may also copy this to your platform directory to use this as a base for custom bundle configuration. RAUC enforces signing of update bundles. PTXdist versions since 2020.06.0 use its `code signing infrastructure `_ for signing and keyring verification. Previous versions expected the signing key in ``$(PTXDIST_PLATFORMCONFIGDIR)/config/rauc/rauc.key.pem``. Once you are done with your setup, PTXdist will automatically create a RAUC update bundle for you during the run of ``ptxdist images``. It will be placed under ``$(PTXDIST_PLATFORMDIR)/images/update.raucb``. .. _genimage: https://github.com/pengutronix/genimage .. _ptxdist-code-signing: https://www.ptxdist.org/doc/dev_code_signing.html Buildroot --------- .. note:: RAUC support in Buildroot is available since version 2017.08.0. To build RAUC using Buildroot, enable ``BR2_PACKAGE_RAUC`` in your configuration. .. _sec_int_migration: Bundle Format Migration ----------------------- Migrating from the `plain` to the `verity` :ref:`bundle format ` should be simple in most cases and can be done in a single update. The high-level functionality of RAUC (certificate checking, update installation, hooks/handlers, …) is independent of the low-level bundle format. The required steps are: * Configure your build system to build RAUC v1.5 (or newer). * Enable ``CONFIG_CRYPTO_SHA256``, ``CONFIG_MD``, ``CONFIG_BLK_DEV_DM`` and ``CONFIG_DM_VERITY`` in your kernel configuration. These may already be enabled if you are using dm-verity for verified boot. * Add a new bundle output configured for the `verity` format by adding the following to the manifest: .. code-block:: cfg [bundle] format=verity .. note:: For OE/Yocto with an up-to-date meta-rauc, you can choose the bundle format by adding the ``RAUC_BUNDLE_FORMAT = "verity"`` option in your bundle recipe. The bundle.bbclass will insert the necessary option into the manifest. For PTXdist or Buildroot with genimage, you can add the manifest option above to the template in your genimage config file. With these changes, the build system should produce two bundles (one in either format). A `verity` bundle will only be installable on systems that have already received the migration update. A `plain` bundle will be installable on both migrated and unmigrated systems. You should then test that *both* bundle formats can be installed on a migrated system, as RAUC will now perform additional checks when installing a ``plain`` bundle to protect against potential modification during installation. This testing should include all bundle sources (USB, network, …) that you will need in the field to ensure that these new checks don't trigger in your case (which would prohibit further updates). .. note:: When installing bundles from a FAT filesystem (for example on a USB memory stick), check that the mount option ``fmask`` is set to ``0022`` or ``0133``. When you no longer need to be able to install previously built bundles in the `plain` format, you should also disable it in the ``system.conf``: .. code-block:: cfg [system] … bundle-formats=-plain … If you later need to support downgrades, you can use ``rauc extract`` and ``rauc bundle`` to convert a `plain` bundle to a `verity` bundle, allowing installation to systems that have already been migrated.