rpi-image-gen

https://raspberrypi.github.io/rpi-image-gen/
Admin
rpi-image-gen is a tool for generating complete disk images and device filesystems for Raspberry Pi...
Tokens:24,701
Snippets:500
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Static Slot Map Example

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-ab-slot-mapper.html

A concrete example of a slot map configuration file.

```text
a.boot=::2
a.system=::4
b.boot=::3
b.system=mapper:cryptroot:1
```

--------------------------------

### Serve documentation locally

Source: https://raspberrypi.github.io/rpi-image-gen/index.html

Starts a web server on port 3142 to view the documentation in a browser.

```bash
rpi-image-gen docs
```

--------------------------------

### Generate example YAML configuration

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Create a template YAML configuration file for the project.

```bash
rpi-image-gen config --gen
```

--------------------------------

### Example IGconf Variable Assignments

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Concrete examples of variables following the IGconf naming convention.

```text
IGconf_device_class=pi5
IGconf_device_storage_type=sd
IGconf_image_compression=zstd
```

--------------------------------

### Define layers in configuration

Source: https://raspberrypi.github.io/rpi-image-gen/layer/index.html

Example of how to specify layers in the configuration file using arbitrary keys.

```yaml
layer:
  foo: trixie-minbase
  bar: rpi5
  app: my-app
```

--------------------------------

### Specify packages for installation

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

The packages section supports installing apt packages or local .deb files, with local files processed before apt dependencies.

```yaml
packages:
  - curl
  - vim
  - git
```

```yaml
packages:
  apt: curl
  local1: /path/to/mypkg_1.0_arm64.deb
  local2: myotherpkg_2.0_arm64.deb
```

--------------------------------

### Configure Layer Variables

Source: https://raspberrypi.github.io/rpi-image-gen/layer/index.html

Example of setting layer-specific variables using a configuration file.

```yaml
device:
  storage_type: nvme

image:
  compression: zstd
```

--------------------------------

### Configuration Loading Output

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Example of how configuration loading displays variable sources, distinguishing between file-based and command-line overrides.

```text
CFG IGconf_device_class=pi5         # From configuration file
OVR IGconf_device_hostname=pi5-test  # From command line override
```

--------------------------------

### Define a YAML list section

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Example of defining a list of packages in YAML.

```yaml
packages:
  - vim
  - git
  - curl
```

--------------------------------

### Define a YAML configuration mapping

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Example of a standard configuration file structure using includes, environment variables, and device/image settings.

```yaml
include:
  file: base.yaml

env:
  MYVAR: UNCHANGED

device:
  class: pi5
  storage_type: sd
  hostname: ${IGconf_device_class}-$(tr -dc 'a-z' < /dev/urandom | head -c 6)

image:
  compression: zstd
  boot_part_size: 200%
  root_part_size: 300%
```

--------------------------------

### Define Configuration Variables

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Example of using variable expansion and command substitution within a YAML configuration file.

```yaml
device:
  name: controllerbox
  rev: 2
  hostname: ${IGconf_device_name}-$(uuidgen | cut -d'-' -f1)

image:
  assetdir: ${WORKSPACE}/build/assets/${IGconf_device_name}-rev${IGconf_device_rev}

ssh:
  pubkey_user1: ${DEPLOY}/device/baseassets/id_rsa.pub
  pubkey_only: y
```

--------------------------------

### Configure mmdebstrap apt options

Source: https://raspberrypi.github.io/rpi-image-gen/layer/debian-trixie-arm64-multi.html

Sets APT configuration to disable the installation of suggested and recommended packages.

```text
APT::Install-Suggests "false"
APT::Install-Recommends "false"
```

--------------------------------

### Disable splash screen installation

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-splash-screen.html

Set image_path to an empty string to skip the splash screen installation process.

```yaml
layer:
  base: trixie-minbase
  splash: rpi-splash-screen

splash:
  image_path: ""  # Empty string skips installation
```

--------------------------------

### Define Validated Environment Variables

Source: https://raspberrypi.github.io/rpi-image-gen/layer/variable-validation.html

Example configurations for various validation types including integers, allowed values, regex patterns, and keywords.

```text
# Port number validation
X-Env-Var-port-Valid: int:1024-65535

# Environment selection
X-Env-Var-env-Valid: development,staging,production

# Hostname validation
X-Env-Var-hostname-Valid: regex:^[a-zA-Z0-9.-]+$

# Boolean flag
X-Env-Var-debug-Valid: bool

# Component selection with keywords
X-Env-Var-component-Valid: keywords:frontend,backend,database
```

