PBSClientTool

interactive script to install Proxmox Backup Server Client on any linux machine to start and schedule backups to your PBS

Generate Convert Improve

Install / Use

npx skills add cauldr0nx/PBSClientTool

Installs into whichever agent you are using.

About this skill

Quality Score

0/100

README

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:

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

2. Grant Permissions:

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

Usage

Installation Wizard

Run the tool and follow the prompts:

sudo PBSClientTool

You'll be asked for:

PBS Server: IP/hostname and port
Authentication: API token (recommended) or password
Backup Type:
- File-level only (fast, selective restore)
- Block device only (full disk image, bootable as VM)
- Both (recommended) - Files daily + disk weekly
Schedule: When to run backups
Retention: How long to keep backups
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:

List all backup targets - View all configured servers
Add new backup target - Configure additional PBS server
Edit existing target - Update connection/settings
Delete target - Remove a backup destination
Run backup now - Test or run immediate backup
Reinstall PBS client - Reinstall the backup software
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:

Print the paper backup immediately (/root/pbs-encryption-key-*.txt)
Store printed copy in safe location (fireproof safe, safety deposit box)
Copy encryption-key.json to password manager
NEVER store key on the same system being backed up
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 |