ZFS

ZFS support is optional. Yeet works without it, but ZFS is useful when you want service roots on named datasets, pre-change snapshots, or fast VM disk clones on a ZFS pool.

ZFS is a storage choice, not a payload type. It can back:

• Container, binary, script, and cron service roots.
• VM service roots and VM disks.
• Yeet-managed snapshots before risky service changes.
• Shared VM image bases for faster ZFS-backed VM creates.

Use raw filesystem paths when you do not need those behaviors.

Without --zfs, --service-root is an absolute filesystem path on the catch host. With --zfs, --service-root is a ZFS dataset name.

yeet run <svc> ./compose.yml --service-root=/srv/apps/<svc>
yeet run <svc> ./compose.yml --service-root=tank/apps/<svc> --zfs

Catch accepts an existing dataset or runs plain zfs create <dataset>, resolves the dataset mountpoint, and uses that path as the service root. Parent datasets must already exist. If the dataset already exists or its mountpoint already contains files, catch prints a warning and deploys into it.

Catch stores both the mounted filesystem path and the ZFS dataset identity in its DB. yeet.toml stores the replay intent, including service_root and service_root_zfs. If another checkout changes the live service root, run:

yeet service sync <svc>

ZFS-backed service roots get yeet-managed snapshots before risky changes. The built-in default is enabled and required, keeps the newest 5 yeet-created snapshots, prunes snapshots older than 7 days, and snapshots before these events:

• run
• docker-update
• service-root-migration

First deploys are skipped because there is no prior service state to recover. Catch prunes only snapshots it created for that service.

yeet snapshots defaults show
yeet snapshots defaults set --enabled=true --keep-last=5 --max-age=7d
yeet snapshots defaults set --events=run,docker-update --required=false

Override one service with yeet service set:

yeet service set <svc> --snapshots=off
yeet service set <svc> --snapshots=on --snapshot-keep-last=3 --snapshot-max-age=72h
yeet service set <svc> --snapshot-events=run,docker-update
yeet service set <svc> --snapshots=inherit

Snapshot-only changes do not require the service to be stopped. Service-root moves still require the service to be stopped.

For VM payloads, the policy controls retention for manual yeet snapshots create <vm> commands. VM snapshots target the VM ZVOL instead of the service-root dataset. --snapshot-events and --snapshot-required are for automatic service-root snapshots and are not shown in the VM web-run snapshot controls.

Yeet-created ZFS snapshots are recovery points for a service or VM disk. List them when you need to see what yeet can identify for a service:

yeet snapshots list
yeet snapshots list <svc>

Inspect a recovery point before relying on it. The inspect view shows the service, snapshot name, storage target, creation time, event, mode, retention state, and any comment saved with the point:

yeet snapshots inspect <svc> <snapshot>

Protect important recovery points when they should survive automatic retention pruning:

yeet snapshots protect <svc> <snapshot>

Protected recovery points are excluded from automatic pruning. They must be unprotected before removal.

Manual recovery point flow:

yeet snapshots create <svc> --comment "before upgrade"
yeet snapshots list <svc>
yeet snapshots inspect <svc> <snapshot>
yeet snapshots protect <svc> <snapshot>
yeet snapshots unprotect <svc> <snapshot>
yeet snapshots rm <svc> <snapshot> --yes

Use clone first when you want to inspect a recovery point or copy files out without changing the original service:

yeet snapshots clone <svc> <snapshot> <svc>-recover
yeet info <svc>-recover

Use restore when you want to roll the original service data back in place:

yeet snapshots restore <svc> <snapshot> --stop --yes

restore creates a pre-restore recovery point before it mutates ZFS state. If the restore does not produce the result you expected, inspect the new pre-restore point before making another change.

Snapshots recover storage state. Service generations recover deployed definitions and install artifacts. The default --generation=current keeps the current deployed definition while restoring data. Pass --generation=snapshot only when the selected snapshot recorded a generation and you also want to restore that older deployed definition.

yeet run can set the initial root for a new service. To move an existing service root, stop the service and use yeet service set:

yeet stop <svc>
yeet service set <svc> --service-root=tank/apps/<svc> --zfs --copy
yeet service set <svc> --service-root=tank/apps/<svc> --zfs --empty

Use --copy to copy the old root into the new dataset, or --empty to create a new empty root. yeet service set leaves the old root in place.

For VMs, --zfs lets yeet prepare the VM disk on a ZFS-backed service root:

yeet run <vm> vm://ubuntu/26.04 --service-root=tank/vms/<vm> --zfs

The first VM created on a pool for an image family/version prepares a shared ZFS image base. Later VMs on the same pool and image family/version clone that base instead of writing the root filesystem again.

When a newer VM image is cached, yeet keeps ZFS image bases that are still referenced by VM clones and prunes only old unreferenced bases. Use yeet vm images prune --dry-run to inspect cleanup before removing anything.

Grow an existing ZFS-backed VM disk while the VM is stopped:

yeet stop <vm>
yeet vm set <vm> --disk=128g
yeet start <vm>

Yeet grows the VM ZVOL, waits for the block device to settle, checks the ext4 filesystem, and then grows the guest root filesystem. Disk shrink and live resize are not supported.

yeet rm --clean-data <vm> removes the VM service data and VM clone. It does not remove the shared image base, so future VMs can keep cloning it.

If ZFS is present for VM disk setup, the host also needs udevadm.

Use ZFS when you want named datasets, storage-level recovery points, or faster repeat VM creates on the same pool. Skip it for simple services where a normal filesystem path is enough.

• Data Layout shows where service files live.
• VMs covers VM-specific ZFS behavior.
• Containers, Binaries & Scripts, and Cron Jobs show payload-specific examples.
• yeet CLI lists the --zfs, snapshot, and service-root flags.