--------------------------------

### Define a WPA2 network profile

Source: https://raspberrypi.github.io/rpi-image-gen/layer/network-manager.html

Example of an nmcli command to create a WPA2 connection profile for NetworkManager.

```bash
--offline connection add type wifi ifname wlan0 con-name "Guest Only" ssid "Guest Only" wifi-sec.auth-alg open wifi-sec.key-mgmt wpa-psk wifi-sec.psk <passphrase> connection.autoconnect-retries 0 > /etc/NetworkManager/system-connections/Guest_Only.nmconnection
```

--------------------------------

### Define an IWD network profile

Source: https://raspberrypi.github.io/rpi-image-gen/layer/iwd.html

Example content for an IWD network profile file named after the SSID.

```text
[Security]
Passphrase=<passphrase>
```

--------------------------------

### Define a trait with child inclusion

Source: https://raspberrypi.github.io/rpi-image-gen/trait.html

Example of a trait definition that includes a child file for further trait definitions.

```text
X-Env-Trait-storage-Desc: Onboard or directly attached storage
X-Env-Trait-storage-Valid: bool
X-Env-Trait-storage-Include: periph/storage.deb822
```

--------------------------------

### Define Conditional and Unconditional Triggers

Source: https://raspberrypi.github.io/rpi-image-gen/layer/index.html

Examples of basic trigger syntax including conditional, unconditional, and multi-line definitions.

```text
# X-Env-Var-rootfs_type-Triggers: when=IGconf_image_rootfs_type == ‘btrfs’ set IG_HAS_BTRFS_PROGS=1 policy=force
```

```text
# X-Env-Var-rootfs_type-Triggers: set IG_ALWAYS_ON=1 policy=immediate
```

```text
# X-Env-Var-rootfs_type-Triggers:
#  when=IGconf_image_rootfs_type == ‘btrfs’ set IG_HAS_BTRFS_PROGS=1 policy=force
#  when=IGconf_image_rootfs_type == ‘ext4’ set IG_HAS_E2FS_PROGS=1 policy=force
```

--------------------------------

### Define Variable Conflict Expressions

Source: https://raspberrypi.github.io/rpi-image-gen/layer/index.html

Examples showing mutual exclusion, conditional constraints, and multi-line conflict definitions using DEB822 syntax.

```text
# Mutual exclusion - conflict if both user1pass and user1passhash are set:
# X-Env-Var-user1pass:
# X-Env-Var-user1pass-Conflicts: IGconf_device_user1pass != '' and IGconf_device_user1passhash != ''
#
# X-Env-Var-user1passhash:
# X-Env-Var-user1passhash-Conflicts: IGconf_device_user1passhash != '' and IGconf_device_user1pass != ''

# Conditional - lite variant cannot be used with emmc storage:
# X-Env-Var-variant: none
# X-Env-Var-variant-Valid: none,lite
# X-Env-Var-variant-Conflicts: IGconf_device_variant == 'lite' and IGconf_device_storage_type == 'emmc'

# Multi-line - two independent conflict expressions for one variable:
# X-Env-Var-ptable_protect: n
# X-Env-Var-ptable_protect-Conflicts: IGconf_image_ptable_protect == 'y' and IGconf_device_storage_type != 'emmc'
#  IGconf_image_ptable_protect == 'y' and IGconf_image_type == 'raw'
```

--------------------------------

### Configure and Build with Hierarchical Resources

Source: https://raspberrypi.github.io/rpi-image-gen/execution/index.html

Demonstrates how to reference built-in configurations while overriding layers with local project files, and how to trigger the build using the -S flag.

```yaml
# Local config can include built-in base
# File: ./my-project/config/kiosk.yaml
include:
  file: bookworm-minbase.cfg  # Resolves to built-in config

layer:
  app: my-kiosk               # Resolves to ./my-project/layer/my-kiosk.yaml

# Build with mixed local/built-in resources
$ rpi-image-gen build -S ./my-project/ -c kiosk.cfg
```

--------------------------------

### Configuration File Structure

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Recommended directory layout for organizing base configurations, environment-specific overrides, and variant settings.

```text
config/
├── base.yaml              # Common base configuration
├── environments/
│   ├── development.yaml   # Development overrides
│   ├── staging.yaml      # Staging overrides
│   └── production.yaml   # Production overrides
└── variants/
    ├── local.yaml       # Local development settings
    └── ci.yaml          # CI/CD specific settings
```

--------------------------------

### Provision image using IDP helper

Source: https://raspberrypi.github.io/rpi-image-gen/provisioning/index.html

