image-base - Layer Documentation

Additional Documentation

Common Attributes

Different image layers are provided to support image generation with a specific footprint while allowing for customisation. Unless otherwise stated, the following apply to all image layers:

Provider

rpi-image-gen uses genimage for creating filesystem images.

Default Partition Size

Each partition image encapsulated in a disk image has a default size. Typically this is 100% of the filesystem that is created and filled, which means there is no headroom if the filesystem is intended to be writable. Customisation of images should involve setting variables governing size accordingly if the default is not suitable. 100% is likely a suitable size if the partition contains a read-only filesystem such as squashfs.

mke2fs.conf

In order to ensure ext filesystems are created consistently, image creation involves genimage using a particular mke2fs.conf. Additional options may be passed to mke2fs via the genimage template.

vfat

When creating FAT filesystems, different options may be passed to mkdosfs(8) by genimage depending on needs.

Ramdisk Boot

The Raspberry Pi device boot flow supports loading a FAT image named boot.img and using it as the boot filesystem. This is selected by boot_ramdisk=1 in config.txt. When secure boot is enabled, the device only boots this way and verifies boot.img against a detached boot.sig alongside it.

An image layer builds the boot filesystem and declares an 'outer' partition image to carry it:

image bootpartition.vfat {
   vfat {
      label = "BOOT"
      file boot.img { image = "bootfiles.img" }
   }
   size = <BOOT_SIZE>
   exec-post = "bootimg ramdisk bootfiles.img"
}

bootimg is a thin utility shipped by rpi-image-gen which provides an abstraction for boot image file generation. It can be used with genimage templates and provides a documented interface to support custom signing commands, for example to support an HSM flow.

bootimg ramdisk writes the config.txt setting boot_ramdisk=1 and adds it, together with the signature file, into the outer image. Where the image containing the bootfiles is served whole instead of carried in a partition (eg, boot.img over rpiboot), bootimg sign writes the signature alongside it.

In the example fragment above, the already generated image bootfiles.img is added, under the name boot.img, to the partition image bootpartition.vfat being created. boot.img is the name the bootloader looks for. bootimg ramdisk is given the generated image’s name because that is the file it signs, and does not need a full path because it resolves one against $OUTPUTPATH which genimage supplies in the hook environment.

Signing

IGconf_image_bootsign_cmd specifies the signing command that bootimg will execute to generate the signature file. It is invoked with three arguments:

$1

Image to sign.

$2

Size of the image in bytes.

$3

Path to write the signature to.

A non-zero exit fails the build.

No key is passed - the command determines that for itself. This keeps the interface indifferent to a local key, a PKCS#11 token, an HSM or a remote signing service. rpi-eeprom-digest produces signatures in the form the bootloader expects, so a command can map $1 and $3 onto its -i and -o arguments and supply the key itself.

The command runs with a defined set of environment variables including USER, PATH, HOME, SHELL, SSH_AUTH_SOCK and SOURCE_DATE_EPOCH. Image and device identity information is provided via IGconf_ variables which enables a key/flow to be selected per product or device class.

An example signing flow using SSH is shown below. The image goes up stdin and the signature comes back on stdout:

#!/bin/sh
set -eu
ssh $USER@signer "SOURCE_DATE_EPOCH=$SOURCE_DATE_EPOCH sign-boot-image" < "$1" > "$3"

The path to this script would be set in IGconf_image_bootsign_cmd.

Sparse Images

Image layers create sparse images by default. Sparse format means filesystem images with lots of empty space can be transferred and written to device storage in a much shorter time using fastboot when compared with primitive tools such as dd. Other utilities such as bmaptool provide a similar much-improved way for storage handling of large images. Because genimage can create sparse images itself, this removes the need to use AOSP tools in the image creation flow.

Warning

