proxmox-backup-client is the command line tool that backs up the files of a Linux machine to a Proxmox Backup Server (PBS): deduplication, compression, client-side encryption and file-level restore. Proxmox only publishes it for Debian. We republish its official static build, without recompiling it, in an unofficial repository that installs with each distribution's standard tools.
For Windows, see our Windows client for PBS. To keep your restic or rsync jobs, see offsite Linux server backup through the Gateway.
In short
- Install the package from your distribution's repository.
- Create an API token on the PBS and store it in a file only root can read.
- Create an encryption key before the first backup, and keep a copy elsewhere.
- Run
proxmox-backup-client backup root.pxar:/. - Schedule it with a systemd timer, or cron.
- Test a restore. A backup that was never restored is not a backup.
1. Install the client
The commands below add the repository and its signing key, then install the package. All metadata is signed: no --nogpgcheck or --allow-untrusted is needed, and you should not add one. The key fingerprint is shown on the repository page: compare it with the one your package manager shows you.
Debian and Ubuntu
The repository serves Proxmox's official .deb as is, byte for byte. The package is called proxmox-backup-client-static; its only dependency is qrencode.
install -d /etc/apt/keyrings
curl -fsSL -o /etc/apt/keyrings/unofficial-repository-proxmox-backup-client.asc \
https://nimbus.rdem-systems.com/unofficial-repository-proxmox-backup-client/keys/unofficial-repository-proxmox-backup-client.asc
echo "deb [signed-by=/etc/apt/keyrings/unofficial-repository-proxmox-backup-client.asc] https://nimbus.rdem-systems.com/unofficial-repository-proxmox-backup-client/deb stable main" \
> /etc/apt/sources.list.d/unofficial-repository-proxmox-backup-client.list
apt update
apt install proxmox-backup-client-staticOn Debian, Proxmox's own pbs-client repository remains an official alternative: it ships the same package, signed by Proxmox.
RHEL, Rocky, Alma, Fedora
curl -fsSL -o /etc/yum.repos.d/unofficial-repository-proxmox-backup-client.repo \
https://nimbus.rdem-systems.com/unofficial-repository-proxmox-backup-client/rpm/unofficial-repository-proxmox-backup-client.repo
dnf install proxmox-backup-clientOn the first dnf install, dnf shows the key fingerprint and asks to import it: check it before you accept.
Arch Linux
curl -fsSL -o /tmp/upc.asc https://nimbus.rdem-systems.com/unofficial-repository-proxmox-backup-client/keys/unofficial-repository-proxmox-backup-client.asc
gpg --show-keys /tmp/upc.asc # compare the fingerprint with the repository page
pacman-key --add /tmp/upc.asc
pacman-key --lsign-key "$(gpg --with-colons --show-keys /tmp/upc.asc | awk -F: '/^fpr:/{print $10; exit}')"
printf '\n[unofficial-repository-proxmox-backup-client]\nServer = https://nimbus.rdem-systems.com/unofficial-repository-proxmox-backup-client/arch/$arch\n' >> /etc/pacman.conf
pacman -Syu proxmox-backup-clientAlpine
wget -O /etc/apk/keys/unofficial-repository-proxmox-backup-client.rsa.pub \
https://nimbus.rdem-systems.com/unofficial-repository-proxmox-backup-client/keys/unofficial-repository-proxmox-backup-client.rsa.pub
echo "https://nimbus.rdem-systems.com/unofficial-repository-proxmox-backup-client/alpine" >> /etc/apk/repositories
apk add proxmox-backup-clientarm64
Same commands. The arm64 packages come from the official aarch64 static build that Proxmox publishes in the test component of its client repository: it is official, but can be one release behind amd64. The repository page shows the version available for each architecture.
Our CI runs on our Proxmox infrastructure, and we had to change one setting to create this repository. If you want other distributions, let us know, and tell us why.
Check the installation:
proxmox-backup-client versionWhat if I extract the .deb by hand?
The binary starts, but outside Debian and Ubuntu it rejects valid certificates: certificate validation failed - Certificate fingerprint was not confirmed. It was built with Debian's OpenSSL directory, /usr/lib/ssl, and finds no certificate authority there. We reproduced it on Alpine 3.24 and Fedora 43.
Our packages add two symlinks, /usr/lib/ssl/cert.pem and /usr/lib/ssl/certs, to the distribution's certificates. That is our only change. If you prefer extracting by hand, export SSL_CERT_FILE pointing to your distribution's CA bundle (/etc/pki/tls/certs/ca-bundle.crt on RHEL and Fedora, /etc/ssl/certs/ca-certificates.crt on Alpine and Arch).
2. Connect the client to the PBS with an API token
Use an API token dedicated to the machine rather than a password: it can be revoked on its own, without touching other machines. At NimbusBackup, creating the token is covered in token management; the downloaded JSON file holds everything you need:
{
"baseurl": "https://pbs-01.nimbus.rdem-systems.com:8007",
"authid": "backup_47_uvrno2hngh@pbs!server01",
"secret": "0490bc61-368e-4b3f-b80b-430015dea457",
"datastore": "ds_47_uvrno2hngh"
}The client expects a repository of the form authid@server:port:datastore. Store it with the secret in a file only root can read:
PBS_REPOSITORY=backup_47_uvrno2hngh@pbs!server01@pbs-01.nimbus.rdem-systems.com:8007:ds_47_uvrno2hngh
PBS_PASSWORD=0490bc61-368e-4b3f-b80b-430015dea457install -d -m 700 /etc/proxmox-backup-client
install -m 600 /dev/null /etc/proxmox-backup-client/pbs.env # created empty, root-only
# … write the two lines above into it with your editor …
set -a; . /etc/proxmox-backup-client/pbs.env; set +a
proxmox-backup-client snapshot list # empty at first: the connection worksFingerprint. A PBS with a valid certificate, like NimbusBackup's, needs nothing. A self-signed PBS asks for its fingerprint: copy it from the PBS dashboard (Show Fingerprint) and add PBS_FINGERPRINT=… to the file.
3. Create the encryption key, before the first backup
Client-side encryption encrypts your data with AES-256 before it leaves the machine: the server only stores blocks that are unreadable without your key. Create it right away. An encrypted backup does not deduplicate against an unencrypted one, so turning encryption on later sends everything again.
# No passphrase, for a scheduled backup (the file is the key: protect it)
proxmox-backup-client key create --kdf none /etc/proxmox-backup-client/encryption-key.json
chmod 600 /etc/proxmox-backup-client/encryption-key.json
# Paper or text copy (with a QR code), to keep away from this server.
# Redirect to a file rather than printing the key in the terminal (history, logs).
proxmox-backup-client key paperkey /etc/proxmox-backup-client/encryption-key.json \
--output-format text > /root/pbs-key-to-print.txtkey paperkey draws the QR code with the qrencode command, installed with the package on Debian, Ubuntu, Arch and Alpine, and as a recommended dependency on RHEL and Fedora: install it if it is missing.
Without this key, nobody can restore: not you, not whoever hosts the PBS. Keep a copy outside the machine you back up, and outside the PBS.
4. First backup
proxmox-backup-client backup root.pxar:/ \
--keyfile /etc/proxmox-backup-client/encryption-key.json- One file system per archive. By default the client does not cross mount points: if
/homeor/varare separate partitions, add one archive per partition (home.pxar:/home) or the--include-dev /homeoption. - Exclusions. A
.pxarexcludefile in a directory, or--excludeon the command line (caches,/tmp, dumps already backed up elsewhere). - Servers with many files.
--change-detection-mode metadatacompares metadata with the previous snapshot instead of re-reading every unchanged file. The flip side: a file changed without its metadata changing would be missed. Use it where that is acceptable. - The backup ID is the host name;
--backup-idoverrides it.
5. Schedule it with a systemd timer
[Unit]
Description=Backup to Proxmox Backup Server
Wants=network-online.target
After=network-online.target
[Service]
Type=oneshot
EnvironmentFile=/etc/proxmox-backup-client/pbs.env
ExecStart=/usr/bin/proxmox-backup-client backup root.pxar:/ \
--keyfile /etc/proxmox-backup-client/encryption-key.json \
--change-detection-mode metadata
Nice=10
IOSchedulingClass=idle[Unit]
Description=Daily backup to Proxmox Backup Server
[Timer]
OnCalendar=*-*-* 02:30:00
RandomizedDelaySec=30min
Persistent=true
[Install]
WantedBy=timers.targetsystemctl daemon-reload
systemctl enable --now pbs-backup.timer
systemctl start pbs-backup.service # a first run right now
journalctl -u pbs-backup.service -n 50 # the resultWithout systemd (Alpine): one line in root's crontab is enough.
30 2 * * * umask 077; set -a; . /etc/proxmox-backup-client/pbs.env; set +a; flock -n /run/pbs-backup.lock /usr/bin/proxmox-backup-client backup root.pxar:/ --keyfile /etc/proxmox-backup-client/encryption-key.json >> /var/log/pbs-backup.log 2>&1umask 077 keeps the log out of everyone else's reach, and flock stops a backup that overruns from triggering a second one.
On the AirGapped Drive PBS plan, we strongly recommend keeping the schedule outside the weekly 4-hour window reserved for the snapshot that goes onto the offline disks: a backup running then would be incomplete on the offline copy. Retention is set on the server side: at NimbusBackup the token cannot delete, and we apply the retention.
6. Restore a file
proxmox-backup-client snapshot listTo find a few files, the catalog shell is the most comfortable:
proxmox-backup-client catalog shell host/server01/2026-09-11T02:30:12Z root.pxar \
--keyfile /etc/proxmox-backup-client/encryption-key.json
pxar:/ > find etc/nginx/**/*.conf --select
pxar:/ > restore-selected /tmp/restoreOr in one command, with a pattern:
proxmox-backup-client restore host/server01/2026-09-11T02:30:12Z root.pxar /tmp/restore \
--pattern 'etc/nginx/**' \
--keyfile /etc/proxmox-backup-client/encryption-key.jsonmount also mounts an archive read-only, over FUSE, so you can browse a backup like a directory — FUSE must be available on the machine, and remember to unmount:
proxmox-backup-client mount host/server01/2026-09-11T02:30:12Z root.pxar /mnt/backup \
--keyfile /etc/proxmox-backup-client/encryption-key.json
ls /mnt/backup
fusermount3 -u /mnt/backup # or "umount /mnt/backup" as rootRestore onto another server from time to time: it is the only test that proves the key, the token and the data belong together.
Frequently asked questions
Is the client installed from this repository the official client?
Yes for the binary, no for the repository. The proxmox-backup-client and pxar files are the ones from Proxmox's official proxmox-backup-client-static package, checked against Proxmox's signed index and never recompiled. The repository itself is run by RDEM Systems: it is unofficial and not affiliated with Proxmox Server Solutions GmbH. On Debian you can also use Proxmox's own pbs-client repository.
Why does the client reject a valid certificate on RHEL, Fedora or Alpine?
Because the static binary was built with Debian's OpenSSL directory, /usr/lib/ssl, compiled in, and that directory does not exist elsewhere. Without it the client finds no certificate authority and asks for a fingerprint, even for a perfectly valid certificate. Our RPM, Arch and Alpine packages add two symlinks to the distribution's certificates. If you extract the .deb by hand, export SSL_CERT_FILE pointing to your distribution's CA bundle.
Does client 4.x work with a PBS 3.x server?
In its 3-to-4 upgrade guide, Proxmox says it tests compatibility between the major versions still supported, including the previous one; beyond that, it is best effort at most. We recommend matching the client major version to the server, and checking backup, listing and restore yourself before going to production.
Can I turn encryption on after several backups?
Yes, but it only applies to backups made with the key: earlier ones stay unencrypted. An encrypted backup also does not deduplicate against unencrypted backups or against backups encrypted with another key, so the first encrypted backup sends all the data again. That is why we recommend creating the key before the first backup.
How do I schedule backups without systemd, on Alpine for instance?
With cron. One line in root's crontab that loads the environment file and runs proxmox-backup-client backup is enough. The rest of this guide (token, key, restore) is identical.
Who handles retention and deletes old backups?
The server. On your own PBS, that is the datastore's prune jobs. At NimbusBackup, the token we provide cannot delete: it creates and restores its own backups, nothing else. We apply the agreed retention, which also means an attacker who stole the token cannot erase your backups.
The client is installed. It needs an offsite target.
NimbusBackup hosts managed Proxmox Backup Servers, billed per usable TB: write-only token, monitoring, and options for two-site replication, offline disks or LTO tape. From 12 EUR excl. tax per TB per month.