Enhance README with installation and usage details
Expanded README with detailed installation instructions, usage examples, troubleshooting tips, and security considerations for the PBS Client Installer.
This commit is contained in:
zaphod-black
GitHub
parent
6b6baa3281
commit
f15e01918b
1 changed files with 337 additions and 1 deletions
338
README.md
338
README.md
|
|
@ -1,2 +1,338 @@
|
|||
# PBSClientInstaller
|
||||
interactive script to install Proxmox Backup Server Client on any linux machine to start and schedule backups to your PBS
|
||||
|
||||
Interactive bash script that automatically installs and configures Proxmox Backup Client on Ubuntu, Debian, and Arch Linux systems.
|
||||
|
||||
## Features
|
||||
|
||||
- **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
|
||||
|
||||
## 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
|
||||
- Have your PBS server details ready:
|
||||
- Server IP/hostname (e.g., 192.168.1.181)
|
||||
- Port (default: 8007)
|
||||
- Datastore name
|
||||
- Authentication credentials (username/password or API token)
|
||||
|
||||
## Installation
|
||||
|
||||
### Download the script
|
||||
|
||||
```bash
|
||||
wget https://raw.githubusercontent.com/YOUR-REPO/pbs-client-installer.sh
|
||||
chmod +x pbs-client-installer.sh
|
||||
```
|
||||
|
||||
### Run with sudo
|
||||
|
||||
```bash
|
||||
sudo ./pbs-client-installer.sh
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# Run backup immediately
|
||||
sudo systemctl start 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 Fails
|
||||
|
||||
Check your PBS server is accessible:
|
||||
```bash
|
||||
ping 192.168.1.181
|
||||
curl -k https://192.168.1.181:8007
|
||||
```
|
||||
|
||||
Verify credentials on PBS web interface.
|
||||
|
||||
### 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
|
||||
|
||||
## 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue