YAML Configuration Syntax

Introduction

This page documents the sections, keys, and validation requirements for Factory YAML files.

Note

The examples use placeholder package names and reserved .invalid domains; replace them with values from your own configuration.

1. Syntax description

Each document describes one operation. The rootfs and ISO documents use top-level mappings; a package snapshot document uses top-level keys.

Rootfs document
├── buildinfo
│   ├── rootfs
│   ├── archive
│   ├── compression
│   ├── compression_level
│   └── distrorepo
├── base or packages
└── exclude

Package snapshot document
├── repo_url
├── suite
├── component
├── architecture
├── output_dir
└── packages

ISO document
└── iso
    ├── rootfs
    ├── data_dir
    ├── grub_theme
    ├── stages
    ├── prepare_host
    ├── output_dir, image, volume_label, work_dir
    └── squashfs
        ├── compression
        ├── level
        ├── block_size
        └── memory

2. Rootfs document

buildinfo.distrorepo is required. One non-empty package list is required: base, or packages when base is absent.

2.1 buildinfo keys

Key	Type	Required	Description
rootfs	path	No	Target chroot directory. Defaults to build/rootfs. Relative paths use the command's working directory.
archive	path	No	Output archive path. Defaults to a name derived from the rootfs path and compression. Relative paths use the command's working directory.
compression	string	No	Archive format: gzip, xz, bzip2, or zstd. Defaults to xz.
compression_level	integer	No	Compression level. Defaults are gzip 6, xz 6, bzip2 9, and zstd 3. Supported ranges are gzip 1–9, xz 0–9, bzip2 1–9, and zstd 1–19.
distrorepo	list or mapping	Yes	A non-empty list of repositories. A mapping may hold the list under base. All repositories must use the same architecture.

The archive preserves numeric ownership, ACLs, and extended attributes.

2.2 Repository entries

Each distrorepo entry defines an APT source and exactly one signing-key source.

Key	Type	Required	Description
name	string	No	Repository label used in keyring filenames and build messages. Defaults to the URL hostname when available.
url	URL	Yes*	Repository base URL. uri is an alias. HTTP, HTTPS, and local file: URLs are accepted.
release	string	Yes*	APT suite or codename. suite is an alias.
arch	string	Yes*	Package architecture. architecture is an alias. All entries must agree.
components	list or string	No	APT components. Defaults to main; a string is split on whitespace.
key_url	HTTP(S) URL	One of two	URL of the repository signing key.
keyring	path	One of two	Local signing-key file. Relative paths use the rootfs YAML file's directory.
distro	string	No	Repository metadata. debian-snapshot disables APT Valid-Until checking by default.
check_valid_until	boolean	No	Enables or disables APT Valid-Until checking; overrides the distro default.

The asterisk marks values with aliases: provide one of url or uri, one of release or suite, and one of arch or architecture. Set exactly one of key_url or keyring.

2.3 Package selection and exclusions

base is a non-empty list of package roots. packages is accepted when base is absent. exclude is an optional list of package names that must not be installed.

2.4 Rootfs configuration

2.4.1 Example #1 - Multiple repositories

buildinfo:
  rootfs: build/rootfs
  archive: build/rootfs.tar.xz
  compression: xz
  compression_level: 6
  distrorepo:
    base:
      - name: primary
        url: https://packages.example.invalid/debian
        release: stable
        arch: amd64
        components: [main]
        key_url: https://packages.example.invalid/keys/archive.asc
      - name: additional
        url: https://packages.example.invalid/extra
        release: stable
        arch: amd64
        components: [main]
        keyring: keys/extra-archive.gpg
base:
  - package-one
  - package-two
exclude:
  - package-to-exclude

3. Package snapshot document

All keys in a package snapshot document are required.

Key	Type	Required	Description
repo_url	URL	Yes	Base URL of the APT repository.
suite	string	Yes	Repository suite or codename.
component	string	Yes	APT component whose package index is read.
architecture	string	Yes	Architecture used to select the binary package index.
output_dir	path	Yes	Destination for downloaded .deb files. Relative paths use the command's working directory.
packages	string or list of strings	Yes	Package names to find. A string may separate names with whitespace or commas; architecture qualifiers are ignored.

Factory tries the gzip package index and then xz. Missing package names are reported; the command fails if none of the requested packages are available.

3.1 Snapshot configuration

3.1.1 Example #1 - Package snapshot

repo_url: https://packages.example.invalid/debian
suite: stable
component: main
architecture: amd64
output_dir: package-snapshot
packages:
  - package-one
  - package-two

4. ISO document

An ISO document contains one top-level iso mapping. It must identify a rootfs archive, an asset directory, and an ordered list of stages.

4.1 iso keys

Key	Type	Required	Description
rootfs	path or mapping	Yes	Local archive path, or a mapping with one of path or url. A mapping may also contain sha256 or sha256_url.
data_dir	path	Yes	ISO asset directory. Relative paths use the ISO YAML file's directory. It must contain the bootstrap runner, stage and support scripts, GRUB files, and runch and mkiso tools.
grub_theme	path	Yes	GRUB theme directory. Relative paths use data_dir.
output_dir	path	No	Output directory. Defaults to build-artifacts; relative paths use the ISO YAML file's directory.
image	filename	No	ISO output filename ending in .iso. Defaults to system.iso.
volume_label	string	No	ISO volume label, from 1 to 32 characters.
prepare_host	boolean	No	Runs the external 00-install-host-packages stage before the build. Defaults to true; the stage file must exist in the asset directory.
work_dir	path	No	Parent directory for temporary build files. Relative paths use the ISO YAML file's directory.
stages	list of strings	Yes	Ordered stage filenames under the asset directory's configs/scripts/stages. Stage names must exist, cannot repeat, and cannot name the separately run host-dependency stage.
squashfs	mapping	No	SquashFS compression and filesystem settings.

For a local rootfs path, sha256 is optional. For a remote URL, provide sha256 or an HTTP(S) sha256_url. Factory verifies the checksum before extraction.

4.2 squashfs keys

Key	Type	Required	Description
compression	string	No	zstd, xz, gzip, lzo, or lz4. Defaults to zstd.
level	integer	No	Compression level for zstd (1–22), gzip (1–9), lzo (1–9), or lz4 (1–12). XZ does not accept a level. LZ4 levels require support in the installed mksquashfs.
block_size	integer	No	SquashFS block size from 4096 to 1048576 bytes. Defaults to 262144.
memory	size string	No	Memory limit passed to mksquashfs. Defaults to 4G.

The ISO output directory receives the image, SHA-512 checksum, stage log, package build lists, and any generated variable-data archives.

4.3 ISO configuration

4.3.1 Example #1 - ISO definition

iso:
  rootfs:
    path: ../artifacts/rootfs.tar.xz
  data_dir: assets/iso
  grub_theme: configs/files/grub_files/theme/custom
  image: product-amd64.iso
  volume_label: PRODUCT
  prepare_host: false
  stages:
    - 01-prepare-system
    - 02-build-image
  squashfs:
    compression: zstd
    level: 15
    block_size: 262144
    memory: 4G

The asset directory must contain both listed stage files. With prepare_host disabled, install the host tools before building.