NAME
gyptazy - it's all about FreeBSD, Proxmox, BGP and Coding!

OPTIONS

CONTENT

ProxSnap The Missing Snapshot Management Tool for Proxmox Clusters

():

Snapshots are one of the most useful safety mechanisms in virtualized environments. They make it easy to roll back changes, reduce risk during upgrades, and provide confidence when testing or migrating workloads. Proxmox VE supports snapshots for both virtual machines and containers, and on a single guest level this works well and reliably.

The problem starts once a setup grows into a real Proxmox VE cluster. There is no native way to get a complete overview of snapshots across all nodes in a cluster. Simple but important questions are surprisingly hard to answer. Which nodes currently have snapshots? Which VMs or containers still carry old snapshots? How many snapshots exist in total and how old are they? Answering these questions usually means clicking through every node and every guest manually. Over time, snapshots tend to pile up quietly. A snapshot created before a quick change or update is often forgotten. Weeks or even months later it may still exist, consuming storage, affecting performance, or complicating backups, without being obvious at first glance. Not only my customers but also I had to deal with such situations in my BoxyBSD project.

ProxSnap was created by gyptazy to fill exactly this gap. ProxSnap gives you a clear, cluster wide view of all snapshots in a Proxmox VE environment. It breaks the information down per node and lists every VM and container together with their snapshots, including the snapshot name and creation date. This makes it immediately visible which snapshots are recent and which ones have been around for far too long. In its date based mode, ProxSnap allows you to find all snapshots that were created before a specific date. This is especially useful to identify very old snapshots that should be reviewed or removed. You can use this mode purely for auditing, or enable removal mode to automatically clean up snapshots once you are confident in the result.

ProxSnap is written entirely in Rust and is delivered as a standalone binary for Debian and Proxmox VE based systems. All communication happens through the secure Proxmox VE API, without touching the underlying storage directly. The configuration layout follows the same structure as ProxLB, making it possible to reuse and share configuration files. ProxSnap is also part of my Prox-Tools collection, alongside tools like ProxLB, ProxCLMC, ProxWall, and ProxWire. All of them follow the same philosophy of solving concrete operational gaps in Proxmox based environments with small, focused, and reliable tools.

ProxSnap Installation

Installing ProxSnap is intentionally kept simple and follows the same approach as all other tools from the Prox Tools collection. The recommended way is to install it via the gyptazy open-source solutions Debian repository, which provides ready to use packages for Debian and Proxmox VE based systems.

When using the repository, ProxSnap integrates cleanly into the system package management. Updates are delivered automatically through the regular package upgrade process, making maintenance straightforward and predictable.

Alternatively, ProxSnap can be installed by downloading the prebuilt .deb package directly. This package can be installed either with apt or dpkg, depending on personal preference or environment constraints. No additional build steps or dependencies are required.

Both installation methods result in a native system package that installs the standalone ProxSnap binary and follows standard Debian filesystem conventions. This keeps installation and removal clean and consistent with other Prox Tools, allowing ProxSnap to fit naturally into existing Proxmox VE environments.

ProxSnap Debian Mirror

The easiest way to get on track with ProxSnap is by installg it via the gyptazy open-source solutions Debian repository. You can simply use the follwing snippet to add the repository and to install it: 


echo "deb https://repo.gyptazy.com/stable /" > /etc/apt/sources.list.d/proxlb.list
wget -O /etc/apt/trusted.gpg.d/proxlb.asc https://repo.gyptazy.com/repository.gpg
apt-get update && apt-get -y install proxsnap

Afterwards, you can simply run proxsnap from the cli. You can find more about it in the following chapter.

ProxSnap Debian Package

Another quick solutions leads into simply downloading the static compiled Rust binary as a Debian package. This can simply be installed via apt or dpkg without any further dependencies. 


wget https://cdn.gyptazy.com/debian/proxclmc/proxsnap_1.0.0_amd64.deb
dpkg -i proxsnap_1.0.0_amd64.deb

Afterwards, you can simply run proxsnap from the cli. You can find more about it in the following chapter.

ProxSnap Config

