ProxmoxBackupClientPBSClientTool/README.md

PBSClientTool

Interactive bash script that automatically installs and configures Proxmox Backup Client on Ubuntu, Debian, and Arch Linux systems.

Features

• Multi-target backup support - Backup to multiple PBS servers for redundancy
• Auto-detects Linux distribution (Ubuntu 20.04/22.04/24.04, Debian 10/11/12, Arch Linux)
• Installs correct PBS client version for your system
• Interactive configuration via console prompts
• Automatic encryption key generation with paper backup
• Systemd service and timer for automated backups
• Configurable retention policies (daily, weekly, monthly)
• Connection testing before finalizing setup
• Immediate backup option after installation
• System-wide installation - Run from anywhere with PBSClientTool command

Installation

Quick Install

# Clone the repository
git clone https://github.com/zaphod-black/PBSClientTool.git
cd PBSClientTool

# Install PBSClientTool to your system
sudo ./pbs-client-installer.sh --install

After installation, you can run the tool from anywhere:

sudo PBSClientTool

Manual Usage (Without Installing)

You can also run the script directly without installing:

sudo ./pbs-client-installer.sh

Command-Line Options

sudo PBSClientTool --help       # Show help message
sudo PBSClientTool --version    # Show version
sudo PBSClientTool --install    # Install to /usr/local/bin
sudo PBSClientTool --uninstall  # Remove from system

Uninstallation

To remove the PBSClientTool command from your system:

sudo PBSClientTool --uninstall

Note: This only removes the command. Your backup targets and configurations are preserved. To completely remove all backups and configurations, use:

sudo ./uninstaller.sh

Prerequisites

All Systems

• Root/sudo access
• Active internet connection
• Proxmox Backup Server accessible on network

Arch Linux Specifically

• yay AUR helper must be installed
• Install yay first: https://github.com/Jguer/yay

Before Running - PBS Server Setup

1. Create API Token (Recommended)

API tokens are the recommended authentication method for automated backups. They're more secure than passwords and don't expire.

In PBS Web Interface:

1. Login to your PBS server (e.g., https://192.168.1.181:8007)
2. Go to Configuration → Access Control → API Tokens
3. Click Add
4. Fill in:
   • User: root@pam (or your backup user)
   • Token ID: backupAutomations (or any name you prefer)
   • Privilege Separation: Leave unchecked for full user permissions
5. Click Add
6. IMPORTANT: Copy the Secret immediately - it's only shown once!
   • Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Configure Datastore Permissions

Your API token needs backup permissions on the datastore:

1. Go to Configuration → Access Control → Permissions
2. Click Add → User Permission
3. Fill in:
   • Path: /datastore/YOUR-DATASTORE-NAME
   • User: root@pam!backupAutomations (your token)
   • Role: DatastoreBackup (or DatastoreAdmin for full access)
4. Click Add

Common Permission Error:

Error: permission check failed - missing Datastore.Audit|Datastore.Backup

This means the token lacks permissions. Double-check the permission settings above.

3. Gather Information

Have these details ready before running the installer:

• Server IP/hostname: (e.g., 192.168.1.181)
• Port: (default: 8007)
• Datastore name: (exactly as shown in PBS, e.g., DEAD-BACKUP)
• API Token:
  • Username: root
  • Realm: pam
  • Token name: backupAutomations
  • Token secret: (the secret you copied earlier)

Installation

Clone the repository

git clone https://github.com/zaphod-black/PBSClientTool
cd PBSClientTool
chmod +x pbs-client-installer.sh

Run with sudo

sudo ./pbs-client-installer.sh

Step-by-Step Walkthrough

This walkthrough shows a complete installation using API token authentication (recommended).

Step 1: Run the Installer

sudo ./pbs-client-installer.sh

If PBS client is already installed, you'll see options. Choose 1 to configure or 2 to reinstall.

Step 2: PBS Server Configuration

Enter your server details:

Enter PBS server IP/hostname [192.168.1.181]: 192.168.1.181
Enter PBS server port [8007]: 8007
Enter datastore name [backups]: DEAD-BACKUP

Important: The datastore name must match exactly as shown in your PBS web interface.

Step 3: Authentication Method

Choose API Token (option 2):

Authentication Method:
  1) Username + Password
  2) API Token (recommended for automation)
Select authentication method [1/2] [2]: 2

Why API Tokens?

• More secure than passwords
• Don't expire
• Can be easily revoked without changing passwords
• Recommended for automated/scheduled backups

Step 4: Enter API Token Details

Enter username [backup]: root
Enter realm [pbs]: pam
Enter token name [backup-token]: backupAutomations
Enter token secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Note: The token secret won't be displayed as you type (for security).

Step 5: Backup Configuration

Choose your backup type:

Backup Type:
  1) File-level only (.pxar) - Fast, efficient, selective restore
  2) Block device only (.img) - Full disk image, bootable as VM
  3) Both (Hybrid) - Daily files + Weekly block device (recommended)
Select backup type [1/2/3] [3]: 3

Recommendation: Option 3 (Both) gives you:

• Daily file-level backups (fast, efficient)
• Weekly block device backups (full system image)

Step 6: File Backup Paths

Enter paths to backup (space-separated) [/]: /
Enter exclusion patterns (space-separated) [/tmp /var/tmp /var/cache /proc /sys /dev /run]:

Press Enter to accept defaults, or customize as needed.

Step 7: Block Device Selection

The script auto-detects your root device:

[INFO] Auto-detected root device: /dev/mapper/root
Enter block device to backup [/dev/mapper/root]:

Press Enter to accept, or enter a different device (e.g., /dev/sda, /dev/nvme0n1).

Common devices:

• /dev/sda - First SATA/SCSI drive
• /dev/nvme0n1 - First NVMe drive
• /dev/vda - Virtual disk (VM)
• /dev/mapper/root - LVM/encrypted volume

Step 8: Backup Schedule

Backup Schedule:
  1) Hourly
  2) Daily (recommended)
  3) Weekly
  4) Custom
Select schedule type [1/2/3/4] [2]: 2
Enter hour for daily backup (0-23) [2]: 2

Note: If you selected "Both" backup type:

• File backups run on this schedule (e.g., daily at 2 AM)
• Block device backups run weekly on Sunday

Step 9: Retention Policy

Keep last N backups [3]: 3
Keep daily backups for N days [7]: 7
Keep weekly backups for N weeks [4]: 4
Keep monthly backups for N months [6]: 6

These settings determine how long backups are kept before automatic pruning.

Step 10: Encryption

Enable encryption? (yes/no) [yes]: yes

If you enable encryption:

• A unique encryption key is generated
• Paper backup saved to /root/pbs-encryption-key-YYYYMMDD.txt
• Print and store this securely - lost keys = lost data!

Step 11: Connection Test

The installer will test your connection in 3 steps:

[INFO] Step 1/3: Checking if server is reachable...
[INFO] Server is reachable
[INFO] Step 2/3: Testing authentication...
[INFO] SSL fingerprint accepted: a1:41:69:b7:...
[INFO] Authentication successful
[INFO] Step 3/3: Verifying datastore access...
[INFO] Datastore access verified
[INFO] Connection test successful!

If Step 2 fails with permission error:

• Go back to PBS web interface
• Verify API token has DatastoreBackup permission on your datastore
• See "Prerequisites → Configure Datastore Permissions" section above

Step 12: Service Creation

The installer creates systemd service and timer:

[INFO] Creating systemd service and timer...
[INFO] Systemd service and timer created successfully

Step 13: Optional Immediate Backup

Do you want to run a backup now? (yes/no) [no]: yes
[INFO] Starting immediate backup...

╔════════════════════════════════════════════════════════════╗
║  Backup Progress (Live)                                    ║
║  Press Ctrl+C to exit (backup continues in background)    ║
╚════════════════════════════════════════════════════════════╝

[2025-11-01 18:30:00] Starting backup for mcware-01
[2025-11-01 18:30:00] Backup type: both
[2025-11-01 18:30:00] Starting file-level backup (.pxar)...
Starting backup: host/mcware-01/2025-11-01T23:30:00Z
Client name: mcware-01
Starting backup protocol: Sat Nov  1 18:30:00 2025

Uploaded 123.4 MiB in 5s (24.7 MiB/s)
Files: 12,345 | Dirs: 1,234 | Size: 4.5 GiB

[2025-11-01 18:30:05] File-level backup completed successfully
════════════════════════════════════════════════════════════

[INFO] Backup completed successfully!

Choose yes to test your backup immediately with live progress monitoring, or no to wait for the scheduled time.

What you'll see:

• Real-time backup progress with file counts and transfer speeds
• PBS client's built-in progress indicators
• Automatic completion detection
• You can press Ctrl+C to exit (backup continues in background)

Step 14: Completion

======================================
  Installation Complete!
======================================

Configuration Summary:
  PBS Server: 192.168.1.181:8007
  Datastore: DEAD-BACKUP
  Repository: root@pam!backupAutomations@192.168.1.181:8007:DEAD-BACKUP
  Backup Type: both
  Backup Paths: /
  Block Device: /dev/mapper/root
  Schedule: Files daily (02:00:00), Block device weekly (Sunday)

Your backups are now configured! 🎉

Reconfiguration

If PBS client is already installed, the script will detect this and offer you options:

With existing configuration:

1. Reconfigure connection only - Quick update of PBS server IP/credentials only
2. Full reconfiguration - Redo all settings (paths, schedules, retention, etc.)
3. Reinstall PBS client and reconfigure - Complete reinstall
4. Run backup now - Test your backups with live progress monitoring
5. Exit without changes

Without existing configuration:

1. Configure PBS client - Set up for the first time
2. Reinstall and configure - Fresh installation
3. Exit without changes

Connection-only reconfiguration is perfect for:

• Switching to a different backup server
• Updating expired API tokens
• Changing authentication methods
• Updating datastore names
• All backup settings (paths, schedules, retention policies) are preserved

Run backup now provides:

• Immediate backup testing without waiting for schedule
• Live progress monitoring with real-time statistics
• File counts, transfer speeds, and compression ratios
• Automatic completion detection
• Option to exit early (backup continues in background)

Usage Example

The script will interactively prompt you for:

1. PBS Server Configuration

   • Server IP/hostname
   • Port (default: 8007)
   • Datastore name

2. Authentication

   • Username + Password OR
   • API Token (recommended for automation)

3. Backup Configuration

   • Paths to backup (e.g., /, /home)
   • Exclusion patterns (e.g., /tmp, /var/cache)

4. Schedule

   • Hourly, Daily, Weekly, or Custom schedule
   • Specific time for backups

5. Retention Policy

   • Number of last backups to keep
   • Daily/weekly/monthly retention

6. Encryption

   • Enable/disable client-side encryption

Example Session

╔════════════════════════════════════════╗
║  Proxmox Backup Client Installer      ║
║  Version: 1.0.0                        ║
╚════════════════════════════════════════╝

[INFO] Detected: Ubuntu 24.04 LTS
[INFO] Installing Proxmox Backup Client on Ubuntu 24.04...
[INFO] PBS client installed successfully

======================================
  PBS Client Configuration
======================================

Enter PBS server IP/hostname [192.168.1.181]: 
Enter PBS server port [8007]: 
Enter datastore name [backups]: 

Authentication Method:
  1) Username + Password
  2) API Token (recommended for automation)
Select authentication method [1/2] [2]: 

Enter username [backup]: 
Enter realm [pbs]: 
Enter token name [backup-token]: 
Enter token secret: 

Backup Configuration:
Enter paths to backup (space-separated) [/]: /
Enter exclusion patterns (space-separated) [/tmp /var/tmp /var/cache /proc /sys /dev /run]: 

Backup Schedule:
  1) Hourly
  2) Daily (recommended)
  3) Weekly
  4) Custom
Select schedule type [1/2/3/4] [2]: 2
Enter hour for daily backup (0-23) [2]: 3

Retention Policy:
Keep last N backups [3]: 3
Keep daily backups for N days [7]: 7
Keep weekly backups for N weeks [4]: 4
Keep monthly backups for N months [6]: 12

Enable encryption? (yes/no) [yes]: yes

[INFO] Encryption key created successfully
[WARN] IMPORTANT: Encryption key paper backup saved to: /root/pbs-encryption-key-20251101.txt
[WARN] Print this file and store it securely. Lost keys = permanent data loss!

[INFO] Testing connection to PBS server...
[INFO] Connection test successful!

[INFO] Creating systemd service and timer...
[INFO] Systemd service and timer created successfully

Do you want to run a backup now? (yes/no) [no]: yes
[INFO] Starting immediate backup...

Post-Installation

Check Status

# Check timer status
sudo systemctl status pbs-backup.timer

# Check last backup run
sudo systemctl status pbs-backup.service

# View backup logs
sudo journalctl -u pbs-backup.service

# Follow logs in real-time
sudo journalctl -fu pbs-backup.service

Manual Backup

Easy way (with live progress):

# Run the installer and choose option 4
sudo ./pbs-client-installer.sh
# Select: 4) Run backup now

This provides:

• Live progress monitoring with file counts and transfer speeds
• Automatic completion detection
• Clear success/failure status

Direct command (no progress display):

# Run backup immediately
sudo systemctl start pbs-backup.service

# Follow logs manually
sudo journalctl -fu pbs-backup.service

# List all backups
sudo -E proxmox-backup-client snapshot list

Configuration Files

• /etc/proxmox-backup-client/config - Main configuration
• /etc/proxmox-backup-client/backup.sh - Backup script
• /root/.config/proxmox-backup/encryption-key.json - Encryption key
• /etc/systemd/system/pbs-backup.service - Systemd service
• /etc/systemd/system/pbs-backup.timer - Systemd timer

Modify Configuration

Edit the config file and restart the timer:

sudo nano /etc/proxmox-backup-client/config
sudo systemctl daemon-reload
sudo systemctl restart pbs-backup.timer

Disable Automatic Backups

sudo systemctl disable pbs-backup.timer
sudo systemctl stop pbs-backup.timer