Use the provided shell script to provision an image based on a JSON description file.

```bash
$ ./bin/idp.sh -f /path/to/image.json
```

--------------------------------

### Configure Auth Key via Command Line

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-connect.html

Set the authentication key directly during the build process using command line arguments.

```bash
$ rpi-image-gen build <args> -- IGconf_connect_authkey=$KEY
```

--------------------------------

### Define a trait with dependency requirements

Source: https://raspberrypi.github.io/rpi-image-gen/trait.html

Example of a trait definition that enforces a dependency on another trait token.

```text
X-Env-Trait-nvme-Desc: NVMe storage (soldered or socket-attached)
X-Env-Trait-nvme-Valid: bool
X-Env-Trait-nvme-Requires: hw:pcie:bus
```

--------------------------------

### Include a single configuration file

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Syntax for including a single base configuration file.

```yaml
include:
  file: base.yaml
```

--------------------------------

### Configure network commands via command line

Source: https://raspberrypi.github.io/rpi-image-gen/layer/network-manager.html

Passing the network commands file path directly during the build process.

```bash
$ rpi-image-gen build -S ./examples/myimage/ -c myimage.yaml -- IGconf_nm_cmds=/path/to/nm.cmds
```

--------------------------------

### Configure Auth Key via Configuration File

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-connect.html

Define the authentication key in the configuration file using either a file path or the raw key string.

```yaml
connect:
   authkey: /path/to/file
```

```yaml
connect:
   authkey: $KEY
```

--------------------------------

### Include multiple configuration files

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Syntax for including multiple files, where later entries override earlier ones.

```yaml
include:
  - device/cm5.yaml
  - device/cm5io.yaml
```

--------------------------------

### Execute configuration commands via CLI

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Various commands to load, write, or override configuration settings using the rpi-image-gen tool.

```bash
# Load all sections into environment
rpi-image-gen config myconfig.yaml

# Load specific section
rpi-image-gen config myconfig.yaml --section device

# Write resolved config to file
rpi-image-gen config myconfig.yaml --write-to build.env

# Use command line overrides
rpi-image-gen config myconfig.yaml -- IGconf_device_class=pi5 IGconf_image_compression=xz

# Custom include search paths
rpi-image-gen config myconfig.yaml --path "./config:./shared:./templates"

# Disable variable expansion
rpi-image-gen config myconfig.yaml --no-expand

# Combine options with overrides
rpi-image-gen config myconfig.yaml --section device --write-to build.env -- IGconf_device_class=pi5
```

--------------------------------

### Configure IWD profile via command line

Source: https://raspberrypi.github.io/rpi-image-gen/layer/iwd.html

Passing the profile path as a build variable during image generation.

```bash
$ rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- IGconf_iwd_profile='Pi Towers Guest.psk'
```

--------------------------------

### Assign Variables via Command Line

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Demonstrates immediate shell expansion versus deferred engine expansion when passing variables via the command line.

```bash
rpi-image-gen build -c config.yaml -- "IGconf_ssh_pubkey_user1=$(< /path/to/.ssh/id_rsa.pub)"
```

```bash
rpi-image-gen build -c config.yaml -- 'IGconf_ssh_pubkey_user1=$(cat /path/to/.ssh/id_rsa.pub)'
```

--------------------------------

### List and Inspect Traits via CLI

Source: https://raspberrypi.github.io/rpi-image-gen/trait.html

Commands to list all available traits or inspect specific token details.

```bash
rpi-image-gen config --trait
```

```bash
rpi-image-gen config --trait hw:soc:bcm2712
```

```text
hw:soc:bcm2712
  Desc: Broadcom BCM2712 - Raspberry Pi 5 / CM5 (quad Cortex-A76)
  Type: bool
  File: trait/hw/soc/broadcom.deb822
  Activates:
    hw:arch
    hw:arch:arm
    hw:arch:arm:aes-accel
    hw:arch:arm:sha-accel
    hw:crypto
    hw:crypto:aes-accel
    hw:crypto:sha-accel
    hw:exec
    hw:exec:kernel
    hw:exec:kernel:aarch64
    hw:exec:user
    hw:exec:user:aarch32
    hw:exec:user:aarch64
    hw:isa
    hw:isa:armv8
    hw:soc
    hw:uarch
    hw:uarch:cortex-a76
```

```bash
rpi-image-gen config -S ./my-board --trait
```

--------------------------------

### Declare a shared path configuration

Source: https://raspberrypi.github.io/rpi-image-gen/layer/image-rota.html

