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

OPTIONS

CONTENT

ProxSnap - A Snapshot Manager for Proxmox VE 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.

ProxSnap Installation

Installing ProxSnap is deliberately kept straightforward and consistent with the rest of the Prox Tools collection. The preferred installation method is via the gyptazy open source solutions Debian repository, which provides ready to use packages for both Debian and Proxmox VE based systems and allows ProxSnap to be deployed within minutes.

Using the repository ensures that ProxSnap is fully integrated into the system package management. Updates are handled automatically through the standard package upgrade workflow, making it easy to keep the tool up to date without additional maintenance overhead or manual intervention.

For environments where a repository based installation is not desired, ProxSnap can also be installed by downloading the prebuilt .deb package directly. The package can be installed using either apt or dpkg, depending on operational requirements or personal preference, and does not require any compilation or additional dependencies.

Both installation options result in a clean, native system package that installs the standalone ProxSnap binary and follows standard Debian filesystem conventions. This approach ensures a smooth installation and removal process and keeps ProxSnap aligned with other Prox Tools, allowing it to blend seamlessly into existing Proxmox VE environments.

ProxSnap Debian Mirror

The easiest way to get started with ProxSnap is by installing it through the gyptazy open source solutions Debian repository. This method is recommended because it integrates ProxSnap directly into the system package management and ensures that updates are delivered automatically through the regular upgrade process.

By using the repository, no manual downloads or build steps are required. Once the repository is added, ProxSnap can be installed like any other system package, making the initial setup quick and reliable. The following snippet shows how to add the repository and install ProxSnap on Debian or Proxmox VE based systems.


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

ProxSnap Debian Package

As an alternative, ProxSnap can also be obtained by directly downloading the statically compiled Rust binary packaged as a Debian .deb file. This option is useful for environments where adding an external repository is not desired or possible.

The downloaded package can be installed using either apt or dpkg and does not require any additional dependencies or build steps. This makes it a quick and self contained installation method while still providing the same standalone ProxSnap binary and full functionality.


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

ProxSnap Config

ProxSnap is built to fit seamlessly into existing Proxmox VE environments while keeping configuration effort to a minimum. By default, it automatically reads its configuration from /etc/proxsnap/proxsnap.yaml, allowing ProxSnap to be deployed system wide without the need for additional command line arguments.

If a different configuration location is required, or if multiple setups need to be tested, the default path can be overridden using the -c option together with a custom file path. This is particularly useful in development environments or when running ProxSnap in isolated or temporary setups.

In environments where ProxLB is already in use on the same node, the existing configuration can be reused without modification. ProxSnap follows the same configuration structure, making it possible to share credentials and connection settings across tools. This keeps configuration consistent within the Prox Tools collection and avoids unnecessary duplication.

The configuration itself defines how ProxSnap communicates with the Proxmox VE API. Access is handled through an API token, providing a secure and permission controlled authentication mechanism. Options such as SSL verification and request timeouts can be adjusted to match the specific requirements of the environment. Below, you can find an example config:


proxmox_api:
  hosts: virt01-de-ne01.dev.gyptazy.com
  user: proxsnap@pam
  token_id: test
  token_secret: ac1079bb-3333-3333-3333-8a3262da6077
  ssl_verification: False
  timeout: 10

The hosts setting specifies the Proxmox VE node or API endpoint that ProxSnap should connect to. Together, the user, token_id, and token_secret form the API token used for authentication, ensuring access is both secure and permission controlled. Depending on the certificate setup in the environment, SSL verification can be enabled or disabled, while the timeout option defines how long ProxSnap waits for responses from the Proxmox VE API.

This clear and familiar configuration layout makes ProxSnap easy to adopt, particularly in environments where other Prox Tools are already in use. Once the configuration is in place, no additional setup is required and ProxSnap can immediately start delivering cluster wide snapshot visibility.

Using ProxSnap in Proxmox VE Environments

ProxSnap is built with a strong focus on transparency and ease of use. Its output is intentionally structured and explicit, allowing administrators to quickly understand the snapshot state of an entire Proxmox VE cluster without having to interpret complex or condensed information. Every command is designed to provide clear results that can be acted upon immediately.

At its core, ProxSnap operates by querying the Proxmox VE API and collecting snapshot information across all nodes in a cluster. This includes both virtual machines and containers. The tool aggregates this data and presents it in a readable, node based structure, making it easy to spot patterns, inconsistencies, or outdated snapshots.

Cluster Wide Snapshot Overview

