Farrow 0.3.0

Farrow 0.3.0

Farrow 0.3.0 makes image-catalog access explicit, turns guest bootstrap
failures into actionable per-node diagnostics, and removes CLI surface that no
longer earns its complexity. The Pigsty Inventory format, fixed-IP deployment
model, and embedded Catalog revision 2026082903 remain unchanged.

中文说明见下文。

Highlights

• No implicit Catalog network access. up, plan, and ordinary image
  commands open one local Catalog snapshot and never refresh metadata in the
  background. farrow update explicitly fetches the configured repository;
  farrow image sync remains the exact-URL/file recovery path.
• Actionable readiness failures. Guests publish an atomic bootstrap stage,
  so Farrow reports failures such as guest bootstrap failed during data-disks immediately and points to farrow logs <node>. Already-running
  guests can be rechecked without restarting QEMU.
• Accurate multi-node results. Partial operations report each failed node,
  stage, and error in text and structured output. Successful peers are kept,
  and the SSH client configuration is rebuilt from every committed node even
  after a partial lifecycle result.
• Distribution-native interface names. Netplan matches deterministic MAC
  addresses without renaming guest interfaces. Runtime checks locate the
  private interface by MAC before validating its address, routes, and DNS.
• Portable data-disk setup. vm_disks[].fs: auto prefers XFS and falls back
  to ext4 when the guest lacks mkfs.xfs; omitting fs keeps the released XFS
  default.
• Smaller CLI. The redundant ss command and root aliases cp, h, i,
  and p are removed. --force, --rollback, --remove, and --name no
  longer reuse ambiguous short flags. image reset replaces
  reset-manifest, which remains an alias.

Operational notes

• Catalog refresh is never automatic. Run farrow update when you want the
  configured repository's current Catalog.
• --rollback is available on up and reload; it removes only safe prepare
  artifacts belonging to nodes that failed in that run.
• Exit code 5 covers partial node completion and a post-lifecycle SSH
  integration failure. Exit code 7 remains integrity/ownership failure.
• The default Catalog, image cache, deployment state, and retained 0.1/0.2
  compatibility readers are unchanged.

Install or upgrade

Download install.sh from this Release, then run:

chmod +x install.sh
FARROW_VERSION=0.3.0 ./install.sh
farrow version
farrow doctor

Homebrew formula and amd64/arm64 DEB/RPM packages are attached to the same
Release. Full installation and privilege details are at
https://farrow.pgsty.com/docs/start/tutorial/.

Release integrity

The tag workflow checks out the exact commit, reruns make check, builds and
verifies all archives, native Linux packages, SBOMs, the Homebrew formula, and
the installer, then writes checksums.txt before creating an immutable draft.
Because 0.3.0 is below 1.0.0, GitHub and release.json both classify it as a
pre-release. The draft must not be published until those checks and anonymous
asset downloads pass.

The latest native lifecycle matrix remains the dated evidence recorded on the
documentation Status page; source, package, release, and native-host evidence
remain separate gates.

---

Farrow 0.3.0（中文）

Farrow 0.3.0 将镜像 Catalog 访问改为完全显式，把 Guest Bootstrap 失败变成可操作的
逐节点诊断，并删除已经无法抵偿复杂度的 CLI 表面。Pigsty Inventory 格式、固定 IP
Deployment 模型与内嵌 Catalog revision 2026082903 均未变化。

亮点

• Catalog 不再隐式联网。 up、plan 与普通 image 命令只打开一份本地 Catalog
  快照，不在后台刷新元数据。farrow update 显式获取配置仓库；farrow image sync
  保留为精确 URL/文件恢复路径。
• 就绪失败可以直接行动。 Guest 原子发布 Bootstrap 阶段，Farrow 可立即报告
  guest bootstrap failed during data-disks 等错误并指向 farrow logs <node>；已经
  运行的 Guest 可在不重启 QEMU 的情况下重新检查。
• 准确的多节点结果。 部分失败在文本和结构化输出中携带每个失败节点、阶段与错误；
  成功节点保留，SSH 客户端配置即使在生命周期部分失败后也会根据全部 committed 节点重建。
