1. RAUC Overview

RAUC (Robust Auto-Update Controller) is an open-source framework for secure and reliable software updates in embedded Linux systems. Since CCLinux 4, RAUC handles bootloader, operating system, and application updates on CCpilot displays. Updates can be installed from a USB drive or over the air (OTA).

RAUC updates are:

  • Atomic: An update is either fully installed or not installed at all. The system is never left in a partially updated state.

  • Redundant: The display keeps two copies, A and B, of the operating system and the application. An update is written to the inactive copy while the system keeps running. If the update fails, the active copy is untouched and the update can be retried. If the updated system does not boot, the display returns to the previous copy.

  • Signed: Every update bundle is signed, and the display verifies the signature before installing it.

CrossControl delivers update bundles containing:

  • Bootloader

  • Root filesystem

  • Application filesystem

  • OS update (bootloader + root filesystem)

  • System update (OS update + application update)

A display can also be flashed completely using uuu, as described in CC Linux – System Update Using uuu.

This guide covers the most common use cases. For more details, see the RAUC documentation.

2. Partitions and file systems

CCLinux 4 and newer use an A/B partition layout for both the root filesystem (rootfs), which contains the operating system, and the application filesystem (appfs). Partition sizes depend on the flash size and hardware, see section “Partition Sizes” in CC Linux – Programmer’s Guide.

CC Linux 4 and newer
+-------------------+
|      Boot A       |
+-------------------+
|      Boot B       |
+-------------------+
|       OS A        |
|      (1.3 GB)     |
+-------------------+
|       OS B        |
|      (1.3 GB)     |
+-------------------+
|      App A        |
|      (1.3 GB)     |
+-------------------+
|      App B        |
|      (1.3 GB)     |
+-------------------+
|       Data        |
|      (2.7+ GB)    |
+-------------------+

Only one set is active at a time, for example rootfs A together with appfs A. Each appfs belongs to one rootfs, so switching to the other appfs also switches the rootfs. See 3.2. Rootfs and appfs in one bundle.

2.1. Read-only rootfs and appfs

The rootfs and appfs partitions are read-only. They can only be modified with RAUC updates, which is required for atomic updates.

Most configuration files in Linux are located in /etc. To allow changing settings such as the IP address, firewall rules, and passwords, an overlay filesystem (OverlayFS) is mounted on top of /etc:

  • The lower layer is the original /etc from the rootfs.

  • The upper layer is /data/cc-etc, which stores all changes made to /etc.

A factory reset with ccsettingsconsole removes the overlay and restores the original configuration. RAUC hooks can also modify /etc, for example to set a static IP address or to replace the CrossControl demo certificate. See 3.1. Hooks.

2.2. The /data partition

/data is the only location where applications and the default user ccs can write. It is created automatically on the first boot and uses the remaining free space on the flash. It contains:

  • The home directory of the ccs user.

  • Application data, such as databases, log files, and configuration files.

  • The /etc overlay, in /data/cc-etc.

  • Docker containers, images, and configuration files, if Docker is enabled. Docker can use a lot of flash space, so make sure that /data has enough free space.

  • /data/rauc, where RAUC stores its status, installation logs, the certificates used to verify bundles, and the block hash indexes used for adaptive updates. There is no need to modify anything in this folder manually.

Parts of /data are used by the operating system. Handle them with care to avoid corrupting the system.

Note

Changes from CCLinux 3: CCLinux 3 used one OS partition and a rescue partition. The OS partition was read-only with a writable overlay, so any system file could be modified, and applications were stored in /opt. Since CCLinux 4, system files can only be modified with RAUC updates or through the /etc overlay, and applications are installed in the appfs.

CC Linux 3
+-------------------+
|       Boot        |
+-------------------+
|      Rescue       |
|     (160 MB)      |
+-------------------+
|       Main        |
|      (1 GB)       |
+-------------------+
|       Data        |
|      (6 GB)       |
+-------------------+

3. Update bundles

