How to Create a Backup with Proxmox Backup Client

Table of Contents#

Prerequisites
Installing Proxmox Backup Client
Configuring the Client
- Understanding the Configuration File
- Setting Up Credentials Securely
Creating Your First Backup
Advanced Backup Options
Restoring Data from Backups
- Basic Restore Syntax
- Restoring a Directory Example
Scheduling Backups Automatically
- Using Cron (Linux)
- Using Task Scheduler (Windows)
Troubleshooting Common Issues
Best Practices for Proxmox Backups
Conclusion
References

Prerequisites#

Before using the Proxmox Backup Client, ensure you have the following:

Proxmox Backup Server (PBS) Installed: The client requires a running Proxmox Backup Server to store backups. If you haven’t set up PBS yet, follow the official installation guide.
Network Connectivity: The client machine must have network access to the PBS (TCP port 8007, or 8006 if using the web interface for management).
Storage on PBS: Ensure your PBS has sufficient storage space for backups (configure a datastore in PBS first).
Client Machine: A Linux (Debian/Ubuntu, RHEL/CentOS) or Windows system where you’ll install the Proxmox Backup Client.

Installing Proxmox Backup Client#

Proxmox provides official packages for Linux and Windows. Choose the method below based on your OS.

On Debian/Ubuntu#

Add the Proxmox Repository:
Proxmox signs packages with a GPG key. Add the key and repository:

# Download and add the GPG key  
wget https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg  
chmod +r /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg  
 
# Add the repository (use "pbs-no-subscription" for non-enterprise users)  
echo "deb http://download.proxmox.com/debian/pbs bookworm pbs-no-subscription" > /etc/apt/sources.list.d/pbs.list

Update and Install the Client:

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

Verify Installation:
```
proxmox-backup-client version  
```
You should see output like: proxmox-backup-client 3.1.4 (running on Debian 12.4, kernel 6.1.0-13-amd64)

On Red Hat/CentOS#

Add the Proxmox Repository:
Create a repo file:

cat > /etc/yum.repos.d/proxmox-backup-client.repo << EOF  
[proxmox-backup-client]  
name=Proxmox Backup Client  
baseurl=http://download.proxmox.com/rhel/8/proxmox-backup-client/\$basearch  
enabled=1  
gpgcheck=1  
gpgkey=https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg  
EOF

Install the Client:
```
dnf install proxmox-backup-client -y  
```
Verify Installation:
```
proxmox-backup-client version  
```

On Windows#

Download the Installer:
Visit the Proxmox Backup Client downloads page and grab the latest Windows MSI (e.g., proxmox-backup-client_3.1.4-1_win64.msi).
Run the Installer:
Double-click the MSI and follow the prompts. The client will be installed to C:\Program Files\Proxmox\Proxmox Backup Client\.
Verify Installation:
Open PowerShell or Command Prompt and run:
```
proxmox-backup-client.exe version  
```

Configuring the Client#

To avoid typing long commands or credentials repeatedly, configure the client with a proxmox-backup.conf file.

Understanding the Configuration File#

The client reads configuration from:

Linux: ~/.config/proxmox-backup/proxmox-backup.conf (user-specific) or /etc/proxmox-backup/proxmox-backup.conf (system-wide).
Windows: %APPDATA%\Proxmox\proxmox-backup.conf.

Example Config File:

repository "my-pbs-repo" {  
    server "pbs.example.com"  
    user "backupuser@pbs"  
    datastore "mydatastore"  
    password "your-secure-password"  # Avoid plaintext! Use a credential file instead.  
    # encryption-key "path/to/encryption.key"  # Optional: For encrypted backups  
}

Setting Up Credentials Securely#

Storing passwords in plaintext is risky. Instead, use a credential file or environment variables:

Option 1: Credential File#

Create a file (e.g., ~/.pbs-credentials) with:

password: "your-secure-password"

Set strict permissions:

chmod 600 ~/.pbs-credentials

Reference it in your config:

repository "my-pbs-repo" {  
    server "pbs.example.com"  
    user "backupuser@pbs"  
    datastore "mydatastore"  
    password-file "/home/youruser/.pbs-credentials"  
}

Option 2: Environment Variables#

Set variables before running commands:

export PBS_REPOSITORY="backupuser@[email protected]:mydatastore"  
export PBS_PASSWORD="your-secure-password"

Creating Your First Backup#

The core command for backups is proxmox-backup-client backup. Let’s break down its usage.

Basic Backup Syntax#

proxmox-backup-client backup <backup-name.pxar> --include <path-to-backup> --repository <repo-url> [options]

<backup-name.pxar>: A name for the backup archive (.pxar is Proxmox’s archive format).
--include: Path to the file/directory to backup (use multiple --include flags for multiple items).
--repository: PBS repository URL (format: user@pbs@server:datastore).

Backing Up a Single File#

Example: Backup /home/user/important.docx to PBS:

proxmox-backup-client backup important-doc.pxar --include /home/user/important.docx --repository backupuser@[email protected]:mydatastore

Output:

Starting backup: 2024-05-20T14:30:00Z  
Backup name: important-doc.pxar  
Including: /home/user/important.docx  
Uploading to repository 'backupuser@[email protected]:mydatastore'  
Successfully created backup snapshot '2024-05-20T14:30:00Z'

Backing Up a Directory#

Example: Backup /home/user/documents (including subdirectories):

