Connection

cv4pve-node-protect connects to every node over SSH, not to the Proxmox VE API. Set up the account first: see SSH access and security.

What happens on each node

For every host in --host, one after the other, the tool:

1. opens an SSH connection (port 22, or the one given as host:port);

2. runs one command, with the paths from --paths in single quotes:

   tar --one-file-system --ignore-failed-read -czPf - -- '/etc/.' '/etc/pve/.' '/var/lib/pve-cluster/.'

3. writes what tar sends on the SSH channel straight into the local archive, and closes the connection.

Nothing is installed and no file is written on the node, not even in /tmp. The command only reads. With --debug the tool prints the exact command it runs.

Options

Option	What it does
--host	The nodes to back up, comma-separated, each host[:port]; the port defaults to 22. Every node in the list is backed up: it is not a list of alternatives as in the API-based cv4pve tools.
--username	SSH user. Always needed, with a key too. Use root, see Which account.
--private-key-file	SSH private key; the file must exist. When given, only the key is tried, not the password.
--passphrase	Passphrase of the key, if it has one.
--password	SSH password, or file:/path to read it from a file (whole file, leading and trailing spaces and new lines removed).
--timeout	SSH connection timeout in seconds. Default 30.

On error the tool prints ERROR: … and exits with code 1.

Hosts

--host=pve01                        # host name, port 22
--host=pve01:2222                   # custom port
--host=192.168.1.10,192.168.1.11    # several nodes, IPv4
--host=fe80::1                      # IPv6 without port
--host=[fe80::1]:2222               # IPv6 with port: brackets required
--host=[::1]:22,pve01,192.168.1.10  # mixed

The nodes are backed up in the order given. The archive takes its name from the host as you wrote it: --host=192.168.1.10 gives 192.168.1.10-config.tar.gz, so use node names if you want archives named after the nodes. On Windows, which does not allow : in file names, the : of an IPv6 address becomes _: --host=fe80::1 gives fe80__1-config.tar.gz.

If one node fails, the others are still backed up and the run ends with exit code 1: see When a run fails.

Options in a file

A backup run by cron or Task Scheduler repeats the same connection every time: keep it in a file. It is also the place for a password, instead of the command line.

Put the options you repeat (the connection above all) in a file and pass it with @. The file is read as if its content were typed on the command line, so no shell quoting is needed: an API token with ! goes in as it is.

nodes.rsp

# Every node to back up: each one gets its own archive
--host=pve01,pve02,pve03
--username=root

# SSH key (recommended)
--private-key-file=/root/.ssh/id_ed25519
# --passphrase=<passphrase>

# ...or a password: used only when no key is given
# --password=<password>
# ...or the password in a file
# --password=file:/etc/cv4pve/password

cv4pve-node-protect @nodes.rsp backup --paths='/etc/.;/etc/pve/.;/var/lib/pve-cluster/.' --directory-work=/srv/node-protect --keep=7

• @nodes.rsp is replaced by its content where it stands, so put it where those options are valid: with the other options of the command, before or after them.
• Options are separated by spaces, one or more per line: --option=value or--option value. A value with spaces goes in quotes: --settings-file="C:\My Files\settings.json".
• A line that starts with # is a comment: handy to keep alternatives ready, as above. A# after an option is not: it is read as an argument and the command fails.
• @other.rsp inside a file includes another file, for example one with the connection, shared by files with different options.

A file with a password or an API token is as sensitive as the password itself: keep it readable only by the account that runs the tool (chmod 600 on Linux). TheSystem.CommandLine library the tools are built on calls such a file a response file.