Getting started

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.

Installation

Platform	How
Linux	wget https://github.com/Corsinvest/cv4pve-node-protect/releases/latest/download/cv4pve-node-protect-linux-x64.zip && unzip cv4pve-node-protect-linux-x64.zip && chmod +x cv4pve-node-protect ARM: cv4pve-node-protect-linux-arm64.zip, cv4pve-node-protect-linux-arm.zip
Debian / Ubuntu	sudo dpkg -i cv4pve-node-protect-VERSION-ARCH.deb (amd64, arm64, armhf)
RHEL / Fedora	sudo rpm -i cv4pve-node-protect-VERSION-ARCH.rpm (x86_64, aarch64, armv7hl)
Arch Linux	yay -S cv4pve-node-protect
Windows (WinGet)	winget install Corsinvest.cv4pve.nodeprotect
Windows (manual)	cv4pve-node-protect.exe-win-x64.zip, also x86 and arm64
macOS (Homebrew)	brew install corsinvest/tap/cv4pve-node-protect
macOS (installer)	cv4pve-node-protect-VERSION-arm64.pkg (Apple silicon) or -x86_64.pkg (Intel)
macOS (manual)	cv4pve-node-protect-osx-arm64.zip or cv4pve-node-protect-osx-x64.zip

Binaries are self-contained: no .NET runtime to install. All files are on thelatest release page.

First run

You need SSH access as root to every node (see SSH access and security) and a local folder for the archives, readable only by you: the tool does not create it.

mkdir -p /srv/node-protect && chmod 700 /srv/node-protect

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=7

Custom ports, IPv6, password authentication and options in a file for scheduled runs: see Connection.

Run

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. The output:

ACTION Backup
Keep: 7
Directory Work: /srv/node-protect
Directory Node to archive:
/etc/.
/etc/pve/.
/var/lib/pve-cluster/.
Create config: 2026-09-29-03-00-01/pve01-config.tar.gz
Create config: 2026-09-29-03-00-01/pve02-config.tar.gz
Create 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.

A missing file is only a warning

Paths that do not exist on the node, and files the SSH user cannot read, are left out of the archive: tar’s message is printed as a warning and the run still ends with exit code 0. A typo in --paths gives an archive of a few dozen bytes. Read the warnings of the first run, and look inside the archive once, and after every change of --paths or of the SSH user:

tar -tzvf /srv/node-protect/2026-09-29-03-00-01/pve01-config.tar.gz | less

Next

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.