<commit_before>Examples
========

This chapter aims to explain the basic concepts needed for rauc using a simple
but realistic scenario.

The system is a x86 system with 1GiB of disk space and 1GiB of RAM. GRUB_ was
selected as the bootloader and we want to have two symmetric installations.
Each installation consists of an ext4 root file system only (which contains the
matching kernel image).

We want to provide update bundles using a USB memory stick. We don't have a
hardware watchdog, so we need to explicitly tell GRUB_ whether a boot was
successful.

This scenario can be easily reproduced using a QEMU_ virtual machine.

.. _GRUB: https://www.gnu.org/software/grub/
.. _QEMU: http://wiki.qemu.org/

PKI Setup
---------

rauc uses an x.509 PKI (public key infrastructure) to sign and verify updates.
To create a simple key pair for testing, we can use ``openssl``::

  > openssl req -x509 -newkey rsa:4096 -nodes -keyout demo.key.pem -out demo.cert.pem -subj "/O=rauc Inc./CN=rauc-demo"

For actual usage, setting up a real PKI (with a CA separate from the signing
keys and a revocation infrastructure) is *strongly* recommended. OpenVPN's
easy-rsa_ is a good first step.

.. _easy-rsa: https://github.com/OpenVPN/easy-rsa

rauc Configuration
------------------

We need a rauc system configuration file to describe the slots which can be
updated::

  [system]
  compatible=rauc-demo-x86
  bootloader=grub
  mountprefix=/mnt/rauc

  [keyring]
  path=demo.cert.pem

  [slot.rootfs.0]
  device=/dev/sda2
  type=ext4
  bootname=A

  [slot.rootfs.1]
  device=/dev/sda3
  type=ext4
  bootname=B

In this case, we need to place the signing certificate into
``/etc/rauc/demo.cert.pem``, so that it is used by rauc for verification.

GRUB Configuration
------------------

GRUB itself is stored on ``/dev/sda1``, separate from the root file system. To
access GRUB's environment file, this partition should be mounted to ``/boot``
(which means that the environment file is found at ``/boot/grub/grubenv``).

GRUB does not provide the boot target selection logic as needed by rauc
out of the box. Instead we use a script to implement it::

  default=0
  timeout=3
  
  set ORDER="A B"
  set A_OK=0
  set B_OK=0
  set A_TRY=0
  set B_TRY=0
  load_env
  
  # select bootable slot
  for SLOT in $ORDER; do
      if [ "$SLOT" == "A" ]; then
          INDEX=0
          OK=$A_OK
          TRY=$A_TRY
          A_TRY=1<commit_msg>docs: examples: enable syntax highlighting<commit_after>Examples
========

This chapter aims to explain the basic concepts needed for rauc using a simple
but realistic scenario.

The system is a x86 system with 1GiB of disk space and 1GiB of RAM. GRUB_ was
selected as the bootloader and we want to have two symmetric installations.
Each installation consists of an ext4 root file system only (which contains the
matching kernel image).

We want to provide update bundles using a USB memory stick. We don't have a
hardware watchdog, so we need to explicitly tell GRUB_ whether a boot was
successful.

This scenario can be easily reproduced using a QEMU_ virtual machine.

.. _GRUB: https://www.gnu.org/software/grub/
.. _QEMU: http://wiki.qemu.org/

PKI Setup
---------

rauc uses an x.509 PKI (public key infrastructure) to sign and verify updates.
To create a simple key pair for testing, we can use ``openssl``::

  > openssl req -x509 -newkey rsa:4096 -nodes -keyout demo.key.pem -out demo.cert.pem -subj "/O=rauc Inc./CN=rauc-demo"

For actual usage, setting up a real PKI (with a CA separate from the signing
keys and a revocation infrastructure) is *strongly* recommended. OpenVPN's
easy-rsa_ is a good first step.

.. _easy-rsa: https://github.com/OpenVPN/easy-rsa

rauc Configuration
------------------

We need a rauc system configuration file to describe the slots which can be
updated

.. code-block:: cfg

  [system]
  compatible=rauc-demo-x86
  bootloader=grub
  mountprefix=/mnt/rauc

  [keyring]
  path=demo.cert.pem

  [slot.rootfs.0]
  device=/dev/sda2
  type=ext4
  bootname=A

  [slot.rootfs.1]
  device=/dev/sda3
  type=ext4
  bootname=B

In this case, we need to place the signing certificate into
``/etc/rauc/demo.cert.pem``, so that it is used by rauc for verification.

GRUB Configuration
------------------

GRUB itself is stored on ``/dev/sda1``, separate from the root file system. To
access GRUB's environment file, this partition should be mounted to ``/boot``
(which means that the environment file is found at ``/boot/grub/grubenv``).

GRUB does not provide the boot target selection logic as needed by rauc
out of the box. Instead we use a script to implement it

.. code-block:: sh

  default=0
  timeout=3
  
  set ORDER="A B"
  set A_OK=0
  set B_OK=0
  set A_TRY=0
  set B_TRY=0
  load_env
  
  # select bootable slot
  for SLOT in $ORDER; do
      if [ "$SLOT" == "A" ]; then
          INDEX=0
          OK=$A_OK
          TRY=$A_TRY
          A_TRY=1
{'fraction_non_alphanumeric': 0.0993485342019544, 'fraction_numerical': 0.013029315960912053, 'mean_word_length': 3.160033869602032, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, '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': '574566', 'n_tokens_mistral': 1622, 'n_tokens_neox': 1546, 'n_words': 651}