danvics/ProxmoxBackupClientPBSClientTool
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs: Major README simplification + dedicated troubleshooting guide

Browse source 
Reorganized documentation for better usability and maintenance.

CHANGES:

1. README.md simplified (750 → 243 lines):
   - Focused on quick start and essential usage
   - Removed redundant step-by-step sections
   - Removed duplicate explanations
   - Clearer structure with better hierarchy
   - Link to dedicated troubleshooting guide

2. New TROUBLESHOOTING.md (comprehensive guide):
   - Connection Issues:
     - Connection test script usage
     - 3-step failure diagnosis
     - SSL certificate handling
   - Permission Errors:
     - Missing Datastore.Backup permission
     - PBS web interface and CLI solutions
     - Required permissions explained
   - Installation Issues:
     - Ubuntu 22.04 libssl1.1 missing
     - Arch Linux libfuse3 errors
     - yay AUR helper installation
   - Backup Issues:
     - Backups not running diagnostics
     - "Skip mount point" explanation
     - No space left solutions
     - Encryption key problems
   - Multi-Target Issues:
     - Target connection test failures
     - Missing services
   - Configuration Issues:
     - Whitespace in configuration
     - Incomplete configuration warning
   - Advanced Troubleshooting:
     - Verbose logging
     - Manual testing
     - PBS server logs
     - Network timeout solutions
   - Common Misconfigurations:
     - Token format examples
     - Datastore name case-sensitivity
     - Repository string format
     - Permission path format

BENEFITS:
- Faster onboarding (README focused on getting started)
- Easier problem-solving (dedicated troubleshooting guide)
- Better maintainability (separate concerns)
- Improved searchability (detailed error solutions)
- Professional documentation structure

README now covers:
- Features and quick start
- Prerequisites (simplified)
- Basic usage
- Multi-target management
- Backup types explained
- Encryption key best practices
- Updating and uninstallation

TROUBLESHOOTING covers:
- All error messages and solutions
- Step-by-step diagnostic procedures
- Advanced configuration options
- Common pitfalls and how to avoid them

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
zaphod-black 2025-11-02 00:58:38 -05:00
parent 1e930c2775
commit 0186349d99
3 changed files with 623 additions and 697 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
CHANGELOG.md
View file

@ -139,6 +139,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Runs in subshell to avoid environment pollution
### Changed
- **Documentation reorganization**
- README.md simplified from 750 lines to 243 lines
- Removed redundant step-by-step walkthrough sections
- Moved all troubleshooting content to TROUBLESHOOTING.md
- Focused README on quick start and essential usage
- New TROUBLESHOOTING.md covers:
- Connection issues and SSL certificate problems
- Permission errors with detailed PBS setup instructions
- Installation issues (Ubuntu libssl1.1, Arch libfuse3)
- Backup problems and configuration issues
- Common misconfigurations with examples
- Easier to find relevant information
- Better navigation and organization
- **Clearer installation flow when PBS client not installed**
- Shows what the script will do before proceeding
- Lists 3 steps: Install PBS client, Configure target, Set up automation

886
README.md
View file