• 保留发行版原生网卡名。 Netplan 按确定性 MAC 匹配，不再重命名 Guest 网卡；运行时
  检查先按 MAC 找到私网接口，再验证地址、路由与 DNS。
• 可移植的数据盘初始化。 vm_disks[].fs: auto 优先使用 XFS，Guest 缺少
  mkfs.xfs 时回退到 ext4；省略 fs 仍保持已发布的 XFS 默认值。
• 更小的 CLI。 删除冗余 ss 命令和根别名 cp、h、i、p；--force、
  --rollback、--remove、--name 不再复用含义模糊的短参数。image reset 取代
  reset-manifest，旧名称仍作为别名。

运维说明

• Catalog 永不自动刷新；需要配置仓库当前 Catalog 时显式运行 farrow update。
• --rollback 用于 up 与 reload，只删除本次运行中失败节点的安全 prepare 产物。
• 退出码 5 表示节点操作或生命周期后 SSH 集成部分完成；退出码 7 仍表示完整性或
  属主失败。
• 默认 Catalog、镜像缓存、Deployment 状态以及保留的 0.1/0.2 兼容读取器均未变化。

安装或升级

从本 Release 下载 install.sh，然后运行：

chmod +x install.sh
FARROW_VERSION=0.3.0 ./install.sh
farrow version
farrow doctor

同一 Release 还附带 Homebrew Formula 与 amd64/arm64 DEB/RPM 软件包。完整安装与权限
边界见 https://farrow.pgsty.com/docs/start/tutorial/。

发布完整性

Tag 工作流检出精确 Commit，重跑 make check，构建并验证全部 Archive、Linux 原生
Package、SBOM、Homebrew Formula 与 Installer，然后生成 checksums.txt 并创建不可变
Draft。由于 0.3.0 低于 1.0.0，GitHub 与 release.json 都将其标为 Pre-release；只有
这些检查和匿名资产下载通过后才可公开草稿。

最新真机生命周期矩阵仍以文档 Status 页中的日期证据为准；源码、打包、发布与真机证据
继续作为不同门禁。

Farrow 0.2.0

Farrow 0.2.0 is a correctness and hygiene release on top of 0.1.0. It changes
how every command behaves at its boundary — under signals, in --json/--yaml
output, and when given misspelled input — and adds the gates that keep those
boundaries in place. The engine contract, the inventory format, the on-disk
state layout under $FARROW_HOME, and the embedded image catalog
(revision 2026082903, 9 families, 27 artifacts) are unchanged. 0.1.0
deployments continue to work without migration.

Highlights

• VPN split routes no longer block a healthy lab. A less-specific route
  such as MonoProxy's physical-interface 10.0.0.0/8 exclusion cannot beat
  Farrow's owned 10.10.10.0/24, so preflight now permits it. Equal and
  more-specific foreign routes, overlapping interfaces, occupied addresses,
  and a missing owned /24 remain hard failures.
• Guest host markers converge on deployment terminology. New and
  recreated guests delete both # farrow-project-host and
  # farrow-deployment-host rows before writing only the deployment marker,
  so upgrading never duplicates Farrow-owned /etc/hosts entries.
• Selected scale-out is truly selected. farrow up u24-1 no longer
  downloads every image named elsewhere in the inventory. Desired peers that
  have not been created are reported as absent; port/UUID allocation,
  stop/start/destroy, persistent-disk validation, and generated SSH/hosts
  integrations all operate on committed nodes without losing the full desired
  inventory used by later incremental up.
• Clean cancellation. SIGINT/SIGTERM cancel long-running commands
  through one context: the progress line stops, held locks are released, and
  the command exits 130 with exactly one structured result
  ({"error":"cancelled"}). An interrupted up, recreate, or destroy
  still appends its event to events.jsonl, so the audit trail shows what the
  signal cut short. Ctrl-C inside an SSH session stays remote.
• reload is one operation. Definition drift and removed inventory nodes
  are refused before any node stops, so a configuration that needs
  recreate or destroy never takes a healthy lab down; --json emits a
  single document instead of one per phase.