ProxSnap is designed to integrate smoothly into existing Proxmox VE environments with minimal configuration effort. By default, it looks for its configuration file at /etc/proxsnap/proxsnap.yaml. This makes it easy to deploy ProxSnap system wide without requiring additional command line parameters.

If you prefer a different location or want to test multiple configurations, you can override the default path by using the -c option and providing a custom path to the configuration file. This is especially useful in development setups or when running ProxSnap from non standard locations.

When ProxLB is already running on the same node, the configuration can be reused directly. ProxSnap follows the same configuration layout, allowing both tools to share credentials and connection settings. This keeps configuration consistent across the Prox Tools collection and avoids duplication.

The configuration defines how ProxSnap connects to the Proxmox VE API. Authentication is handled using an API token, ensuring secure and permission controlled access. SSL verification and request timeouts can be adjusted to match the environment.


proxmox_api:
  hosts: 10.10.10.11
  user: root@pam
  token_id: test
  token_secret: ac1079bb-366f-46ab-9658-8a3262da6077
  ssl_verification: False
  timeout: 10

The hosts option defines the Proxmox VE node or API endpoint to connect to. The user, token_id, and token_secret together form the API token used for authentication. SSL verification can be enabled or disabled depending on your certificate setup, and the timeout controls how long ProxSnap waits for API responses.

This simple and familiar configuration approach makes ProxSnap easy to adopt, especially in environments where other Prox Tools are already in use. Once configured, no further setup is required, and ProxSnap can immediately start providing cluster wide snapshot visibility.

ProxSnap Usage

ProxSnap is designed to be simple and explicit in its output, allowing you to immediately understand the snapshot situation in your Proxmox VE cluster and decide what action, if any, is required. The focus is on clarity and predictability, so every result can be interpreted without additional context or guesswork.

The most basic usage is the list mode. By running ProxSnap with the -l option, the tool queries the entire Proxmox VE cluster via the API and prints a node by node overview of all virtual machines and containers. For each guest, ProxSnap reports whether snapshots exist and, if so, lists their names together with their creation dates.

List snapshots within Proxmox clusters

The parameter -l or --list can be used to simply return an overview over all nodes, all guests (VMs and CTs) and their snapshots. This overview shows all snapshots by their names and their dates 


$ proxsnap -l
Node: virt01-de-ne01
  ✓ VM 101 (backup01-de-ne01.int.gyptazy.com) has no snapshots
  ⚠ VM 110 (dev-sylve03) has 1 snapshots:
      • init (2026-01-01 16:33:35 (2 weeks ago))
  ✓ VM 104 (dev-pmx03) has no snapshots
  ⚠ VM 108 (dev-sylve01) has 1 snapshots:
      • init (2026-01-01 16:33:24 (2 weeks ago))
  ⚠ VM 102 (dev-pmx01) has 1 snapshots:
      • network (2026-01-16 12:22:42 (a day ago))
  ✓ VM 103 (dev-pmx02) has no snapshots
  ⚠ VM 109 (dev-sylve02) has 1 snapshots:
      • init (2026-01-01 16:33:29 (2 weeks ago))
  ✓ CT 100 (vpn01-de-ne01.int.gyptazy.com) has no snapshots
Node: virt02-de-ne01
  ✓ VM 111 (dev-proxmox01) has no snapshots
  ✓ VM 106 (dev-talos02) has no snapshots
  ✓ VM 107 (dev-talos03) has no snapshots
  ✓ VM 105 (dev-talos01) has no snapshots

A checkmark indicates that a VM or container has no snapshots attached. A warning symbol highlights guests that currently have one or more snapshots. For those guests, ProxSnap prints the snapshot name, the exact creation timestamp, and a human readable age. This makes it easy to spot snapshots that were created recently as well as those that may have been forgotten.

List snapshots created eefore a specific date

To go beyond a simple overview, ProxSnap offers a date based mode that helps identify outdated snapshots across the entire cluster. By specifying a cutoff date with the -d or --dateoption, ProxSnap searches for all snapshots that were created before that date (older than the given date). This is particularly useful after maintenance windows, migrations, or testing phases where temporary snapshots were created and never removed.


