Install cv4pve-node-protect and back up a Proxmox VE node
cv4pve-node-protect runs outside the cluster (on your workstation, a management VM or the machine that keeps your backups) and connects to each node over SSH on port 22. It does not use the Proxmox VE API and nothing is installed on the nodes.
First backup
Section titled “First backup”-
Install cv4pve-node-protect
arch=$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/;s/armv7l/arm/')wget https://github.com/Corsinvest/cv4pve-node-protect/releases/latest/download/cv4pve-node-protect-linux-$arch.zipunzip cv4pve-node-protect-linux-$arch.zipchmod +x cv4pve-node-protectcurl -s https://api.github.com/repos/Corsinvest/cv4pve-node-protect/releases/latest | grep -o "https://[^\"]*-$(dpkg --print-architecture)\.deb" | xargs curl -LOsudo dpkg -i cv4pve-node-protect-*-$(dpkg --print-architecture).debcurl -s https://api.github.com/repos/Corsinvest/cv4pve-node-protect/releases/latest | grep -o "https://[^\"]*-$(rpm --eval %_target_cpu)\.rpm" | xargs curl -LOsudo rpm -i cv4pve-node-protect-*-$(rpm --eval %_target_cpu).rpmyay -S cv4pve-node-protectbrew install corsinvest/tap/cv4pve-node-protectcurl -s https://api.github.com/repos/Corsinvest/cv4pve-node-protect/releases/latest | grep -o "https://[^\"]*-$(uname -m)\.pkg" | xargs curl -LOsudo installer -target / -pkg cv4pve-node-protect-*-$(uname -m).pkgarch=$(uname -m | sed 's/x86_64/x64/')curl -LO https://github.com/Corsinvest/cv4pve-node-protect/releases/latest/download/cv4pve-node-protect-osx-$arch.zipunzip cv4pve-node-protect-osx-$arch.zipchmod +x cv4pve-node-protectwinget install Corsinvest.cv4pve.nodeprotect$arch = @{ AMD64 = 'x64'; x86 = 'x86'; ARM64 = 'arm64' }[$env:PROCESSOR_ARCHITECTURE]Invoke-WebRequest https://github.com/Corsinvest/cv4pve-node-protect/releases/latest/download/cv4pve-node-protect.exe-win-$arch.zip -OutFile cv4pve-node-protect.zipExpand-Archive cv4pve-node-protect.zip -DestinationPath . -ForceAll files are on the latest release page.
-
Set up SSH access
You need SSH access as
rootto every node: see SSH access and security. -
Run
cv4pve-node-protect backupCreate a local folder for the archives, readable only by you (the tool does not create it), then run the backup:
mkdir -p /srv/node-protect && chmod 700 /srv/node-protectcv4pve-node-protect --host=pve01,pve02,pve03 --username=root --private-key-file=/root/.ssh/id_ed25519 \backup --paths='/etc/.;/etc/pve/.;/var/lib/pve-cluster/.' --directory-work=/srv/node-protect --keep=7Custom ports, IPv6, password authentication and options in a file for scheduled runs: see Connection.
-
Check the archive
Each run creates a folder named after the local date and time, with one archive per node. Read the warnings of the first run and look inside the archive once: a path that does not exist on the node is only a warning, see Run.
tar -tzvf /srv/node-protect/2026-09-29-03-00-01/pve01-config.tar.gz | less
cv4pve-node-protect has one command, backup. Its options:
| Option | What it does |
|---|---|
--paths |
Paths on the node to archive, separated by ;. Required, no default: see What to back up. |
--directory-work |
Local folder for the archives. Required; it must exist. |
--keep |
Number of dated folders to keep, 1 to 100. Required: see Retention. |
The connection options go before backup, these after it:
cv4pve-node-protect --host=pve01,pve02,pve03 --username=root --private-key-file=/root/.ssh/id_ed25519 \ backup --paths='/etc/.;/etc/pve/.;/var/lib/pve-cluster/.' --directory-work=/srv/node-protect --keep=7The output:
ACTION BackupKeep: 7Directory Work: /srv/node-protectDirectory Node to archive:/etc/./etc/pve/./var/lib/pve-cluster/.Create config: 2026-09-29-03-00-01/pve01-config.tar.gzCreate config: 2026-09-29-03-00-01/pve02-config.tar.gzCreate config: 2026-09-29-03-00-01/pve03-config.tar.gz
Each run creates a folder named after the local date and time, with one archive per node. From the
eighth run on, --keep=7 deletes the oldest folder and prints Delete Backup: <folder>. The tool
exits with code 0 when every node is backed up, 1 on an error.
What to back up explains which paths to pass and why /etc/.
alone misses /etc/pve; Scheduling runs it every night;
Restore shows how to get a node’s configuration back.