A RAUC bundle (.raucb) contains:

  • The images to install, for example the rootfs and appfs .ext4 images.

  • A manifest (manifest.raucm) that lists the images and contains options and metadata.

  • Optional hook scripts, and other files used by them.

  • A signature, see 4. Signature.

The content is packed into a SquashFS image. This gives good compression and allows the display to mount the bundle without unpacking it first, so no intermediate storage is needed.

Bundles can have one of three formats:

Format

Description

CCLinux support

plain

The original format. No built-in integrity protection of the payload, so it is vulnerable to tampering and corruption.

Not supported

verity

Protects the integrity of the payload using the Linux dm-verity module. The payload is verified before it is installed.

Supported

crypt

Adds encryption to the verity format. The payload is encrypted with a symmetric key, which is stored in the manifest. The manifest itself is encrypted asymmetrically. Provides confidentiality in addition to integrity.

Supported in CCLinux 4 and later. Decryption with a key stored via PKCS#11 is supported in CCLinux 5.1 and later

3.1. Hooks

Hooks are scripts that RAUC runs at defined points during the installation, for example before or after the images are installed. Hooks are defined in the manifest, and all hooks are handled by one executable that must be included in the bundle.

Hooks can be used, for example, to:

  • Perform additional migration steps.

  • Check which bundle version is already installed.

  • Modify /etc, see 2.1. Read-only rootfs and appfs.

  • Install images that RAUC cannot handle natively.

The most common hooks are the pre-install and post-install hooks. See the RAUC documentation for a complete guide.

3.2. Rootfs and appfs in one bundle

In /etc/rauc/system.conf, each appfs slot has a rootfs slot as its parent:

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

[slot.appfs.0]
device=/dev/mmcblk1p4
type=ext4
parent=rootfs.0
...

RAUC always writes to the inactive slots. A bundle that contains only an appfs image is written to the inactive appfs, which is used only after the display switches to the matching inactive rootfs. RAUC cannot check that the appfs in the bundle is compatible with the rootfs in that slot.

Therefore, always include both the appfs image and the rootfs image that your application has been tested with in the same bundle. This is also the approach recommended by RAUC.

Slot skipping

When a bundle is created, RAUC stores the size and SHA256 hash of each image in the manifest. During installation, RAUC compares the hash with the hash of the image it last installed in the target slot. If they are identical, the slot is not written again. This is enabled by install-same=false in system.conf.

4. Signature

Every bundle is signed when it is created, using a private signing key and the matching signing certificate. RAUC uses the OpenSSL library for this. The signature and the signing certificate are stored in the bundle.

Before installing a bundle, RAUC on the display verifies the signature against the CA certificates in /data/rauc/certs/. The bundle is installed only if the signature is valid and the signing certificate is issued by one of these CA certificates. This ensures:

  • Integrity: The bundle has not been modified or corrupted after it was signed.

  • Authenticity: The bundle was created by someone who holds a signing key trusted by the display.

If the verification fails, RAUC rejects the bundle.

A factory-configured display trusts the CrossControl demo CA, see 5.3. CrossControl demo keys. Before production, replace it with your own CA, as described in 8. Switch to customer keys.

5. Development setup

Creating and inspecting bundles is done on a Linux development computer with the CCLinux SDK for the display, which contains the rauc tool, and the CrossControl example repository.

5.1. Set up the SDK

Install the CCLinux SDK for the selected display, as described in section “Software Development Kit” in CC Linux – Programmer’s Guide.

Source the SDK environment setup script in every new terminal session before running any rauc command. The script name ends with the target architecture and differs between platforms:

$ source <sdk-install-dir>/environment-setup-<XXXX>

For example, for a V1x00 SDK installed in /opt/v1x00:

$ source /opt/v1x00/environment-setup-cortexa35-poky-linux

The script adds the SDK tools, including rauc, to $PATH.

In this guide, commands that must be run in a terminal where the SDK environment has been set up are shown with the [SDK]$ prompt.

5.2. Set up the example repository

