shell/docs/plex-backup.md

Enhanced Plex Backup Script Documentation

This document provides comprehensive documentation for the enhanced backup-plex.sh script. This advanced backup solution includes performance monitoring, parallel processing, intelligent notifications, WAL file handling, and automated testing capabilities.

Script Overview

The enhanced script performs the following advanced tasks:

1. Performance Monitoring: Tracks backup operations with JSON-based performance logging
2. Intelligent Backup Detection: Only backs up files that have changed since last backup
3. WAL File Handling: Properly handles SQLite Write-Ahead Logging files
4. Database Integrity Verification: Comprehensive integrity checks with automated repair options
5. Parallel Processing: Concurrent verification for improved performance
6. Multi-Channel Notifications: Console, webhook, and email notification support
7. Checksum Caching: Intelligent caching to avoid recalculating unchanged file checksums
8. Enhanced Service Management: Safe Plex service management with progress indicators
9. Comprehensive Logging: Detailed logs with color-coded output and timestamps
10. Automated Cleanup: Configurable retention policies for old backups

Enhanced Features

Performance Tracking

• JSON Performance Logs: All operations are timed and logged to logs/plex-backup-performance.json
• Performance Reports: Automatic generation of average performance metrics
• Operation Monitoring: Tracks backup, verification, service management, and overall script execution times

Notification System

The script supports multiple notification channels:

Console Notifications

• Color-coded status messages (Success: Green, Error: Red, Warning: Yellow, Info: Blue)
• Timestamped log entries with clear formatting

Webhook Notifications

./backup-plex.sh --webhook=https://your-webhook-url.com/endpoint

Sends JSON payloads with backup status, hostname, and timestamps.

Email Notifications

./backup-plex.sh --email=admin@example.com

Requires sendmail to be configured on the system.

WAL File Management

The script now properly handles SQLite Write-Ahead Logging files:

• Automatic Detection: Identifies and backs up .db-wal and .db-shm files when present
• WAL Checkpointing: Performs PRAGMA wal_checkpoint(FULL) before integrity checks
• Safe Backup: Ensures WAL files are properly backed up alongside main database files

Database Integrity & Repair

Enhanced database management features:

• Pre-backup Integrity Checks: Verifies database health before backup operations
• Automated Repair: Optional automatic repair of corrupted databases using advanced techniques
• Interactive Repair Mode: Prompts for repair decisions when issues are detected
• Post-repair Verification: Re-checks integrity after repair operations

Parallel Processing

• Concurrent Verification: Parallel backup verification for improved performance
• Fallback Safety: Automatically falls back to sequential processing if parallel mode fails
• Configurable: Can be disabled with --no-parallel for maximum safety

Command Line Options

Usage: ./backup-plex.sh [OPTIONS]

Options:
  --auto-repair        Automatically attempt to repair corrupted databases
  --check-integrity    Only check database integrity, don't backup
  --non-interactive    Run in non-interactive mode (for automation)
  --no-parallel        Disable parallel verification (slower but safer)
  --no-performance     Disable performance monitoring
  --webhook=URL        Send notifications to webhook URL
  --email=ADDRESS      Send notifications to email address
  -h, --help          Show help message

Detailed Steps

1. Create Log Directory

mkdir -p /mnt/share/media/backups/logs || { echo "Failed to create log directory"; exit 1; }

This command ensures that the log directory exists. If it doesn't, it creates the directory. If the directory creation fails, the script exits with an error message.

2. Define Log File

LOG_FILE="/mnt/share/media/backups/logs/backup_log_$(date +%Y%m%d_%H%M%S).md"

This line defines the log file path, including the current date and time in the filename to ensure uniqueness.

3. Define Log File Details Function

log_file_details() {
    local src=$1
    local dest=$2
    local size=$(du -sh "$dest" | cut -f1)
    echo "Source: $src" >> "$LOG_FILE"
    echo "Destination: $dest" >> "$LOG_FILE"
    echo "Size: $size" >> "$LOG_FILE"
}

This function logs the details of the copied files, including the source, destination, and size.

4. Stop Plex Media Server Service

if systemctl is-active --quiet plexmediaserver.service; then
  /home/acedanger/shell/plex.sh stop || { echo "Failed to stop plexmediaserver.service"; exit 1; }
fi

This block checks if the Plex Media Server service is running. If it is, the script stops the service using a custom script (plex.sh).

5. Create Backup Directory

mkdir -p /mnt/share/media/backups/plex/$(date +%Y%m%d)/ || { echo "Failed to create backup directory"; exit 1; }

This command creates a backup directory with the current date. If the directory creation fails, the script exits with an error message.

6. Copy Plex Database Files and Preferences

cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.db" /mnt/share/media/backups/plex/$(date +%Y%m%d)/ || { echo "Failed to copy com.plexapp.plugins.library.db"; exit 1; }
log_file_details "com.plexapp.plugins.library.db" "/mnt/share/media/backups/plex/$(date +%Y%m%d)/"

cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.blobs.db" /mnt/share/media/backups/plex/$(date +%Y%m%d)/ || { echo "Failed to copy com.plexapp.plugins.library.blobs.db"; exit 1; }
log_file_details "com.plexapp.plugins.library.blobs.db" "/mnt/share/media/backups/plex/$(date +%Y%m%d)/"

cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Preferences.xml" /mnt/share/media/backups/plex/$(date +%Y%m%d)/ || { echo "Failed to copy Preferences.xml"; exit 1; }
log_file_details "Preferences.xml" "/mnt/share/media/backups/plex/$(date +%Y%m%d)/"

These commands copy the Plex database files and preferences to the backup directory. Each file copy operation is followed by a call to the log_file_details function to log the details of the copied files.

7. Compress the Backup Directory

tar -czf /mnt/share/media/backups/plex/$(date +%Y%m%d).tar.gz -C /mnt/share/media/backups/plex/plex $(date +%Y%m%d) || { echo "Failed to compress backup folder"; exit 1; }

This command compresses the backup directory into a gzip archive. If the compression fails, the script exits with an error message.

8. Delete Original Backup Directory

if [ $? -eq 0 ]; then
    if [ -s /mnt/share/media/backups/plex/$(date +%Y%m%d).tar.gz ]; then
        rm -rf /mnt/share/media/backups/plex/$(date +%Y%m%d)/ || { echo "Failed to delete original backup folder"; exit 1; }
    else
        echo "Compressed file is empty, not deleting the backup folder" >> "$LOG_FILE"
    fi
else
    echo "Compression failed, not deleting the backup folder" >> "$LOG_FILE"
fi

This block checks if the compression was successful. If it was, and the compressed file is not empty, it deletes the original backup directory. If the compression failed or the compressed file is empty, it logs an appropriate message.

9. Send Notification

curl \
    -H tags:popcorn,backup,plex,${HOSTNAME} \
    -d "The Plex databases have been saved to the /media/backups/plex folder" \
    https://notify.peterwood.rocks/lab || { echo "Failed to send notification"; exit 1; }

This command sends a notification upon completion of the backup process. If the notification fails, the script exits with an error message.

10. Restart Plex Media Server Service

if systemctl is-enabled --quiet plexmediaserver.service; then
  /home/acedanger/shell/plex.sh start || { echo "Failed to start plexmediaserver.service"; exit 1; }
fi

This block checks if the Plex Media Server service is enabled. If it is, the script restarts the service using a custom script (plex.sh).

Important Information

• Ensure that the plex.sh script is available and executable. This script is used to stop and start the Plex Media Server service.
• The script uses systemctl to manage the Plex Media Server service. Ensure that systemctl is available on your system.
• The backup directory and log directory paths are hardcoded. Modify these paths as needed to fit your environment.
• The script logs important actions and errors to a log file with a timestamped filename. Check the log file for details if any issues arise.

By following this documentation, you should be able to understand and use the backup-plex.sh script effectively.