<commit_before>Reference
=========

.. _sec_ref_slot_config:

System Configuration File
-------------------------

A configuration file located in ``/etc/rauc/system.conf`` describes the
number and type of available slots.
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.

Example configuration:

.. code-block:: cfg

  [system]
  compatible=FooCorp Super BarBazzer
  bootloader=barebox

  [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


**[system] section**

``compatible``
  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.

``bootloader``
  The bootloader implementation RAUC should use for its slot switching
  mechanism. Currently supported values (and bootloaders) are ``barebox``,
  ``grub``, ``u-boot``.

**[keyring] section**

The ``keyring`` section refers to the trusted keyring used for signature
verification.

``path``
  Path to the keyring file in PEM format. Either absolute or relative to the
  system.conf file.


**[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 :ref:`Custom Handlers (Interface)`.

``system-info``
  This script will be called ...

``pre-install``
  This script will be called ...

``post-install``
  This script will be called ...


**[slot.<slot-class>.<idx>] section**

Each slot is identified by a section starting with ``slot.`` followed by
the slot class name, and a slot number.
The *slot class* name is used in the *update manifest* to target the correct
set of slots.

``device``
  The slot's device path.

``type``
  The type describing the slot. Currently supported values are ``raw``,
  ``nand``, ``ubivol``, ``ubifs``, ``ext4``. See table :ref:`todo` for a more
  detailed list about these different types.

``bootname``
  For bootable slots, the name the bootloader uses to identify it. The real
  meaning of this depends on the bootloader implementation used.

``parent``
  The ``parent`` entry is used to bind additional slots to a bootable root
  file system slot.
  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 ``<slot-class>.<idx>``.

``readonly``
  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.


Manifest
--------

A valid manifest file must have the file extension ``.raucm``.

.. code-block:: cfg

  [update]
  compatible=FooCorp Super BarBazzer
  version=2016.08-1
  
  [image.rootfs]
  filename=rootfs.ext4
  size=419430400
  sha256=b14c1457dc10469418b4154fef29a90e1ffb4dddd308bf0f2456d436963ef5b3
  
  [image.appfs]
  filename=appfs.ext4
  size=219430400
  sha256=ecf4c031d01cb9bfa9aa5ecfce93efcf9149544bdbf91178d2c2d9d1d24076ca


**[update] section**

``compatible``
  A user-defined compatible string that must match the compatible string of the
  system the bundle should be installed on.

``version``
  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``
  A free-form description field that can be used to provide human-readable
  bundle information.

``build``
  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.


**[hooks] section**

``filename``
  Hook script path name, relative to the bundle content.

``hooks``
  List of hooks enabled for this bundle.


**[image.<slot-class>] section**

``filename``
  Name of the image file (relative to bundle content).

``sha256``
  sha256 of image file. RAUC determines this value automatically when creating
  a bundle, thus it is not required to set this by hand.

``size``
  size of image file. RAUC determines this value automatically when creating a
  bundle, thus it is not required to set this by hand.

``hooks``
  List of per-slot hooks enabled for this image.


**[file.<slot-class>] section**

Slot Status File
----------------

A slot status file is generated by RAUC after having updated a slot. If the
slot is writeable for RAUC (because it contains a writable filesystem), it will
place a small file named ``slot.raucs`` in its root directory, containing the
sha256 of the installed image.
<commit_msg>doc: reference: do not mention manifest [file] section anymore<commit_after>Reference
=========

.. _sec_ref_slot_config:

System Configuration File
-------------------------

A configuration file located in ``/etc/rauc/system.conf`` describes the
number and type of available slots.
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.

Example configuration:

.. code-block:: cfg

  [system]
  compatible=FooCorp Super BarBazzer
  bootloader=barebox

  [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


**[system] section**

``compatible``
  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.

``bootloader``
  The bootloader implementation RAUC should use for its slot switching
  mechanism. Currently supported values (and bootloaders) are ``barebox``,
  ``grub``, ``u-boot``.

**[keyring] section**

The ``keyring`` section refers to the trusted keyring used for signature
verification.

``path``
  Path to the keyring file in PEM format. Either absolute or relative to the
  system.conf file.


**[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 :ref:`Custom Handlers (Interface)`.

``system-info``
  This script will be called ...

``pre-install``
  This script will be called ...

``post-install``
  This script will be called ...


**[slot.<slot-class>.<idx>] section**

Each slot is identified by a section starting with ``slot.`` followed by
the slot class name, and a slot number.
The *slot class* name is used in the *update manifest* to target the correct
set of slots.

``device``
  The slot's device path.

``type``
  The type describing the slot. Currently supported values are ``raw``,
  ``nand``, ``ubivol``, ``ubifs``, ``ext4``. See table :ref:`todo` for a more
  detailed list about these different types.

``bootname``
  For bootable slots, the name the bootloader uses to identify it. The real
  meaning of this depends on the bootloader implementation used.

``parent``
  The ``parent`` entry is used to bind additional slots to a bootable root
  file system slot.
  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 ``<slot-class>.<idx>``.

``readonly``
  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.


Manifest
--------

A valid manifest file must have the file extension ``.raucm``.

.. code-block:: cfg

  [update]
  compatible=FooCorp Super BarBazzer
  version=2016.08-1
  
  [image.rootfs]
  filename=rootfs.ext4
  size=419430400
  sha256=b14c1457dc10469418b4154fef29a90e1ffb4dddd308bf0f2456d436963ef5b3
  
  [image.appfs]
  filename=appfs.ext4
  size=219430400
  sha256=ecf4c031d01cb9bfa9aa5ecfce93efcf9149544bdbf91178d2c2d9d1d24076ca


**[update] section**

``compatible``
  A user-defined compatible string that must match the compatible string of the
  system the bundle should be installed on.

``version``
  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``
  A free-form description field that can be used to provide human-readable
  bundle information.

``build``
  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.


**[hooks] section**

``filename``
  Hook script path name, relative to the bundle content.

``hooks``
  List of hooks enabled for this bundle.


**[image.<slot-class>] section**

``filename``
  Name of the image file (relative to bundle content).

``sha256``
  sha256 of image file. RAUC determines this value automatically when creating
  a bundle, thus it is not required to set this by hand.

``size``
  size of image file. RAUC determines this value automatically when creating a
  bundle, thus it is not required to set this by hand.

``hooks``
  List of per-slot hooks enabled for this image.


Slot Status File
----------------

A slot status file is generated by RAUC after having updated a slot. If the
slot is writeable for RAUC (because it contains a writable filesystem), it will
place a small file named ``slot.raucs`` in its root directory, containing the
sha256 of the installed image.

{'fraction_non_alphanumeric': 0.08965125094768764, 'fraction_numerical': 0.0233131159969674, 'mean_word_length': 3.945173383317713, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1411671', 'n_tokens_mistral': 3184, 'n_tokens_neox': 2988, 'n_words': 1368}