shell/docs/enhanced-media-backup.md

Enhanced Media Backup Script

Overview

The enhanced backup-media.sh script provides robust, enterprise-grade backup functionality for Docker-based media services including Sonarr, Radarr, Prowlarr, Audiobookshelf, Tautulli, SABnzbd, and Jellyseerr.

Features

Core Functionality

• Multi-service support: Backs up 7 different media services
• Parallel execution: Run multiple backups simultaneously for faster completion
• Verification: Optional integrity checking of backed up files
• Error handling: Comprehensive error detection and reporting
• Performance monitoring: Track backup duration and performance metrics

Enhanced Logging

• Multiple log formats: Plain text, JSON, and Markdown reports
• Detailed tracking: File sizes, checksums, timestamps, and status
• Performance logs: JSON-formatted performance data for analysis
• Color-coded output: Easy-to-read terminal output with status colors

Safety Features

• Dry run mode: Preview operations without making changes
• Pre-flight checks: Verify disk space and Docker availability
• Container verification: Check if containers are running before backup
• Graceful error handling: Continue with other services if one fails

Maintenance

• Automatic cleanup: Remove old backups based on age and count limits
• Configurable retention: Customize how many backups to keep
• Space management: Monitor and report disk usage

Usage

Basic Usage

# Run standard backup
./backup-media.sh

# Preview what would be backed up
./backup-media.sh --dry-run

# Run backups sequentially instead of parallel
./backup-media.sh --sequential

# Skip verification for faster backup
./backup-media.sh --no-verify

# Interactive mode with confirmations
./backup-media.sh --interactive

Command Line Options

Option	Description
--dry-run	Show what would be backed up without actually doing it
--no-verify	Skip backup verification for faster execution
--sequential	Run backups one at a time instead of parallel
--interactive	Ask for confirmation before each backup
--webhook URL	Custom webhook URL for notifications
-h, --help	Show help message

Configuration

Environment Variables

The script uses several configurable parameters at the top of the file:

# Retention settings
MAX_BACKUP_AGE_DAYS=30        # Delete backups older than 30 days
MAX_BACKUPS_TO_KEEP=10        # Keep only 10 most recent backups

# Directory settings
BACKUP_ROOT="/mnt/share/media/backups"
LOG_ROOT="/mnt/share/media/backups/logs"

# Feature toggles
PARALLEL_BACKUPS=true         # Enable parallel execution
VERIFY_BACKUPS=true          # Enable backup verification
PERFORMANCE_MONITORING=true  # Track performance metrics

Services Configuration

The script automatically detects and backs up these services:

Service	Container Path	Backup Content
Sonarr	/config/Backups/scheduled	Scheduled backups
Radarr	/config/Backups/scheduled	Scheduled backups
Prowlarr	/config/Backups/scheduled	Scheduled backups
Audiobookshelf	/metadata/backups	Metadata backups
Tautulli	/config/backups	Statistics backups
SABnzbd	/config/sabnzbd.ini	Configuration file
Jellyseerr	/config/db/ + /config/settings.json	Database and settings

Output Files

Log Files

• Text Log: media-backup-YYYYMMDD_HHMMSS.log - Standard log format
• Markdown Report: media-backup-YYYYMMDD_HHMMSS.md - Human-readable report
• JSON Log: media-backup.json - Machine-readable backup status
• Performance Log: media-backup-performance.json - Performance metrics

Backup Structure

/mnt/share/media/backups/
├── logs/
│   ├── media-backup-20250525_143022.log
│   ├── media-backup-20250525_143022.md
│   └── media-backup.json
├── sonarr/
│   └── scheduled/
├── radarr/
│   └── scheduled/
├── prowlarr/
│   └── scheduled/
├── audiobookshelf/
│   └── backups/
├── tautulli/
│   └── backups/
├── sabnzbd/
│   ├── sabnzbd_20250525.ini
│   └── sabnzbd_20250524.ini
└── jellyseerr/
    ├── backup_20250525/
    │   ├── db/
    │   └── settings.json
    └── backup_20250524/

Notifications

The script supports webhook notifications (compatible with ntfy.sh and similar services):

# Default webhook
WEBHOOK_URL="https://notify.peterwood.rocks/lab"

# Custom webhook via command line
./backup-media.sh --webhook "https://your-notification-service.com/topic"

Notification includes:

• Backup status (success/failure)
• Number of successful/failed services
• Total execution time
• Hostname for identification

Performance Monitoring

When enabled, the script tracks:

• Individual service backup duration
• Overall script execution time
• Timestamps for performance analysis
• JSON format for easy parsing and graphing

Example performance log entry:

{
  "timestamp": "2025-05-25T14:30:22-05:00",
  "operation": "backup_sonarr",
  "duration": 45,
  "hostname": "media-server"
}

Error Handling

The script provides robust error handling:

1. Container Health: Checks if Docker containers are running
2. Disk Space: Verifies sufficient space before starting
3. Docker Access: Ensures Docker daemon is accessible
4. Verification: Optional integrity checking of backups
5. Graceful Failures: Continues with other services if one fails

Integration

Cron Job

Add to crontab for automated daily backups:

# Daily at 2 AM
0 2 * * * /home/acedanger/shell/backup-media.sh >/dev/null 2>&1

# Weekly full backup with verification
0 3 * * 0 /home/acedanger/shell/backup-media.sh --verify

Monitoring

Use the JSON logs for monitoring integration:

# Check last backup status
jq '.sonarr.status' /home/acedanger/shell/logs/media-backup.json

# Get performance metrics
jq '.[] | select(.operation == "full_media_backup")' /home/acedanger/shell/logs/media-backup-performance.json

Troubleshooting

Common Issues

1. Container Not Running

   WARNING: Container 'sonarr' is not running
   

   • Verify the container is running: docker ps
   • Start the container: docker start sonarr

2. Permission Denied

   ERROR: Backup failed for sonarr
   

   • Check Docker permissions
   • Verify backup directory permissions
   • Ensure script has execute permissions

3. Disk Space

   ERROR: Insufficient disk space
   

   • Free up space in backup directory
   • Adjust MAX_BACKUP_AGE_DAYS for more aggressive cleanup
   • Run manual cleanup: find /mnt/share/media/backups -mtime +7 -delete

Debug Mode

For troubleshooting, run with verbose output:

# Enable debugging
bash -x ./backup-media.sh --dry-run

# Check specific service
docker exec sonarr ls -la /config/Backups/scheduled

Comparison with Original Script

Feature	Original	Enhanced
Error Handling	Basic	Comprehensive
Logging	Simple text	Multi-format (text/JSON/markdown)
Performance	No tracking	Full metrics
Verification	None	Optional integrity checking
Execution	Sequential only	Parallel and sequential modes
Notifications	Basic webhook	Enhanced with statistics
Cleanup	Manual	Automatic with retention policies
Safety	Limited	Dry-run, pre-flight checks
Documentation	Minimal	Comprehensive help and docs

Security Considerations

• Script runs with user permissions (no sudo required for Docker operations)
• Backup files inherit container security context
• Webhook URLs should use HTTPS for secure notifications
• Log files may contain sensitive path information
• JSON logs are readable by script owner only

Future Enhancements

Potential improvements for future versions:

• Database integrity checking for specific services
• Compression of backup archives
• Remote backup destinations (S3, rsync, etc.)
• Backup restoration functionality
• Integration with monitoring systems (Prometheus, etc.)
• Encrypted backup storage
• Incremental backup support