Ensuring reliable backups is essential for keeping your infrastructure safe whether you’re running Proxmox VE or any other Linux server.
With the Proxmox Backup Client, you can create complete or partial backups and store them securely on a Proxmox Backup Server (PBS) including fully managed services like Cloud-PBS.
Why use the Proxmox Backup Client ?
Proxmox Backup Client is a lightweight tool that can install on almost any Linux distribution.
Within minutes it allows you to back up your system directly to a PBS instance and so on Cloud-PBS. Even if your servers are not running on a Proxmox VE host, you can still benefit from the same enterprise-grade backup infrastructure.
This article walks you through a simple, working example to get you started with backing up any Linux system.
To follow this tutorial, you’ll need to have the Proxmox Backup Client installed and fully functional on your server. You can read our guide on how to install it here.
💡 If you’re backing up a Proxmox VE host itself, you don’t need to install the client, it’s already built in.
Key features of Proxmox Backup Client
- Incremental and deduplicated backups – Fast and storage efficient
- Source-side encryption – Data is encrypted before it leaves your server
- Flexible – Backup any specific folder or your entire file system
How to backup your Linux host ?
Create an API token
First, create a restricted API token on your Cloud-PBS datastore. We strongly recommend limiting permissions to the minimum necessary. In this case, assign DatastoreBackup role only.
Be sure to save the token name and secret in a secure location, you’ll need it later.
Configure your Linux host
On your Linux host, create a working directory in the /etc directory, and move into it :
mkdir /etc/pbc cd /etc/pbc
Now create a config file containing the environment variables required by the Proxmox Backup Client :
export PBS_HOST="MY_PBS_URL"
export PBS_PORT="8007"
export PBS_USERNAME="MY_TOKEN_NAME"
export PBS_PASSWORD="MY_TOKEN_SECRET"
export PBS_DATASTORE="MY_DATASTORE"
export PBS_NAMESPACE=""
export PBS_FINGERPRINT=""
export PBS_REPOSITORY="${PBS_USERNAME}@${PBS_HOST}:${PBS_PORT}:${PBS_DATASTORE}"
- Replace the placeholders with your actual values.
- Not all fields are mandatory (e.g., PBS_NAMESPACE can be left empty).
These environment variables will be sourced before running the backup script.
Make sure to protect this file due to the sensitive data like the PBS_PASSWORD variable.
chmod 400 /opt/pbc/config
Variables references
| Variable | Content |
|---|---|
| PBS_HOST | The IP / Hostname of your Cloud-PBS instance |
| PBS_PORT | Default is 8007, adjust if needed |
| PBS_USERNAME | Your API token name. In our example root@pam!proxmox-backup-client (should be different on your setup) |
| PBS_PASSWORD | Your API token secret |
| PBS_DATASTORE | Your Cloud-PBS datastore name. (pbs on dedicated instances, random string on shared instances). |
| PBS_NAMESPACE | Optional namespace for organizing backups. If you leave it empty the backup will be stored in the root namespace of your PBS Instance |
| PBS_FINGERPRINT | Your Cloud-PBS (or PBS) fingerprint. If you are a Cloud-PBS user you don’t need to set this variable because of well known certificates used by your instance. |
You can find the PBS fingerprint on the PBS web interface if necessary.
Create a backup script
Create a simple script in /etc/pbc/ to run your backups :
touch /etc/pbc/run_pbc chmod u+x /etc/pbc/run_pbc
Edit /etc/pbc/run_pbc with your favorite editor and paste
#!/usr/bin/env bash
set -euo pipefail
PBC_CFG_FILE="/etc/pbc/config"
if [ "$( stat -c '%a' ${PBC_CFG_FILE} )" -ne "400" ]; then
echo "permissions on ${PBC_CFG_FILE} need to be 400"
exit 1
fi
source ${PBC_CFG_FILE}
proxmox-backup-client backup --ns="$PBS_NAMESPACE" root.pxar:/ 2>&1
Run your first backup
/etc/pbc/run_pbc
Now your host is fully backed up, your can verify in the Cloud-PBS dashboard or PBS web interface :
👉 By default, Proxmox Backup Client automatically skips certain mount points (e.g., /boot, /dev, /proc, /sys, /tmp).
Restoring your backup
You can browse and restore your backups either via the Proxmox Backup Server web interface or directly from the CLI using the Proxmox Backup Client.
If you want to use the PBC cli, you will need to source your config file to automatically request your datastore.
List your snapshots first :
# Source your configuration file . /etc/pbc/config # List all backups proxmox-backup-client snapshot list # List last snapshots proxmox-backup-client list
The last command should returns something like
Browse and restore via CLI
Open a snapshot
proxmox-backup-client catalog shell host/pve01-36/2025-08-25T09:58:35Z root.pxar
Inside this shell, you can browse using normal Linux commands such as cd, find, ls, pwd.
To restore the full archive to /tmp/restore
pxar:/ > restore /tmp/restore
Depending on your backup size, it can take some time to have a complete restore. Once done you can exit the shell and start to explore your restored files in /tmp/restore directory.
It’s also possible to restore a single file with the select command into the Proxmox Backup Client shell (example with the /etc/hostname file)
proxmox-backup-client catalog shell host/rocky9/2025-06-24T21:31:16Z root.pxar pxar:/ > select /etc/hostname added path: "/etc/hostname" pxar:/ > restore-selected /tmp/restore-hostname
Then you’ll find your /etc/hostname file in your host /tmp/restore-hostname directory
root@pve01-36 /etc/pbc # tree /tmp/restore-hostname/
/tmp/restore-hostname/
└── etc
└── hostname
2 directories, 1 file
Conclusion
With just a few steps, you can protect any Linux system (Proxmox or not) using Proxmox Backup Server and Cloud-PBS.
The Proxmox Backup Client makes backups efficient, scriptable, and reliable. Whether you need to recover an entire system or just one file, everything is only a command away.
English 
French