The CrossControl example repository RAUC Package Generation Tools for CrossControl Displays contains the scripts, configuration files, and demo keys used in this guide.

  1. Install Git. mkfs.ext4 is also required, and is included in most Linux distributions. On Ubuntu or Debian:

    $ sudo apt update
    $ sudo apt install git e2fsprogs
    
  2. Clone the repository:

    $ git clone https://github.com/crosscontrol-open-source/rauc-simple-pki-example.git
    $ cd rauc-simple-pki-example
    
  3. Set the SDK installation directory in conf.sh. The example scripts use the rauc tool from this SDK:

    SDK_INSTALL_PATH=/opt/<cclinux-sdk-directory>
    

All commands in this guide that run on the development computer are run from the root of the repository. The rauc commands use the following options:

  • --conf=rauc-host.conf uses the repository’s RAUC configuration for the development computer. It contains the certificate check settings required to verify CrossControl bundles.

  • --keyring=cc-demo-keys/ca.cert.pem selects the CA certificate used to verify bundle signatures.

Messages about a missing data directory or system status can be ignored.

Important

These options are only used on the development computer. On the display, rauc uses /etc/rauc/system.conf automatically, for example rauc install <bundle-name>.raucb.

5.3. CrossControl demo keys

A factory-configured display accepts bundles signed with the CrossControl demo key. The demo key can be used to create bundles during development. The following files are needed:

File

Location

Demo CA certificate (ca.cert.pem)

cc-demo-keys/ca.cert.pem in the example repository

Demo signing key (development-1.key.pem)

Appendix A. CrossControl demo key and certificate

Demo signing certificate (development-1.cert.pem)

Appendix A. CrossControl demo key and certificate

Warning

The demo key is publicly available. Anyone can use it to create bundles that a factory-configured display installs. Replace it with your own key before production, as described in 8. Switch to customer keys.

Note

CrossControl demo keys have been updated in CCLinux 4.2. If updating development devices using demo keys from 4.0 or 4.1, use uuu instead to update the device.

6. Update bundle creation

CrossControl provides the update bundles for the bootloader and the operating system. They are built for each CCLinux release. To install your own application, create a bundle that contains your appfs image together with the rootfs image it has been tested with, as described in 3.2. Rootfs and appfs in one bundle.

The example in this chapter creates a bundle for a CCpilot V700 containing a Qt application called myApplication, signed with the demo key. It uses the example repository from 5.2. Set up the example repository, which is also used for customer keys in 8.1. Generate customer signing keys and for encryption in 9. Add encryption to bundles. The following parts of the repository are used:

rauc-simple-pki-example/
+-- conf.sh                      Build settings, for example the SDK path
+-- appfs/                       Files to install in /appfs on the display
+-- cclinux-rauc-bundles/        CrossControl OS update bundle
+-- cc-demo-keys/                Demo signing key and certificates
+-- release-full-1.0.0/          Bundle content: manifest and images only
|   +-- manifest.raucm
+-- build-all-demo.sh            Builds a bundle signed with the demo key
+-- build-all.sh                 Builds a bundle signed with the customer key
+-- install-package-1.0.0.raucb  Created bundle

6.1. Prepare the bundle folder

Every file in release-full-1.0.0/ is included in the bundle. Remove the example files, so that the folder only contains manifest.raucm:

$ rm release-full-1.0.0/padding.txt release-full-1.0.0/test_handler.sh

6.2. Add the application to the appfs

The appfs is an ext4 filesystem that is written in one atomic operation. The build script creates the .ext4 image from the content of the appfs/ folder. Everything in the folder is installed in /appfs on the display.

  1. Remove the example README.txt, so that it is not installed on the display, and copy your application to appfs/:

    $ rm appfs/README.txt
    $ cp <path-to>/myApplication appfs/
    
  2. To start the application automatically at boot, add its systemd service file and enable it with a symbolic link. Use a relative link, so that it resolves correctly on the display:

    $ mkdir -p appfs/lib/systemd/system/multi-user.target.wants
    $ cp <path-to>/myApplication.service appfs/lib/systemd/system/
    $ ln -s ../myApplication.service \
      appfs/lib/systemd/system/multi-user.target.wants/myApplication.service
    

    Note

    In addition to the normal locations in the rootfs, systemd on CCLinux also loads service files from /appfs/lib/systemd/system. The link enables the service on every display where the appfs image is installed.

    The service stays enabled as long as the link is in the appfs. systemctl disable on the display cannot remove the link, because the appfs is read-only. To disable the service, remove the link in a new appfs image.

    How to write a service file is described in section “6.2 Systemd Management” in CC Linux – Software Guide.

  3. If your application uses Qt, add the Qt runtime. It can be downloaded from CrossControl under Device Download -> QT for the display. For example, Qt runtime 6.8 for V700 and CCLinux 4.1:

    $ tar -xf linx-qt68-v700-ccl41_6.8.3-1_aarch64.tar.gz -C appfs
    

