Images

Barn uses a materialized static-file Catalog plus immutable qcow2 artifacts. Official and HTTP Catalogs are signed; explicitly selected local and HTTPS repositories may be unsigned. A Catalog update does not require a new Barn binary, but the binary decides which signing keys and image safety rules are trusted.

Aliases and pull order

Barn 0.9.0 embeds Catalog 2026092001: 9 families and 37 artifacts, retaining all 27 artifacts from the previous Catalog. el7 is amd64-only; every other family has amd64 and arm64 artifacts. EL9 includes 9.3, 9.6, 9.7, and 9.8; EL10 includes 10.0, 10.1, and 10.2. u24:stable (Ubuntu 24.04) on the native architecture is the default request.

The September stable versions below include both amd64 and arm64. This is the embedded Catalog snapshot, not a live repository listing. Run barn update then barn image list to inspect the currently selected repository. Dated public endpoint checks and guest point-release observations are recorded in Status.

Debian retains offline-installed XFS tools and the generated en_US.UTF-8 locale, with C.UTF-8 still the default. Ubuntu retains Canonical’s original image bytes; cloud-init configures accounts and networking at startup. A Catalog refresh changes newly resolved stable requests. Existing VMs and explicitly pinned versions continue using their original base images.

barn image list
barn image info d13
barn image info d13:stable
barn image info [email protected]
barn image pull [email protected]
barn image pull d13 --arch arm64
barn update

Catalog status values are advisory rather than an activation switch: supported has passed the declared support gate; testing is available for explicit test/risk acceptance but is not supported; deprecated is retained only for EOL compatibility; and unknown has no support classification. Non-supported entries remain runnable and print a warning.

For a pull, Barn:

1. reads the selected repository’s active local Catalog once for the complete command: the Catalog embedded in this build, or the one last activated for that repository by barn update or image sync;
2. resolves image[:channel] or image@version-prefix, defaulting to u24:stable with the official Catalog; standalone image pull defaults to the native architecture and accepts --arch, while lifecycle resolution honors vm_arch;
3. reuses a local file only after size, SHA-256, and qcow2 checks pass;
4. otherwise downloads the exact Catalog-named artifact, with retries and resumption; the two official repositories can fall back to one another, while custom repositories remain exclusive. All accepted bytes must match the Catalog. An immutable upstream URL is provenance, not a fallback.

Released builds use https://repo.pigsty.io/barn by default. Long-only --mirror selects https://repo.pigsty.cc/barn; precedence is --repo, --mirror, BARN_REPO, then the global default. Both official roots retain canonical signed-Catalog trust. Repository selection determines both the local Catalog slot and the source of downloads. Keep selecting the same custom repository even when its image bytes are cached. Barn never refreshes the Catalog on its own; ordinary image resolution can work offline with an active local Catalog and verified cache. Run barn update to fetch, verify, and activate the selected repository’s current Catalog. Catalog updates use that selected source; a failed update is an error. An image download fails when none of its permitted sources supplies verified bytes. Changing --repo alone does not fetch or activate that repository’s Catalog; run barn update --repo <root> before using its custom aliases.

Verified writable cache files are made read-only again. A damaged, unreferenced cache file is preserved with a .corrupt-<timestamp> suffix before replacement; a base image still referenced by a VM is kept in place and reported as an error.

Runtime policy

Matching architectures use native HVF/KVM except one catalogued incompatibility: the stock EL8 arm64 64K-granule kernel cannot run through Apple HVF, so Apple Silicon uses visible same-architecture TCG automatically. Explicit foreign vm_arch also uses TCG. amd64-on-arm64 uses a single translation thread to preserve x86 memory ordering. TCG results are not performance evidence.

EL7 is deliberately limited to native Linux/amd64. Linux setup installs only the native QEMU family; foreign architectures require the matching system emulator and UEFI firmware before up or recreate can proceed. For Catalog images, plan resolves the intended image and runtime without requiring those tools. Named local-* imports are byte-checked during resolution and still need qemu-img.

barn image pull d13 --mirror
barn image pull d13 --repo https://mirror.example/barn
BARN_REPO=/absolute/local/repository barn up

Unsigned repositories must be local paths or HTTPS. HTTP repositories require a Catalog signed by a trusted key. Immutable upstream artifact URLs must be HTTPS.

Trust and verification

Current ordinary builds embed both production public verification keys. The private signing keys are external to the source repository. Catalog activation rejects unknown keys, malformed content, equivocation, and revisions below the repository-scoped high-water mark unless the operator explicitly allows a downgrade.

Every accepted image must be a size- and SHA-256-matched plain qcow2 with no backing file, external data file, encryption, or unknown incompatible feature. Verified base images become read-only; node root disks are overlays and never modify the base.

barn update
barn image sync --repo https://repo.example/barn \
  https://repo.example/barn/catalog.json
barn image sync --repo /absolute/repo --allow-downgrade /absolute/repo/catalog.json
barn image reset

