Backing up non-PVE hosts with proxmox-backup-client · Proxmox VE

Every estate has hosts that are not virtual machines on your cluster: the physical database server nobody will virtualise, the cloud instance running the public-facing thing, the build machine, the NAS, the router with a configuration you would hate to rebuild. They usually end up on a different backup product, with a different retention policy, a different restore procedure and a different set of people who know how to use it.

proxmox-backup-client puts them in the same datastore as everything else. Same deduplication, same verification, same prune and garbage-collection machinery, same restore skills. It is a standalone binary that talks to PBS directly; PVE is not involved at any point.

Installing the client

The client ships in the Proxmox repositories, and on a non-Proxmox Debian or Ubuntu host you add the client repository rather than the full PBS one.

Configuration changeclient installation on Debian 13— Adds the Proxmox client repository and its signing key. On a PVE or PBS host the client is already present and this step is unnecessary.

set -euo pipefail

apt update && apt install -y ca-certificates wget

wget -O /usr/share/keyrings/proxmox-archive-keyring.gpg \
https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg

cat > /etc/apt/sources.list.d/pbs-client.sources <<'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF

apt update && apt install -y proxmox-backup-client
proxmox-backup-client version

The repository string and the credential

Everything the client does is aimed at a repository, whose format is:

[[username@]server[:port]:]datastore

The username defaults to root@pam if unset — which, per the previous lesson, is exactly what you do not want a standalone host holding.

Configuration changeon the PBS server: an identity for this host, scoped to one namespace— One user and token per host. A compromised host then reaches only its own backups, and revoking one token affects nothing else.

set -euo pipefail

proxmox-backup-manager user create db01@pbs --comment 'Physical DB server db01'
proxmox-backup-manager user generate-token db01@pbs client

# DatastoreBackup: can write and restore its own backups; cannot prune.
for id in 'db01@pbs' 'db01@pbs!client'; do
proxmox-backup-manager acl update /datastore/store1/hosts/db01 \
  DatastoreBackup --auth-id "$id"
done

Do not put the token secret in the backup script

PBS_PASSWORD exists and it is the wrong tool for a scheduled job, because an environment variable set in a script is readable by anything that can read the script and frequently ends up in a git repository.

The client supports three better sources, all documented:

Variable	Reads the password from
`PBS_PASSWORD_FILE`	A named file
`PBS_PASSWORD_FD`	An already-open file descriptor
`PBS_PASSWORD_CMD`	The standard output of a command

PBS_PASSWORD_FILE pointing at a root-owned 0600 file is the minimum. PBS_PASSWORD_CMD is the one to use where a secret manager exists, because the secret never lands on disk at all. The same four-way choice exists for the encryption passphrase as PBS_ENCRYPTION_PASSWORD, PBS_ENCRYPTION_PASSWORD_FILE, PBS_ENCRYPTION_PASSWORD_FD and PBS_ENCRYPTION_PASSWORD_CMD.

Configuration change/etc/proxmox-backup/client.env - sourced by the unit, never committed— Create with umask 077. This file is the credential; treat it as one.

set -euo pipefail
install -d -m 0700 /etc/proxmox-backup

umask 077
cat > /etc/proxmox-backup/client.env <<'EOF'
PBS_REPOSITORY=db01@pbs!client@pbs1.example.com:store1
PBS_NAMESPACE=hosts/db01
PBS_PASSWORD_FILE=/etc/proxmox-backup/token.secret
PBS_ENCRYPTION_PASSWORD_FILE=/etc/proxmox-backup/key.passphrase
PBS_FINGERPRINT=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
EOF

printf '%s\n' 'REPLACE_ME_WITH_THE_TOKEN_SECRET' > /etc/proxmox-backup/token.secret
chmod 0600 /etc/proxmox-backup/token.secret /etc/proxmox-backup/client.env

PBS_FINGERPRINT verifies the server certificate. Setting it means a client that finds itself talking to a different server — because DNS was poisoned, or because someone stood up a lookalike — refuses rather than uploading your data to it.

Encryption, and the key you must not lose

Client-side encryption is the feature that makes it reasonable to back up a sensitive host into a shared datastore, or into a datastore you do not administer.

Configuration changecreate an encryption key, then get it out of the building— The key is created on the client and never leaves it. Without the key and its passphrase the backups are unrecoverable - by you as well as by an attacker.

set -euo pipefail

proxmox-backup-client key create /etc/proxmox-backup/db01.key
chmod 0600 /etc/proxmox-backup/db01.key

# A printable copy for the safe. This is the escrow that matters.
proxmox-backup-client key paperkey /etc/proxmox-backup/db01.key \
> /root/db01-paperkey.txt