The appfs/ folder must contain at least 4 KB of files. Otherwise, the bundle is too small for the verity format.

6.3. Build the bundle

  1. Download the official CrossControl OS update bundle for the display, for the same CCLinux version your application has been tested with. Place it in cclinux-rauc-bundles/. The folder must contain only one .raucb file, unless the bundle is selected with --bundle.

  2. Build the bundle:

    $ ./build-all-demo.sh
    

    The script:

    • Creates appfs.ext4 from the content of appfs/ and copies it to release-full-1.0.0/.

    • Extracts the OS update bundle to cclinux-rauc-bundles/latest/, see B.1. Extract a bundle, and copies the rootfs image to release-full-1.0.0/.

    • Updates compatible and the rootfs filename in release-full-1.0.0/manifest.raucm to match the OS update bundle.

    • Signs the bundle with the demo key in cc-demo-keys/, see 5.3. CrossControl demo keys, and creates install-package-1.0.0.raucb.

    The appfs image is 800 MB by default. The size must not exceed the appfs partition size of the display, see section “Partition Sizes” in CC Linux – Programmer’s Guide. Set another size in MB with --appfs-size. Run ./build-all-demo.sh --help for all options.

  3. Check the manifest. For the V700, release-full-1.0.0/manifest.raucm contains:

    [update]
    compatible=CrossControl V700
    version=1.0.0
    description=Rauc example package
    
    [bundle]
    format=verity
    
    [image.rootfs]
    filename=ccpilot-v700-release-v700.ext4
    
    [image.appfs]
    filename=appfs.ext4
    

    compatible must exactly match the value in the display’s /etc/rauc/system.conf. RAUC refuses to install a bundle with a different value. The filename values must match the image files in release-full-1.0.0/. Change version and description to describe your release.

The bundle install-package-1.0.0.raucb can now be installed on the display, as described in 7. Install a bundle.

When the display has been switched to customer keys, see 8. Switch to customer keys, build the bundle with build-all.sh instead. It runs the same steps as build-all-demo.sh, but signs install-package-1.0.0.raucb with the keys generated in 8.1. Generate customer signing keys:

$ ./build-all.sh

Resigned bundles in cclinux-rauc-bundles/, see 8.2. Resign CrossControl bundles, are ignored. The other options are the same as for build-all-demo.sh.

For the manual steps, see Appendix B. Create a bundle manually.

7. Install a bundle

A bundle can be installed from a USB drive, manually over SSH, or over the air. After an installation attempt, detailed logs can be found in /data/rauc/install.log on the display.

7.1. USB update

The display automatically installs a bundle from a USB drive:

  1. Copy the .raucb file to the root directory of a USB drive. The drive must contain only one .raucb file in its root directory.

  2. Insert the USB drive into the display. After a short delay, up to about 20 seconds, the display emits a short beep and the LED starts blinking yellow. The installation has started.

  3. When the installation has completed successfully, the LED turns green and a longer beep sounds. The display then reboots automatically.

Keep the USB drive connected until the display starts rebooting. Removing it earlier can interrupt the update.

If the installation fails, the LED blinks red with falling-tone beeps, and the installation log is copied to the USB drive as rauc_install.log. After a short while, the LED switches back to green and the installation is retried automatically.

The display stores a SHA256 checksum of the last installed bundle in /data. A bundle with the same checksum is not installed again, so the update is not repeated when the display reboots with the USB drive still connected.