• Misspelled nodes are refused, not executed. farrow ssh metaa -- uptime
  is a usage error instead of running metaa uptime on the control node.
  Unknown or repeated node selectors on any lifecycle command exit 2 before
  host preflight or a confirmation prompt. The ambiguous no--- form warns
  once; -- remains the unambiguous and recommended remote-command boundary.
• Confirmations are exact. destroy asks for the same destroy token
  whether or not nodes are selected and prints the exact scope (nodes,
  persistent disks, keys, state) first. setup treats end of input at its
  [Y/n] prompt as a cancellation; only an answered prompt defaults to yes.
• Structured output keeps its reasons. Every failure that used to be
  written straight to stderr now reaches the --json payload with its
  category; presentation flags never change an exit status. Verbose
  diagnostics redact credentials and query strings from source URLs.
• Smaller dependency graph. Viper and its nine transitive modules are gone;
  the shipped license inventory drops from 19 modules to 9 and the binaries
  read FARROW_OUTPUT/FARROW_VERBOSE directly.
• Installer retention. install.sh and development builds keep at most
  three verified release directories under .farrow-releases
  (FARROW_INSTALL_KEEP=N, 0 disables); current is never touched.

Compatibility notes

• 0.1.0 deployments remain readable without an on-disk format migration. After
  upgrading, run farrow status while each retained VM is live so any
  pre-release process-birth identity can be rewritten from native evidence.
• A pre-0.1 development deployment whose resolved network is user is not a
  released format. Preserve any required disks, destroy that development
  deployment explicitly, and rebuild it on the fixed-IP network.
• Existing guests keep their current /etc/hosts bytes until they are
  recreated. Every 0.2 seed removes both the 0.1.0 project marker and the new
  deployment marker before writing the current rows.
• New exit code 130: interrupted by SIGINT/SIGTERM, or a confirmation was
  declined. Scripts that checked for 2 after a mismatched destroy token or
  4 after answering no to setup must accept 130; a missing --yes or
  --force on a pipe remains 2.
• farrow logs --source events rejects a node argument; it is the
  deployment-wide log.
• farrow image list help now says what the command always did: every
  architecture is listed; info and pull select the native one.
• Diagnostics say deployment where they used to say project. JSON keys and
  file names are unchanged.

Validated boundary

The current source ran a real macOS arm64/HVF replay with MonoProxy's covering
10.0.0.0/8 route present: selected u24-1 creation, SSH, stop/start,
incremental cached el9-1 creation, whole-deployment status with five absent
desired peers, both SSH connections, and full destroy/SSH-fragment cleanup all
passed. On Ubuntu 26.04 amd64/KVM, the current Linux binary audited an existing
four-node deployment as live and reached its control guest over the persisted
SSH identity without mutating that host. make check, the source CI, and the
packaging workflow — including race, four-target builds, installer boundaries,
SBOM/package verification, and the development archive — are green.

For contributors: deadcode (four-target intersection), errcheck, and a
maintenance-inventory check are part of make check; CONTRIBUTING.md
carries an expiry table for every pre-0.1 compatibility path.

Start

Download the archive or native Linux package for your host from this Release.
The release install.sh performs a user-scoped archive install after checking
the selected asset against the checksums.txt generated by GitHub Actions:

chmod +x install.sh
FARROW_VERSION=0.2.0 ./install.sh
farrow setup --dry-run
farrow setup --yes
farrow up

Upgrading from 0.1.0 is the same command; the installer switches the current
link atomically and prunes older release directories beyond the retention
bound. Review the installation and privilege boundary before applying setup:
https://farrow.pgsty.com/docs/start/tutorial/.

Farrow 0.1.0

Farrow 0.1.0

Farrow 0.1.0 is the first public, pre-1.0 developer release of the native
Go/QEMU runtime for Pigsty-compatible local labs.

Highlights

• One Pigsty-compatible Inventory is both the VM specification and the Pigsty
  deployment inventory; there is no second project format.
• One owner-scoped deployment supports fixed-IP additive scale-out on macOS
  and Linux, with explicit drift, recreate, and deletion boundaries.
