Proxmox Backup Server isn't limited to Proxmox VE. The proxmox-backup-client binary runs on any Linux system. That means your Hetzner cloud VMs, bare-metal servers, LXC containers, and even Raspberry Pis can push backups to the same PBS datastore that handles your virtual machines. You get chunk-level deduplication, optional client-side encryption (AES-256-GCM), true incremental backups, and fine-grained file restore through the pxar archive format. This guide walks through installation, authentication, backup commands, encryption, and automation so you can have any Linux box backing up to PBS in under an hour.
Key Takeaways
- proxmox-backup-client works on any Linux distro, not just Proxmox VE hosts
- The pxar archive format provides chunk-level deduplication across all backups in a datastore
- Use API tokens instead of passwords for authentication
- Encryption is optional but recommended for any offsite PBS
- Store encryption keys separately from the backup target
- Automate with systemd timers for reliable scheduled backups
How proxmox-backup-client Works
The client stores files in Proxmox's own pxar archive format. pxar is POSIX-compliant and content-addressable: it splits data into variable-size chunks, hashes each chunk, and only uploads chunks the server doesn't already have. Deduplication happens on the client before anything crosses the network.
After the first full backup, subsequent runs are incremental at the chunk level. If you change a single config file on a 50 GB server, only the affected chunks get transferred. This is the same chunk store used when Proxmox VE backs up virtual machines, so a single datastore can efficiently hold both VM backups and file-level backups from standalone Linux servers.
Encryption is optional. When enabled, each chunk is encrypted with AES-256-GCM before leaving the client. The encryption key never reaches the PBS server. The server stores opaque encrypted blobs and can still deduplicate based on chunk hashes, but cannot read the contents.
Installing the Client
Debian and Ubuntu
Add the Proxmox repository and install the package directly.
# Add the Proxmox release key
wget https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg \
-O /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
# Add the free (no-subscription) repository
echo "deb http://download.proxmox.com/debian/pbs-client bookworm main" \
> /etc/apt/sources.list.d/pbs-client.list
apt update
apt install proxmox-backup-clientFor Ubuntu, replace bookworm with your matching Debian base (e.g., bookworm for Ubuntu 24.04).
Static Binary (Any x86_64 Linux)
If you run RHEL, Fedora, Arch, or any distro without a Proxmox repo, the static binary is the simplest option. It has zero dependencies.
# Download the static client (check proxmox.com for latest version)
wget https://repo.proxmox.com/debian/pbs-client/proxmox-backup-client-static.bin
# Make it executable and move into PATH
chmod +x proxmox-backup-client-static.bin
mv proxmox-backup-client-static.bin /usr/local/bin/proxmox-backup-clientARM64
Recent Proxmox releases include ARM64 builds. If a prebuilt binary isn't available for your platform, you can compile from source using the proxmox-backup Rust codebase.
Verify Installation
proxmox-backup-client versionYou should see the client version and build info. If this works, you're ready to connect.
Connecting to PBS
Create a Dedicated Backup User
Don't use root@pam for backup jobs. Create a user with limited permissions on the PBS web UI under Configuration > Access Control > User Management. A user like backup@pbs with the DatastoreBackup role on your target datastore is enough.
Create an API Token
API tokens are the preferred authentication method. They can be scoped to specific datastores, don't expire with password changes, and can be revoked individually.
On the PBS web UI, go to Configuration > Access Control > API Token and create a token for your backup user. Note the token ID and secret. The secret is shown only once.
Prefer API Tokens Over Passwords
API tokens are safer than passwords. They can be scoped to specific datastores and revoked without changing the user password. If a server is compromised, you revoke that server's token instead of rotating a shared password.
Get the Server Fingerprint
Open the PBS dashboard and navigate to Dashboard. The SHA-256 fingerprint of the TLS certificate is displayed there. You'll need this for the client to trust the connection.
Set Environment Variables
The client reads credentials from environment variables. This keeps secrets out of command-line arguments (which would be visible in ps output).
export PBS_REPOSITORY="backup@pbs!mytoken@pbs.example.com:mydata"
export PBS_FINGERPRINT="AA:BB:CC:DD:..."
export PBS_PASSWORD="<api-token-secret>"The repository format is user@realm!tokenname@server:datastore. For password auth (without a token), use user@realm@server:datastore and set PBS_PASSWORD to the user's password.
Test the Connection
proxmox-backup-client snapshot listAn empty list or a list of existing snapshots means the connection works. An error here means a wrong fingerprint, bad credentials, or a firewall blocking port 8007.
Running Backups
File-Level Backups
The basic syntax maps a local path to a named archive inside the backup snapshot.
proxmox-backup-client backup \
etc.pxar:/etc \
home.pxar:/homeEach .pxar archive is an independent unit inside the snapshot. You can restore them individually. The backup ID defaults to the hostname but can be overridden with --backup-id myserver to group snapshots under a custom name.
Full System Backup
Back up the root filesystem while excluding virtual filesystems, caches, and temporary files.
proxmox-backup-client backup root.pxar:/ \
--exclude /proc \
--exclude /sys \
--exclude /dev \
--exclude /run \
--exclude /tmp \
--exclude /var/tmp \
--exclude /var/cache \
--exclude /swap.img \
--exclude "*.socket" \
--exclude /mnt \
--exclude /mediaCommon Exclusion Patterns
| Pattern | /proc, /sys, /dev | /tmp, /var/tmp | /var/cache | *.socket | /swap.img | /mnt, /media |
|---|---|---|---|---|---|---|
Reason | Virtual filesystems, regenerated at boot | Temporary files with no long-term value | Package caches, regenerated by apt/yum | Runtime UNIX sockets, not restorable | Swap file, wastes space and dedup ratio | Mount points for external or network storage |
Database Dumps
You can pipe output from database dump tools directly into a backup archive. The .pxar.didx suffix tells the client to read from stdin.
mysqldump --all-databases --single-transaction | \
proxmox-backup-client backup db.pxar.didx:-pg_dumpall | \
proxmox-backup-client backup pgdump.pxar.didx:-For consistency, use --single-transaction (MySQL/MariaDB) or take the dump while the database is in a known-good state. On busy databases, consider stopping writes briefly or using a replication follower for the dump.
You can combine file archives and piped archives in a single backup job:
mysqldump --all-databases --single-transaction | \
proxmox-backup-client backup \
etc.pxar:/etc \
home.pxar:/home \
db.pxar.didx:-This produces a single snapshot containing file archives and the database dump, all deduplicated and stored together.
Encryption and Automation
Client-Side Encryption
Generate an encryption key with the client. This creates a key file protected by an optional passphrase.
# With passphrase protection
proxmox-backup-client key create /root/pbs-encryption-key.enc
# Without passphrase (for unattended backups)
proxmox-backup-client key create --kdf none /root/pbs-encryption-key.encPass the key to any backup command with --keyfile:
proxmox-backup-client backup root.pxar:/ \
--keyfile /root/pbs-encryption-key.enc \
--exclude /proc --exclude /sys --exclude /dev \
--exclude /run --exclude /tmp --exclude /var/cacheOr set the environment variable PBS_ENCRYPTION_PASSWORD if your key uses a passphrase, and PBS_ENCRYPTION_KEY to point to the key file.
For a deeper look at AES-256-GCM encryption modes, master keys, and key management strategies, see our complete guide to PBS client-side encryption. If you're sending backups offsite, also consider enabling immutable backups to protect against ransomware and accidental deletion.
Back Up Your Encryption Key Separately
Store encryption keys outside the backup. If the key lives on the same server and that server dies, you've lost both the data and the means to decrypt it. Copy the key to a password manager, a hardware token, or a separate secure location.
Automating with Systemd Timers
A systemd timer is more reliable than cron for servers. It handles missed runs (if the server was off), logs output to the journal, and integrates with system monitoring.
[Unit]
Description=Backup to Proxmox Backup Server
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
EnvironmentFile=/etc/pbs-backup.env
ExecStart=/usr/bin/proxmox-backup-client backup \
root.pxar:/ \
--keyfile /root/pbs-encryption-key.enc \
--exclude /proc \
--exclude /sys \
--exclude /dev \
--exclude /run \
--exclude /tmp \
--exclude /var/cache \
--exclude /swap.img
# Send email on failure
ExecStopPost=/bin/sh -c 'if [ "$$EXIT_STATUS" -ne 0 ]; then echo "PBS backup failed on $(hostname)" | mail -s "Backup failure" admin@example.com; fi'[Unit]
Description=Daily PBS backup
[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true
RandomizedDelaySec=900
[Install]
WantedBy=timers.targetPBS_REPOSITORY=backup@pbs!mytoken@pbs.example.com:mydata
PBS_FINGERPRINT=AA:BB:CC:DD:...
PBS_PASSWORD=<api-token-secret>Lock down the environment file:
chmod 600 /etc/pbs-backup.env
systemctl daemon-reload
systemctl enable --now pbs-backup.timerPersistent=true ensures that if the server was powered off at 2 AM, the backup runs as soon as the system comes back. RandomizedDelaySec=900 spreads the load if multiple servers target the same PBS.
Restores and Verification
List Snapshots
proxmox-backup-client snapshot listEach snapshot shows the backup type, ID, timestamp, and size.
Mount and Browse
Mount a snapshot as a read-only FUSE filesystem to browse and copy individual files without a full restore.
# Create a mount point
mkdir -p /mnt/pbs-restore
# Mount a specific archive from a snapshot
proxmox-backup-client mount \
host/myserver/2026-02-27T02:00:00Z root.pxar \
/mnt/pbs-restore
# Browse and copy what you need
ls /mnt/pbs-restore/etc/nginx/
# Unmount when done
umount /mnt/pbs-restoreRestore a Full Archive
proxmox-backup-client restore \
host/myserver/2026-02-27T02:00:00Z root.pxar \
/target/restore/pathFor encrypted backups, add --keyfile /path/to/key.enc to any mount or restore command.
Verify Integrity
Run a verification to confirm chunks are intact and readable:
proxmox-backup-client verify host/myserver/2026-02-27T02:00:00ZTest restores regularly. A backup you can't restore isn't a backup. For a structured approach to restore testing, see Restore Testing and DR Drills.
Wrapping Up
proxmox-backup-client brings PBS deduplication, encryption, and incremental backups to any Linux system. Start with a simple backup command, add encryption once the workflow is solid, then automate with a systemd timer. For offsite protection, sync your datastore to a remote PBS instance using sync jobs, or skip the infrastructure overhead entirely. Use the initial seed calculator to estimate how long your first full backup will take over your connection.
