The build spec

14 min read

peiso.toml is the declarative TOML spec that drives peiso. A single file describes the whole bootable image: the peipkg-compose manifest to build the package root from, how the initramfs is packed, and the optional squashfs, UKI, ISO, registry-seed and feature stages that the build pipeline layers on top. This page documents schema version 1 — the only schema peiso accepts — field by field.

The spec is passed to peiso positionally and defaults to peiso.toml in the current directory:

sudo peiso build [spec.toml]

Three properties hold across the whole file:

• TOML, parsed strictly. An unknown key anywhere in the spec is a hard error, not a warning — peiso rejects the first undecoded key by name. A mistyped field fails the build rather than being silently ignored.
• schema is checked first. The spec must declare schema = 1; any other value (or a missing schema, which reads as 0) fails with unsupported schema.
• Relative paths resolve against the spec file's own directory — never the current working directory. So a build behaves the same wherever you invoke it from. There are two kinds of path handling, and each field uses one of them:
  • Spec-relative paths (root.manifest, root.out, initramfs.manifest, squashfs.out, uki.cmdline_file, iso.source, iso.out, inject.src) are made absolute against the spec's directory. An already-absolute value is kept as given.
  • Root-relative paths (initramfs.dir, initramfs.cpio, uki.out, iso.efi_boot, inject.dest) are cleaned and kept relative (any leading / is stripped). These double as chroot-absolute paths inside the composed root, so they are validated to not escape with .. (see Validation).

A complete example #

A full spec that composes a root, packs the initramfs, squashes the rootfs, builds a UKI, emits a bootable ISO, and enables a feature on first boot:

schema      = 1
source_date = "2026-06-22T00:00:00Z"   # pins reproducible build timestamps

# Let packages declaring `special_system_package` compose outside the layout
# rules. Needed by any image carrying the base-filesystem package, whose whole
# job is to lay down the mountpoint tree those rules protect.
bypass_path_restrictions = true

# The whole image. manifest.toml is multi-root — it composes the main system
# root into `out` and the nested initramfs root (at out/boot/initramfs) in one
# pass, so [initramfs] below needs no manifest of its own.
[root]
manifest = "manifest.toml"
out      = "root"

# How mkirf packs the already-composed initramfs root into a cpio. `dir` and
# `cpio` are root-relative: inside the chroot they are mkirf's /<dir> source and
# /<cpio> output. The peipkg database isn't needed at early boot, so it's excluded.
[initramfs]
dir     = "boot/initramfs"
cpio    = "system/boot/initramfs.cpio.gz"
exclude = ["var/state/peipkg", "lcl/conf/peipkg"]

# Read-only rootfs image, squashed from the WHOLE composed root. `out` is written
# OUTSIDE root/ so the image can never contain itself.
[squashfs]
out         = "rootfs.squashfs"
compression = "zstd"

# Unified Kernel Image: kernel + initramfs cpio + cmdline in one EFI binary.
# cmdline_file is read from the composed root, so build-time and runtime agree.
[uki]
cmdline_file = "root/usr/share/live-boot/cmdline"
out          = "boot/efi/EFI/BOOT/BOOTX64.EFI"

# Bootable UEFI ISO built from the ESP tree at `source`, with the UKI marked as
# the EFI boot image at `efi_boot` (relative to source).
[iso]
source   = "root/boot/efi"
efi_boot = "EFI/BOOT/BOOTX64.EFI"
out      = "peios.iso"
label    = "PEIOS"

# Features this image enables on first boot (feat add <name>).
[features]
enable = ["dynamic-boot"]

[squashfs], [uki], [iso], [registry] and [features] are all optional — a minimal spec is just schema, [root] and [initramfs], which composes the root and packs the initramfs.

Top-level fields #

[root] — the package root (required) #

The main system root, composed by shelling out to peipkg-compose build. Both keys are required.

[[root.inject]] #

Each entry copies one file into the composed main root, after compose and before every stage that reads the root — so an injected file is visible to the registry-seed staging, the squashfs, and the UKI. src and dest are both required.

An injected file has no package owner, so peipkg will not upgrade, verify or remove it. That cost is the reason to prefer a package for anything images should get properly. What it buys is a home for the composing artifact's own contributions — an image-specific registry seed, a boot script — which is the same authority peiso already exercises when it stages the seed queue and the autorun script into /lcl/policy.

