dpkg-pre-post-snapper

Enhanced Snapper pre/post snapshot hook for Debian-based systems.

dpkg-pre-post-snapper creates paired Snapper snapshots around package transactions and replaces generic descriptions such as apt with concise, meaningful descriptions based on the package manager or frontend that initiated the transaction.

Examples include:

install firefox
install firefox +3 pkg
remove libreoffice
full-upgrade
/usr/bin/plasma-discover
/usr/sbin/synaptic

---

Background

Debian's Snapper integration can create snapshots before and after package transactions, but the default descriptions often provide little information about what changed.

This project traces its origins to Debian Bug #770938 and Debian's 80snapper APT hook. It builds upon the external-script implementation published by imthenachoman, which moved Debian's inline snapshot commands into a standalone script and added process-tree detection.

This maintained version substantially expands that foundation with additional package manager detection, PackageKit and Plasma Discover support, concise package-list summaries, transaction locking, duplicate snapshot prevention, retry handling, and safer description updates.

---

Features

• Creates matching pre and post Snapper snapshots around package transactions.
• Walks the parent process tree to identify the package manager or frontend that initiated the transaction.
• Recognizes common Debian package managers and package operations.
• Detects PackageKit backend transactions.
• Uses Plasma Discover as a best-effort PackageKit description when available.
• Summarizes long package lists using +N pkg.
• Preserves existing descriptive pre-snapshot text.
• Prevents duplicate pre-snapshots during a single package transaction.
• Serializes concurrent hook invocations to protect transaction state.
• Retries transient Snapper config is in use failures with backoff.
• Uses Snapper's JSON output for reliable snapshot-description lookup.
• Respects DISABLE_APT_SNAPSHOT=yes in /etc/default/snapper.
• Falls back gracefully when the originating application cannot be identified.

---

Requirements

• Debian, Ubuntu, or a compatible derivative using APT and dpkg.
• Snapper installed with a root configuration at /etc/snapper/configs/root.
• Bash.
• Python 3.
• flock from util-linux.
• Standard process utilities including ps, awk, xargs, and pidof.

pidof is used only for best-effort Plasma Discover detection. PackageKit transactions still fall back to PackageKit if Discover cannot be identified.

---

Installation

Clone the repository and run the installer:

git clone https://github.com/mcsgeek/dpkg-pre-post-snapper.git
cd dpkg-pre-post-snapper
sudo ./install.sh

The installer places:

/etc/apt/apt.conf.d/80snapper
/opt/snapper/bin/dpkg-pre-post-snapper.sh

If /etc/apt/apt.conf.d/80snapper already exists, the installer preserves the original hook before replacing it.

The installed APT hook invokes:

/opt/snapper/bin/dpkg-pre-post-snapper.sh pre
/opt/snapper/bin/dpkg-pre-post-snapper.sh post

---

Supported Package Managers

Direct process-tree detection currently recognizes:

• apt
• apt-get
• aptitude
• unattended-upgr
• synaptic
• muon

PackageKit backend detection recognizes:

• packagekitd
• PK-Backend

For PackageKit transactions, the script attempts to identify a running Plasma Discover process. If none is available, the description falls back to:

PackageKit

---

Package Operation Detection

The script recognizes common operations including:

• install
• remove
• purge
• build-dep
• update
• upgrade
• full-upgrade
• dist-upgrade
• autoremove

For example:

apt install firefox

becomes:

install firefox

and:

apt full-upgrade

becomes:

full-upgrade

Commands that do not match a recognized operation retain their original command line as the snapshot description.

---

Package List Summarization

Long package lists are reduced to the first package name plus the number of additional packages.

For example:

apt install firefox thunderbird gimp inkscape vlc

becomes:

install firefox +4 pkg

This keeps common APT descriptions concise while still showing the operation and indicating that multiple packages were involved.

---

Process and Transaction Safety

The script walks the parent process tree until it finds a recognized caller. The traversal includes a maximum depth and retrieves the process name and command line together to reduce process-exit race conditions.

If no known caller is found, the description becomes:

apt (unrecognized caller)

A file lock serializes concurrent hook invocations so separate package managers cannot race on the shared pre-snapshot tracking file.

If APT or dpkg invokes the pre-hook more than once during the same transaction, the existing pre-snapshot is reused rather than creating a duplicate.

Snapper commands are retried with backoff when Snapper temporarily reports that the configuration is already in use.

During the post-hook, the script reads the pre-snapshot description through Snapper's JSON interface. Existing descriptive text is preserved; only an empty description or the generic value apt may be repaired before the matching post-snapshot is created.

---

Example Snapshots

Installing one package

$ sudo apt install firefox

pre   install firefox
post  install firefox

Installing multiple packages

$ sudo apt install firefox thunderbird gimp vlc

pre   install firefox +3 pkg
post  install firefox +3 pkg

Removing a package

$ sudo apt remove libreoffice

pre   remove libreoffice
post  remove libreoffice

Full upgrade

$ sudo apt full-upgrade

pre   full-upgrade
post  full-upgrade

Plasma Discover

pre   /usr/bin/plasma-discover
post  /usr/bin/plasma-discover

Synaptic

pre   /usr/sbin/synaptic
post  /usr/sbin/synaptic

---

Why This Is Useful

Meaningful descriptions make it easier to:

• identify package operations,
• locate snapshots created around upgrades,
• compare system changes,
• determine which transaction introduced a problem, and
• choose an appropriate snapshot when reviewing or rolling back system state.

Instead of scrolling through many snapshots labeled only apt, each pair shows what operation most likely created it.

---

Limitations

PackageKit communicates over D-Bus, so the original graphical frontend is not normally preserved in the PackageKit backend's process tree.

Plasma Discover detection is therefore best effort. Other PackageKit frontends, background transactions, or transactions where Discover is no longer running may appear simply as:

PackageKit

Command parsing is designed for normal APT invocations. Unusual command lines containing complex shell quoting or option values separated from their options may not be summarized perfectly; in those cases, the original command line or a safe fallback is used.

---

Project Origins and Acknowledgements

This project traces its origins through:

• Debian Bug #770938, which proposed automatic Snapper snapshots around APT transactions.
• Debian's 80snapper APT hook, which implemented the snapshot commands inline.
• The external helper script published by imthenachoman, which moved those commands into dpkg-pre-post-snapper.sh and added process-tree detection for more useful descriptions.

This repository continues that work with broader caller detection, PackageKit and Discover support, package-list summarization, transaction locking, duplicate pre-snapshot prevention, machine-readable description handling, retry logic, documentation, and ongoing maintenance.

Original Debian bug report:

https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=770938

---

License

This project is licensed under the GNU General Public License version 2 only (GPL-2.0-only).

See LICENSE for the complete license text.