colibri/docs/CLAWDIE-INSTALLER-VALIDATION.md

Clawdie Installer — FreeBSD Validation Handoff

For: Codex (FreeBSD 15 host) · Crate: crates/clawdie (binary clawdie)

clawdie discovers a host's ZFS layout and provisions the clawdie service. It is built and unit-tested on Linux; the disk-touching and service-install paths require FreeBSD validation because they exercise host-specific ZFS and rc.d functionality.

1. Build + unit tests

cargo build -p clawdie --release
cargo test -p clawdie
cargo clippy -p clawdie --all-targets -- -D warnings

Report: full cargo test output, rustc --version, freebsd-version.

2. Read-only checks (safe on any host)

clawdie discover     # expect: os=FreeBsd, zfs available=true, real pools, clawdie datasets
clawdie plan         # expect: resolves to the single pool (or pass --pool), ZFS dataset steps

Verify:

• discover lists the real pools (parsed from zpool list -H) and any clawdie datasets.
• On FreeBSD plan resolves exclusively to ZFS; plain-dir layouts are unsupported and cause a clear error.
• Expected gap: the disks: section uses lsblk (Linux-only), so it is empty on FreeBSD — that is correct. --create-pool is a Linux convenience; FreeBSD already has ZFS.

3. Provisioning — DESTRUCTIVE, scratch host / VM / test pool only

clawdie apply --pool <testpool>         # dry-run: prints the plan, writes nothing
clawdie apply --pool <testpool> --yes   # provisions

Validate after --yes:

1. Datasets (zfs list): <testpool>/clawdie (canmount=off), …/db → /var/db/clawdie, …/log → /var/log/clawdie.
2. Service user + ownership (pw usershow clawdie, ls -ld /var/db/clawdie /var/log/clawdie): nologin, home /var/db/clawdie, state directories owned by clawdie:clawdie.
3. rc.d service: /usr/local/etc/rc.d/clawdie (mode 0555) and clawdie_enable=YES (sysrc). Check service clawdie enabled / rcvar.
   • The script execs /usr/local/bin/colibri-daemon through /usr/sbin/daemon -u clawdie; if that binary isn't staged, service clawdie start will fail on the missing exec — expected. Confirm the script + enable are correct regardless.
4. Teardown to reset:

   service clawdie stop 2>/dev/null; sysrc -x clawdie_enable
   rm -f /usr/local/etc/rc.d/clawdie; pw userdel clawdie
   zfs destroy -r <testpool>/clawdie
   

4. Optional — Linux --create-pool path (if a Linux host + spare disk exists)

clawdie discover                                       # spare disk shows "spare (usable…)"
clawdie apply --pool tank --create-pool /dev/sdX --yes # DESTROYS /dev/sdX

Verify zpool create + datasets + systemd unit (systemctl status clawdie). Confirm the guard: --create-pool on a non-empty disk is refused without --force.

5. FreeBSD read-only validation notes (13.jun.2026, Codex/Pi)

Host/version evidence:

FreeBSD osa.smilepowered.org 15.0-RELEASE-p10 GENERIC amd64
rustc 1.94.0 (4a4ef493e 2026-03-02)
cargo 1.94.0 (85eff7c80 2026-01-15)

Checks run on a real FreeBSD 15 host:

cargo fmt --check
./scripts/check-format.sh
git diff --check
cargo test -p clawdie -- --nocapture
cargo clippy -p clawdie --all-targets -- -D warnings
cargo build -p clawdie --release
target/release/clawdie discover
target/release/clawdie plan
target/release/clawdie apply --pool zroot        # dry-run only
target/release/clawdie plan --pool does-not-exist # expected error

Observed results:

• cargo test -p clawdie -- --nocapture: 15 tests passed.
• discover: detected os: FreeBsd, zfs available: true, and pool zroot [ONLINE].
• plan: resolved to ZFS on existing pool zroot and rendered rc.d provisioning.
• bare apply --pool zroot: printed the same plan and exited as a dry-run (DRY-RUN — nothing written).
• plan --pool does-not-exist: now errors before rendering/apply: ZFS pool \does-not-exist` not found; available pools: zroot`.

Hardening applied (PR #53):

• generated FreeBSD rc.d runs /usr/local/bin/colibri-daemon through /usr/sbin/daemon -u clawdie (not root);
• service installation chowns /var/db/clawdie and /var/log/clawdie after creating the clawdie user;
• existing-pool plans validate the named pool before rendering/applying.

Not done: no destructive apply --yes; still requires scratch pool/VM.

6. Acceptance — delete this doc when all are true

• cargo test -p clawdie passes on FreeBSD 15 (output + versions reported).
• discover + plan correct against a real FreeBSD ZFS host for read-only/dry-run paths.
• apply --yes on a scratch pool creates the datasets, user, and rc.d service as specified; teardown verified. (OSA file-backed testpool, 21.jun.2026.)
• Idempotent re-run: second apply --yes skips user creation (exit 65 = already exists), rc.d + sysrc overwrite cleanly.
• (if tested) Linux --create-pool works on a spare disk and the empty-disk guard refuses non-empty disks.
• Any FreeBSD-specific differences from the Linux-built behavior are filed as a PR and reported back.

Platform notes

• Disk candidacy (lsblk) is Linux-only; FreeBSD relies on its existing pool.
• apply writes only with --yes; discover, plan, and bare apply are read-only/dry-run.