An encrypted backup with a lost key is not a backup

This is not a caution, it is arithmetic. The chunks are encrypted on the client before they are sent. PBS stores ciphertext and holds nothing that can decrypt it. If the key file and its passphrase are both lost — and they will be, because the host holding them is the host you are backing up — the entire retention history is gone.

Two escrow mechanisms exist and you should use at least one:

Paper key. A printable representation of the key, stored physically, offline, somewhere with different access control from the datacentre.
Master key. proxmox-backup-client key create-master-key produces an RSA key pair; key import-master-pubkey installs the public half on each client. Encryption keys are then stored in the backup itself, wrapped with the master public key, and can be recovered later with key import-with-master-key and the master private key.

The master key approach scales to a fleet. The paper key is the one that survives the loss of the fleet. A serious estate has both, in different places, and tests the recovery once a year.

The backup itself

Read-only / Safea first backup, run by hand— Reads from the host and writes to the datastore. Nothing on the host is modified.

set -euo pipefail
set -a; . /etc/proxmox-backup/client.env; set +a

proxmox-backup-client backup \
root.pxar:/ \
--keyfile /etc/proxmox-backup/db01.key \
--exclude /proc --exclude /sys --exclude /dev --exclude /run \
--exclude /tmp --exclude /var/tmp \
--exclude /var/lib/postgresql \
--exclude /mnt --exclude /media

proxmox-backup-client snapshot list

Three design decisions are embedded in that command and they are the difference between a copy and a restorable host.

Split archives by restore unit, not by directory tidiness. An archive is the granularity at which you restore. Anything you might want to recover without touching the rest deserves its own archive:

Read-only / Safemultiple archives in one snapshot— One snapshot, three independently restorable archives, one atomic point in time across all of them.

set -euo pipefail
set -a; . /etc/proxmox-backup/client.env; set +a

proxmox-backup-client backup \
system.pxar:/ \
data.pxar:/srv/data \
dbdump.pxar:/var/backups/pgdump \
--keyfile /etc/proxmox-backup/db01.key \
--exclude /proc --exclude /sys --exclude /dev --exclude /run \
--exclude /srv/data --exclude /var/backups/pgdump

Exclusions belong in two places. Pseudo-filesystems and caches go on the command line, where they are visible in the unit file and in review. Anything application-specific is better expressed as a .pxarexclude file in the directory it concerns, where it lives next to the thing it describes and survives a rewrite of the backup script. Patterns are one per line, # introduces a comment, ! reverses a pattern into an inclusion, a leading / anchors to the current directory and a pattern without one matches in subdirectories too.

A live database directory is not a backup of the database. The exclusion of /var/lib/postgresql above is deliberate: what is included is /var/backups/pgdump, produced by a dump that runs before the backup. Copying running database files with a file-level tool produces exactly the crash consistency problem from xiii-pbs-backup-modes, without even the benefit of a coordinated snapshot.

Why a file-level host backup deduplicates worse than a VM image, and what to do about it

VM images are chunked at fixed 4 MiB boundaries. A file archive is chunked dynamically, with boundaries chosen by a rolling hash over the generated .pxar stream so that inserting data perturbs one chunk instead of shifting every boundary after it.

Dynamic chunking is the right answer for archives, but it is weaker than the fixed case in one specific way: the chunk boundaries depend on the stream, and the stream depends on the order in which files are encoded and on their metadata. A large reorganisation of a directory tree can therefore change more chunks than the amount of data that actually changed.

Two practical consequences:

Do not rewrite the archive layout casually. Renaming data.pxar to srv-data.pxar starts a new backup group and gives up the reuse against every previous snapshot in the old one.
Reach for --change-detection-mode metadata on hosts with large static trees. It splits data and metadata into separate streams using pxar format version 2 and uses the previous snapshot’s metadata archive to detect unchanged files, so those files are not re-read from disk at all. The first run after switching is not faster — it is building the metadata archive.

Scheduling it

There is no backup job scheduler outside PVE, and that is fine, because systemd already is one.

Configuration change/etc/systemd/system/pbs-backup.service— A oneshot unit. EnvironmentFile keeps the credential out of the unit, and out of anything that renders unit files.

set -euo pipefail

