Table of Contents

← Back to Main Documentation

IDP (Image Description Provisioning)

IDP enables secure, flexible device provisioning by bridging rpi-image-gen with rpi-sb-provisioner using a JSON description of your image. IDP supports any partition layout (not just Raspberry Pi OS distribution images) which means it’s possible to securely provision completely custom images on your Raspberry Pi device.

How it works:

  1. Generate - rpi-image-gen creates an image description JSON file

  2. Send - Client transfers the description to device

  3. Validate - Device verifies compatibility (model, storage requirements, security attributes)

  4. Prepare - Device creates partition tables, LUKS containers, etc.

  5. Provision - Client writes partition images to prepared block devices

IDP acts as a "smart block device creation tool" that prepares device storage and orchestrates secure image deployment through a defined protocol.

Transport Protocol

IDP was designed to be transport medium agnostic. The current implementation uses fastboot as the transport protocol, which allows it to interoperate with devices running the pi-gen-micro fastboot gadget.

JSON Structure

The image description is split into two components using a simple schema:

  • Image layout - partition table and individual image information, sizes, filesystem types, attributes, metadata

  • Provisioning map (PMAP) - defines how the image will be provisioned on-device, e.g. partitions to encrypt, security attributes to use

If an image layer is to support IDP, it must declare support of a provisioning map in its config settings and install the applicable JSON fragment as ${IGconf_image_outputdir}/provisionmap.json. Typically this is handled by image layer specific hooks. If installed, rpi-image-gen will automatically include the PMAP in the final image description file (image.json). Please refer to the individual layer documentation for available PMAP options.

Benefits:

  • Smart provisioning - Device validates before writing

  • Flexible layouts - Support custom partition schemes

  • Encryption support - Integrates with LUKSv2, signed boot and industry standard encryption flows

  • Secure workflow - Validation at every step

Dependencies

IDP requires fastboot to be installed in the client. On Debian systems, this can be installed using sudo apt install fastboot. Sparse format images are used when writing to device storage and rpi-image-gen image layers create sparse images by default using genimage. This avoids reliance on any external tooling, such as AOSP utilities. Using sparse format means 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 and IO transfer.

Warning

Raspberry Pi provisioning tools such as rpi-sb-provisioner (https://github.com/raspberrypi/rpi-sb-provisioner) rely on sparse images, so rpi-image-gen ships its own up-to-date genimage to avoid compatibility problems seen with older distribution versions.

Usage:

To use IDP without rpi-sb-provisioner:

  1. Become familiar with rpiboot (https://github.com/raspberrypi/usbboot)

  2. Build the pi-gen-micro fastboot gadget (https://github.com/raspberrypi/pi-gen-micro)

  3. Boot the fastboot gadget on the target device

  4. From your client, provision your image on the target device using rpi-image-gen’s helper:

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

It’s also possible to issue conventional fastboot commands from the client to the device. For example, to write a sparse image to device storage:

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

rpi-sb-provisioner will gain support for IDP which will enable seamless integration and secure deployment of rpi-image-gen created images on your Raspberry Pi device. Refer to the rpi-sb-provisioner documentation for further details.