YAML Configuration Syntax

YAML configuration syntax

Factory reads three YAML document types. The rootfs document describes APT repositories, package roots, exclusions, and the rootfs archive. The package snapshot document selects .deb files from one APT repository. The ISO document describes the rootfs archive, external asset directory, stage order, output paths, and SquashFS settings.

1. Rootfs document

A rootfs document has three top-level sections: buildinfo, base (or its packages alias), and the optional exclude list. buildinfo.distrorepo is required. At least one package name must be supplied through base or packages.

1.1 buildinfo keys

Key	Type	Required	Meaning
rootfs	path string	No	Target chroot directory. Defaults to build/rootfs; relative paths are resolved from the command's working directory.
archive	path string	No	Output archive path. If omitted, Factory derives the filename and extension from the rootfs path and selected compression. Relative paths are resolved from the command's working directory.
compression	string	No	Rootfs archive compressor: gzip, xz, bzip2, or zstd. Defaults to xz.
compression_level	integer	No	Compressor level. Defaults are gzip 6, xz 6, bzip2 9, and zstd 3. Valid 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 APT repository definitions. A mapping may contain the list under base. Every repository in one rootfs build must use the same architecture.

The selected compressor must be installed on the build host. The archive preserves numeric ownership, ACLs, and extended attributes.

1.2 Repository entry keys

Each item in distrorepo describes one APT source and its signing-key source. The YAML always supplies the URL; Factory does not choose a mirror from a distribution name.

Key	Type	Required	Meaning
name	string	No	Repository label used in generated keyring filenames and build messages.
url	URL string	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 repository 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	Signing-key URL. Exactly one of key_url and keyring must be set.
keyring	path string	One of two	Local signing-key file. Relative paths are resolved from the rootfs YAML file's directory.
distro	string	No	Repository metadata. The value debian-snapshot disables APT Valid-Until checking by default.
check_valid_until	boolean	No	Explicitly enables or disables APT Valid-Until checking; overrides the distro default.

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

1.3 Package selection and exclusions

base is the YAML package list. packages is accepted when base is absent. The list must not be empty. Factory first installs its fixed minbase baseline, then installs these YAML package roots in a second APT transaction. APT adds the required dependency closure but does not add recommendations or suggestions.

The baseline consists of APT, Debian base files and account data, a shell and core utilities, dpkg, package-management support, and the utilities needed to run package scripts. ca-certificates is added when any configured repository uses HTTPS. Repository priority and Essential metadata do not expand the fixed baseline.

exclude is an optional list of package names. APT pins these names so they cannot be installed as baseline packages, requested packages, or dependencies. If a requested package requires an excluded package, the build fails rather than silently adding it.

2. Package snapshot document

A snapshot document selects packages from one repository index.

Key	Type	Required	Meaning
repo_url	URL string	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 string	Yes	Destination for downloaded .deb files. Relative paths are resolved from the command's working directory.
packages	string or list of strings	Yes	Package names to locate. A string may separate names with whitespace or commas; architecture qualifiers are ignored.

The downloader reads the compressed package index, checks each package's SHA-256 before replacing a destination file, and reports names missing from the selected index. If none of the requested packages are available, the command fails.

3. ISO document

An ISO document has one top-level iso mapping. It must identify exactly one local rootfs archive or remote rootfs URL.

3.1 iso keys

Key	Type	Required	Meaning
rootfs	path string or mapping	Yes	Local archive path, or a mapping containing one of path or url. A mapping may also contain sha256 or sha256_url.
data_dir	path string	Yes	External ISO asset directory. Relative paths are resolved from the ISO YAML file's directory. The directory must contain bootstrap, configs/scripts/stages, configs/scripts/others, configs/files/grub_files, and tooling/runch and tooling/mkiso.
output_dir	path string	No	Output directory. Defaults to build-artifacts; relative paths are resolved from the ISO YAML file's directory.
image	filename	No	ISO output filename. It must be a filename ending in .iso; defaults from the selected flavor.
volume_label	string	No	ISO volume label, from 1 to 32 characters.
flavor	string	No	mesa or nvopen. Defaults to mesa; NVOpen-only repository and driver changes are enabled for nvopen.
prepare_host	boolean	No	Runs the externally supplied 00-install-host-packages stage before the build. Defaults to true; that file must exist under the asset directory's stage directory.
work_dir	path string	No	Parent directory for temporary build files. Relative paths are resolved from the ISO YAML file's directory.
stages	list of strings	Yes	Ordered filenames of ISO stages under the external asset directory's configs/scripts/stages directory. There is no default sequence. Names cannot repeat or refer to the separately run host-dependency stage.
squashfs	mapping	No	SquashFS compressor and filesystem creation settings.

For a local rootfs.path, sha256 is optional. For a remote rootfs.url, either sha256 or an HTTP(S) sha256_url is required. The checksum is verified before extraction. Paths inside the rootfs mapping are resolved from the ISO YAML file's directory. The asset directory is supplied by the user and is not included in Factory. It provides the bootstrap runner, stage scripts, supporting configuration files, and ISO tooling used by the selected build.

3.2 squashfs keys

Key	Type	Required	Meaning
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). The xz compressor does not accept this setting. 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.

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