cat > /etc/systemd/system/pbs-backup.service <<'EOF'
[Unit]
Description=Back up this host to Proxmox Backup Server
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
EnvironmentFile=/etc/proxmox-backup/client.env
ExecStartPre=/usr/local/sbin/pre-backup-dump.sh
ExecStart=/usr/bin/proxmox-backup-client backup \
system.pxar:/ data.pxar:/srv/data dbdump.pxar:/var/backups/pgdump \
--keyfile /etc/proxmox-backup/db01.key \
--exclude /proc --exclude /sys --exclude /dev --exclude /run \
--exclude /srv/data --exclude /var/backups/pgdump
Nice=10
IOSchedulingClass=idle
EOF

cat > /etc/systemd/system/pbs-backup.timer <<'EOF'
[Unit]
Description=Nightly PBS backup

[Timer]
OnCalendar=*-*-* 01:30:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now pbs-backup.timer
systemctl list-timers pbs-backup.timer

RandomizedDelaySec matters more than it looks: forty hosts with an OnCalendar of 01:30 all connect at 01:30 and turn a manageable load into a thundering herd against one datastore. Persistent=true runs a missed backup after the host comes back, which is the behaviour you want on a machine that is not always on.

Read-only / Safestale-backup detector - run it on the PBS server itself— Read-only. A local repository name is a valid repository string, so no credential is needed. Any group whose newest snapshot is older than the threshold is either broken or gone, and both need a human.

set -euo pipefail
STORE=store1
MAX_AGE_HOURS=36

# snapshot list prints one line per snapshot; the group is the first column.
# Keep only the newest line per group and compare its timestamp to now.
proxmox-backup-client snapshot list --repository "$STORE" \
| awk 'NR>2 {print $2}' \
| sort -t/ -k1,2 -k3,3r \
| awk -F/ '!seen[$1"/"$2]++ {print $0}' \
| while read -r snap; do
  when=$(printf '%s' "$snap" | sed 's|.*/||')
  age=$(( ( $(date +%s) - $(date -d "$when" +%s) ) / 3600 ))
  if [ "$age" -gt "$MAX_AGE_HOURS" ]; then
    printf 'STALE %-40s %s h old\n' "$snap" "$age"
  fi
done

Restoring a host

Destructiverestore paths, in increasing order of commitment— The mount is read-only and safe. The restore writes to the target path - stage it, never point it at a live root filesystem.

set -euo pipefail
set -a; . /etc/proxmox-backup/client.env; set +a

proxmox-backup-client snapshot list

# 1. Browse, decide, extract selectively.
proxmox-backup-client catalog shell 'host/db01/2026-08-11T01:30:00Z' data.pxar

# 2. Mount read-only and copy out what you need.
mkdir -p /mnt/restore
proxmox-backup-client mount 'host/db01/2026-08-11T01:30:00Z' data.pxar /mnt/restore
# ... copy ...
umount /mnt/restore

# 3. Restore a whole archive into a staging directory.
proxmox-backup-client restore 'host/db01/2026-08-11T01:30:00Z' \
data.pxar /srv/staging/db01-restore/

What happens when the host you are restoring is the host that is gone?

This is the scenario that separates a host backup from a VM backup, and it is the one people skip when they rehearse.

Restoring a VM is self-contained: the image contains the machine. Restoring a physical host from a file-level archive gives you the files, and you supply everything else — an installed base OS, a bootloader, a partition table, a network configuration, the encryption key, the token, and the client binary itself. None of that is in the archive, and some of it is on the machine that no longer exists.

So the recovery procedure has a bootstrap phase that has to be written down separately:

Install a base Debian 13 on replacement hardware, matching the original partition layout closely enough that the restored /etc/fstab is valid.
Install proxmox-backup-client.
Obtain the encryption key from escrow, and the token secret from your secret manager. If either lives only on the dead host, stop here — this is the failure the paper key exists to prevent.
Restore system.pxar to a staging directory, then merge deliberately: /etc, /home, /srv, service unit files. Do not restore over a running root filesystem.
Reinstall the bootloader and regenerate the initramfs, because those are host-specific and the restored files describe the old disks.

That is a runbook, not a command, and it should exist before you need it. The disciplined version of this lesson ends with restoring one host onto a spare machine once, timing it, and writing down every step you had to improvise.

Knowledge check

Why this matters

The argument for putting non-PVE hosts in PBS is not that PBS is the best file-level backup tool available. It is consolidation of skill.

A separate product for the physical hosts means a second retention policy nobody reviews, a second restore procedure nobody has rehearsed, a second monitoring integration nobody wired up, and a second set of credentials nobody rotates. In an incident it means the person who knows how to restore is the person who is on holiday.

One datastore, one permission model, one prune and garbage-collection story, one verification regime, one restore skill. The technical benefits — deduplication across similar hosts, client-side encryption, incremental metadata detection — are real, and they are secondary to the fact that everyone on the team already knows how the thing works.