The USB update is configured in /etc/cc-update-config.sh:

Setting

Description

DO_USB_UPDATE=1

Set to 0 to disable USB updates, for example if updates are handled by the application.

DO_UPDATE_AUTO_REBOOT=1

Set to 0 to disable the automatic reboot after a successful update. The display must then be rebooted manually to use the update.

7.2. Manual update over SSH

  1. Copy the bundle to the display:

    $ scp install-package-1.0.0.raucb ccs@<display-hostname-or-address>:
    
  2. Log in to the display and install the bundle with cc-update:

    $ ssh ccs@<display-hostname-or-address>
    [CCpilot]$ sudo cc-update install /data/home/ccs/install-package-1.0.0.raucb
    

    cc-update is the same tool that is used for USB updates. It uses the same settings in /etc/cc-update-config.sh and reboots the display automatically after a successful update. It must be run with sudo.

To install without the automatic reboot, use rauc install and reboot the display manually. rauc install does not require sudo:

[CCpilot]$ rauc install /data/home/ccs/install-package-1.0.0.raucb
[CCpilot]$ sudo reboot

7.3. OTA updates

rauc install also accepts an HTTP or HTTPS address instead of a local file. CCLinux has no built-in feature for updating from a web address, but applications or scripts can use this. CCLinux supports fleet management clients such as qbee, hawkBit, and other commercial alternatives, but none is included in the OS image. Contact CrossControl to discuss these alternatives.

7.4. Adaptive updates

RAUC does not use binary delta updates. Instead, adaptive updates reduce the amount of data to download by reusing data already on the display, from the previous version or from an incomplete installation. No specific previous version is required.

When the bundle is created, RAUC stores a hash of each 4 KiB block of the image in an index (block-hash-index). During installation, RAUC compares the blocks in the target slot with the index and downloads only the blocks that differ.

Adaptive updates work best with HTTP streaming, and are enabled by default in CCLinux.

7.5. Check the slot status

rauc status shows which slots are booted and active, and whether an installed slot booted successfully. The following example shows a failed boot of slot B (rootfs.1), which caused a rollback to slot A:

[CCpilot]$ rauc status
=== System Info ===
Compatible:  CrossControl V1X00
Variant:
Booted from: rootfs.0 (A)

=== Bootloader ===
Activated: rootfs.0 (A)

=== Slot States ===
  [bootloader.0] (/dev/mmcblk1, boot-emmc, inactive)

○ [rootfs.1] (/dev/mmcblk1p3, ext4, inactive)
      bootname: B
      boot status: bad
    [appfs.1] (/dev/mmcblk1p5, ext4, inactive)

⏺ [rootfs.0] (/dev/mmcblk1p2, ext4, booted)
      bootname: A
      mounted: /
      boot status: good
    [appfs.0] (/dev/mmcblk1p4, ext4, active)
      mounted: /appfs

For scripts, the output is also available as shell variables or JSON:

[CCpilot]$ rauc status --output-format=shell
[CCpilot]$ rauc status --output-format=json
[CCpilot]$ rauc status --output-format=json-pretty

The slot status is also available through the RAUC D-Bus API, see 12. Using the RAUC D-Bus API.

7.6. Rollback on boot errors

After an update, the display tries to boot the new slot up to five times. The boot counts as successful when rauc-mark-good.service is reached. If this does not happen within five attempts, the display returns to the previous slot, and the new slot is marked as bad.

Important

The bootloader counts the failed boot attempts. If the bootloader or its configuration in the eMMC is damaged, rollback may not be possible.

7.7. Switch the active slot manually

To boot the other slot, mark it as active and reboot:

[CCpilot]$ rauc status mark-active other
[CCpilot]$ sudo reboot

To keep the currently booted slot active instead, use booted in place of other.

8. Switch to customer keys

A factory-configured display accepts bundles signed with the CrossControl demo key. The demo private key is published in this manual, so anyone can create a bundle that such a display installs. The demo key can be used during development, see 6. Update bundle creation, but before production every display must be switched to accept only bundles signed with your own key.

