# apt-pacman-hook Ubuntu APT hook for automatic ZFS snapshots. This is the Ubuntu/APT counterpart to [zfs-pacman-hook](https://quico.space/quico-os-setup/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 ``. 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: ```bash sudo chmod +x /apt-zfs-snapshot.sh sudo ln -s /apt-zfs-snapshot.sh \ /usr/local/sbin/apt-zfs-snapshot sudo ln -s /90apt-zfs-snapshot.conf \ /etc/apt/apt.conf.d/90apt-zfs-snapshot.conf sudo install -Dm644 /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: ```bash 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: ```bash 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: ```text dataset@apt_DATE_COUNTER_op:OP_sev:SEVERITY_pkgs:PACKAGE-LIST ``` Example: ```text 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: ```text 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](LICENSE).