image reset restores the embedded Catalog but keeps the anti-rollback high-water mark; reset-manifest remains as a compatibility alias.

barn update checks the repository now and activates a newer Catalog. Barn never refreshes the Catalog on its own; the Catalog embedded in each release is used until you update. image sync is the recovery path for an exact URL or file, including a downgrade.

For repository-scoped recovery, pass the same root explicitly:

barn image sync --repo /srv/barn --allow-downgrade /srv/barn/catalog.json
barn image reset --repo /srv/barn

--repo selects the independent active-Catalog and high-water slot. The source argument does not change this selection. image sync and image reset accept --repo, but not --mirror; when --repo is omitted they use BARN_REPO or the compiled default. For an unsigned custom Catalog, the exact source must be the selected root’s catalog.json.

Static repository format

The published root is deliberately small:

barn/
├── repo.yaml
├── catalog.json
├── catalog.json.minisig       # required for official and HTTP repositories
└── images/
    └── <image>-<version>-<arch>.qcow2

repo.yaml stores author intent: defaults, aliases, channels, exact versions, architectures, boot mode, status, and optional provenance-only upstream URLs. source_user records the image’s declared source login identity, for example rocky in an upstream image or dba after Barn’s official normalization. The pipeline takes the upstream account separately when sanitizing a candidate. Catalog/import metadata does not replace the deployment SSH user (dba by default) or itself normalize the image. The file contains no generated checksum or size fields. catalog.json uses the same logical tree but materializes each variant’s file, SHA-256, artifact size, and virtual size. repo.yaml is schema: 1; the generated catalog.json is the schema-3 Catalog that Barn embeds and signs.

schema: 1
revision: 1
defaults: { image: u24, channel: stable, arch: native, boot: uefi }
images:
  u24:
    aliases: [ubuntu24, noble, ubuntu]
    channels: { stable: "1" }
    versions:
      "1":
        status: unknown
        variants:
          amd64: {}
          arm64: {}

With no explicit file, the two expected artifacts are images/u24-1-amd64.qcow2 and images/u24-1-arm64.qcow2. A variant may use a safe basename override for an existing custom file.

Channels and numeric prefixes are movable selectors. An exact key wins; otherwise a prefix matches on dot-component boundaries and chooses the numerically newest version ([email protected] selects the newest 9.7 build, while el9@9 selects the newest 9.x release). The immutable artifact identity remains (image, exact version, arch):

d13:stable + native
  -> [email protected] + arm64
  -> images/d13-20260914.2601.1-arm64.qcow2

barn repo scan is read-only. build performs strict YAML validation, full qcow2 inspection/checking, and atomic Catalog replacement without changing repo.yaml or QCOW bytes. verify requires the generated Catalog bytes to match a fresh materialization exactly. build and verify require local qemu-img; scan does not. Build on a QEMU host, then publish immutable artifacts first and the Catalog plus its matching signature last. Update a signed Catalog/signature pair together where possible; an inconsistent pair fails verification. Increase revision when changing Catalog contents.

Local layout and imports

Images live under BARN_HOME/images (default ~/.barn/images): family directories contain downloaded artifacts, manifests/ stores the active Catalog with an independent high-water entry per repository, and local/ plus local-images.json hold imports.

barn image import --sha256 <digest> /path/to/base.qcow2
barn image import --name local-mybase --boot uefi \
  --source-user ubuntu --sha256 <digest> /path/to/base.qcow2

The expected --sha256 is optional in the CLI; supplying an independently obtained trusted digest adds an explicit authenticity check to the mandatory qcow2 inspection. Import copies and verifies the file; it does not clean credentials, install cloud-init, detect the guest CPU architecture, or prove that it boots.

Named local aliases must begin with local-, so a future signed Catalog cannot shadow them. --name, --boot, and --source-user must be supplied together. A named import records the importing host’s native architecture; there is no image import --arch option. Use a static repository with explicit variants for foreign-architecture artifacts. Aliases are immutable: choose a new name for different bytes or metadata. Use vm_image: local-mybase in an inventory to select a named import; unnamed imports only populate the cache.

Pruning

barn image prune --dry-run
barn image prune --yes

Bare prune and --dry-run only report candidates; --yes deletes them. Prune protects the union of all artifacts in the selected active Catalog, applied node image digests, and registered local aliases. Therefore a cached Catalog image or named import is retained even when no VM uses it. Unprotected images and recognized stale staging files are candidates; unsafe or damaged files cause an error. Use the same --repo when inspecting a custom Catalog’s cache policy. Images remain cached after destroy, destroy --purge, and purge.

The compiled schema-3 Catalog can be exported byte-for-byte with go run ./tools/catalogexport /absolute/new/catalog.json. A public Catalog at the embedded version must use those exact bytes; same-version different bytes are rejected as equivocation. Release signing and image Catalog signing remain separate trust domains.