RAUC - Robust Auto-Update Controller

RAUC controls the update process on embedded Linux systems. It is both a target application that runs as an update client and a host/target tool that allows you to create, inspect and modify update files ("bundles").

Source Code: https://github.com/rauc/rauc

Documentation: https://rauc.readthedocs.org/

Chat: IRC channel #rauc on libera.chat (bridged to the Matrix channel #rauc:matrix.org)

Features

Fail-Safe & Atomic:
- An update may be interrupted at any point without breaking the running system.
- Update compatibility check
- Atomic bootloader updates (eMMC boot partitions, MBR, GPT)
Cryptographic signing and verification of updates using OpenSSL (signatures based on x.509 certificates)
- Keys and certificates on PKCS#11 tokens (HSMs) are supported
Flexible and customizable redundancy/storage setup
- Symmetric setup (Root-FS A & B)
- Asymmetric setup (recovery & normal)
- Application partition, data partitions, ...
- Allows grouping of multiple slots (rootfs, appfs) as update targets
Built-in HTTP(S) streaming mode
- No intermediate storage on target required
Delta-like adaptive update support
- Transparent selection of download optimization
Alternative network delta-streaming mode (using casync tool)
- chunk-based binary delta updates
- special bundle format and external chunk store
Bundle encryption for multiple recipients
Bootloader support:
- grub
- barebox
- u-boot
- EFI
- Custom implementation
Storage support:
- read-only filesystems: SquashFS, EROFS, dm-verity protected images, ...
- read-write filesystems: ext4, VFAT, UBIFS, JFFS2
- eMMC boot partitions (atomic update)
- UBI volumes
- raw NAND flash (using nandwrite)
- raw NOR flash (using flashcp)
- MBR partition table
- GPT partition table
Independent from update source
- Simple webserver (e.g. lighttpd)
- Software provisioning server (e.g. hawkBit with rauc-hawkbit-updater)
- USB Stick
Controllable via D-Bus interface
Supports data migration
Network protocol support using libcurl (https, http, tftp/ftp, ssh, ...)
Several layers of update customization
- Update-specific extensions (hooks)
- System-specific extensions (handlers)
- fully custom update script

Host Features

Create and sign update bundles
Resign bundles
Encrypt bundles
Inspect bundle files

Target Features

Run as a system service (D-Bus interface)
Install bundles
View system status information
Change status of symmetric/asymmetric/custom slots

Target Requirements

Boot state storage
- GRUB: environment file on SD/eMMC/SSD/disk
- Barebox: State partition on EEPROM/FRAM/MRAM or NAND flash
- U-Boot: environment variable
- EFI: EFI variables
- Custom: depends on implementation
Boot target selection support in the bootloader
Enough mass storage for two symmetric/asymmetric/custom slots
Storage location and storage space for the bundle:
- For USB stick update: Sufficent space on the stick for (compressed) bundle, no on-target storage required
- For HTTP(S) bundle streaming installation: Sufficient space on server, no on-target storage requied
  - For adaptive updates: some on-target storage for meta-data
- For casync-based updates: temporary on-target storage for downloaded chunks required
- For external (non-streaming) download: Sufficient temporary on-target storage space for (compressed) bundle
Hardware watchdog (optional, but recommended)
RTC (optional, but recommended)

Usage

Please see the documentation for details.

Prerequisites

Host (Build) Prerequisites

build-essential
meson
libtool
libdbus-1-dev
libglib2.0-dev
libcurl3-dev
libssl-dev

sudo apt-get install build-essential meson libtool libdbus-1-dev libglib2.0-dev libcurl3-dev libssl-dev

For HTTP(S) streaming support, you also need netlink protocol headers:

sudo apt-get install libnl-genl-3-dev

If you intend to use json-support you also need

sudo apt-get install libjson-glib-dev

Target Prerequisites

Required kernel options (either y or m):

CONFIG_MD
CONFIG_BLK_DEV_DM
CONFIG_BLK_DEV_LOOP
CONFIG_DM_VERITY
CONFIG_SQUASHFS
CONFIG_CRYPTO_SHA256
CONFIG_BLK_DEV_NBD (for streaming support)
CONFIG_DM_CRYPT (for encryption support)
CONFIG_CRYPTO_AES (for encryption support)

For using tar archive in RAUC bundles with Busybox tar, you have to enable the following Busybox feature:

CONFIG_FEATURE_TAR_AUTODETECT=y
CONFIG_FEATURE_TAR_LONG_OPTIONS=y

Depending on the actual storage type and/or filesystem used, further target tools might be required. The documentation chapter Required Target Tools gives a more detailed list on these.

Building from Sources

Note

RAUC is intended to be built both as a host tool as well as a target tool (service). Therefore it is fully prepared for cross-compilation with meson.

git clone https://github.com/rauc/rauc
cd rauc
meson setup build
meson compile -C build # or 'ninja -C build' on meson < 0.54.0

Manual Installation

Note

To prepare RAUC for the target device, it is highly recommended to use an embedded Linux distribution build suite such as Yocto/OE, PTXdist or Buildroot.

On the host system RAUC can be used directly from the build dir, or optionally be installed. On the target instead, installing is highly recommended as it also unpacks service and D-Bus configuration files required to run RAUC properly:

meson install

Running the Test Suite

sudo apt-get install qemu-system-x86 time squashfs-tools e2fsprogs python3-pytest python3-dasbus python3-aiohttp python3-requests python3-pyasn1 python3-pyasn1-modules
# Optional to run all tests:
# sudo apt-get install faketime casync grub-common openssl softhsm2 opensc opensc-pkcs11 libengine-pkcs11-openssl mtd-utils
./qemu-test

Creating a Bundle (Host)

Create a directory with the content that should be installed:

mkdir content-dir/
cp $SOURCE/rootfs.ext4 content-dir/

Create a manifest describing which image to install where together with some meta info:

cat >> content-dir/manifest.raucm << EOF
[update]
compatible=FooCorp Super BarBazzer
version=2019.01-1
[image.rootfs]
filename=rootfs.ext4
EOF

Let RAUC create a bundle from this:

rauc --cert autobuilder.cert.pem --key autobuilder.key.pem bundle content-dir/ update-2019.01-1.raucb

Starting the RAUC Service (Target)

Create a system configuration file in /etc/rauc/system.conf and start the service process in background:

rauc service &

Installing a Bundle (Target)

To install the bundle (from local storage) on your target device, run:

rauc install update-2023.02-1.raucb

To install a bundle from a webserver (using RAUC's built-in HTTP(S) streaming), run:

rauc install https://example.com/update-2023.02-1.raucb

Contributing

Fork the repository and send us a pull request.

Please read the Documentation's Contributing section for more details.

License

Copyright (C) 2015–2026 RAUC project

RAUC is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this source code, see the file named COPYING. If not, see https://www.gnu.org/licenses/.

Name		Name	Last commit message	Last commit date
Latest commit History 4,521 Commits
.github		.github
LICENSES		LICENSES
build-aux		build-aux
contrib		contrib

License

rauc/rauc

Folders and files

Latest commit

History