Create a .conf file in /etc/rpi-image-gen/slot-shared.d/ to specify which paths should be bind-mounted from the persistent partition.

```text
Version=1
Path=/var/lib/myapp
Path=/etc/myapp/state
```

--------------------------------

### Configure mmdebstrap dpkg options

Source: https://raspberrypi.github.io/rpi-image-gen/layer/debian-trixie-arm64-multi.html

Defines path exclusion and inclusion rules for dpkg to minimize image size by removing unnecessary documentation and locale files.

```text
path-exclude=/usr/share/man/*
path-include=/usr/share/man/man[1-9]/*
path-exclude=/usr/share/locale/*
path-include=/usr/share/locale/locale.alias
path-exclude=/usr/share/doc/*
path-include=/usr/share/doc/*/copyright
path-include=/usr/share/doc/*/changelog.Debian.*
path-exclude=/usr/share/{doc,info,man,omf,help,gnome/help}/*
path-exclude=/usr/share/lintian/*
```

--------------------------------

### Configure basic splash screen

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-splash-screen.html

Set the path to a custom TGA splash screen image.

```yaml
layer:
  base: trixie-minbase
  splash: rpi-splash-screen

splash:
  image_path: /home/user/my-logo.tga
```

--------------------------------

### Inspect Trait Configuration

Source: https://raspberrypi.github.io/rpi-image-gen/trait.html

Displays the output of the rpi-image-gen command to inspect the activated traits for a specific device.

```bash
$ rpi-image-gen config --tr hw:device:rpi:pi5
hw:device:rpi:pi5
  Desc: Raspberry Pi 5 - BCM2712 platform (quad Cortex-A76)
  Type: bool
  File: trait/hw/device/rpi/sbc/pi5.deb822
  Activates:
    boot:gpt
    boot:rpi
    boot:rpi:dtbootpartn
    hw:arch
    hw:arch:arm
    hw:arch:arm:aes-accel
    hw:arch:arm:sha-accel
    hw:bluetooth
    hw:bluetooth:broadcom
    hw:crypto
    hw:crypto:aes-accel
    hw:crypto:sha-accel
    hw:device
    hw:device:rpi
    hw:eeprom
    hw:eeprom:rpi
    hw:ethernet
    hw:exec
    hw:exec:kernel
    hw:exec:kernel:aarch64
    hw:exec:user
    hw:exec:user:aarch32
    hw:exec:user:aarch64
    hw:isa
    hw:isa:armv8
    hw:pcie
    hw:pcie:bus
    hw:soc
    hw:soc:bcm2712
    hw:soc:pcie
    hw:storage
    hw:storage:sd
    hw:uarch
    hw:uarch:cortex-a76
    hw:wlan
    hw:wlan:broadcom
```

--------------------------------

### Configure network commands via YAML

Source: https://raspberrypi.github.io/rpi-image-gen/layer/network-manager.html

Specifying the path to the nm.cmds file in the configuration YAML.

```yaml
nm:
  cmds: /path/to/nm.cmds
```

```yaml
nm:
  cmds: ${@SRCROOT}/nm.cmds
```

--------------------------------

### Flash sparse image using fastboot

Source: https://raspberrypi.github.io/rpi-image-gen/provisioning/index.html

Directly write a sparse image to device storage using standard fastboot commands.

```bash
$ fastboot flash mmcblk0 /path/to/fullimage.sparse
```

--------------------------------

### Static Slot Map Format

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-ab-slot-mapper.html

Defines the structure for the /boot/slot.map file using triplets to identify partition members.

```text
a.boot=KIND:NAME:PART
a.system=KIND:NAME:PART
b.boot=KIND:NAME:PART
b.system=KIND:NAME:PART
```

--------------------------------

### Define Layer Dependencies with Environment Variables

Source: https://raspberrypi.github.io/rpi-image-gen/layer/index.html

Use X-Env-Layer-Requires to specify mandatory layers, supporting dynamic resolution via environment variables like ${ARCH} and ${DISTRO}.

```text
# METABEGIN
# X-Env-Layer-Name: conditional-layer
# X-Env-Layer-Requires: base-layer,${ARCH}-toolchain,${DISTRO}-packages
# METAEND
```

--------------------------------

### Cross-Reference Configuration Variables

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Shows how to reference previously defined configuration variables within the same YAML file.

```yaml
device:
  class: pi5
  hostname: ${IGconf_device_class}-server

image:
  name: ${IGconf_device_class}-custom-image
```

--------------------------------

### Generate Splash Screen with Helper Script

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-splash-screen.html