The most common entry point when working with ProxSnap is the list mode. By using the -l or --list option, ProxSnap retrieves a complete overview of all nodes in the cluster and lists every VM and container along with their snapshot status. This mode is ideal for regular audits and quick health checks.

The output is grouped by node and clearly distinguishes between guests with and without snapshots. For guests that do have snapshots, ProxSnap prints each snapshot name together with its creation timestamp and a human readable age.


$ proxsnap -l
Node: virt01-de-ne01
  ✓ VM 101 (pmx01-dev.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))
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 guest currently has no snapshots attached, while a warning symbol highlights guests with existing snapshots. This visual distinction makes it easy to focus on systems that may require attention. The combination of exact timestamps and relative ages helps quickly assess whether snapshots are still relevant or potentially outdated.

Finding Snapshots Older Than a Specific Date

For more targeted analysis, ProxSnap provides a date based mode. By supplying the -d or --date option followed by a date in the format YYYY-MM-DD, ProxSnap searches the entire cluster for snapshots that were created before the given date. In other words, it identifies snapshots that are older than the specified cutoff.

This mode is particularly useful after maintenance tasks, migrations, upgrades, or testing phases, where snapshots are often created temporarily and later forgotten. Instead of manually checking each VM or container, ProxSnap highlights all matching snapshots in a single run.


$ 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)

By default, this mode performs a dry run. No changes are made to the environment. ProxSnap simply reports which snapshots match the criteria, allowing you to review the results carefully before deciding on further action.

Removing Outdated Snapshots

Once you have reviewed the output and confirmed that the listed snapshots are no longer needed, ProxSnap can be instructed to remove them automatically. This is done by adding the -r or --remove option. When enabled, ProxSnap deletes the matching snapshots using the Proxmox VE API.

Removal is explicit and controlled. Only snapshots that match the cutoff date are affected, and the implicit current snapshot is never touched.


$ proxsnap -d 2026-01-04 -r
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 in detail, showing exactly which snapshot was removed and from which VM or container. This ensures full traceability and makes it easy to audit the cleanup process.

After completing a cleanup run, the list mode can be executed again to verify the result and confirm that the snapshots have been removed successfully.


$ proxsnap -l
Node: virt01-de-ne01
  ✓ VM 101 (pmx01-dev.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))
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 structured workflow makes ProxSnap suitable for both routine snapshot audits and controlled cleanup operations. Administrators can start with a read only overview, narrow the scope using a date threshold, and only enable removal once they fully understand which snapshots will be affected. As a result, snapshot management becomes predictable, safe, and easy to integrate into everyday Proxmox VE operations.

Scenarios of ProxSnap Usage

ProxSnap is designed to address real world operational gaps that commonly appear in Proxmox VE clusters over time. Snapshots are often created with good intentions, but without a clear overview or regular cleanup process, they can easily become forgotten. The following scenarios highlight typical situations where ProxSnap provides immediate value.

In all of these scenarios, ProxSnap acts as a visibility and control layer that is missing from default Proxmox VE tooling. Instead of relying on manual checks or assumptions, administrators gain concrete data that can be reviewed, audited, and acted upon. Whether used interactively for troubleshooting or automated as part of regular maintenance, ProxSnap helps ensure that snapshots remain a useful safety feature rather than a hidden operational risk.

Open-Source & Code of ProxSnap

ProxSnap is developed with an open source mindset, focusing on transparency, reliability, and practical value for Proxmox VE environments. At the current stage, ProxSnap is distributed as prebuilt binary packages, allowing users to benefit from the tool without having to compile or maintain the source code themselves.

At the moment, the source code of ProxSnap is not publicly available. The primary reason for this decision is not technical, but practical. Publishing source code often comes with expectations around long term maintenance, rapid bug fixes, feature requests, and community support. With several other active projects such as ProxLB, ProxCLMC, BoxyBSD, and additional tooling already requiring ongoing attention, available time is a limiting factor.

Despite this, it still makes sense to share ProxSnap as a usable utility. Even in its current form, the tool already delivers clear value by closing an important operational gap in Proxmox VE cluster management. Making the binary available allows users to benefit from its functionality today, rather than waiting for a future point where full open source maintenance could be realistically sustained.

This approach is not set in stone. As the project evolves and circumstances change, publishing the source code remains a possibility. ProxSnap may eventually follow the same path as other projects once the required capacity for long term maintenance and community engagement is available.

For now, the focus remains on providing a stable, useful, and well integrated tool that helps administrators manage snapshots more effectively in real world Proxmox VE environments. You can also find some more information about ProxSnap in my blog post about it in automated snapshot cleanups for Proxmox clusters.