Add additional documentation and examples
- Usage examples for different scenarios - Network backup analysis documentation - Restore operation examples and procedures
This commit is contained in:
Radosław Gierwiało
279
restore_example.md
Normal file
279
restore_example.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# Docker2PBS Backup Restore Guide
|
||||
|
||||
## Backup Format
|
||||
|
||||
The script creates **separate .pxar archives for each volume** of the service:
|
||||
|
||||
- `volume_db_data.pxar` - for named volumes
|
||||
- `bind_dot_html.pxar` - for bind mounts (paths converted to safe names)
|
||||
- `bind_dot_backups.pxar` - for other bind mounts
|
||||
|
||||
## How to Restore Backups
|
||||
|
||||
### 1. List Available Backups
|
||||
```bash
|
||||
proxmox-backup-client list --repository user@pbs.example.com:backup-datastore
|
||||
```
|
||||
|
||||
### 2. Inspect Specific Backup Contents
|
||||
```bash
|
||||
proxmox-backup-client catalog \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45
|
||||
```
|
||||
|
||||
### 3. Selective Volume Restoration
|
||||
|
||||
#### Restore Docker Volume
|
||||
```bash
|
||||
proxmox-backup-client restore \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
volume_db_data.pxar /var/lib/docker/volumes/db_data/_data
|
||||
```
|
||||
|
||||
#### Restore Bind Mount
|
||||
```bash
|
||||
proxmox-backup-client restore \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
bind_dot_html.pxar ./html
|
||||
```
|
||||
|
||||
### 4. Restore All Archives at Once
|
||||
```bash
|
||||
# Example script to restore all volumes
|
||||
for archive in volume_db_data.pxar bind_dot_html.pxar bind_dot_backups.pxar; do
|
||||
echo "Restoring $archive..."
|
||||
proxmox-backup-client restore \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
"$archive" "/tmp/restore/$archive/"
|
||||
done
|
||||
```
|
||||
|
||||
## Archive Naming Convention
|
||||
|
||||
The script automatically generates archive names:
|
||||
|
||||
| Volume Type | Source Example | Archive Name |
|
||||
|-------------|----------------|--------------|
|
||||
| Named volume | `db_data` | `volume_db_data.pxar` |
|
||||
| Bind mount | `./html` | `bind_dot_html.pxar` |
|
||||
| Bind mount | `/app/data` | `bind__app_data.pxar` |
|
||||
| Bind mount | `../config` | `bind_dotdot_config.pxar` |
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
1. **Selective Restoration** - restore only specific volumes
|
||||
2. **Clear Structure** - each volume has its own descriptive archive name
|
||||
3. **Easy Management** - inspect contents of specific volumes
|
||||
4. **Safer Operations** - lower risk of overwriting unwanted files
|
||||
5. **Flexible Restore** - restore data to different locations
|
||||
|
||||
## Inspect Archive Contents
|
||||
```bash
|
||||
proxmox-backup-client catalog \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
volume_db_data.pxar
|
||||
```
|
||||
|
||||
## Complete Restore Workflow
|
||||
|
||||
### 1. Stop the Service
|
||||
```bash
|
||||
docker-compose stop service_name
|
||||
```
|
||||
|
||||
### 2. List Available Backups
|
||||
```bash
|
||||
proxmox-backup-client list --repository user@pbs.example.com:backup-datastore
|
||||
```
|
||||
|
||||
### 3. Inspect Backup Contents
|
||||
```bash
|
||||
proxmox-backup-client catalog \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45
|
||||
```
|
||||
|
||||
### 4. Restore Specific Volumes
|
||||
```bash
|
||||
# Restore Docker volume
|
||||
proxmox-backup-client restore \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
volume_db_data.pxar /var/lib/docker/volumes/db_data/_data
|
||||
|
||||
# Restore bind mounts
|
||||
proxmox-backup-client restore \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
bind_dot_html.pxar ./html
|
||||
```
|
||||
|
||||
### 5. Start the Service
|
||||
```bash
|
||||
docker-compose up -d service_name
|
||||
```
|
||||
|
||||
## Advanced Restore Scenarios
|
||||
|
||||
### Restore to Different Location
|
||||
```bash
|
||||
# Restore to temporary location for inspection
|
||||
proxmox-backup-client restore \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
volume_db_data.pxar /tmp/inspect_db_data
|
||||
```
|
||||
|
||||
### Restore with Different Ownership
|
||||
```bash
|
||||
# Restore and fix permissions
|
||||
proxmox-backup-client restore \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
bind_dot_html.pxar ./html
|
||||
|
||||
# Fix ownership if needed
|
||||
sudo chown -R 1000:1000 ./html
|
||||
```
|
||||
|
||||
### Partial Restore (Specific Files)
|
||||
```bash
|
||||
# Mount archive and copy specific files
|
||||
mkdir /tmp/mount_point
|
||||
proxmox-backup-client mount \
|
||||
--repository user@pbs.example.com:backup-datastore \
|
||||
host/service_name/2024-01-15_10-30-45 \
|
||||
/tmp/mount_point
|
||||
|
||||
# Copy specific files
|
||||
cp /tmp/mount_point/volume_db_data.pxar/postgresql.conf ./
|
||||
cp /tmp/mount_point/bind_dot_html.pxar/index.html ./
|
||||
|
||||
# Unmount
|
||||
fusermount -u /tmp/mount_point
|
||||
```
|
||||
|
||||
## Automation Scripts
|
||||
|
||||
### Backup Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# backup.sh - Automated backup script
|
||||
|
||||
SERVICE_NAME="$1"
|
||||
COMPOSE_FILE="docker-compose.yml"
|
||||
PBS_REPO="user@pbs.example.com:datastore"
|
||||
|
||||
if [ -z "$SERVICE_NAME" ]; then
|
||||
echo "Usage: $0 <service_name>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Starting backup of service: $SERVICE_NAME"
|
||||
./docker2pbs.py "$COMPOSE_FILE" "$SERVICE_NAME" --pbs-repository "$PBS_REPO"
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "Backup completed successfully"
|
||||
else
|
||||
echo "Backup failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Restore Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# restore.sh - Automated restore script
|
||||
|
||||
SERVICE_NAME="$1"
|
||||
BACKUP_ID="$2"
|
||||
PBS_REPO="user@pbs.example.com:datastore"
|
||||
|
||||
if [ -z "$SERVICE_NAME" ] || [ -z "$BACKUP_ID" ]; then
|
||||
echo "Usage: $0 <service_name> <backup_id>"
|
||||
echo "Example: $0 database 2024-01-15_10-30-45"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Stopping service: $SERVICE_NAME"
|
||||
docker-compose stop "$SERVICE_NAME"
|
||||
|
||||
echo "Listing archives in backup: $BACKUP_ID"
|
||||
ARCHIVES=$(proxmox-backup-client catalog --repository "$PBS_REPO" "host/$SERVICE_NAME/$BACKUP_ID" | grep "\.pxar$" | awk '{print $1}')
|
||||
|
||||
for ARCHIVE in $ARCHIVES; do
|
||||
echo "Restoring archive: $ARCHIVE"
|
||||
# Determine restore path based on archive type
|
||||
if [[ $ARCHIVE == volume_* ]]; then
|
||||
VOLUME_NAME=${ARCHIVE#volume_}
|
||||
VOLUME_NAME=${VOLUME_NAME%.pxar}
|
||||
RESTORE_PATH="/var/lib/docker/volumes/${VOLUME_NAME}/_data"
|
||||
else
|
||||
# For bind mounts, restore to current directory
|
||||
RESTORE_PATH="./"
|
||||
fi
|
||||
|
||||
proxmox-backup-client restore \
|
||||
--repository "$PBS_REPO" \
|
||||
"host/$SERVICE_NAME/$BACKUP_ID" \
|
||||
"$ARCHIVE" "$RESTORE_PATH"
|
||||
done
|
||||
|
||||
echo "Starting service: $SERVICE_NAME"
|
||||
docker-compose up -d "$SERVICE_NAME"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Permission Denied**
|
||||
```bash
|
||||
# Check PBS client permissions
|
||||
ls -la ~/.config/proxmox-backup/
|
||||
|
||||
# Run with sudo if needed
|
||||
sudo proxmox-backup-client restore ...
|
||||
```
|
||||
|
||||
2. **Archive Not Found**
|
||||
```bash
|
||||
# List all archives in backup
|
||||
proxmox-backup-client catalog \
|
||||
--repository user@pbs.example.com:datastore \
|
||||
host/service_name/backup_id
|
||||
```
|
||||
|
||||
3. **Network/Connection Issues**
|
||||
```bash
|
||||
# Test PBS connectivity
|
||||
proxmox-backup-client list --repository user@pbs.example.com:datastore
|
||||
|
||||
# Check PBS server status
|
||||
ping pbs.example.com
|
||||
```
|
||||
|
||||
4. **Disk Space Issues**
|
||||
```bash
|
||||
# Check available space
|
||||
df -h /var/lib/docker/volumes/
|
||||
df -h ./
|
||||
|
||||
# Clean up if needed
|
||||
docker volume prune
|
||||
docker system prune
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Always stop services before restoring data
|
||||
- Test restore procedures in non-production environments
|
||||
- Keep restore documentation up to date
|
||||
- Monitor disk space during restore operations
|
||||
- Verify data integrity after restoration
|
||||
- Create restore scripts for frequently restored services
|
||||
Reference in New Issue
Block a user