Reference on Farrow

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Discovery

Configuration lookup order is explicit -f, then farrow.yml, farrow.yaml, pigsty.yml, and pigsty.yaml in the current directory. Every name uses the same Pigsty-compatible YAML Inventory format.

The retired top-level version:/nodes: format is rejected with migration guidance.

For plan, up, reload, and recreate, absence of a file falls back to the applied spec when a deployment exists. validate has no fallback. A configuration must be a regular non-symlink file no larger than 4 MiB.

CLI

Mon, 01 Jan 0001 00:00:00 +0000

farrow [--json|--yaml] [--verbose] <command> [flags] [node...]

The installed binary is the authoritative reference for its own version. Every visible command includes its operational boundary and copyable examples:

farrow --help
farrow setup --help
farrow image pull --help

In text mode, bare farrow and namespaces such as farrow image display contextual help and exit successfully. In JSON/YAML mode a bare namespace is a structured usage error; explicit --help always renders human help.

Images

Mon, 01 Jan 0001 00:00:00 +0000

Farrow uses a signed static-file Catalog plus immutable qcow2 artifacts. A Catalog update does not require a new Farrow binary, but the binary decides which signing keys and image safety rules are trusted.

Warning

EL7 is deprecated; every other built-in image is currently testing, not supported. The warning printed by up is intentional: a successful pull is an integrity result, not a production-support promise.

Aliases and pull order

The embedded Catalog contains 9 families and 17 artifacts: el7 is amd64-only; el8, el9, el10, d12, d13, u22, u24, and u26 have amd64 and arm64 artifacts. u24 is the VM default.

Image Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

packaging/image-pipeline/ accepts one already-downloaded immutable qcow2 and an independently obtained SHA-256. It never downloads, uploads, touches Farrow runtime/network state, reads signing keys, or marks an image supported.

Modes

validate: copy/re-hash, force qcow2 inspection, validate the single backing chain, run qemu-img check, and emit an explicitly unpublishable evidence bundle. Guest credentials are not changed.
offline: additionally use libguestfs virt-customize --no-network and virt-cat on the staged copy. It rejects unrelated UID/GID 88 occupants, normalizes the locked dba/admin identity, disables password/root SSH, removes keys/history/host identity/cloud-init cache, restores targeted SELinux labels, and reads back a deterministic marker.

SOURCE_DATE_EPOCH=1787486400

./packaging/image-pipeline/build.sh \
  --mode validate \
  --source /absolute/source.qcow2 \
  --expected-sha256 <digest> \
  --output /absolute/new/evidence-directory \
  --name u24 --release 20260801.0.0 --arch amd64 \
  --source-user ubuntu --boot uefi \
  --source-uri https://immutable.example/source.qcow2 \
  --artifact-url 'https://images.example/u24/{sha256}.qcow2' \
  --license NOASSERTION \
  --source-date-epoch "$SOURCE_DATE_EPOCH" \
  --manifest-version 2026082801

Source/output paths must be absolute; source is canonical, regular, non-symlinked, stable while copied, and at most 16 GiB. Output must not exist. The builder uses an exclusive adjacent lock, mode-0700 staging, and one final rename. Failure removes only its guarded staging directory.