winget install --id=Corsinvest.cv4pve.autosnap -e cv4pve-autosnap is an automatic snapshot tool designed for Proxmox VE virtual machines and containers. It streamlines backup processes by creating snapshots with retention policies, ensuring efficient data management.
Key Features:
Audience & Benefit: Ideal for system administrators managing Proxmox VE environments, cv4pve-autosnap provides reliable backups and efficient data management. Its features enhance flexibility in targeting specific VMs or containers, integrate seamlessly with existing automation scripts, and maintain data integrity through retention policies.
This tool can be installed via winget, offering a straightforward setup process for users familiar with Proxmox VE environments.
______ _ __
/ ____/___ __________(_)___ _ _____ _____/ /_
/ / / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
/ /___/ /_/ / / (__ ) / / / / |/ / __(__ ) /_
\____/\____/_/ /____/_/_/ /_/|___/\___/____/\__/
Automatic Snapshot Tool for Proxmox VE (Made in Italy)
> Automatic snapshot management for Proxmox VE — create, retain and clean snapshots of VM/CT with a single command.
wget https://github.com/Corsinvest/cv4pve-autosnap/releases/download/VERSION/cv4pve-autosnap-linux-x64.zip
unzip cv4pve-autosnap-linux-x64.zip
./cv4pve-autosnap --host=YOUR_HOST --api-token=user@realm!token=uuid --vmid=100 snap --label=daily --keep=7
| Platform | Command |
|---|---|
| Linux | wget .../cv4pve-autosnap-linux-x64.zip && unzip cv4pve-autosnap-linux-x64.zip && chmod +x cv4pve-autosnap |
| Windows WinGet | winget install Corsinvest.cv4pve.autosnap |
| Windows manual | Download cv4pve-autosnap-win-x64.zip from Releases |
| Arch Linux |
yay -S cv4pve-autosnap| Debian/Ubuntu | sudo dpkg -i cv4pve-autosnap-VERSION-ARCH.deb |
| RHEL/Fedora | sudo rpm -i cv4pve-autosnap-VERSION-ARCH.rpm |
| macOS | Homebrew: brew tap Corsinvest/homebrew-tap && brew install cv4pve-autosnap (tap repo)Manual: wget .../cv4pve-autosnap-osx-x64.zip && unzip cv4pve-autosnap-osx-x64.zip && chmod +x cv4pve-autosnap |
All binaries on the Releases page.
--state--max-parallel (see Performance)Security & Permissions
| Permission | Purpose | Scope |
|---|---|---|
| VM.Audit | Read VM/CT configuration and status | Virtual machines |
| VM.Snapshot | Create and delete snapshots | Virtual machines |
| Datastore.Audit | Check storage capacity | Storage systems |
| Pool.Audit (PVE 9+) / Pool.Allocate (PVE 8 and earlier) | Read pool membership (needed for --vmid=@pool-*) | Resource pools |
> Pool selection (--vmid=@pool-*) resolves the pool via GET /pools. On Proxmox VE 9+ that endpoint requires the read-only Pool.Audit privilege; on PVE 8 and earlier it accepted Pool.Allocate. If pool targeting returns "VMs NOT FOUND" on PVE 9, grant Pool.Audit to the token/role. See the Proxmox VE User Management docs.
# Create snapshots with retention
cv4pve-autosnap --host=pve.local --api-token=user@realm!token=uuid --vmid=100 snap --label=daily --keep=7
# Clean old snapshots
cv4pve-autosnap --host=pve.local --api-token=user@realm!token=uuid --vmid=100 clean --label=daily --keep=7
# View snapshot status
cv4pve-autosnap --host=pve.local --api-token=user@realm!token=uuid --vmid=100 status
# Dry-run (no changes)
cv4pve-autosnap --host=pve.local --api-token=user@realm!token=uuid --vmid=100 --dry-run snap --label=daily --keep=7
# Parallel snapshots (up to 5 VMs at once)
cv4pve-autosnap --host=pve.local --api-token=user@realm!token=uuid --vmid=@all snap --label=daily --keep=7 --max-parallel 5
# Parameter file (recommended for complex setups)
cv4pve-autosnap @/etc/cv4pve/production.conf snap --label=daily --keep=14
By default snapshots are processed sequentially (--max-parallel 1). On large clusters with VMs spread across multiple nodes or using ZFS/Ceph storage, parallel execution significantly reduces total run time.
# Run up to 5 snapshots in parallel
cv4pve-autosnap --host=pve.local --api-token=token --vmid=@all snap --label=daily --keep=7 --max-parallel 5
| Setting | Effect | Default |
|---|---|---|
--max-parallel 1 | Sequential — one VM at a time | default |
--max-parallel N | Up to N VMs snapshotted concurrently | — |
> Tip: values between 3 and 10 are a reasonable range. ZFS and Ceph handle parallel snapshots very well.
>
> Warning: if multiple VMs share the same storage backend, parallel snapshots compete for the same I/O — this can slow down or destabilize the storage. On shared or slow storage (NFS, iSCSI, LVM) keep --max-parallel low (2–3) or leave it at the default of 1. On distributed storage (Ceph/RBD) or per-VM storage (ZFS datasets) higher values are safe.
The --vmid parameter supports powerful pattern matching:
| Pattern | Example | Description |
|---|---|---|
| Single ID | --vmid=100 | Specific VM/CT by ID |
| Single name | --vmid=web-server | Specific VM/CT by name |
| Multiple | --vmid=100,101,web-server | Comma-separated list |
| Range | --vmid=100:110 | Range of IDs (inclusive) |
| Wildcard | --vmid=%web% | Contains pattern |
| All VMs | --vmid=@all | All VMs in cluster |
| Pool | --vmid=@pool-production | All VMs in specific pool |
| Tag | --vmid=@tag-backup | All VMs with specific tag |
| Node | --vmid=@node-pve1 | All VMs on specific node |
| Exclusion | --vmid=@all,-100,-test-vm | Exclude specific VMs |
| Tag exclusion | --vmid=@all,-@tag-test | Exclude VMs with tag |
# Daily snapshot at 2 AM (keep 7 days)
0 2 * * * /usr/local/bin/cv4pve-autosnap --host=pve.local --api-token=backup@pve!daily=uuid --vmid=@tag-production snap --label=daily --keep=7
# Weekly snapshot on Sunday at 3 AM (keep 4 weeks)
0 3 * * 0 /usr/local/bin/cv4pve-autosnap --host=pve.local --api-token=backup@pve!weekly=uuid --vmid=@all snap --label=weekly --keep=4
# Monthly cleanup on 1st at 4 AM
0 4 1 * * /usr/local/bin/cv4pve-autosnap --host=pve.local --api-token=backup@pve!clean=uuid --vmid=@all clean --label=monthly --keep=12
Hook scripts receive environment variables for custom automation:
CV4PVE_AUTOSNAP_PHASE # snap-create-pre, snap-create-post, snap-remove-pre, snap-remove-post, ...
CV4PVE_AUTOSNAP_VMID # VM/CT ID
CV4PVE_AUTOSNAP_VMNAME # VM/CT name
CV4PVE_AUTOSNAP_VMTYPE # qemu or lxc
CV4PVE_AUTOSNAP_LABEL # Snapshot label
CV4PVE_AUTOSNAP_KEEP # Retention count
CV4PVE_AUTOSNAP_SNAP_NAME # Snapshot name
CV4PVE_AUTOSNAP_VMSTATE # Memory state included (1/0)
CV4PVE_AUTOSNAP_DURATION # Operation duration in seconds
CV4PVE_AUTOSNAP_STATE # Operation status (1/0)
CV4PVE_AUTOSNAP_DEBUG # Debug mode (1/0)
CV4PVE_AUTOSNAP_DRY_RUN # Dry-run mode (1/0)
Available phases
| Phase | Description |
|---|---|
snap-job-start | Before the entire snap job starts |
snap-job-end | After the entire snap job ends |
snap-create-pre | Before creating a snapshot for a VM |
snap-create-post | After creating a snapshot for a VM |
snap-create-abort | When snapshot creation fails |
snap-remove-pre | Before removing an old snapshot |
snap-remove-post | After removing an old snapshot |
snap-remove-abort | When snapshot removal fails |
clean-job-start | Before the entire clean job starts |
clean-job-end | After the entire clean job ends |
#!/bin/bash
case $CV4PVE_AUTOSNAP_PHASE in
"snap-create-pre")
echo "Starting snapshot for VM $CV4PVE_AUTOSNAP_VMID"
;;
"snap-create-post")
echo "Completed snapshot $CV4PVE_AUTOSNAP_SNAP_NAME"
;;
esac
cv4pve-autosnap --host=pve.local --api-token=token --vmid=100 snap --label=daily --keep=7 --script-hook=/opt/scripts/hook.sh
Ready-to-use templates (Bash, PowerShell, Windows Batch) are available in the hooks/ folder.
> For snapshot consistency with running databases (MySQL, PostgreSQL) and QEMU Guest Agent setup, see docs/snapshot-consistency.md.
Web GUI version: cv4pve-admin
Professional support and consulting available through Corsinvest.
Part of cv4pve suite | Made with ❤️ in Italy by Corsinvest
Copyright © Corsinvest Srl