.. _sec_ref: Reference ========= .. contents:: :local: :depth: 1 .. _sec_ref_slot_config: System Configuration File ------------------------- A configuration file named ``system.conf`` describes the number and type of available slots. This file is loaded from one of the listed directories in order of priority, only the first file found is used: ``/etc/rauc/``, ``/run/rauc/``, ``/usr/lib/rauc/``. It is used to validate storage locations for update images. Each board type requires its special configuration. This file is part of the root file system. .. note:: When changing the configuration file on your running target you need to restart the RAUC service in order to let the changes take effect. Example configuration: .. code-block:: cfg [system] compatible=FooCorp Super BarBazzer bootloader=barebox data-directory=/srv/rauc bundle-formats=-plain [keyring] path=/etc/rauc/keyring.pem [handlers] system-info=/usr/lib/rauc/info-provider.sh post-install=/usr/lib/rauc/postinst.sh [slot.rootfs.0] device=/dev/sda0 type=ext4 bootname=system0 [slot.rootfs.1] device=/dev/sda1 type=ext4 bootname=system1 [artifacts.add-ons] path=/srv/add-ons type=trees .. _system-section: ``[system]`` Section ~~~~~~~~~~~~~~~~~~~~ ``compatible`` (required) A user-defined compatible string that describes the target hardware as specific enough as required to prevent faulty updating systems with the wrong firmware. It will be matched against the ``compatible`` string defined in the update manifest. ``min-bundle-version`` (optional) An optional user-defined version string that follows the `semantic versioning scheme `_. The 'version core' and '-pre_release' parts from the ``version`` string in the update manifest are compared against the configured ``min-bundle-version``. The update will be rejected if the bundle manifest version is smaller/older. This allows to roll out updates with some (breaking) changes by shipping them with a system.conf that sets the ``min-bundle-version`` accordingly. Once the updated system runs, it will prevent the installation of future updates with smaller/older bundle manifest versions. Note that equating the bundle-version with the system-version in this way has the caveat that cases where a rollback (due to a regression for example) would be required, could lead to scenarios where the bundle version would need to be incremented to pass the version-limit, but the rolled back system version would end up at a number below the limit. E.g. 1.2.9 = good; update to 1.3.0 with limit set to 1.3.0; problems!; update-bundle version:=1.3.1 but with content=1.2.9. Also note that the implementation in RAUC relaxes the strict Major.Minor.Path version-core format imposed by the semantic versioning scheme. To accommodate versioning schemes that use YEAR.MONTH or similar, version-cores with just Major or Major.Minor are also allowed. ``bootloader`` (required) The bootloader implementation RAUC should use for its slot switching mechanism. Currently supported values (and bootloaders) are ``barebox``, ``grub``, ``uboot``, ``efi``, ``custom``, ``noop``. .. _bundle-formats: ``bundle-formats`` (optional, recommended) This option controls which :ref:`bundle formats` are allowed when verifying a bundle. You can either specify them explicitly by using a space-separated list for format names (such as ``plain verity``). In this case, any future changes of the built-in defaults will have no effect. Alternatively, you can use format names prefixed by ``-`` or ``+`` (such as ``-plain``) to enable or disable formats relative to the default configuration. This way, formats added in newer releases will be active automatically. ``mountprefix`` (optional) Prefix of the path where bundles and slots will be mounted. Can be overwritten by the command line option ``--mount``. Defaults to ``/mnt/rauc/``. ``grubenv`` (optional) Only valid when ``bootloader`` is set to ``grub``. Specifies the path under which the GRUB environment can be accessed. ``barebox-statename`` (optional) Only valid when ``bootloader`` is set to ``barebox``. Overwrites the default state ``state`` to a user-defined state name. If this key not exists, the bootchooser framework searches per default for ``/state`` or ``/aliases/state``. ``barebox-dtbpath`` (optional) Only valid when ``bootloader`` is set to ``barebox``. Allows to set a path to a separate devicetree (dtb) file to be used for reading `barebox state `_ definition from. This is mainly useful for systems that do not use devicetrees by default, like x86 systems. .. note:: Requires to have at least `dt-utils `_ version 2021.03.0 ``boot-attempts`` (optional) This configures the number of boot attempts to set when a slot is marked good through the D-Bus API or via the command line tool. The configured value should match the bootloader's reset value for attempts. This is currently only supported when ``bootloader`` is set to ``uboot`` or ``barebox`` and defaults to 3 if not set. ``boot-attempts-primary`` (optional) This configures the number of boot attempts to set when a slot is marked as primary (i.e., when an update was installed successfully). This is currently only supported when ``bootloader`` is set to ``uboot`` or ``barebox`` and defaults to 3 if not set. ``efi-use-bootnext`` (optional) Only valid when ``bootloader`` is set to ``efi``. If set to ``false``, this disables using efi variable ``BootNext`` for marking a slot primary. This is useful for setups where the BIOS already handles the slot switching on watchdog resets. Behavior defaults to ``true`` if the option is not set. .. _activate-installed: ``activate-installed`` (optional) This boolean value controls if a freshly installed slot is automatically marked active with respect to the used bootloader. Its default value is ``true`` which means that this slot is going to be started the next time the system boots. If the value of this parameter is ``false`` the slot has to be activated manually in order to be booted, see section :ref:`mark-active`. .. _statusfile: ``statusfile`` (deprecated, optional) .. note:: This option is deprecated. Consider using ``data-directory`` instead. For more details about backwards compatibility, see :ref:`data-directory `. Can be set to point to a central file where slot status information should be stored (e.g. slot-specific metadata, see :ref:`slot-status`). .. important:: This file must be located on a non-redundant filesystem which is not overwritten during updates. .. _data-directory: ``data-directory`` (optional, recommended) This path configures the directory where RAUC should store its slot status and any other internal information. In most cases, a shared RAUC data directory is preferable, as it allows storing data also for read-only or filesystem-less slots. We have multiple levels of backwards compatibility: * per-slot status and no shared data directory (by default or explicitly with ``statusfile=per-slot``) * central status file and no shared data directory (``statusfile=/data/central.raucs``) * central status file and shared data directory (``statusfile=/data/central.raucs`` and ``data-directory=/data/rauc``) * central status file in shared data directory (``data-directory=/data/rauc``, implies ``statusfile=/data/rauc/central.raucs``) .. important:: This directory must be located on a non-redundant filesystem which is not overwritten during updates. ``max-bundle-download-size`` (optional) Defines the maximum downloadable bundle size in bytes, and thus must be a simple integer value (without unit) greater than zero. It overwrites the compiled-in default value of 8388608 (8 MiB). If RAUC is configured with streaming support, this has no effect, as the bundle is not downloaded as a whole. ``max-bundle-signature-size`` (optional) Defines the maximum bundle signature size in bytes, and thus must be a simple integer value (without unit) greater than zero. It overwrites the compiled-in default value of 64 KiB. As this limit also applies to the encrypted signature when using ``crypt`` bundles, you may need to increase it if you encrypt to a large number of recipients. ``variant-name`` (optional) String to be used as variant name for this board. If set, neither ``variant-file`` nor ``variant-dtb`` must be set. Refer chapter :ref:`sec-variants` for more information. ``variant-file`` (optional) File containing variant name for this board. If set, neither ``variant-name`` nor ``variant-dtb`` must be set. Refer chapter :ref:`sec-variants` for more information. ``variant-dtb`` (optional) If set to ``true``, use current device tree compatible as this boards variant name. If set, neither ``variant-name`` nor ``variant-file`` must be set. Refer chapter :ref:`sec-variants` for more information. .. _perform-pre-check: ``perform-pre-check`` (optional) For ``verity`` and ``crypt`` bundles, this boolean value controls whether the complete bundle is checked for data corruption before it is mounted. Normally, this option is not needed as every access to the bundle payload during installation is already protected by ``dm-verity``. The default value is ``false`` which means that this pre-check is not performed. This option is useful when the installation should be aborted early even if the corrupt part of the bundle is not used during installation (perhaps due to adaptive updates or image variants). It has no effect for ``plain`` bundles, as the signature verification already checks the whole bundle. ``prevent-late-fallback=`` (optional) In some use-cases, fallback to an older version must be prevented after the update is completed successfully (``rauc status mark-good`` executed from the new version). If this option is enabled, RAUC will execute the equivalent of ``rauc status mark-bad other`` after marking the currently booted slot as good. This means that the other slot(s) is/are no longer eligible for fallback. .. _keyring-section: ``[keyring]`` Section ~~~~~~~~~~~~~~~~~~~~~ The ``keyring`` section refers to the trusted keyring used for signature verification. Both ``path`` and ``directory`` options can be used together if desired, though only one or the other is necessary to verify the bundle signature. ``path`` (optional) Path to the keyring file in PEM format. Either absolute or relative to the system.conf file. ``directory`` (optional) Path to the keyring directory containing one or more certificates. Each file in this directory must contain exactly one certificate in CRL or PEM format. The filename of each certificate must have the form hash.N for a certificate or hash.rN for CRLs; where hash is obtained by ``X509_NAME_hash(3)`` or the ``--hash`` option of ``openssl(1)`` ``x509`` or ``crl`` commands. See documentation in ``X509_LOOKUP_hash_dir(3)`` for details. ``use-bundle-signing-time=`` (optional) If this boolean value is set to ``true`` then the bundle signing time is used instead of the current system time for certificate validation. .. _allow-partial-chain: ``allow-partial-chain=`` (optional) If this boolean value is set to ``true``, RAUC will also treat intermediate certificates in the keyring as trust-anchors, in addition to self-signed root CA certificates. This makes it possible to trust only one (or more) sub-tree(s) in a larger PKI. Note that without the root CA certificate in the keyring, CRLs signed by it can not be authenticated. If CRL checking is needed, the PKI needs to be structured with this in mind. ``allowed-signer-cns=Name 1;Other Name`` (optional) If this config parameter is set, RAUC will check the ``CommonName`` field of the bundle's signer certificates against this semicolon-separated list. If no signature from a certificate with a matching ``CommonName`` is found, the target device is not eligible for the update bundle and the update process is aborted. This parameter can be used instead of relying on the RAUC system compatible check if only specific certificates in a shared PKI are trusted for specific target devices. If the ``allowed-signer-cns`` check fails, no code from the bundle is executed, so unlike the system compatible check, it cannot be overridden by an ``install-check`` hook. This parameter can contain multiple values, separated by semicolons. Values can contain whitespace. ``check-crl=`` (optional) If this boolean value is set to ``true``, RAUC will enable checking of CRLs (Certificate Revocation Lists) stored in the keyring together with the CA certificates. Note that CRLs have an expiration time in their signature, so you need to make sure you don't end up with an expired CRL on your device (which would block further updates). .. _check-purpose: ``check-purpose`` (optional) This option can be used to set the OpenSSL certificate purpose used during chain verification. Certificates in the chain with incompatible purposes are rejected. Possible values are provided by OpenSSL (``any``, ``sslclient``, ``sslserver``, ``nssslserver``, ``smimesign``, ``smimeencrypt``) and RAUC (``codesign``). See ``-purpose`` and ``VERIFY OPERATION`` in the OpenSSL verify_ manual page and the :ref:`sec-key-usage` section for more information. .. _verify: https://www.openssl.org/docs/man1.1.1/man1/verify.html .. _streaming-config-section: ``[streaming]`` Section ~~~~~~~~~~~~~~~~~~~~~~~ The ``streaming`` section contains streaming-related settings. For more information about using the streaming support of RAUC, refer to :ref:`http-streaming`. ``sandbox-user`` (optional) This option can be used to set the user name which is used to run the streaming helper process. By default, the ``nobody`` user is used. At compile time, the default can be defined using the ``-Dstreaming_user=USERNAME`` meson setup option. ``tls-cert`` (optional) This option can be used to set the path or PKCS#11 URL for the TLS/HTTPS client certificate. ``tls-key`` (optional) This option can be used to set the path or PKCS#11 URL for the TLS/HTTPS client private key. ``tls-ca`` (optional) This option can be used to set the path of the CA certificate which should be used instead of the system wide store of trusted TLS/HTTPS certificates. .. _send-headers: ``send-headers`` (optional) This option takes a ``;``-separated list of information to send as HTTP header fields to the server with the first request. Supported values are: * ``boot-id``: Enables sending the *boot_id* as ``RAUC-Boot-ID`` header field. * ``machine-id``: Enables sending the *machine-id* as ``RAUC-Machine-ID`` header field. .. note:: The machine ID should be considered "confidential" and thus not be used over unauthenticated connections or with untrusted servers! * ``system-version``: Enables sending the *system version* as ``RAUC-System-Version`` header field. * ``serial``: Enables sending the *system serial* as ``RAUC-Serial`` header field. * ``variant``: Enables sending the *variant* as ``RAUC-Variant`` header field. * ``transaction-id``: Enables sending the *transaction UUID* as ``RAUC-Transaction-ID`` header field. * ``uptime``: Enables sending the system's current uptime as ``RAUC-Uptime`` header field. These headers are sent on the initial HTTP request when streaming a bundle, e.g. when using ``rauc install`` or ``rauc info`` (or their corresponding D-Bus calls). They are *not* sent for the subsequent requests which fetch the actual bundle data. .. note:: Currently, when using ``rauc info`` without the service or without an explicit config file, most headers are not sent, because the ``system-info`` handler is not used and the status information is not loaded. ``[encryption]`` Section ~~~~~~~~~~~~~~~~~~~~~~~~ The ``encryption`` section contains information required to decrypt a 'crypt' bundle. For more information about encrypted RAUC bundle bundles, refer to :ref:`sec-encryption`. ``key`` (required to use encryption) Path or PKCS#11 URL for the private key used to decrypt bundles. ``cert`` (optional) Path or PKCS#11 URL for the certificate matching the encryption key. This is optional but allows to speed up key lookup and thus is especially useful for larger number of recipients. ``[casync]`` Section ~~~~~~~~~~~~~~~~~~~~ The ``casync`` section contains casync-related settings. For more information about using the casync support of RAUC, refer to :ref:`casync-support`. ``install-args`` (optional) Allows to specify additional arguments that will be passed to casync when installing an update. For example it can be used to include additional seeds or stores. ``storepath`` (optional) Allows to set the path to use as chunk store path for casync to a fixed one. This is useful if your chunk store is on a dedicated server and will be the same pool for each update you perform. By default, the chunk store path is derived from the location of the RAUC bundle you install. ``tmppath`` (optional) Allows to set the path to use as temporary directory for casync. The temporary directory used by casync can be specified using the TMPDIR environment variable. It falls back to /var/tmp if unset. If ``tmppath`` is set then RAUC runs casync with TMPDIR sets to that path. By default, the temporary directory is left unset by RAUC and casync uses its internal default value ``/var/tmp``. ``use-desync=`` (optional) If this boolean value is set to ``true``, RAUC will use desync instead of casync. Desync support is still experimental, use with caution. ``[autoinstall]`` Section ~~~~~~~~~~~~~~~~~~~~~~~~~ The auto-install feature allows to configure a path that will be checked upon RAUC service startup. If there is a bundle placed under this specific path, this bundle will be installed automatically without any further interaction. This feature is useful for automatically updating the slot RAUC currently runs from, like for asymmetric redundancy setups where the update is always performed from a dedicated (recovery) slot. ``path`` (optional) The full path of the bundle file to check for. If file at ``path`` exists, auto-install will be triggered. .. _sec_ref_handlers: ``[handlers]`` Section ~~~~~~~~~~~~~~~~~~~~~~ Handlers allow to customize RAUC by placing scripts in the system that RAUC can call for different purposes. All parameters expect pathnames to the script to be executed. Pathnames are either absolute or relative to the system.conf file location. RAUC passes a set of environment variables to handler scripts. See details about using handlers in `Custom Handlers (Interface)`_. ``system-info`` (optional) This handler will be called when RAUC starts up, right after loading the system configuration file. It is used for obtaining further information about the individual system RAUC runs on. The handler script must print the information to standard output in form of key value pairs. A valid generic key must start with ``RAUC_`` as prefix to be added to the system information; e.g. ``RAUC_KEY=value``. Some additional special keys that are supported, are: :``RAUC_SYSTEM_SERIAL``: Serial number of the individual board :``RAUC_SYSTEM_VARIANT``: Sets the RAUC system variant :``RAUC_SYSTEM_VERSION``: Sets the system version (depending on your versioning strategy, this could match the version of a previously installed bundle or be completely independent) System information is made available to other handlers via environment variables that have the exact same name and value. The ``system-info`` handler also allows to define custom information that is forwarded to the server upon RAUC's first streaming request. In order to define forwarded info, this must be returned as a key prefixed. with ``RAUC_HTTP_``. The generated header field will be name of the key (with out the prefix) where an ``RAUC-`` is prepended and all underscores are converted to hyphens. E.g. ``RAUC_HTTP_MY_CUSTOM_INFO=dummyvalue`` will emit a header ``RAUC-MY-CUSTOM-INFO: dummyvalue``. ``pre-install`` (optional) This handler will be called right before RAUC starts with the installation. This is after RAUC has verified and mounted the bundle, thus you can access bundle content. ``post-install`` (optional) This handler will be called after a successful installation. The bundle is still mounted at this moment, thus you could access data in it if required. ``bootloader-custom-backend`` (required for ``bootloader=custom``) This handler will be called to trigger the following actions: * get the primary slot * set the primary slot * get the boot state * set the boot state if a custom bootloader backend is used. See :ref:`sec-custom-bootloader-backend` for more details. .. _slot.slot-class.idx-section: ``[slot..]`` Sections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each slot is identified by a section starting with ``slot.`` followed by the slot class name, and a slot number. The ```` name is used in the *update manifest* to target the correct set of slots. It must not contain any ``.`` (dots) as these are used as hierarchical separator. ``device=`` (required) The slot's device path. ``type=`` (optional, recommended) The type describing the slot. Currently supported ```` values are ``raw``, ``nand``, ``nor``, ``ubivol``, ``ubifs``, ``ext4``, ``vfat``, ``jffs2`` for normal slots and ``boot-emmc``, ``boot-mbr-switch``, ``boot-gpt-switch``, and ``boot-raw-fallback`` for atomically updatable bootloader slots. See table :ref:`sec-slot-type` for a more detailed list of these different types. Defaults to ``raw`` if none given. ``extra-mkfs-opts=`` (optional) Allows to specify custom filesystem creation options that will be passed to the slot's ``mkfs.`` call (ext4, vfat, and ubifs only). ``bootname=`` (optional) Registers the slot for being handled by the :ref:`bootselection interface ` with the ```` specified. The value must be unique across all slots. Only slots without a ``parent`` entry can have a ``bootname``. The actual meaning of the name provided depends on the bootloader implementation used. ``parent=`` (optional) The ``parent`` entry is used to bind additional slots to a bootable root file system ````. Indirect parent references are discouraged, but supported for now. This is used together with the ``bootname`` to identify the set of currently active slots, so that the inactive one can be selected as the update target. The parent slot is referenced using the form ``.``. ``allow-mounted=`` (optional) Setting this entry ``true`` tells RAUC that the slot may be updated even if it is already mounted. Such a slot can be updated only by a custom install hook. ``readonly=`` (optional) Marks the slot as existing but not updatable. May be used for sanity checking or informative purpose. A ``readonly`` slot cannot be a target slot. .. _install-same: ``install-same=`` (optional) If set to ``false``, this will tell RAUC to skip writing slots that already have the same content as the one that should be installed. Having the 'same' content means that the hash value stored for the target slot and the hash value of the update image are equal. The default value is ``true`` here, meaning that no optimization will be done as this can be unexpected if RAUC is not the only one that potentially alters a slot's content. This replaces the deprecated entries ``ignore-checksum`` and ``force-install-same``. ``resize=`` (optional) If set to ``true`` this will tell RAUC to resize the filesystem after having written the image to this slot. This only has an effect when writing an ext4 file system to an ext4 slot, i.e. if the slot has``type=ext4`` set. ``extra-mount-opts=`` (optional) Allows to specify custom mount options that will be passed to the slot's ``mount`` call as ``-o`` argument value. ``region-start=`` (mandatory for specific types, invalid for others) Defines the start of the disk region used for atomic bootloader updates. Valid for slot types ``boot-mbr-switch``, ``boot-gpt-switch``, ``boot-raw-fallback`` only! Accepts integer values in bytes. Supports optional size suffixes: ``K``, ``M``, ``G``, ``T`` (powers of 1024). See :ref:`sec-mbr-partition` and the following for more details. ``region-size`` (mandatory for specific types, invalid for others) Defines the size of the disk region used for atomic bootloader updates. Valid for slot types ``boot-mbr-switch``, ``boot-gpt-switch``, ``boot-raw-fallback`` only! Accepts integer values in bytes. Supports optional size suffixes: ``K``, ``M``, ``G``, ``T`` (powers of 1024). See :ref:`sec-mbr-partition` and the following for more details. ``size-limit=`` (type-specific, optional) .. warning:: The ``size-limit`` option is intended only for backwards compatibility and should not be used in new designs! Valid for slot type ``boot-emmc`` only. Allows defining the maximum size of an eMMC boot partition to write. This is only useful if the eMMC boot partitions contain e.g. manufacturer at the end and, for certain reason, this cannot be migrated to a more appropriate location anymore. Accepts integer values in bytes. Supports optional size suffixes: ``K``, ``M``, ``G``, ``T`` (powers of 1024). .. _sec_ref_artifacts: ``[artifacts.]`` Sections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each :ref:`artifact repository ` is identified by a section starting with ``artifacts.`` followed by the repository name. The ```` name is used in the *update manifest* to target the correct repository. It must not contain any ``.`` (dots) as these are used as hierarchical separator. The name must be different from any slot class names. ``path=`` (required) Full path to a directory (on a shared partition) to be used to store the artifacts. The underlying shared partition must be mounted before starting RAUC. ``type=`` (required) The type of this repository. Currently supported values are ``files`` and ``trees``. ``files`` each artifact is a single file ``trees`` each artifact is a directory tree containing files ``composefs`` each artifact is a directory containing a composefs metadata image See :ref:`sec-repository-types` for more details. ``description=`` (optional) A description of this repository. ``parent-class=`` (optional) Reference to a slot class, if the set of installed artifacts should be managed separately for each instance of that class, instead of globally. If so, it should refer to the class of the rootfs slots. .. warning:: Support for parent classes is not fully implemented yet. Do not use. .. _ref-logger-sections: ``[log.]`` Sections ~~~~~~~~~~~~~~~~~~~~~~~~~~~ With a logger section, a *RAUC event logger* can be configured. The ```` suffix determines the internal name of the logger and must be unique per ``system.conf``. For an overview over the event logging framework in RAUC and its purpose, have a look at :ref:`sec-advanced-event-log`. ``filename`` (required) The log file name used for logging. If no absolute path is given, the location is assumed to be relative to the ``data-directory``. Using a relative file name without ``data-directory`` set will cause a configuration error. ``events`` (optional) Semicolon-separated list of events to log. Currently supported event types are: * ``install`` - Logs start and end of installation * ``boot`` - Logs boot information * ``mark`` - Logs slot marking information * ``all`` - Log all events (default, cannot be combined with other events) ``format`` (optional) The output format used for the logger. Supported values are * ``readable``: readable multi-line output (default) * ``short``: Single-line readable output * ``json``: single-line JSON output * ``json-pretty``: formatted JSON output ``max-size=`` (optional) Allows to configure a basic log rotation. When given, the logger's log file will be rotated before reaching the size configured with ``max-size`` and renamed to ``.1``. Existing rotation file names will be incremented by one. The oldest file is removed. To configure a maximum number of files to keep, see ``max-files``. Accepts integer values in bytes. Supports optional size suffixes: ``K``, ``M``, ``G``, ``T`` (powers of 1024). ``max-files`` (optional) Configures the maximum number of files to keep per logger. E.g. if set to ``3``, only ````, ``.1`` and ``.2`` will be kept during rotation. Defaults to 10 if unset. .. _sec_ref_manifest: Manifest -------- The manifest file located in a RAUC bundle describes the images packed in the bundle and their corresponding target slot class. A valid RAUC manifest file must be named ``manifest.raucm``. .. code-block:: cfg [update] compatible=FooCorp Super BarBazzer version=2016.08-1 [bundle] format=verity verity-hash=3fcb193cb4fd475aa174efa1f1e979b2d649bf7f8224cc97f4413b5ee141a4e9 verity-salt=4b7b8657d03759d387f24fb7bb46891771e1b370fff38c70488e6381d6a10e49 verity-size=24576 [image.rootfs] filename=rootfs.ext4 size=419430400 sha256=b14c1457dc10469418b4154fef29a90e1ffb4dddd308bf0f2456d436963ef5b3 [image.appfs] filename=appfs.ext4 size=219430400 sha256=ecf4c031d01cb9bfa9aa5ecfce93efcf9149544bdbf91178d2c2d9d1d24076ca [image.add-ons/webserver] filename=webserver.tar size=6573863 sha256=f23204174c70ff03a9efcd6c2dfd6d2b8ebdd8bb66936043341e728438a1f0ea .. _sec-manifest-update: ``[update]`` Section ~~~~~~~~~~~~~~~~~~~~ This section contains some high-level information about the bundle. ``compatible`` (required) A user-defined compatible string that must match the RAUC compatible string of the system the bundle should be installed on. ``version`` (optional) A free version field that can be used to provide and track version information. No checks will be performed on this version by RAUC itself, although a handler can use this information to reject updates. ``description`` (optional) A free-form description field that can be used to provide human-readable bundle information. ``build`` (optional) A build id that would typically hold the build date or some build information provided by the bundle creation environment. This can help to determine the date and origin of the built bundle. ``min-rauc-version`` (optional) An optional version limit which causes the manifest to be rejected if the running version is older/lower than the requested minimum. This was introduced with version 1.14 and will cause an error on older versions. ``[bundle]`` Section ~~~~~~~~~~~~~~~~~~~~ The bundle section contains information required to process the bundle. ``format`` (optional, recommended) Either ``plain`` (default), ``verity`` or ``crypt``. This selects the :ref:`format` used when wrapping the payload during bundle creation. .. _verity-metadata: ``verity-hash`` (generated) The dm-verity root hash over the bundle payload in hexadecimal. RAUC determines this value automatically, so it should be left unspecified when preparing a manifest for bundle creation. ``verity-salt`` (generated) The dm-verity salt over the bundle payload in hexadecimal. RAUC determines this value automatically, so it should be left unspecified when preparing a manifest for bundle creation. ``verity-size`` (generated) The size of the dm-verity hash tree. RAUC determines this value automatically, so it should be left unspecified when preparing a manifest for bundle creation. ``crypt-key`` (generated) The encryption key of the dm-crypt. RAUC generates the key automatically when creating a ``crypt`` bundle. ``[hooks]`` Section ~~~~~~~~~~~~~~~~~~~ The hooks section allows to provide a user-defined executable for :ref:`executing hooks ` during the installation. ``filename`` (optional) Hook script path name, relative to the bundle content. ``hooks`` (optional) List of hooks enabled for this bundle. See :ref:`sec-install-hooks` for more details. Valid items are: ``install-check`` .. _sec-manifest-handler: ``[handler]`` Section ~~~~~~~~~~~~~~~~~~~~~ The ``handler`` section refers to the `full custom handler `_ that allows to fully replace the default RAUC update process. .. note:: This is not to be confused with the ``[handlers]`` section from the system.conf which defines e.g. pre- and post-install handlers! When the full custom handler is enabled in a bundle, it will be invoked during the bundle installation * **after** bundle signature verification * **after** slot state and target slots determination logic * **after** the ``pre-install`` system handler * **before** the ``post-install`` system handler Also, the bundle will be mounted at this point and thus all its content is available to the full custom handler. Further system information is passed by RAUC via environment variables. No built-in slot update will run and no hook will be executed. ``filename`` (optional) Full custom handler path, relative to the bundle content. Having this set will activate the full custom handler and use the given script/binary instead of the default handling. ``args`` (optional) Arguments to pass to the full custom handler, such as ``args=--setup --verbose`` .. note:: Until RAUC v1.9, these arguments were also implicitly passed to handlers defined in the system.conf. This behavior was fixed/removed in v1.10. If someone uses this undocumented behavior and still requires this, please file an `issue `_. If additional arguments are provided via ``--handler-args`` command line argument, these will be appended to the ones defined in the manifest. .. _image-section: ``[image.*]`` Sections ~~~~~~~~~~~~~~~~~~~~~~ The image section names can take different forms to support slots, artifacts and variants. ``[image.]`` This form is used to specify images that should be installed to (inactive) slots of the given class. ``[image..]`` This form is used to specify an image that will be used instead of the default one above if the target system's variant matches ````. Refer to chapter :ref:`sec-variants` for more information. ``[image./]`` This form is used to specify an image that should be installed into an artifact repository. ``[image./.]`` This form is not yet supported, but will be used to handle artifacts with variants. The following fields are supported for image sections: .. _image-filename: ``filename`` (required) Name of the image file (relative to bundle content). .. note:: While RAUC can automatically detect the image type from filename extensions for backward compatibility, it is recommended to explicitly specify the ``type`` field for new projects or in cases where all target systems are running a new enough version. .. note:: This field is not required and not supported for images with ``type=emptyfs``, which creates an empty filesystems without source data. .. important:: RAUC uses the file name extension and the slot type to decide how to install the image file content to the slot. Make sure to only use :ref:`supported file name extensions `! .. _image-type: ``type`` (optional, recommended) Specifies the type of the image content. This determines how RAUC will process the image during installation. If not specified, the image type is automatically detected based on the filename extension. This was added in RAUC v1.15. Detailed information about the supported types is described in the :ref:`Supported Image Types ` section. ``sha256`` (generated) sha256 of image file. RAUC determines this value automatically when creating a bundle, thus it is not required to set this by hand. ``size`` (generated) size of image file. RAUC determines this value automatically when creating a bundle, thus it is not required to set this by hand. ``hooks`` (optional) List of per-slot hooks enabled for this image. See :ref:`sec-slot-hooks` for more details. Valid items are: ``pre-install``, ``install``, ``post-install`` Hooks are not yet supported for artifacts. ``adaptive`` (optional) List of ``;``-separated per-slot adaptive update method names. These methods will add extra information to the bundle, allowing RAUC to access only the parts of an image which are not yet available locally. Together with streaming, this reduces the amount of downloaded data. As the full image is still available in the bundle, older RAUC versions can ignore unsupported adaptive methods. Currently implemented adaptive methods: ``block-hash-index`` Build an index which stores the SHA256 hash for each 4kiB block of the input image, allowing reuse of unchanged blocks. For information on this method, see :ref:`sec-adaptive-block-hash-index`. Adaptive update methods are currently not supported for artifacts. ``convert`` (optional) List of ``;``-separated conversion methods to use during bundle creation. The original image is not included in the bundle, except when ``keep`` is specified. Currently implemented conversion methods: ``tar-extract`` Extract a tar into a directory tree. This method is not very useful on its own, but can be used to test creation and installation of bundles containing many files. The underlying implementation will also be used for future methods. ``composefs`` Create a composefs metadata image and object store from a tar archive. File contents from all composefs artifacts are placed in a shared object store in the bundle (`/.rauc-cfs-store`). This way, duplicated files are stored in the bundle only once. During bundle creation, ``fakeroot`` needs to be available when not running under ``pseudo``. ``keep`` Keep the original image after running the conversion methods. Conversion methods are currently not supported for slot images. ``converted`` (generated) List of ``;``-separated output file/directory names from conversion methods, as generated by RAUC during bundle creation. Each element in the ``convert`` list has a corresponding entry in this list. .. _rollout-section: ``[rollout]`` Section ~~~~~~~~~~~~~~~~~~~~~ The ``rollout`` section is intended to provide a forwards-compatible way to add rollout scheduling configuration (e.g. phases or time windows) to the manifest. Currently, the contents are not interpreted by RAUC in any way. .. _meta.label-section: ``[meta.