The display installs a bundle only if it is signed by a CA certificate in /data/rauc/certs/, see 4. Signature. Switching to customer keys replaces the demo CA in this directory with your own CA:

Factory-configured display              After switching to customer keys
+-------------------------------+       +-------------------------------+
| /data/rauc/certs/             |       | /data/rauc/certs/             |
|   CrossControl demo CA        |  -->  |   Customer CA                 |
+-------------------------------+       +-------------------------------+
Accepts bundles signed with             Accepts only bundles signed with
the demo key                            the customer key

The switch is done in three steps, using the example repository from 5.2. Set up the example repository:

  1. Generate the customer signing keys, see 8.1. Generate customer signing keys.

  2. Resign the CrossControl bundles with the customer key, see 8.2. Resign CrossControl bundles.

  3. Install the customer CA on each display, see 8.3. Install the customer CA.

Warning

After the switch, the display no longer accepts bundles signed with the demo key, including unmodified CrossControl bundles. Keep your signing key and CA key confidential and backed up. If the keys are lost, a display with secure boot enabled can no longer be updated, because RAUC is the only update method on these displays. Reflashing with uuu is only possible on development units without secure boot.

A factory reset with ccsettingsconsole does not restore the demo CA, because it only resets the /etc overlay. On development units without secure boot, reflashing the display with uuu restores the factory configuration, including the demo CA.

Key handling is described in more detail in the RAUC security documentation.

8.1. Generate customer signing keys

generate-ca.sh creates a root CA, a development and a release intermediate CA, and signing keys with certificates issued by these CAs for code signing. The same keys are used for encryption in 9. Add encryption to bundles.

The scripts use the rauc tool from the SDK set in conf.sh, see 5.2. Set up the example repository, so sourcing the SDK environment is not required. OpenSSL is also required. On Ubuntu or Debian:

$ sudo apt update
$ sudo apt install openssl

Run the commands from the root of the example repository:

  1. Set your company name in conf.sh:

    CA_ORG="<company-name>"
    

    CA_ORG is the company name written to the generated certificates.

  2. Generate the keys and certificates once. If openssl-ca/ already contains your signing PKI, reuse it instead:

    $ ./generate-ca.sh
    
  3. The files are created in openssl-ca/. The example scripts use the development signing key and select the following files automatically:

    File

    Description

    root-ca.pem

    Customer root CA certificate. Used to verify bundles signed with the customer key.

    root/hash/

    Root CA certificate and revocation list with hash filenames. Installed in /data/rauc/certs/ by the lock bundle.

    dev/developer-1.cert.pem

    Customer signing certificate.

    dev/private/developer-1.pem

    Customer signing private key. Confidential.

    dev/ca.cert.pem

    Development intermediate CA certificate. Included in the bundle signature so that the display can verify it using the root CA.

    */private/

    CA private keys. Confidential.

  4. Back up the complete openssl-ca/ directory to secure storage. The directory is excluded from Git by .gitignore, so it is not part of any commit.

Warning

Back up the keys before any display is switched to the customer CA. If the keys are lost, a display with secure boot enabled can no longer be updated. Reflashing with uuu is only possible on development units without secure boot. Do not commit private keys to a public source control repository. Anyone with access to the signing key can create bundles that the display installs.

generate-ca.sh does not overwrite an existing openssl-ca/ directory. Deleting it and running the script again creates a new CA. Displays that trust the previous CA do not accept bundles signed with the new keys.

Important

The certificates are valid from 2025-01-01 to 2040-01-01. Review these dates before using them. Once a certificate expires, the display rejects all new bundles signed with it.

8.2. Resign CrossControl bundles

CrossControl delivers the bootloader, OS, and system update bundles signed with the demo key. A display that only trusts the customer CA rejects these bundles. Resigning replaces the demo signature with a customer signature without changing the bundle content.

Bundles you create yourself do not need to be resigned. Sign them with the customer key directly, with build-all.sh as described in 6.3. Build the bundle.

The repository script cclinux-rauc-bundles/resign-bundle.sh uses the customer keys generated in 8.1. Generate customer signing keys.