The common pairing is a seed: inject a .reg master to usr/share/regim/<name> and name it in [registry] autoapply. The inject runs first, so by the time the queue is built the seed is indistinguishable from one a package shipped.

[initramfs] — packing the initramfs (required) #

Describes how peiso packs the initramfs root into a cpio archive using the composed root's own mkirf applet, run inside the chroot. dir and cpio are required; the rest are optional.

[[initramfs.inject]] (temporary) #

Each entry copies one file into the initramfs root before it is packed. This is a transitional mechanism — the intended path is to ship such files in a package so a cross-root dependency pulls them into the initramfs root during compose. src and dest are both required.

[squashfs] — the read-only rootfs image (optional) #

When present, peiso squashes the whole composed root into a read-only image (the live-boot lower layer). Presence of the table is what turns the stage on; out is then required.

[uki] — the Unified Kernel Image (optional) #

When present, peiso bundles a UKI — kernel + initramfs cpio + kernel cmdline in one EFI binary — using the composed root's own mkuki applet in the chroot. You must supply the cmdline exactly one way: cmdline or cmdline_file, never both and never neither.

[iso] — the bootable ISO (optional) #

When present, peiso emits a UEFI-bootable ISO9660 image (via xorriso) from an ESP tree. source, efi_boot and out are required; label defaults.

[[iso.include]] #

Places a file or a whole directory tree into the ISO9660 data area — the part of the medium that is neither the ESP nor the boot chain. Repeatable.

peiso already puts the rootfs squashfs in the data area; this makes the same space available to the image.

[[iso.include]]
src  = "repo"
dest = "repo"

Data-area content is not in the squashfs, which is the point. It costs nothing in the root filesystem, is not decompressed at boot, and — because the squashfs is byte-identical to an installed root — is not inherited by machines installed from the medium. An installation medium can carry a package repository without imposing one on every system installed from it.

Files are hard-linked into the staging tree where the filesystems allow it, so including a large tree that already exists in the build directory costs no extra space or time.

[registry] — registry seeds auto-applied on first boot (optional) #

Selects which vendor registry-seed masters (shipped by packages into /usr/share/regim/) this image auto-applies on first boot. peiso stages each into the composed root's autoapply queue; peinit drains it at first boot. Selection lives here, in the image, not in the packages.

[features] — features enabled on first boot (optional) #

Selects which curated features (shipped by packages into /usr/libexec/features/ and exposed at runtime through /libexec/features/) this image enables on first boot. peiso writes a self-removing autorun script of feat add <name> lines; peinit runs it before Phase 2, so the services a feature creates start the same boot.

Validation #

peiso loads, decodes and validates the spec before running anything. The rules, exactly as enforced:

• Unknown keys are rejected. Any key the schema does not define — at any level — fails the build, naming the first offending key.
• Schema gate. schema must equal 1, or the build fails with unsupported schema.
• Required fields. root.manifest, root.out, initramfs.dir and initramfs.cpio must all be present and non-empty. Within an optional table that is present, its own required keys apply: squashfs.out; uki.out; iso.source, iso.efi_boot and iso.out; and both src and dest on every inject entry, in [[root.inject]] and [[initramfs.inject]] alike.
• No-escape path checks. The root-relative paths initramfs.dir, initramfs.cpio, uki.out, iso.efi_boot and every inject.dest (both roots) may not be .. or begin with ../ — they become chroot-absolute paths and must stay inside their tree. (Spec-relative paths are not subject to this check; they resolve to absolute paths.)
• UKI cmdline mutual-exclusion. When [uki] is present, exactly one of cmdline or cmdline_file must be set. Supplying both, or neither, is an error.
• Registry seeds must be bare filenames. Each registry.autoapply entry must be non-empty and contain no path separator (it must equal its own basename); a path component is a spec error.
• Feature-name grammar. Each features.enable entry must be non-empty, must not be . or .., and must consist only of ASCII alphanumerics plus -, _ and .. This mirrors feat's own name grammar and doubles as a guard against shell metacharacters, since the name is embedded in a generated feat add line.
• Inject mode. inject.mode, when set, must parse as an octal integer; a malformed value fails the build. Applies to both inject tables.

A spec that passes all of these checks is what the build pipeline runs.

See also #

• Building a Peios image — what peiso is and where it sits above compose.
• The build pipeline — the stage each table drives, in run order.
• Running a build — the command, exit codes, and required tools.

Edit this page