proxmox-backup-client backup docs.pxar --include /home/user/documents --repository backupuser@[email protected]:mydatastore

Add --verbose to see progress:

proxmox-backup-client backup docs.pxar --include /home/user/documents --repository ... --verbose

Excluding Files/Directories#

Use --exclude to skip specific files/directories:

Example: Backup /home/user/documents but exclude .git folders and .tmp files:

proxmox-backup-client backup docs.pxar \  
  --include /home/user/documents \  
  --exclude /home/user/documents/**/.git \  
  --exclude /home/user/documents/**/*.tmp \  
  --repository backupuser@[email protected]:mydatastore

Advanced Backup Options#

Encrypting Backups#

Proxmox supports AES-256 encryption for backups. To use encryption:

Generate an Encryption Key:
```
proxmox-backup-client key create /path/to/encryption.key  
```
Store this key securely (e.g., in a password manager or hardware security module).

Use the Key in Backups:

proxmox-backup-client backup encrypted-docs.pxar \  
  --include /home/user/documents \  
  --repository backupuser@[email protected]:mydatastore \  
  --encrypt --encryption-key /path/to/encryption.key

Compression#

PBC supports zstd (default), gzip, or lzma compression. Override the default with --compress:

proxmox-backup-client backup compressed-docs.pxar \  
  --include /home/user/documents \  
  --compress zstd:6 \  # zstd with level 6 (1-19, higher = more compression)  
  --repository backupuser@[email protected]:mydatastore

Incremental Backups#

PBC automatically creates incremental backups by comparing snapshots on the PBS. Only changed data is transferred, saving bandwidth and storage.

No extra steps needed! The client leverages PBS’s snapshot system. Subsequent backups of the same --include path will be incremental.

Restoring Data from Backups#

To restore data, use proxmox-backup-client restore.

Basic Restore Syntax#

proxmox-backup-client restore <snapshot> <backup-name.pxar> <target-directory> --repository <repo-url> [options]

<snapshot>: The snapshot ID (e.g., 2024-05-20T14:30:00Z).
<backup-name.pxar>: The archive name from the backup.
<target-directory>: Where to restore the files.

Restoring a Directory Example#

Step 1: List Available Snapshots
First, find the snapshot to restore:

proxmox-backup-client list --repository backupuser@[email protected]:mydatastore

Output will show snapshots like:

Snapshots on repository 'backupuser@[email protected]:mydatastore':  
  2024-05-20T14:30:00Z  
  2024-05-21T09:15:00Z

Step 2: Restore the Snapshot
Restore docs.pxar from 2024-05-20T14:30:00Z to /tmp/restored-docs:

proxmox-backup-client restore 2024-05-20T14:30:00Z docs.pxar /tmp/restored-docs \  
  --repository backupuser@[email protected]:mydatastore

For encrypted backups, add --encryption-key /path/to/encryption.key.

Scheduling Backups Automatically#

Using Cron (Linux)#

Schedule backups with cron for regular intervals.

Open Crontab:
```
crontab -e  
```

Add a Cron Job (e.g., daily at 2 AM):

0 2 * * * /usr/bin/proxmox-backup-client backup daily-docs.pxar --include /home/user/documents --repository backupuser@[email protected]:mydatastore --password-file /home/user/.pbs-credentials >> /var/log/pbs-backup.log 2>&1

Verify the Job:
```
crontab -l  
```

Using Task Scheduler (Windows)#

Open Task Scheduler → Create Basic Task.
Follow the wizard to set a trigger (e.g., daily at 2 AM).
For the action, select Start a program and point to proxmox-backup-client.exe.

Add arguments (adjust paths as needed):

backup daily-docs.pxar --include "C:\Users\user\Documents" --repository "backupuser@[email protected]:mydatastore" --password-file "C:\Users\user\.pbs-credentials"

Troubleshooting Common Issues#

Connection Failures#

Check PBS Server Status: Ensure PBS is running (systemctl status proxmox-backup-server).
Verify Network: Test connectivity with telnet pbs.example.com 8007.
Check Firewall: Allow TCP 8007 on PBS and client.

Permission Errors#

Client Permissions: The user running PBC needs read access to the --include path.
PBS Permissions: The PBS user (e.g., backupuser@pbs) needs write access to the datastore.

Backup Corruption#

Check Logs: Linux logs are in /var/log/proxmox-backup/client.log; Windows logs in %APPDATA%\Proxmox\logs\.

Verify Integrity: Use proxmox-backup-client verify to check backup consistency:

proxmox-backup-client verify 2024-05-20T14:30:00Z docs.pxar --repository backupuser@[email protected]:mydatastore

Best Practices for Proxmox Backups#

Test Restores Regularly: Ensure backups are valid by restoring test files periodically.
Encrypt Sensitive Data: Always encrypt backups containing PII or confidential info.
Store Encryption Keys Securely: Lose the key, lose the data! Use a password manager or HSM.
Monitor Backups: Use PBS’s built-in monitoring or tools like Prometheus to track backup success/failure.
Off-Site Backups: Replicate PBS datastores to an off-site location for disaster recovery.

Conclusion#

The Proxmox Backup Client is a versatile tool for securing your data with minimal effort. By following this guide, you can install, configure, and automate backups, leverage advanced features like encryption and compression, and restore data when needed. Remember to test backups regularly and follow best practices to ensure your data remains safe.