Important

The script uses --no-verify, which skips verification of the existing signature. Verify the original bundle against the CrossControl demo CA before resigning, and verify the result against the customer CA afterwards. Do not continue if either check fails.

  1. Set up the SDK environment, as described in 5.1. Set up the SDK, and copy the original CrossControl bundle into cclinux-rauc-bundles/:

    $ cp <path-to>/<bundle-name>.raucb cclinux-rauc-bundles/
    
  2. Verify the original bundle against the demo CA. Only continue if signature verification succeeds:

    [SDK]$ rauc info \
           --conf=rauc-host.conf \
           --keyring=cc-demo-keys/ca.cert.pem \
           cclinux-rauc-bundles/<bundle-name>.raucb
    
  3. Resign the bundle. The script must be run from cclinux-rauc-bundles/, with only the filename as argument:

    $ cd cclinux-rauc-bundles
    $ ./resign-bundle.sh <bundle-name>.raucb
    $ cd ..
    

    The script creates cclinux-rauc-bundles/resigned_<bundle-name>.raucb and includes the customer intermediate CA certificate in the signature. An existing output with that name is overwritten.

  4. Verify the resigned bundle against the customer CA:

    [SDK]$ rauc info \
           --conf=rauc-host.conf \
           --keyring=openssl-ca/root-ca.pem \
           cclinux-rauc-bundles/resigned_<bundle-name>.raucb
    

    The output contains Verified inline signature by followed by the subject of the customer signing certificate.

A factory-configured display rejects the resigned bundle until the customer CA has been installed, as described in 8.3. Install the customer CA.

For more details, see Resigning Bundles in the RAUC documentation.

8.3. Install the customer CA

Use build-lock-bundle.sh to create a lock bundle for one or more displays that still trust the CrossControl demo CA. The bundle is signed with the demo key. Its handler replaces the contents of /data/rauc/certs/ with the customer root CA certificate and revocation list generated in 8.1. Generate customer signing keys.

The lock bundle changes only the RAUC trust certificates. It does not change SSH authentication or configure encryption.

Warning

The handler removes all existing CA files before installing the replacements. It does not verify a customer-signed bundle on the display before changing trust. Back up the complete openssl-ca/ directory and successfully verify a resigned bundle as described in 8.2. Resign CrossControl bundles before installing the lock bundle. A display that already trusts only customer keys rejects the demo-signed lock bundle.

  1. From the repository root, build the lock bundle:

    $ ./build-lock-bundle.sh
    

    The output is lock-1.0.0.raucb. The script packages the files in openssl-ca/root/hash/ with the filenames RAUC requires; no manual certificate hashing is needed. It also sets compatible in customer-lock-1.0.0/manifest.raucm to the value in the original CrossControl bundle in cclinux-rauc-bundles/. The resigned bundle is ignored. To use another bundle, add --bundle <path-to-bundle>.raucb.

  2. Install lock-1.0.0.raucb on each display using 7.1. USB update or 7. Install a bundle, and allow the display to reboot. If using USB, keep only the lock bundle in the drive’s root directory. Install the customer-signed release bundle separately afterwards.

  3. Verify the switch using the resigned bundle from 8.2. Resign CrossControl bundles. From the repository root, copy the bundle to the display, then log in:

    $ scp cclinux-rauc-bundles/resigned_<bundle-name>.raucb ccs@<display-hostname-or-address>:
    $ ssh ccs@<display-hostname-or-address>
    [CCpilot]$ rauc info /data/home/ccs/resigned_<bundle-name>.raucb
    

    The output must contain Verified inline signature by followed by the subject of the customer signing certificate. Do not proceed with installation if signature verification fails.

The display now accepts only bundles signed with the customer key:

Install the resigned bundle as described in 7. Install a bundle.

/data is not modified by RAUC updates, so the customer CA stays installed after updates.

Note

This completes the basic RAUC workflow: creating, signing, and installing update bundles with your own keys.

The following chapters cover advanced topics: bundle encryption, additional security measures, special-purpose bundles and development, the RAUC D-Bus API, and BSP integration.