This is the Ubuntu/APT counterpart to zfs-pacman-hook. It snapshots selected ZFS datasets before APT invokes dpkg, includes affected Debian package names in snapshot names, and prunes old snapshots using separate ordinary and important-package retention chains.

Setup

Clone this repository into an arbitrary location <repo>. Install the executable and APT hook as symlinks so that changes in the checkout are immediately available. Install the runtime configuration as a copy so that local configuration is not tied to the repository checkout:

sudo chmod +x <repo>/apt-zfs-snapshot.sh
sudo ln -s <repo>/apt-zfs-snapshot.sh \
    /usr/local/sbin/apt-zfs-snapshot
sudo ln -s <repo>/90apt-zfs-snapshot.conf \
    /etc/apt/apt.conf.d/90apt-zfs-snapshot.conf
sudo install -Dm644 <repo>/apt-zfs-snapshot.conf \
    /etc/apt-zfs-snapshot.conf

The symlink targets must remain at the paths used in the commands above. If you choose different target locations, update the executable path in 90apt-zfs-snapshot.conf as well.

Set dry_run='true' in /etc/apt-zfs-snapshot.conf, run a harmless APT operation, and inspect the planned names. Set it back to false after verifying dataset selection and naming.

The helper runs as root through APT and requires Bash, zfs, and findmnt.

APT integration

The hook uses DPkg::Pre-Install-Pkgs. APT sends its version-3 package action protocol on the file descriptor named by APT_HOOK_INFO_FD. Records contain the package name, old and new versions, version direction, architecture, and action. This captures dependencies selected by APT as well as explicitly requested packages.

Actions are classified as follows:

APT record	Operation marker
No old version and a new version	`inst`
New version greater than old version	`upgr`
New version lower than old version	`down`
`REMOVE` action	`rmvl`

Configuration-only records are ignored. If one callback contains multiple operation classes, the marker is mixd. In normal Ubuntu use, an apt-get -y dist-upgrade produces one useful callback and therefore one snapshot. APT can invoke dpkg more than once for complex operations; this implementation creates one snapshot per package-action callback.

Dataset selection

By default, datasets with this exact ZFS property are selected:

zfs set space.quico:auto-snapshot=true rpool/ROOT/ubuntu

With snap_only_local_datasets='true', only mounted ZFS datasets are selected. This avoids snapshotting another operating system stored in the same pool. To explicitly select roots, set:

snapshot_roots='bpool/BOOT rpool/ROOT'

Explicit roots bypass property discovery and the mounted-dataset check. Each root is snapshotted recursively, and all roots are passed to one zfs snapshot -r command.

Snapshot names

Names use this form:

dataset@apt_DATE_COUNTER_op:OP_sev:SEVERITY_pkgs:PACKAGE-LIST

Example:

rpool/ROOT/ubuntu@apt_2026-09-16-1430_1_op:upgr_sev:imp_pkgs:linux-image-6.17:systemd:libc6

The timestamp is UTC by default and is controlled by date_format and timezone. The counter starts at one and increases if a complete name already exists. This prevents collisions when identical operations happen within the same timestamp interval.

Package names are separated with package_separator, which defaults to :. Plus signs are replaced with underscores before inclusion in a ZFS name. The package list is shortened by dropping complete names from the end first, then truncating the final remaining name and adding ... when at least four characters fit. packages_max_length is a best effort because the complete ZFS name is limited to 255 characters. If the fixed dataset and metadata fields cannot fit, the hook refuses to create a snapshot.

Retention

If any affected package matches important_names, the snapshot belongs to the important chain. Otherwise it belongs to the trivial chain. The default important expression is:

linux-image(-.*)?|linux-headers(-.*)?|systemd|zfs-(dkms|utils)

The defaults retain 25 trivial snapshots and 10 important snapshots. Retention runs only after a successful snapshot and only considers snapshots with this tool's prefix and the current severity marker. Recursive snapshot trees are destroyed with zfs destroy -r.

Configuration

/etc/apt-zfs-snapshot.conf is sourced as a Bash fragment. Available parameters are:

Parameter	Default	Meaning
`dry_run`	`false`	Print planned snapshots without changing ZFS
`important_names`	kernel/systemd/ZFS expression	Exact regex for important packages
`snapshots_trivial_keep`	`25`	Trivial snapshots retained per dataset
`snapshots_important_keep`	`10`	Important snapshots retained per dataset
`trivial_suffix`	`trv`	Ordinary severity marker
`important_suffix`	`imp`	Important severity marker
`packages_max_length`	`30`	Maximum package-list characters
`snap_only_local_datasets`	`true`	Restrict property-selected datasets to mounted datasets
`snapshot_roots`	empty	Explicit space-separated recursive snapshot roots
`field_separator`	`_`	Separator between snapshot fields
`package_separator`	`:`	Separator between package names
`snapshot_prefix`	`apt`	Prefix identifying these snapshots
`date_format`	`%F-%H%M`	Format passed to `date`
`timezone`	`Etc/UTC`	Timestamp timezone
`install_suffix`	`inst`	Install marker
`remove_suffix`	`rmvl`	Remove marker
`upgrade_suffix`	`upgr`	Upgrade marker
`downgrade_suffix`	`down`	Downgrade marker
`mixed_suffix`	`mixd`	Multiple operation classes marker

The property name and value are fixed to space.quico:auto-snapshot=true.

Limitations

The hook covers package changes when APT invokes dpkg; direct dpkg operations are not intercepted.
APT may invoke dpkg more than once in complex cases, producing more than one snapshot.
The snapshot occurs before the corresponding dpkg invocation, not before APT downloads packages or resolves dependencies.
Snapshot failures are reported but do not abort the package operation, matching the warning-oriented original behavior.

License

MIT. See LICENSE.