Older versions of genimage can be problematic when creating sparse images. For example, genimage v16 currently shipping in Debian Bookworm does not create usable sparse images of vfat filesystems. Raspberry Pi provisioning tools such as rpi-sb-provisioner (https://github.com/raspberrypi/rpi-sb-provisioner) rely on sparse image format, so it is recommended to use the most up-to-date version of genimage as possible.

Relationships

Depends on:

Required by:

Requires Provider: device

Configuration Variables

References: IGconf_sys_workroot, IGconf_artefact_version

Declares (prefix: image):

Variable	Description	Default	Validation	Policy
`IGconf_image_suffix`	The base suffix of generated raw image(s)	`img`	Non-empty string value	immediate
`IGconf_image_compression`	Compression scheme for generating image assets, eg update payloads. Downstream layer implementation-dependent.	`<disabled>`	Non-empty string value	skip
`IGconf_image_version`	Version string of generated images. This always maps to the artefact version.	`${IGconf_artefact_version}`	Non-empty string value	force
`IGconf_image_name`	The base name for all generated images	`rpi-${IGconf_image_version}`	Non-empty string value	immediate
`IGconf_image_idp_enable`	Generate an Image Description Provisioning (IDP) document for this image. Set automatically for Raspberry Pi devices. See https://raspberrypi.github.io/rpi-image-gen/provisioning/index.html	`n`	Boolean value - accepts: true/false, 1/0, yes/no, y/n (case insensitive)	lazy
`IGconf_image_pmap`	Set the identifier string for the image Provisioning Map (PMAP). The PMAP file defines how the image will be provisioned on the device for which it's intended. The PMAP is part of the Image Description JSON file generated by the build. Providing a PMAP is optional, but is mandatory for provisioning the image using Raspberry Pi tools.	`<empty>`	String value (may be empty)	lazy
`IGconf_image_pmap_schema`	Image Description PMAP schema for validation	`${@IGROOT}/layer/rpi/schemas/provisionmap/v1/schema.json`	Non-empty string value	lazy
`IGconf_image_idp_schema`	Image Description Provisioning (IDP) schema for validation	`${@IGROOT}/layer/rpi/schemas/idp/v2/schema.json`	Non-empty string value	lazy
`IGconf_image_outputdir`	Location of all image build artefacts.	`${IGconf_sys_workroot}/image-${IGconf_image_name}`	Non-empty string value	immediate
`IGconf_image_provider`	Image generation provider	`genimage`	Must be one of: genimage	lazy
`IGconf_image_assetdir`	Image specific asset location. Use this directory to hold image provider templates, geometry configuration, overlays, etc particular to the image layout.	`/dev/null`	Non-empty string value	lazy
`IGconf_image_bootsign_cmd`	Command producing a detached signature for a boot image. Unset leaves images unsigned.	`<disabled>`	Non-empty string value	skip
`IGconf_image_rootfs_type`	Root filesystem type. Implementation-dependent. May set host tooling requirements / dependencies.	`none`	Non-empty string value	skip

Variable

Description

Default

Validation

Policy

IGconf_image_suffix

The base suffix of generated raw image(s)

img

Non-empty string value

immediate

IGconf_image_compression

Compression scheme for generating image assets, eg update payloads. Downstream layer implementation-dependent.

<disabled>

Non-empty string value

skip

IGconf_image_version

Version string of generated images. This always maps to the artefact version.

${IGconf_artefact_version}

Non-empty string value

force

IGconf_image_name

The base name for all generated images

rpi-${IGconf_image_version}

Non-empty string value

immediate

IGconf_image_idp_enable

Generate an Image Description Provisioning (IDP) document for this image. Set automatically for Raspberry Pi devices. See https://raspberrypi.github.io/rpi-image-gen/provisioning/index.html

n

Boolean value - accepts: true/false, 1/0, yes/no, y/n (case insensitive)

lazy

IGconf_image_pmap

Set the identifier string for the image Provisioning Map (PMAP). The PMAP file defines how the image will be provisioned on the device for which it's intended. The PMAP is part of the Image Description JSON file generated by the build. Providing a PMAP is optional, but is mandatory for provisioning the image using Raspberry Pi tools.

<empty>

String value (may be empty)

lazy

IGconf_image_pmap_schema

Image Description PMAP schema for validation

${@IGROOT}/layer/rpi/schemas/provisionmap/v1/schema.json

Non-empty string value

lazy

IGconf_image_idp_schema

Image Description Provisioning (IDP) schema for validation

${@IGROOT}/layer/rpi/schemas/idp/v2/schema.json

Non-empty string value

lazy

IGconf_image_outputdir

Location of all image build artefacts.

${IGconf_sys_workroot}/image-${IGconf_image_name}

Non-empty string value

immediate

IGconf_image_provider

Image generation provider

genimage

Must be one of: genimage

lazy

IGconf_image_assetdir

Image specific asset location. Use this directory to hold image provider templates, geometry configuration, overlays, etc particular to the image layout.

/dev/null

Non-empty string value

lazy

IGconf_image_bootsign_cmd

Command producing a detached signature for a boot image. Unset leaves images unsigned.

<disabled>

Non-empty string value

skip

IGconf_image_rootfs_type

Root filesystem type. Implementation-dependent. May set host tooling requirements / dependencies.

none

Non-empty string value

skip