@ -1,750 +1,242 @@
# PBSClientTool
Interactive bash script that automatically installs and configures Proxmox Backup Client on Ubuntu, Debian, and Arch Linux systems.
Interactive tool for installing and managing Proxmox Backup Client on Ubuntu, Debian, and Arch Linux.
## 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
- **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
## Installation
### Quick Install
## Quick Start
```bash
# Clone the repository
# Clone and install
git clone https://github.com/zaphod-black/PBSClientTool.git
cd PBSClientTool
# Install PBSClientTool to your system
sudo ./pbs-client-installer.sh --install
# Run from anywhere
sudo PBSClientTool
```
After installation, you can run the tool from anywhere:
## Prerequisites
### On Your System
- Root/sudo access
- Internet connection
- Supported OS: Ubuntu 20.04+, Debian 10+, Arch Linux
- **Arch only:** Install `yay` first ([instructions](https://github.com/Jguer/yay))
### 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:
```bash
sudo PBSClientTool
```
### Manual Usage (Without Installing)
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)
You can also run the script directly without installing:
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):**
```bash
sudo ./pbs-client-installer.sh
# Check timer status
sudo systemctl status pbs-backup-default.timer
# View next scheduled run
sudo systemctl list-timers pbs-backup-*
```
### Command-Line Options
**Manual (on-demand):**
```bash
# 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
```bash
sudo PBSClientTool --help # Show help message
# 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
```bash
sudo PBSClientTool # Interactive menu
sudo PBSClientTool --help # Show help
sudo PBSClientTool --version # Show version
sudo PBSClientTool --install # Install to /usr/local/bin
sudo PBSClientTool --install # Install to system
sudo PBSClientTool --uninstall # Remove from system
```
### Uninstallation
## Configuration Files
To remove the PBSClientTool command from your system:
**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
```bash
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):**
```bash
sudo PBSClientTool --uninstall
```
**Note:** This only removes the command. Your backup targets and configurations are preserved. To completely remove all backups and configurations, use:
**Complete removal (removes everything):**
```bash
cd ~/dev/PBSClientTool
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
```bash
git clone https://github.com/zaphod-black/PBSClientTool
cd PBSClientTool
chmod +x pbs-client-installer.sh
```
### Run with sudo
```bash
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
```bash
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
```bash
# 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):**
```bash
# 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):**
```bash
# 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:
```bash
sudo nano /etc/proxmox-backup-client/config
sudo systemctl daemon-reload
sudo systemctl restart pbs-backup.timer
```
### Disable Automatic Backups
```bash
sudo systemctl disable pbs-backup.timer
sudo systemctl stop pbs-backup.timer
```
### Uninstall
Use the provided uninstaller:
```bash
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:
```bash
# 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:
```bash
./test-connection.sh <server> <port> <datastore> <username> <realm> <password-or-token>
```
**Examples:**
With username/password:
```bash
./test-connection.sh 192.168.1.181 8007 DEAD-BACKUP root pam mypassword
```
With API token:
```bash
./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:**
```bash
# 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:
```bash
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`:
```bash
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:
```bash
yay -S proxmox-backup-client-bin --rebuild
```
### Backups Not Running
Check timer and service status:
```bash
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:
```bash
# 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:
```bash
# 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
Having issues? See the [Troubleshooting Guide](TROUBLESHOOTING.md) for:
- Connection test failures
- Permission errors
- Installation issues
- Backup problems
- Configuration issues
- And more...
## 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 |
| 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](https://github.com/zaphod-black/PBSClientTool/issues)
- **PBS questions:** [Proxmox Forum](https://forum.proxmox.com)
- **PBS docs:** [Official Documentation](https://pbs.proxmox.com/docs/)
## Contributing
Issues and pull requests welcome at [your-repo-url]
Issues and pull requests welcome!
## License
MIT License - see LICENSE file
MIT License
## 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
Created by Cade - Built on Proxmox Backup Client

421
TROUBLESHOOTING.md Normal file
View file

@ -0,0 +1,421 @@
# Troubleshooting Guide
Common issues and solutions for PBSClientTool.
## Connection Issues
### Connection Test Script
If you encounter connection issues, use the included diagnostic script:
```bash
./test-connection.sh <server> <port> <datastore> <username> <realm> <password-or-token>
```
**Examples:**
With username/password:
```bash
./test-connection.sh 192.168.1.181 8007 DEAD-BACKUP root pam mypassword
```
With API token:
```bash
./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 Failures
The installer tests connections 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
**Quick checks:**
```bash
# Test server reachability
ping 192.168.1.181
curl -k https://192.168.1.181:8007
```
**Step 2 - Authentication (15s timeout):**
- Invalid credentials (username/password/token)
- SSL certificate fingerprint issues (automatically handled)
- API token format errors
**Quick checks:**
- Verify credentials in PBS web interface
- Ensure API token includes both username and token name: `root@pam!backupAutomations`
- Check for trailing spaces in input fields (script now trims automatically)
**Step 3 - Datastore Access:**
- Datastore does not exist on server
- User lacks permissions for the datastore
**Quick checks:**
- Verify datastore name matches exactly (case-sensitive)
- Check permissions in PBS: Configuration → Access Control → Permissions
### SSL Certificate Fingerprints
The installer automatically accepts SSL fingerprints during setup. If you need to manually accept:
```bash
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
```
## Permission Errors
### Missing Datastore.Backup Permission
**Error:**
```
Error: permission check failed - missing Datastore.Audit|Datastore.Backup
Error: while creating locked backup group
```
**Solution:**
Your API token needs backup permissions on the datastore.
**Via PBS Web Interface:**
1. Go to **Configuration → Access Control → Permissions**
2. Click **Add → User Permission**
3. Configure:
- **Path:** `/datastore/YOUR-DATASTORE-NAME`
- **User:** `root@pam!backupAutomations` (your token)
- **Role:** `DatastoreBackup` (or `DatastoreAdmin` for full access)
4. Click **Add**
**Via PBS CLI:**
```bash
pveum acl modify /datastore/DEAD-BACKUP -token 'root@pam!backupAutomations' -role DatastoreBackup
```
### Required Permissions
The API token needs at least:
- **Datastore.Backup** - Create new backups
- **Datastore.Verify** - Verify backup integrity (optional)
- **Datastore.Prune** - Remove old backups based on retention policy
The `DatastoreBackup` or `DatastoreAdmin` role includes all of these.
## Installation Issues
### Ubuntu 22.04: libssl1.1 Missing
**Error:**
```
libssl1.1: not found
```
**Solution:**
```bash
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 Linux: libfuse3.so.3 Not Found
**Error:**
```
error while loading shared libraries: libfuse3.so.3: cannot open shared object file
```
**Solution:**
Rebuild the package after fuse3 updates:
```bash
yay -S proxmox-backup-client-bin --rebuild
```
### Arch Linux: yay Not Installed
**Error:**
```
yay: command not found
```
**Solution:**
Install yay AUR helper first:
```bash
git clone https://aur.archlinux.org/yay.git
cd yay
makepkg -si
```
See: https://github.com/Jguer/yay
## Backup Issues
### Backups Not Running
Check timer and service status:
```bash
# Check if timer is enabled and active
sudo systemctl list-timers pbs-backup-default.timer
# Check service status
sudo systemctl status pbs-backup-default.service
# View recent logs
sudo journalctl -u pbs-backup-default.service -n 50
# Follow logs in real-time
sudo journalctl -fu pbs-backup-default.service
```
### "Skip mount point" Messages
**Message:**
```
Skip mount point: /boot/efi
```
**This is normal behavior.** The script excludes separate mount points by default to avoid issues with mounted filesystems.
**To include specific mount points:**
Edit `/etc/proxmox-backup-client/backup-default.sh` and add `--include-dev` flags:
```bash
proxmox-backup-client backup \
root.pxar:/ \
--include-dev /boot/efi \
--repository $PBS_REPOSITORY
```
### Backup Fails with "No space left"
**Error:**
```
Error: No space left on device
```
**Possible causes:**
1. PBS datastore is full
2. Local `/tmp` is full during backup
3. Encryption key storage is full
**Solutions:**
1. Check PBS datastore usage in web interface
2. Prune old backups: `sudo proxmox-backup-client prune`
3. Clean local temp: `sudo rm -rf /tmp/*`
### Encryption Key Issues
**Error:**
```
Error: unable to open encryption key
```
**Solution:**
Ensure encryption key exists and has correct permissions:
```bash
ls -la /root/.config/proxmox-backup/encryption-key.json
# Should show: -rw------- (600) owned by root
# If missing, restore from paper backup
sudo mkdir -p /root/.config/proxmox-backup
sudo cp /path/to/saved/encryption-key.json /root/.config/proxmox-backup/
sudo chmod 600 /root/.config/proxmox-backup/encryption-key.json
```
## Multi-Target Issues
### Target Connection Tests Fail
**Symptom:**
```
default: ✗ Failed
```
**Solution:**
Use option 3 (Edit target) from main menu to reconfigure:
1. Test connection first with standalone test-connection.sh script
2. Verify datastore permissions on PBS server
3. Check for typos in server/datastore names
4. Ensure API token is still valid (not revoked/expired)
### Services Not Found
**Error:**
```
Unit pbs-backup-default.timer not found
```
**Solution:**
The target may not have been fully configured. Reconfigure it:
```bash
sudo PBSClientTool
# Select option 3 (Edit existing target)
# Select option 3 (Full reconfiguration)
```
## Configuration Issues
### Whitespace in Configuration
**Error:**
```
Error: invalid repository format
```
**Cause:**
Previous versions could capture trailing spaces in input fields, breaking the repository string.
**Solution:**
Current version (1.1.0+) automatically trims all input. If you have an old config, reconfigure the target:
```bash
sudo PBSClientTool
# Select option 3 (Edit existing target)
# Select option 1 (Connection only)
# Re-enter connection details (will be auto-trimmed)
```
### Target Shows "Incomplete configuration"
**Symptom:**
```
Target: default
Status: ⚠ Incomplete configuration
Action: Use option 3 (Edit target) to reconfigure
```
**Cause:**
Essential fields (PBS_SERVER or PBS_DATASTORE) are missing or contain placeholder values.
**Solution:**
Use option 3 from main menu to edit the target and complete the configuration.
## Advanced Troubleshooting
### Enable Verbose Backup Logging
Edit `/etc/proxmox-backup-client/backup-default.sh` and add `--verbose`:
```bash
proxmox-backup-client backup \
root.pxar:/ \
--verbose \
--repository $PBS_REPOSITORY
```
### Test Backup Manually
Run backup script directly to see full output:
```bash
sudo /etc/proxmox-backup-client/backup-default.sh
```
### Check PBS Server Logs
On the PBS server:
```bash
journalctl -u proxmox-backup.service -f
```
### Verify Repository Format
Check that PBS_REPOSITORY is correctly formatted:
```bash
source /etc/proxmox-backup-client/targets/default.conf
echo $PBS_REPOSITORY
# Should look like:
# username@realm!tokenname@server:port:datastore
# OR
# username@realm@server:port:datastore
```
### Network Timeout Issues
If backups are slow or timing out over WAN:
Edit backup script and add rate limiting:
```bash
proxmox-backup-client backup \
root.pxar:/ \
--rate-limit 10485760 \
--repository $PBS_REPOSITORY
```
Rate is in bytes/second (10485760 = 10 MB/s).
## Getting Help
### Collect Debug Information
When reporting issues, include:
```bash
# Script version
sudo PBSClientTool --version
# PBS client version
proxmox-backup-client version
# Target list
sudo PBSClientTool
# Select option 1, screenshot the output
# Service status
sudo systemctl status pbs-backup-default.service
# Recent logs
sudo journalctl -u pbs-backup-default.service -n 100 --no-pager
```
### Where to Get Help
- **PBSClientTool issues:** https://github.com/zaphod-black/PBSClientTool/issues
- **PBS client issues:** https://forum.proxmox.com
- **PBS documentation:** https://pbs.proxmox.com/docs/
## Common Misconfigurations
### Token Format
❌ **Wrong:** `backupAutomations` (token name only)
✅ **Correct:** `root@pam!backupAutomations` (full format in permissions)
### Datastore Name
❌ **Wrong:** `DEAD-Backup` (wrong case)
✅ **Correct:** `DEAD-BACKUP` (exact match from PBS)
### Repository String
❌ **Wrong:** `root@pam !backupAutomations@...` (extra space)
✅ **Correct:** `root@pam!backupAutomations@...` (no spaces)
(Note: Current version auto-trims spaces, but good to know the correct format)
### Permission Path
❌ **Wrong:** `/datastore/DEAD-BACKUP/` (trailing slash)
✅ **Correct:** `/datastore/DEAD-BACKUP` (no trailing slash)