PBSClientTool

Interactive tool for installing and managing Proxmox Backup Client on all platforms: Linux (native), Windows, and macOS (Docker).

Features

• Cross-platform support - Native Linux + Docker for Windows/Mac
• Multi-target backups - Backup to multiple PBS servers for redundancy
• Auto-detection - Automatically detects your Linux distribution
• File & block device backups - Supports .pxar (files) and .img (full disk) backups
• Interactive setup - Guided configuration with connection testing
• Flexible scheduling - Separate schedules for file and disk backups
• System-wide install - Run from anywhere with PBSClientTool command

Quick Start

# Clone and install
git clone https://github.com/zaphod-black/PBSClientTool.git
cd PBSClientTool
sudo ./pbs-client-installer.sh --install

# Run from anywhere
sudo PBSClientTool

Prerequisites

On Your System

• Root/sudo access
• Internet connection
• Supported OS: Ubuntu 20.04+, Debian 10+, Arch Linux
• Arch only: Install yay first (instructions)

On Proxmox Backup Server

Before running the installer, set up an API token with backup permissions:

1. Create API Token:

1. Login to PBS web interface (e.g., https://192.168.1.181:8007)
2. Go to Configuration → Access Control → API Tokens
3. Click Add
4. Configure:
   • User: root@pam
   • Token ID: backupAutomations (or any name)
   • Privilege Separation: Leave unchecked
5. Copy the secret immediately (shown only once!)

2. Grant Permissions:

1. Go to Configuration → Access Control → Permissions
2. Click Add → User Permission
3. Configure:
   • Path: /datastore/YOUR-DATASTORE-NAME
   • User: root@pam!backupAutomations
   • Role: DatastoreBackup
4. Click Add

Usage

Installation Wizard

Run the tool and follow the prompts:

sudo PBSClientTool

You'll be asked for:

1. PBS Server: IP/hostname and port
2. Authentication: API token (recommended) or password
3. Backup Type:
   • File-level only (fast, selective restore)
   • Block device only (full disk image, bootable as VM)
   • Both (recommended) - Files daily + disk weekly
4. Schedule: When to run backups
5. Retention: How long to keep backups
6. Encryption: Optional (recommended for sensitive data)

The installer will test your connection and create automated backup services.

Multi-Target Management

After installation, you can manage multiple backup targets:

Main Menu Options:

1. List all backup targets - View all configured servers
2. Add new backup target - Configure additional PBS server
3. Edit existing target - Update connection/settings
4. Delete target - Remove a backup destination
5. Run backup now - Test or run immediate backup
6. Reinstall PBS client - Reinstall the backup software
7. Exit

Running Backups

Scheduled (automatic):

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

# View next scheduled run
sudo systemctl list-timers pbs-backup-*

Manual (on-demand):

# Via menu (recommended - shows live progress)
sudo PBSClientTool
# Select option 5 (Run backup now)

# Via systemd
sudo systemctl start pbs-backup-default-manual.service

# Direct script execution
sudo /etc/proxmox-backup-client/backup-default.sh

Viewing Logs

# View recent backup logs
sudo journalctl -u pbs-backup-default.service -n 50

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

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

Command-Line Options

sudo PBSClientTool              # Interactive menu
sudo PBSClientTool --help       # Show help
sudo PBSClientTool --version    # Show version
sudo PBSClientTool --install    # Install to system
sudo PBSClientTool --uninstall  # Remove from system

Configuration Files

Multi-target setup:

• /etc/proxmox-backup-client/targets/TARGET.conf - Target configurations
• /etc/proxmox-backup-client/backup-TARGET.sh - Backup scripts
• /etc/systemd/system/pbs-backup-TARGET.{service,timer} - Systemd units

Encryption key:

• /root/.config/proxmox-backup/encryption-key.json - Main key
• /root/pbs-encryption-key-*.txt - Paper backup (print and secure!)

Backup Types Explained

File-Level (.pxar)

• Fast - Usually completes in 2-5 minutes
• Selective - Restore individual files/folders
• Efficient - Deduplication and compression
• Best for: Daily backups, quick recovery

Block Device (.img)

• Slow - Can take 20-30+ minutes
• Complete - Entire disk image
• Bootable - Can restore as VM on Proxmox
• Best for: Weekly backups, disaster recovery

Hybrid (Both)

• Recommended - Best of both worlds
• Files backup daily (fast, efficient)
• Disk image weekly (complete system backup)
• Configure separate schedules for each

Encryption Key - Important!

⚠️ Your encryption key is the ONLY way to restore encrypted backups!

If you lose the key, your backups are permanently unrecoverable.

Best practices:

1. Print the paper backup immediately (/root/pbs-encryption-key-*.txt)
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

Updating PBSClientTool

cd ~/dev/PBSClientTool
git pull
sudo ./pbs-client-installer.sh --install
# Confirm overwrite: yes

Your backup targets and configurations are preserved during updates.

Uninstallation

Remove command only (keeps backups and configs):

sudo PBSClientTool --uninstall

Complete removal (removes everything):

cd ~/dev/PBSClientTool
sudo ./uninstaller.sh

Docker Solution (Windows/Mac) - 🚧 IN DEVELOPMENT

⚠️ Note: The Docker solution is currently in active development. The native Linux installer above is the stable, production-ready version. Use Docker for cross-platform testing or if you need Windows/Mac support.

Want to backup Windows or macOS systems? Use the Docker-based solution:

Quick Start

1. Build the image:

cd docker
./build.sh

2. Run the container:

docker run -d \
  --name pbs-backup \
  -p 8080:8080 \
  -v /path/to/backup:/host-data:ro \
  -v pbs-config:/config \
  -v pbs-logs:/logs \
  -e MODE=daemon \
  -e ENABLE_API=true \
  pbsclient:latest

Replace /path/to/backup with your data directory:

• Home directory: -v /home/username:/host-data:ro
• Entire system: -v /:/host-data:ro
• Specific folder: -v /data:/host-data:ro

3. Configure via web UI:

• Open http://localhost:8080
• Click ⚙ Settings
• Enter your PBS server details
• Click 💾 Save Configuration
• Click ▶ Run Backup Now to test

What It Provides

• Cross-platform - Works on Windows, macOS, and Linux
• Web Dashboard - Real-time monitoring with retro terminal UI
• Configuration UI - Set up PBS backups from your browser
• REST API - Remote management and monitoring
• File-level backups - Daily automated backups
• Easy deployment - Single container, simple configuration

Web Dashboard Features:

• Settings page for PBS configuration
• Live backup status and progress
• System health monitoring
• Backup history and logs
• Manual backup trigger
• Retro blue/purple neon aesthetic

See docker/README-DOCKER.md for complete documentation.

Platform Support Matrix:

Feature	Native Linux	Docker (Win/Mac)
File backups	✅ Yes	✅ Yes
Block device backups	✅ Yes	❌ No
Performance	✅ Best	⚠️ Good
Setup complexity	Medium	Easy

Troubleshooting

Having issues? See the Troubleshooting Guide for:

• Connection test failures
• Permission errors
• Installation issues
• Backup problems
• Configuration issues
• And more...

Supported Distributions

OS	Versions	Notes
Ubuntu	20.04, 22.04, 24.04	LTS only
Debian	10, 11, 12	Stable
Arch Linux	Rolling	Requires yay

Getting Help

• Script issues: GitHub Issues
• PBS questions: Proxmox Forum
• PBS docs: Official Documentation

Contributing

Issues and pull requests welcome!

License

MIT License

Credits

Created by Cade - Built on Proxmox Backup Client