2023-10-25
IMGBUILD - makeimg image build description file
This manual page is about the syntax and semantics of IMGBUILD files. Once an IMGBUILD is written, the image can be built with makeimg(1).
An IMGBUILD file is a declarative definition of most aspects of a Linux disk image to be built with makeimg(1). However, some aspects are controlled by files other than the IMGBUILD file, usually in the same directory. See makeimg(1) for details.
The basic syntax of an IMGBUILD file is that of a POSIX-compliant shell script. A set of variables and functions can be defined. Their semantics are described in this file. All variables described here must be strings. Variables that can have multiple values (e.g. packages) must be a multi-line string with one value per line.
imgname
A name for the image. Mostly informational, potentially influences the output file name (see format).
target
The build target. Must be one of 'arch', 'alpine', or 'debian'.
debian_suite
If target is 'debian', specify the suite to be installed. Defaults to 'stable'.
format
The output format of the disk image. Supported values are:
raw SIZE PARTTYPE FILESYSTEM
Creates a single raw diskimage, <imgname>.img. The SIZE parameter is passed to truncate(1). The PARTTYPE parameter is passed to parted(8), but only "msdos" or "gpt" are supported. The FILESYSTEM parameter can be anything that mkfs(8) accepts as --type argument. Parameters have to be in order, but any number of them can be omitted to use the default values: raw 8G msdos ext4.
tar COMPRESSION
Creates a compressed tarball, <imgname>.tar.<COMPRESSION>. The file type must be handled by the local tar(1).
dir
Creates a directory called `<imgname>`. Can be used to create e.g. chroot(1) environments or OCI bundles.
custom
Output format and naming are defined by the setup and cleanup functions in the IMGBUILD build.
hostconf
Specify config items to be copied from the host building the image. Add keyring to install the host's pacman keyring or apk keys onto the image. Otherwise the keyring must be installed manually via files or by running pacman-key(8) in the provision script. Add mirrorlist to install the host's mirrorlist/repositories. Otherwise the mirrorlist must be installed manually by supplying a file or a patch to the default mirrorlist or some custom solution in the provision script. Default is to not use anything from the host.
packages
The packages to install into the image. Passed to pacstrap(8) or apk(8).
passwords
Set login passwords from secrets (see makeimg(1)). Format is <USER>:<SECRET_NAME>. The users must exist. Passwords are set after provisioning, so users can be created there. The passwords must be pre-encrypted to avoid issues with cross-platform builds. See any of the examples included with the source code.
services
The services to enable in the image (systemd on Arch and Debian, OpenRC on Alpine). This happens as the very last step, so it can also be used to enable custom services that were created e.g. by providing custom unit files. For Alpine, the runlevel to add the service to can appended using a colon, e.g. networking:boot. If not specified, the service is added to the default runlevel.
In addition to the special variables documented here, custom variables can be defined at will, e.g. for use in templates.
All of the above variables such as $imgname and $packages are available for use in the customization functions. In addition, makeimg defines the following variables:
PART
The partition mounted to the image root. Only available in the provision() function.
BLKDEV
The block device that PART is on. Only available in the provision() function.
imgroot
The directory at which the setup() function has to prepare the chroot, e.g. the target of the base mount.
The customization functions are:
setup()
This function should prepare the working directory (located at $imgroot) so that bootstrapping can be performed. A setup function for a multi-partition raw image for example would create the image, mount the root partition at $imgroot, create directories for other partitions, and mount them accordingly.
cleanup()
This function should clean up any mounts or similar actions performed during setup. It is executed in the same context as the setup, so any variables set in setup() can be referenced.
provision()
Runs in the context of the image (chrooted). This function should perform all desired modifications to the image that cannot be expressed in any of the other directives.
makeimg(1), pacstrap(8), apk(1)
This project is maintained by Conrad Hoffmann <ch@bitfehler.net>. The source code can be found at https://git.sr.ht/~bitfehler/makeimg. Bugs or patches can be submitted by email to ~bitfehler/anemos@lists.sr.ht.