Uninstall

Use the provided uninstaller:

sudo ./pbs-client-uninstaller.sh

Backup Encryption Key

CRITICAL: Your encryption key is your only way to restore data. If you lose it, your backups are permanently unrecoverable.

Key Locations

• Primary: /root/.config/proxmox-backup/encryption-key.json
• Paper backup: /root/pbs-encryption-key-YYYYMMDD.txt

Best Practices

1. Print the paper backup immediately
2. Store printed copy in safe location (fireproof safe, safety deposit box)
3. Copy encryption-key.json to password manager
4. Never store key on the same system being backed up
5. Test key restoration regularly

Restore Encryption Key

To restore backups on a new system:

# Copy your saved encryption-key.json
sudo mkdir -p /root/.config/proxmox-backup
sudo cp /path/to/saved/encryption-key.json /root/.config/proxmox-backup/

# Or recreate from paper backup QR code
# (scan QR code and save to file)

Troubleshooting

Connection Test Script

If you encounter connection issues, use the included diagnostic script:

./test-connection.sh <server> <port> <datastore> <username> <realm> <password-or-token>

Examples:

With username/password:

./test-connection.sh 192.168.1.181 8007 DEAD-BACKUP root pam mypassword

With API token:

./test-connection.sh 192.168.1.181 8007 DEAD-BACKUP root pam backup-token token-secret-here

The script will:

• Test server reachability
• Handle SSL certificate fingerprint acceptance
• Test authentication
• Verify datastore access
• Provide detailed error messages

Connection Test Fails

The installer tests the connection with a 3-step process:

Step 1 - Server Reachability (5s timeout):

• PBS server is unreachable (check IP/hostname)
• Firewall blocking port (default: 8007)
• Network connectivity issues

Step 2 - Authentication (15s timeout):

• Invalid credentials (username/password/token)
• SSL certificate fingerprint issues (automatically handled)
• API token format errors

Step 3 - Datastore Access:

• Datastore does not exist on server
• User lacks permissions for the datastore

Quick checks:

# Test server reachability
ping 192.168.1.181
curl -k https://192.168.1.181:8007

# Verify credentials in PBS web interface
# Check datastore name matches exactly

SSL Certificate Fingerprints:

The installer automatically accepts SSL fingerprints during setup. If you need to manually accept a fingerprint:

export PBS_REPOSITORY="root@pam@192.168.1.181:8007:DEAD-BACKUP"
export PBS_PASSWORD="your-password"
proxmox-backup-client login
# Answer 'y' when prompted to accept the fingerprint

Installation Fails on Ubuntu 22.04

You may need to manually install libssl1.1:

wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb

Arch: "libfuse3.so.3 not found"

Rebuild after fuse3 updates:

yay -S proxmox-backup-client-bin --rebuild

Backups Not Running

Check timer and service status:

sudo systemctl list-timers pbs-backup.timer
sudo systemctl status pbs-backup.service
sudo journalctl -u pbs-backup.service -n 50

"Skip mount point" Messages

This is normal. The script excludes separate mount points by default. To include specific mount points, edit /etc/proxmox-backup-client/backup.sh and add --include-dev flags.

Advanced Usage

Custom Backup Script

Modify /etc/proxmox-backup-client/backup.sh for advanced scenarios:

# Add specific mount points
--include-dev /boot/efi

# Use data change detection mode
--change-detection-mode=data

# Add rate limiting (10 MB/s)
--rate-limit 10485760

# Verbose output
--verbose

Multiple Backup Jobs

Create additional services for different schedules:

# Copy and modify service/timer files
sudo cp /etc/systemd/system/pbs-backup.service /etc/systemd/system/pbs-backup-hourly.service
sudo cp /etc/systemd/system/pbs-backup.timer /etc/systemd/system/pbs-backup-hourly.timer

# Edit timer OnCalendar setting
sudo nano /etc/systemd/system/pbs-backup-hourly.timer

sudo systemctl daemon-reload
sudo systemctl enable --now pbs-backup-hourly.timer

Security Considerations

• Configuration file contains credentials - protected with mode 600
• Encryption key is root-only accessible
• No passwords logged or displayed in output
• All communication uses TLS encryption
• Consider using API tokens instead of passwords for automation

Supported Distributions

Distribution	Versions	Notes
Ubuntu	20.04, 22.04, 24.04	LTS versions only
Debian	10 (Buster), 11 (Bullseye), 12 (Bookworm)	Stable releases
Arch Linux	Rolling	Requires yay AUR helper

Contributing

Issues and pull requests welcome at [your-repo-url]

License

MIT License - see LICENSE file

Credits

• Proxmox team for PBS client
• Script by Cade

Support

For PBS client issues: https://forum.proxmox.com For script issues: [your-repo-url]/issues