• QMP plus full process identity, atomic state, transaction journals, and
  manifest-scoped host networking keep lifecycle recovery fail-closed.
• Locale/timezone-independent process identity, QMP-bound interrupted-start
  adoption, and bounded post-spawn compensation close the startup recovery
  window without weakening PID-reuse protection.
• Signed image Catalogs, SHA-256/qcow2 verification, immutable upstream
  fallback, local imports, and bounded cache pruning cover the image path.
• Interrupted image downloads resume from the staged bytes and are bounded by an
  inactivity watchdog rather than an overall deadline, so a multi-gigabyte
  artifact on a slow link finishes instead of failing partway through.
• Static image repositories use a source-controlled repo.yaml, generated
  schema-3 catalog.json, immutable readable artifact names, and explicit
  farrow repo scan/build/verify operations.
• Exact image releases and numeric version prefixes are both available;
  Pigsty inventories can keep vm_image: el9 and select the newest matching
  9.x or 9.7.x build with vm_version.
• Release assets include four platform archives, amd64/arm64 DEB and RPM
  packages, SPDX SBOMs, checksums, a Homebrew formula, a user-scoped installer,
  and keyless Sigstore signature/provenance bundles. Reconstructed dependency
  license texts ship inside every archive and package.

Validated boundary

The dated native matrix covers macOS arm64 with HVF/QEMU 11.1/socket_vmnet and
Ubuntu 26.04 amd64 with KVM/QEMU 10.2.1/NetworkManager. Other shipped targets
are cross-built and package-verified but retain the narrower status documented
at https://farrow.pgsty.com/docs/about/status/.

The embedded schema-3 Catalog revision 2026082903 contains 9 image families
and 27 architecture-specific artifacts. Current built-in versions are
supported, except EOL EL7 and the retained EL9 9.3/9.6 and EL10 10.0
compatibility versions, which are deprecated. Apple Silicon runs the stock
Rocky Linux 8 arm64 image with visible same-architecture TCG because its
64K-granule kernel is incompatible with HVF. TCG results are compatibility
evidence, not performance evidence.

Image availability

The built-in Catalog pins distribution-owned artifacts by exact SHA-256, and
distributions rotate those artifacts on their own schedule. Rocky publishes only
the current point release under /pub/rocky/<major>/, and Ubuntu keeps a
rolling window of dated directories, so el8, el9:stable, el10:stable, and
the u22/u24/u26 entries will eventually stop resolving upstream even
though the digests remain correct. Every one of the 27 artifacts resolves as of
this release.

When that happens Farrow says so explicitly and names the three remedies:
upgrade to a Farrow release with a newer Catalog, farrow image sync a
published Catalog, or point --repo/$FARROW_REPO at a mirror that still
carries the bytes. Public builds use https://repo.pigsty.cc/farrow as the
default signed Catalog and artifact mirror. --repo and $FARROW_REPO override
it; if it is unavailable, Farrow uses the embedded Catalog and immutable
distribution upstreams.

Start

Download the archive or native Linux package for your host from this Release.
The release install.sh performs a user-scoped archive install after checking
the selected asset against checksums.txt. If cosign is on the PATH it also
requires the Sigstore bundle and verifies checksums.txt against this
workflow's signing identity first; a missing or invalid bundle fails closed:

chmod +x install.sh
FARROW_VERSION=0.1.0 ./install.sh
farrow setup --dry-run
farrow setup --yes
farrow up

Review the full installation and privilege boundary before applying setup:
https://farrow.pgsty.com/docs/start/tutorial/.

Release integrity

checksums.txt.sigstore.json signs the checksum manifest, and
checksums.provenance.sigstore.json attests its SLSA provenance predicate.
The release workflow verifies both bundles against its exact GitHub Actions
OIDC identity before creating this immutable draft.

Because 0.1.0 is below 1.0.0, the release is marked as a GitHub pre-release and
release.json records the prerelease channel; one rule decides both.

This draft must not be published until source CI, the packaging workflow, the
external native gates, the documentation site/DNS, and clean-host package
consumption are confirmed.