Archives and retention

Layout

Each run creates one folder under --directory-work, named after the local date and time of the machine running the tool, with one archive per node:

/srv/node-protect/
├── 2026-09-28-03-00-01/
│   ├── pve01-config.tar.gz
│   ├── pve02-config.tar.gz
│   └── pve03-config.tar.gz
└── 2026-09-29-03-00-01/
    ├── pve01-config.tar.gz
    ├── pve02-config.tar.gz
    └── pve03-config.tar.gz

• The folder name is yyyy-MM-dd-HH-mm-ss, so sorting by name is sorting by date.
• The archive name is the host as written in --host, without the port, followed by -config.tar.gz. On Windows, which does not allow : in file names, the : of an IPv6 address becomes _: fe80::1 gives fe80__1-config.tar.gz.
• --directory-work must exist; the tool creates only the dated folders inside it.

Format

A gzip-compressed tar archive, made by GNU tar on the node, with owners, groups and permissions of every file. The entries keep their absolute path (/etc/./hostname); the extraction tools remove the leading /, so extracting into a folder is safe (see Restore).

Any tar tool reads them: tar on Linux and macOS, the tar.exe included in Windows 10 and later.

tar -tzvf pve01-config.tar.gz            # list, with permissions and dates
tar -xzf pve01-config.tar.gz -C restore  # extract into ./restore

Retention

After all nodes are backed up, --keep=N (1 to 100, required) keeps the N most recent dated folders and deletes the others, printing Delete Backup: <folder> for each.

Only folders whose name is a date in the format above are counted and deleted. Anything else in --directory-work is left alone, so you can keep notes or other files there.

To keep daily, weekly and monthly copies, use one --directory-work per schedule, each with its own --keep (see Scheduling).

When a run fails

The nodes are backed up one after the other. An error on one node (it does not answer, the login is refused, tar fails) does not stop the others:

• the error is printed as ERROR [node]: … and the run goes on with the next node;
• the half-written archive of the failing node is deleted;
• at the end the tool prints ERROR: Backup failed for N of M node(s): … Retention not applied. and exits with code 1;
• retention does not run, so an incomplete run never makes room by deleting good backups;
• the dated folder keeps the archives of the nodes that succeeded; if every node failed, it is removed.

While a node is down, every run fails for that node and retention never runs, so dated folders pile up in --directory-work. Take the node out of --host for as long as it is down.

A tar that ends with exit code 1, because some file changed while it was read (common on a running system), is not an error: the archive is kept and tar’s message is printed as a warning.