Use the provided shell script to quickly generate a text-based splash screen in the required TGA format.

```bash
# Generate a simple text-based splash screen
./layer/rpi/device/splash-screen/EXAMPLE-splash.sh "Welcome to Raspberry Pi" splash.tga

# The script creates a 1920×1080 black background with centred white text
# Output is automatically in the correct TGA format
```

--------------------------------

### Resulting IGconf Variables from Prefix

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Variables generated based on the defined device prefix.

```text
IGconf_device_class=pi5
IGconf_device_storage_type=sd
```

--------------------------------

### Set Command Line Overrides

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Use this syntax to pass configuration overrides directly to the build command, ensuring they take precedence over file-based settings.

```bash
rpi-image-gen build -c config.yaml -- IGconf_device_class=pi5 IGconf_image_compression=xz
```

--------------------------------

### Use an Anchor in a Configuration File

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Reference an anchor within a configuration file using the ${@ANCHOR} syntax.

```yaml
layer:
  app: example-kiosk
  extra: rpi-splash-screen

splash:
  image_path: ${@SRCROOT}/my.tga
```

--------------------------------

### Define IGconf Variable Naming Pattern

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

The standard naming convention for configuration variables using the IGconf prefix.

```text
IGconf_<section>_<key>
```

--------------------------------

### Accessing by-slot symlinks

Source: https://raspberrypi.github.io/rpi-image-gen/layer/rpi-ab-slot-mapper.html

The layer creates stable symlinks under /dev/disk/by-slot/ to identify active and alternate boot/system partitions.

```text
/dev/disk/by-slot/
  active/boot
  active/system
  other/boot
  other/system
```

--------------------------------

### Define Trait Triggers for Hardware Configuration

Source: https://raspberrypi.github.io/rpi-image-gen/trait.html

Demonstrates using Triggers to set conditional values for hardware traits like frequency and turbo mode.

```text
X-Env-Trait-freq-Desc: clock frequency in MHz
X-Env-Trait-freq: 1500
X-Env-Trait-freq-Valid: int:600-3000

X-Env-Trait-turbo-Desc: turbo mode, bumps the clock to 3000
X-Env-Trait-turbo-Valid: bool
X-Env-Trait-turbo-Triggers: when=y set (hw:freq)=3000
```

--------------------------------

### Define Dynamic Layer Dependencies

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Uses variables within layer metadata to create dynamic dependencies based on build-time environment variables.

```text
# METABEGIN
# X-Env-Layer-Name: arch-specific-tools
# X-Env-Layer-Requires: base-layer,${ARCH}-toolchain,${DISTRO}-packages
# METAEND
```

```bash
$ rpi-image-gen build -c <args> -- ARCH=arm64 DISTRO=debian
...
# Layer dependencies will be equivalent to:
# X-Env-Layer-Requires: base-layer, arm64-toolchain, debian-packages
```

--------------------------------

### Define build layers

Source: https://raspberrypi.github.io/rpi-image-gen/config/index.html

Use the layer section to include additional layers in the build process using either key-value pairs or list syntax.

```yaml
layer:
  app: my-app-layer
  extra: rpi-splash-screen
```

```yaml
layer:
  - rpi-cm5
  - image-rota
```

--------------------------------

### Use has() in trigger when= clauses

Source: https://raspberrypi.github.io/rpi-image-gen/trait.html

Derive variable values based on active traits to allow for hardware-agnostic configuration.

```text
# X-Env-Var-storage_type-Triggers:
#  when=has('hw:storage:sd') set IGconf_device_storage_type=sd policy=lazy
#  when=has('hw:storage:emmc') set IGconf_device_storage_type=emmc policy=lazy
```

--------------------------------

### Cascade Device Identity Traits

Source: https://raspberrypi.github.io/rpi-image-gen/trait.html

Shows how a single device identity token can trigger multiple hardware and boot-related facts.

```text
X-Env-Trait-pi5-Desc: Raspberry Pi 5 - BCM2712 platform (quad Cortex-A76)
X-Env-Trait-pi5-Valid: bool
X-Env-Trait-pi5-Triggers:
 when=y set (hw:soc:bcm2712)=y
 when=y set (hw:pcie:bus)=y
 when=y set (hw:storage:sd)=y
 when=y set (hw:eeprom:rpi)=y
 when=y set (hw:wlan:broadcom)=y
 when=y set (hw:bluetooth:broadcom)=y
 when=y set (hw:ethernet)=y
 when=y set (boot:gpt)=y
 when=y set (boot:rpi:dtbootpartn)=y
```
Tokens:
Raw