$ ./proxsnap -d 2026-01-04
Checking for snapshots older than 2026-01-04
⚠ VM 110 (dev-sylve03) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
⚠ VM 109 (dev-sylve02) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
⚠ VM 108 (dev-sylve01) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)

In this mode, ProxSnap operates as a dry run by default. No changes are made to the environment. Instead, all snapshots that match the given criteria are listed clearly, giving you the opportunity to review them and confirm whether they should be kept or removed.

Removing older snapshots

If you decide that the identified snapshots are no longer required, removal mode can be enabled by adding the -r or --remove option. When this option is set, ProxSnap will actively delete the matching snapshots using the Proxmox VE API.


Checking for snapshots older than 2026-01-04 (REMOVING)
⚠ VM 109 (dev-sylve02) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
  → deleted snapshot 'init' of VM 109
⚠ VM 110 (dev-sylve03) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
  → deleted snapshot 'init' of VM 110
⚠ VM 108 (dev-sylve01) snapshot 'init' is older than cutoff (2026-01-01 < 2026-01-04)
  → deleted snapshot 'init' of VM 108

Each deletion is logged explicitly, showing exactly which snapshot was removed and from which VM or container. ProxSnap never touches the implicit current snapshot and only removes snapshots that clearly match the selected cutoff date, ensuring safe and predictable behavior.

After the cleanup process, the list mode can be run again to validate the result and confirm that the snapshots have been removed successfully.


$ ./proxsnap -l
Node: virt01-de-ne01
  ✓ VM 101 (backup01-de-ne01.int.gyptazy.com) has no snapshots
  ✓ VM 110 (dev-sylve03) has no snapshots
  ✓ VM 103 (dev-pmx02) has no snapshots
  ✓ VM 108 (dev-sylve01) has no snapshots
  ✓ VM 109 (dev-sylve02) has no snapshots
  ✓ VM 104 (dev-pmx03) has no snapshots
  ⚠ VM 102 (dev-pmx01) has 1 snapshots:
      • network (2026-01-16 12:22:42 (a day ago))
  ✓ CT 100 (vpn01-de-ne01.int.gyptazy.com) has no snapshots
Node: virt02-de-ne01
  ✓ VM 106 (dev-talos02) has no snapshots
  ✓ VM 107 (dev-talos03) has no snapshots
  ✓ VM 111 (dev-proxmox01) has no snapshots
  ✓ VM 105 (dev-talos01) has no snapshots

This workflow makes ProxSnap suitable for both regular snapshot audits and controlled cleanup operations. You can begin with a read only overview, narrow the scope using a date threshold, and only enable removal once you fully understand which snapshots will be affected. This approach keeps snapshot management transparent, safe, and easy to integrate into everyday Proxmox VE operations.

Automated Snapshot Cleanups

ProxSnap is well suited for automating snapshot cleanup as part of regular cluster maintenance. Since it is a standalone binary and operates entirely through the Proxmox VE API, it can be executed safely in unattended environments such as cron jobs or systemd timers.

A common use case is the automatic removal of very old snapshots that were never cleaned up manually. By defining a fixed age threshold, for example one year, ProxSnap can regularly scan the cluster and remove snapshots that are older than the defined cutoff. This helps keep storage usage under control and prevents forgotten snapshots from accumulating over time.

The automation itself can be implemented with a small shell script that calculates the cutoff date dynamically and then invokes ProxSnap in removal mode. The following example determines the date 365 days in the past and removes all snapshots older than that date.


#!/usr/bin/env bash
set -euo pipefail
DATE="$(date -d '365 days ago' +%Y-%m-%d)"
echo "Running ProxSnap cleanup for snapshots older than ${DATE}"
proxsnap -d "$DATE" -r

This script can be executed manually, scheduled via a cron job, or triggered by a systemd timer. Because ProxSnap clearly logs every affected snapshot and never touches the implicit current snapshot, the process remains transparent and predictable even when run automatically.

When combined with an initial dry run during setup, this approach allows administrators to confidently automate snapshot cleanup while still maintaining full control over what is removed. As a result, ProxSnap can become a reliable part of long term Proxmox VE cluster housekeeping.