psykar / rauc Goto Github PK

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 installation artifacts.

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

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

Chat: IRC channel #rauc on freenode (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
• 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
• Network streaming mode using casync
  • chunk-based binary delta updates
  • significantly reduce download size
  • no extra storage required
• Bootloader support:
  • grub
  • barebox
  • u-boot
  • EFI
• Storage support:
  • ext4 filesystem
  • eMMC boot partitions (atomic update)
  • vfat filesystem
  • UBI volumes
  • UBIFS
  • raw NAND (using nandwrite)
  • squashfs
  • MBR partition table
• Independent from updates source
  • USB Stick
  • Software provisioning server (e.g. Hawkbit)
• Controllable via D-Bus interface
• Supports Data migration
• Network protocol support using libcurl (https, http, ftp, ssh, ...)
• Several layers of update customization
  • Update-specific extensions (hooks)
  • System-specific extensions (handlers)
  • fully custom update script

Host Features

• Create update bundles
• Sign/resign 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
• Boot target selection support in the bootloader
• Enough mass storage for two symmetric/asymmetric/custom slots
• For normal bundle mode:
  • Enough storage for the compressed bundle file (in memory, in a temporary partition or on an external storage device)
• For casync bundle mode:
  • No additional storage needed
  • Network interface
• Hardware watchdog (optional, but recommended)
• RTC (optional, but recommended)

Usage

Please see the documentation for details.

Prerequisites

Host (Build) Prerequisites

• automake
• libtool
• libdbus-1-dev
• libglib2.0-dev
• libcurl3-dev
• libssl-dev

sudo apt-get install automake libtool libdbus-1-dev libglib2.0-dev libcurl3-dev libssl-dev

If you intend to use json-support you also need

sudo apt-get install libjson-glib-dev

Target Prerequisites

Required kernel options:

• CONFIG_BLK_DEV_LOOP=y
• CONFIG_SQUASHFS=y

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

git clone https://github.com/rauc/rauc
cd rauc
./autogen.sh
./configure
make

Manual Installation

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:

make install

Running the Test Suite

sudo apt-get install user-mode-linux slirp squashfs-tools
# Optional to run all tests:
# sudo apt-get install faketime casync grub-common softhsm2 opensc opensc-pkcs11 libengine-pkcs11-openssl
make check
./uml-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 on your target device, run:

rauc install update-2019.01-1.raucb

Contributing

Fork the repository and send us a pull request.

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