Add comprehensive installation walkthrough to README

DOCUMENTATION UPDATE: Added detailed step-by-step guide covering the
entire installation process from PBS server setup to completion.

README.md Changes:

Prerequisites Section (Expanded):
- How to create API tokens in PBS web interface
- How to configure datastore permissions
- Common permission error and how to fix it
- Information gathering checklist before running installer

New: Step-by-Step Walkthrough (14 Steps):
1. Running the installer
2. PBS server configuration (IP, port, datastore)
3. Authentication method selection (why API tokens)
4. Entering API token details
5. Backup type selection (files/block/hybrid)
6. File backup paths configuration
7. Block device selection and auto-detection
8. Backup schedule configuration
9. Retention policy settings
10. Encryption setup and key management
11. 3-step connection test process
12. Systemd service creation
13. Optional immediate backup
14. Completion summary

Each step includes:
- Example prompts and responses
- Explanation of options
- Recommendations and best practices
- Common device types and their paths
- Troubleshooting tips

CHANGELOG.md Updates:
- Documented new comprehensive walkthrough
- Listed PBS server setup documentation
- Added permission error troubleshooting to Added section

This addresses the most common user questions and provides a
complete reference for first-time users. Users can now follow
the guide step-by-step to successfully configure PBS backups.

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

Co-Authored-By: Claude <noreply@anthropic.com>

CHANGELOG.md

@@ -23,6 +23,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Parameterized for security (no hardcoded credentials)
   - Tests server reachability, authentication, and datastore access
   - Handles SSL fingerprint acceptance interactively
+- Comprehensive documentation in README:
+  - Step-by-step walkthrough of complete installation (14 steps)
+  - PBS server setup guide (API token creation and permissions)
+  - Common permission error troubleshooting
+  - Explanation of backup types, schedules, and retention policies
 
 ### Changed
 - Installation instructions now use `git clone` instead of `wget`
@@ -33,6 +38,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - More specific error messages based on which step of connection test fails
 - SSL certificate fingerprints are now automatically accepted during setup
 - Reduced authentication timeout from 30s to 15s
+- README now includes comprehensive step-by-step walkthrough
+- Prerequisites section expanded with detailed PBS server setup instructions
 
 ### Fixed
 - **CRITICAL**: SSL fingerprint prompt no longer causes authentication timeout

README.md

@@ -24,12 +24,54 @@ Interactive bash script that automatically installs and configures Proxmox Backu
 - `yay` AUR helper must be installed
 - Install yay first: https://github.com/Jguer/yay
 
-### Before Running
+### Before Running - PBS Server Setup
-- Have your PBS server details ready:
+
-  - Server IP/hostname (e.g., 192.168.1.181)
+#### 1. Create API Token (Recommended)
-  - Port (default: 8007)
+
-  - Datastore name
+API tokens are the recommended authentication method for automated backups. They're more secure than passwords and don't expire.
-  - Authentication credentials (username/password or API token)
+
+**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
 
@@ -47,6 +89,195 @@ chmod +x pbs-client-installer.sh
 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...
+```
+
+Choose `yes` to test your backup immediately, or `no` to wait for the scheduled time.
+
+### 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: