================================== Genimage - The Image Creation Tool

genimage is a tool to generate multiple filesystem and flash/disk images from a given root filesystem tree. genimage is intended to be run in a fakeroot environment. It also supports creating flash/disk images out of different file-system images and files.

Configuration is done in a config file parsed by libconfuse. Options like the path to tools can be given via environment variables, the config file or from commandline switches.

The Configuration File

The config file of genimage uses a simple configuration language, provided by libconfuse_. This supports nested sections, as well as simple key-value pairs.

.. _libconfuse: https://github.com/libconfuse/libconfuse

Single-line comments can be introduced with # or //, multi-line comments look like /* … */ (as in C).

The config file is separated into the main sections image, flash and config, and provides an include primitive.

The image section

An image section describes a single filesystem or disk image to be built. It can be given multiple times to generate multiple images. An image can also have multiple partitions which refer to images themselves. Each image must have a type which can have different suboptions depending on the type.

Let's have a look at an example::

image nand-pcm038.img { flash { } flashtype = "nand-64M-512" partition barebox { image = "barebox-pcm038.bin" size = 512K } partition root { image = "root-nand.jffs2" size = 24M } }

This would generate a nand-pcm038.img which is a flash of type "nand-64M-512" The image contains two partitions, "barebox-pcm038.bin" and "root-nand.jffs2" which must refer to images described elsewhere in the config file. For example "root-nand.jffs2" partition could be described like this::

image root-nand.jffs2 { name = "root" jffs2 {} size = 24M mountpoint = "/" }

In this case a single jffs2 image is generated from the root mountpoint.

Here are all options for images:

:name: The name of this image. This is used for some image types to set the name of the image. :size: Size of this image in bytes. 'k', 'M' or 'G' can be used as suffix to specify the size in multiple of 1024 etc. The suffix 's' specifies a multiple of the (traditional) sector size of 512. If the image if filled from a mountpoint then '%' as suffix indicates a percentage. '200%' means the resulting filesystem should be about 50% filled. Note that is is only a rough estimate based on the original size of the content. :mountpoint: mountpoint if image refers to a filesystem image. The default is "/". The content of "${rootpath}${mountpoint}" will be used to fill the filesystem. :srcpath: If this is set, specified path will be directly used to fill the filesystem. Ignoring rootpath/mountpoint logic. Path might be absolute or relative to current working directory. :empty: If this is set to true, then the specified rootpath and mountpoint are ignored for this image and an empty filesystem is created. This option is only used for writeable filesystem types, such as extX, vfat, ubifs and jffs2. This defaults to false. :temporary: If this is set to true, the image is created in tmppath rather than outputpath. This can be useful for intermediate images defined in the configuration file which are not needed by themselves after the main image is created. This defaults to false. :exec-pre: Custom command to run before generating the image. Available variables are documented in the Environment Variables_ section below. :exec-post: Custom command to run after generating the image. :flashtype: refers to a flash section. Optional for non flash like images like hd images. :partition: can be given multiple times and refers to a partition described below. The section title will be use as the partition label (only with GPT).

Additionally each image can have one of the following sections describing the type of the image:

cpio, cramfs, custom, erofs, ext2, ext3, ext4, f2fs, file, flash, hdimage, iso, jffs2, mdraid, qemu, squashfs, tar, ubi, ubifs, verity, verity-sig, vfat.

Partition options:

:offset: The offset of this partition as a total offset to the beginning of the device. :size: The size of this partition in bytes. If the size and autoresize are both not set then the size of the partition image is used. :align: Alignment value to use for automatic computation of offset and size. Defaults to 1 for partitions not in the partition table, otherwise to the image's align value. :partition-type: Used by dos partition tables to specify the partition type. :image: The image file this partition shall be filled with :imageoffset: The offset within the partition image to start reading from. :fill: Boolean specifying that all bytes of the partition should be explicitly initialized. Any bytes beyond the size of the specified image will be set to 0. :sparse: If true (the default) 'holes' in the input images are preserved and the remaining free space in the partition is also a 'hole'. If false, the 'holes' in the input image are explicitly filled with zeros when the image is copied. If the partition has no image, the whole partition content is a 'hole'. If fill is specified as well then the remaining free space is also filled with zeros. :autoresize: Boolean specifying that the partition should be resized automatically. For UBI volumes this means that the autoresize flag is set. Only one volume can have this flag. For hd images this can be used for the last partition. If set the partition will fill the remaining space of the image. :bootable: Boolean specifying whether to set the bootable flag. :hidden: Boolean specifying whether to set the hidden flag (only with GPT). :no-automount: Boolean specifying whether to set the no-automount flag (only with GPT). :read-only: Boolean specifying whether to set the read-only flag (only with GPT). :in-partition-table: Boolean specifying whether to include this partition in the partition table. Defaults to true. :forced-primary: Force this partition to be a primary partition in the MBR partition table, useful when the extended partition should be followed by primary partitions. If there are more partitions defined after the first forced-primary, they must be also defined as forced-primary. Defaults to false. :partition-uuid: UUID string used by GPT partition tables to specify the partition id. Defaults to a random value. :partition-type-uuid: String used by GPT partition tables to specify the partition type. Either a UUID or a shortcut:

		* ``L``, ``linux``, ``linux-generic``: Linux filesystem (0fc63daf-8483-4772-8e79-3d69d8477de4)
		* ``S``, ``swap``: Swap (0657fd6d-a4ab-43c4-84e5-0933c84b4f4f)
		* ``H``, ``home``: Home (933ac7e1-2eb4-4f13-b844-0e14e2aef915)
		* ``U``, ``esp``, ``uefi``: EFI System Partition (c12a7328-f81f-11d2-ba4b-00a0c93ec93b)
		* ``R``, ``raid``: Linux RAID (a19d880f-05fc-4d3b-a006-743f0f84911e)
		* ``V``, ``lvm``: Linux LVM (e6d6d379-f507-44c2-a23c-238f2a3df928)
		* ``F``, ``fat32``: FAT32 / Basic Data Partition (ebd0a0a2-b9e5-4433-87c0-68b6b72699c7)
		* ``barebox-state`` (previously ``B``): Barebox State (4778ed65-bf42-45fa-9c5b-287a1dc4aab1)
		* ``barebox-env``: Barebox Environment (6c3737f2-07f8-45d1-ad45-15d260aab24d)
		* ``u-boot-env``: U-Boot Environment (3de21764-95bd-54bd-a5c3-4abe786f38a8)

		Furthermore, for ``{arch}`` being one of ``alpha``,
		``arc``, ``arm``, ``arm64``, ``ia64``, ``loongarch64``,
		``mips``, ``mips64``, ``mips-le``, ``mips64-le``, ``parisc``, ``ppc``,
		``ppc64``, ``ppc64-le``, ``riscv32``, ``riscv64``,
		``s390``, ``s390x``, ``tilegx``, ``x86``, ``x86-64``,
		the following shortcuts from the `Discoverable
		Partitions Specification <dps-spec_>`_ are accepted (see the spec
		for the respective UUIDs):

		* ``root-{arch}``: Root Partition
		* ``usr-{arch}``: /usr Partition
		* ``root-{arch}-verity``: Root Verity Partition
		* ``usr-{arch}-verity``: /usr Verity Partition
		* ``root-{arch}-verity-sig``: Root Verity Signature Partition
		* ``usr-{arch}-verity-sig``: /usr Verity Signature Partition
		* ``xbootldr``: Extended Boot Loader Partition
		* ``srv``: Server Data Partition
		* ``var``: Variable Data Partition
		* ``tmp``: Temporary Data Partition
		* ``user-home``: Per-user Home Partition

		Custom shortcuts can be defined in the global ``config`` section::

		  config {
			gpt-shortcuts {
				forty-two = "2a422a42-2a42-2a42-2a42-2a422a422a42"
			}
		  }

		Defaults to ``L``.

.. _dps-spec: https://uapi-group.org/specifications/specs/discoverable_partitions_specification/

For each partition, its final alignment, offset and size are determined as follows:

• If the align option is not present, it defaults to the value of the image's align option if the partition is in the partition table, otherwise to 1.

• If the offset option is absent or zero, and in-partition-table is true, the partition is placed after the end of all previously defined partitions, with the final offset rounded up to the partition's align value.

• Otherwise, the offset option is used as-is. Note that if absent, that option defaults to 0, so in practice one must specify an offset for any partition that is not in the partition table (with at most one exception, e.g. a bootloader).

• If the partition has the autoresize flag set, its size is computed as the space remaining in the image from its offset (for a GPT image, space is reserved at the end for the backup GPT table), rounded down to the partition's align value. If the partition also has a size option, it is ensured that the computed value