peterwood/shell
1
0
Fork 0
mirror of https://github.com/acedanger/shell.git synced 2025-12-06 04:30:13 -08:00
Code Issues 19 Packages Projects Releases Wiki Activity

Add comprehensive Plex backup management scripts

Browse Source 
- Introduced `restore-plex.sh` for restoring Plex backups with logging and validation.
- Created `test-plex-backup.sh` for automated testing of backup functionalities.
- Developed `validate-plex-backups.sh` for validating backup integrity and monitoring.
- Updated `update.sh` to reference the correct path for Plex service management.
This commit is contained in:
Peter Wood
2025-05-26 13:20:12 -04:00
parent a91fc79449
commit c9b69ea789
30 changed files with 702 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/crontab-merging-issue-resolution.md
View File

226
docs/enhanced-crontab-system.md
View File

@@ -1,226 +0,0 @@
# Enhanced Crontab and Backup Monitoring System
## Overview
This enhanced system provides comprehensive crontab management with automatic backups, system logging, and advanced monitoring capabilities for your backup operations.
## Components
### 1. Crontab Entries (`crontab-*.txt`)
- **Move backups** (01:00): Transfers Docker backups with logging
- **Plex backup** (04:15): Daily Plex database backup with auto-repair
- **Plex validation** (07:00): Validates and fixes backup integrity
- **Immich backup** (05:00 Mon): Weekly Immich database backup move
- **Weekly report** (08:00 Sun): Comprehensive backup status report
### 2. Crontab Management (`manage-enhanced-crontab.sh`)
- Install enhanced crontab entries with validation
- Verify all backup scripts exist and are executable
- Setup automated backups and log rotation
- Integration with backup and monitoring systems
### 3. Crontab Backup System (`crontab-backup-system.sh`)
- Automated timestamped crontab backups
- Backup comparison and restoration
- Syntax validation
- Automated cleanup of old backups
- Daily automated backup scheduling
### 4. Backup Log Monitor (`backup-log-monitor.sh`)
- Real-time log monitoring with color coding
- Error analysis and reporting
- System health checks
- Comprehensive backup reports
- Service status overview
## Quick Start
### 1. Install the Enhanced System
```bash
# Make scripts executable
chmod +x manage-enhanced-crontab.sh crontab-backup-system.sh backup-log-monitor.sh
# Install enhanced crontab with all features
sudo ./manage-enhanced-crontab.sh install
```
### 2. Monitor Your Backups
```bash
# Real-time monitoring
./backup-log-monitor.sh monitor
# Check system health
./backup-log-monitor.sh health
# View recent activity
./backup-log-monitor.sh recent 24
# Generate weekly report
./backup-log-monitor.sh report 7
```
### 3. Manage Crontab Backups
```bash
# Create manual backup
./crontab-backup-system.sh backup manual
# List all backups
./crontab-backup-system.sh list
# Compare current with backup
./crontab-backup-system.sh compare current
# System status
./crontab-backup-system.sh status
```
## Features
### Enhanced Logging
All backup operations now log to syslog with specific tags:
- `plex-backup`: Plex database backup operations
- `backup-move`: Docker backup file transfers
- `plex-validation`: Backup integrity checks
- `immich-backup`: Immich database operations
- `plex-report`: Weekly reporting
- `crontab-backup`: Crontab backup operations
### Automatic Backups
- **Crontab backups**: Daily automated backups at midnight
- **Cleanup**: Automatic removal of backups older than 30 days
- **Validation**: Syntax checking before applying changes
- **Recovery**: Easy restoration from any backup point
### Health Monitoring
- Script existence and permissions
- Backup directory availability
- Recent activity tracking
- Error rate monitoring
- Overall system health scoring
### Error Handling
- Graceful failure handling in cron jobs
- Detailed error logging and reporting
- Exit code tracking for debugging
- Comprehensive error summaries
## Log Analysis
### View Real-time Logs
```bash
# All backup services
sudo journalctl -f -t plex-backup -t backup-move -t plex-validation -t immich-backup -t plex-report
# Specific service
sudo journalctl -f -t plex-backup
# With our monitor (recommended)
./backup-log-monitor.sh monitor
```
### Historical Analysis
```bash
# Last 24 hours
sudo journalctl --since '24 hours ago' -t plex-backup
# Last week with errors only
sudo journalctl --since '1 week ago' --priority=err -t plex-backup
# Using our tools
./backup-log-monitor.sh recent 24 plex-backup
./backup-log-monitor.sh errors 7
```
## Backup Recovery
### Restore Crontab from Backup
```bash
# List available backups
./crontab-backup-system.sh list
# Restore specific backup
./crontab-backup-system.sh restore crontab-manual-20250526_120000.backup
# Compare before restoring
./crontab-backup-system.sh compare current crontab-manual-20250526_120000.backup
```
### Emergency Recovery
If you need to quickly restore the original crontab:
```bash
# The system automatically creates pre-install backups
./crontab-backup-system.sh list | grep pre-install
./crontab-backup-system.sh restore [backup-filename]
```
## Maintenance
### Regular Tasks
```bash
# Weekly health check
./backup-log-monitor.sh health
# Monthly backup cleanup
./crontab-backup-system.sh cleanup 30
# Quarterly comprehensive report
./backup-log-monitor.sh report 90
```
### Troubleshooting
```bash
# Verify all components
./manage-enhanced-crontab.sh verify
# Check system status
./manage-enhanced-crontab.sh status
# View configuration
./manage-enhanced-crontab.sh show
# Monitor for issues
./backup-log-monitor.sh monitor
```
## Integration Notes
- All scripts follow the established shell repository coding standards
- Logging uses consistent tags and priorities
- Error handling preserves backup integrity
- Color-coded output for better readability
- Comprehensive documentation and help systems
## Security Considerations
- Scripts validate input and handle errors gracefully
- Backup files include metadata for tracking
- Permissions are properly managed
- Sensitive operations require sudo confirmation
- All operations are logged for audit trails
## Next Steps
1. **Install the system**: Run `sudo ./manage-enhanced-crontab.sh install`
2. **Test monitoring**: Use `./backup-log-monitor.sh monitor` during next backup
3. **Review reports**: Generate weekly reports to establish baseline
4. **Set up alerts**: Consider integrating with your notification system
5. **Document customizations**: Add any local modifications to this guide

280
docs/multi-system-crontab-management.md
View File

@@ -1,280 +0,0 @@
# Multi-System Crontab Management Guide
## Overview
The enhanced crontab backup system now supports managing crontab backups across multiple systems using a hostname-based directory structure. This enables centralized backup management for distributed environments.
## System Architecture
### Directory Structure
```
crontab-backups/
├── europa/ # Current system (example)
│ ├── current-crontab.backup
│ └── archive/
│ ├── europa-crontab-initial-20250526_101354.backup
│ └── europa-crontab-pre-install-20250526_100622.backup
├── io/ # Remote system backups
│ ├── current-crontab.backup
│ └── archive/
│ └── io-crontab-sample-20250526_101558.backup
└── racknerd/ # Another remote system
├── current-crontab.backup
└── archive/
└── racknerd-crontab-sample-20250526_101558.backup
```
### File Naming Convention
- Format: `{hostname}-crontab-{type}-{timestamp}.backup`
- Examples:
- `europa-crontab-manual-20250526_101354.backup`
- `io-crontab-pre-upgrade-20250526_120000.backup`
- `racknerd-crontab-auto-20250526_000001.backup`
## Features
### 🔄 Multi-System Support
- **Hostname-based organization**: Each system gets its own directory
- **Cross-system operations**: View, compare, and restore backups from any system
- **Centralized management**: Manage all systems from a single location
### 📊 System Status Monitoring
```bash
# View status for current system
./crontab-backup-system.sh status
# View status for specific system
./crontab-backup-system.sh status io
# View status for all systems
./crontab-backup-system.sh status all
```
### 🗂️ Backup Operations
```bash
# Create backup on current system
./crontab-backup-system.sh backup pre-upgrade
# List backups for specific system
./crontab-backup-system.sh list io
# List all systems with backups
./crontab-backup-system.sh list-systems
# Import backup from external source
./crontab-backup-system.sh import /path/to/backup.txt io manual
```
### 🔍 Cross-System Comparison
```bash
# Compare current crontab with backup from another system
./crontab-backup-system.sh compare current io-crontab-sample-20250526_101558.backup
# Compare two backups from different systems
./crontab-backup-system.sh compare europa-crontab-manual-20250526_101354.backup racknerd-crontab-sample-20250526_101558.backup
```
### 🧹 Cleanup Management
```bash
# Clean up backups older than 30 days for current system
./crontab-backup-system.sh cleanup 30
# Clean up backups for specific system
./crontab-backup-system.sh cleanup 7 io
# Clean up backups for all systems
./crontab-backup-system.sh cleanup 30 all
```
## Enhanced Logging Integration
All backup operations now integrate with system logging:
### Syslog Integration
- **Tag-based logging**: Each operation uses specific syslog tags
- **Priority levels**: Different priorities for info, warnings, and errors
- **Performance monitoring**: Execution time tracking for all operations
### Example Enhanced Crontab Entries
```bash
# Plex backup with comprehensive logging
15 4 * * * /home/acedanger/shell/backup-plex.sh 2>&1 | logger -t plex-backup -p user.info
# Backup move operation with error handling
0 1 * * * /home/acedanger/shell/move-backups.sh 2>&1 | logger -t backup-move -p user.info
# Validation with performance tracking
0 7 * * * /home/acedanger/shell/validate-plex-backups.sh --fix 2>&1 | logger -t plex-validation -p user.info
```
### Log Monitoring
```bash
# View all backup-related logs
journalctl -t plex-backup -t backup-move -t plex-validation -f
# View logs for specific operation
journalctl -t plex-backup --since "1 hour ago"
# Monitor backup performance
./backup-log-monitor.sh --real-time
```
## Migration from Legacy Structure
The system automatically detects and migrates legacy backup structures:
### Automatic Migration
- **Legacy detection**: Automatically detects old `crontab-backups/archive/` structure
- **Hostname prefix**: Adds hostname prefix to existing backup files
- **Backward compatibility**: Preserves all existing backup data
- **Safe migration**: Original files remain untouched until manual cleanup
### Manual Migration
```bash
# Force migration of legacy backups
./crontab-backup-system.sh migrate
```
## Production Deployment
### System Setup
1. **Deploy script**: Copy `crontab-backup-system.sh` to each system
2. **Configure permissions**: Ensure proper read/write access to backup directories
3. **Setup automation**: Configure automated daily backups
### Automated Backup Setup
```bash
# Setup automated daily backups on each system
./crontab-backup-system.sh setup-auto
```
This adds the following entry to the system crontab:
```bash
0 0 * * * /path/to/crontab-backup-system.sh backup auto --auto-cleanup 2>&1 | logger -t crontab-backup -p user.info
```
### Cross-System Synchronization
For distributed environments, consider setting up backup synchronization:
```bash
# Example rsync command to sync backups from remote systems
rsync -avz europa:/home/acedanger/shell/crontab-backups/europa/ /home/acedanger/shell/crontab-backups/europa/
rsync -avz io:/home/acedanger/shell/crontab-backups/io/ /home/acedanger/shell/crontab-backups/io/
```
## Security Considerations
### File Permissions
- **Backup directories**: Restrict access to authorized users only
- **Log files**: Ensure proper log rotation and access controls
- **Remote access**: Use secure methods (SSH, rsync) for cross-system operations
### Backup Integrity
- **Validation**: Regular syntax validation of backup files
- **Checksums**: Consider adding checksum verification for critical backups
- **Retention**: Implement appropriate backup retention policies
## Advanced Use Cases
### Disaster Recovery
```bash
# Restore from specific system backup during emergency
./crontab-backup-system.sh restore io-crontab-pre-incident-20250526_101354.backup
# Compare pre-incident and post-incident configurations
./crontab-backup-system.sh compare io-crontab-pre-incident-20250526_101354.backup current
```
### Configuration Management
```bash
# Standardize crontab across multiple systems
./crontab-backup-system.sh compare europa-crontab-standard-20250526_101354.backup io-crontab-current-20250526_120000.backup
# Validate configurations before deployment
./crontab-backup-system.sh validate new-crontab-config.txt
```
### Compliance and Auditing
- **Change tracking**: Complete history of all crontab changes across systems
- **Audit trails**: System logs provide comprehensive audit information
- **Compliance reporting**: Generate reports showing backup frequency and success rates
## Monitoring and Alerting
### Health Checks
```bash
# Check backup system health
./crontab-backup-system.sh status all
# Monitor recent backup activity
./backup-log-monitor.sh --health-check
```
### Alert Integration
Consider integrating with monitoring systems:
- **Backup failures**: Alert when backups fail or are missing
- **Old backups**: Alert when systems haven't been backed up recently
- **Disk space**: Monitor backup directory disk usage
## Best Practices
1. **Regular Testing**: Periodically test backup restoration procedures
2. **Documentation**: Keep records of system configurations and backup schedules
3. **Automation**: Use automated cleanup to prevent disk space issues
4. **Monitoring**: Implement comprehensive monitoring and alerting
5. **Security**: Regularly review and update access controls
## Support and Troubleshooting
### Common Issues
- **Permission errors**: Ensure proper file permissions on backup directories
- **Missing backups**: Check automated backup cron entries
- **Syntax errors**: Use validation feature before deploying new crontabs
### Debug Mode
Enable verbose logging for troubleshooting:
```bash
# Add debug logging to any command
./crontab-backup-system.sh status all 2>&1 | tee debug.log
```
### Log Analysis
```bash
# Analyze backup patterns
grep "SUCCESS" logs/crontab-management.log | tail -20
# Check for errors
grep "ERROR" logs/crontab-management.log | tail -10
```
---
*This multi-system crontab management solution provides robust, scalable backup management for distributed environments while maintaining simplicity and reliability.*

495
docs/plex-backup.md
View File

@@ -1,495 +0,0 @@
# 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, and WAL file handling.
## Script Overview
The enhanced script performs the following advanced tasks:
1. **Performance Monitoring**: Tracks backup operations with JSON-based performance logging
2. **Full Backup Operations**: Performs complete backups of all Plex files every time
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. **Enhanced Service Management**: Safe Plex service management with progress indicators
8. **Comprehensive Logging**: Detailed logs with color-coded output and timestamps
9. **Safe Automated Cleanup**: Retention policies based on age and backup count
## Enhanced Features
### Full Backup Operation
The script performs complete backups every time it runs:
- **What it does**: Backs up all Plex files regardless of modification status
- **Benefits**:
- Guarantees every backup is a complete restoration point
- Eliminates risk of file loss from incomplete backup coverage
- Simplifies backup management and restoration
- **Usage**: `./backup-plex.sh` (no options needed)
### 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
```bash
./backup-plex.sh --webhook=https://your-webhook-url.com/endpoint
```
**Default Webhook**: The script includes a default webhook URL (`https://notify.peterwood.rocks/lab`) that will be used if no custom webhook is specified. To use a different webhook, specify it with the `--webhook` option.
Sends JSON payloads with backup status, hostname, and timestamps. Notifications include tags for filtering (backup, plex, hostname, and status-specific tags like "errors" or "warnings").
#### Email Notifications
```bash
./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
```bash
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 Backup Process Steps
The backup script follows these detailed steps to ensure data integrity and reliability:
### 1. Create Log Directory
```bash
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
```bash
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. Stop Plex Media Server Service
```bash
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`).
### 4. Backup Plex Database Files and Preferences
The enhanced backup system creates compressed archives directly, eliminating intermediate directories:
```bash
# Files are copied to temporary staging area for verification
cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.db" "$BACKUP_PATH/"
cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.blobs.db" "$BACKUP_PATH/"
cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Preferences.xml" "$BACKUP_PATH/"
```
These commands copy the Plex database files and preferences directly to the backup root directory. Each file copy operation includes integrity verification and checksum validation.
### 5. Create Compressed Archive
```bash
# Create archive directly with timestamp naming convention
final_archive="${BACKUP_ROOT}/plex-backup-$(date '+%Y%m%d_%H%M%S').tar.gz"
tar -czf "$final_archive" -C "$temp_staging_dir" .
```
The system creates compressed archives directly using a timestamp-based naming convention (`plex-backup-YYYYMMDD_HHMMSS.tar.gz`), eliminating the need for intermediate dated directories.
### 6. Archive Validation and Cleanup
```bash
# Validate archive integrity
if tar -tzf "$final_archive" >/dev/null 2>&1; then
log_success "Archive created and validated: $(basename "$final_archive")"
rm -rf "$temp_staging_dir"
else
log_error "Archive validation failed"
rm -f "$final_archive"
fi
```
The system validates the created archive and removes temporary staging files, ensuring only valid compressed backups are retained in the backup root directory.
### 7. Send Notification
```bash
curl \
-H tags:popcorn,backup,plex,${HOSTNAME} \
-d "The Plex databases have been saved to the /media/backups/plex folder as plex-backup-YYYYMMDD_HHMMSS.tar.gz" \
https://notify.peterwood.rocks/lab || { echo "Failed to send notification"; exit 1; }
```
This command sends a notification upon completion of the backup process, indicating the compressed archive has been created.
### 8. Restart Plex Media Server Service
```bash
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`).
### 9. Legacy Cleanup
```bash
# Clean up any remaining dated directories from old backup structure
find "${BACKUP_ROOT}" -maxdepth 1 -type d -name "????????" -exec rm -rf {} \; 2>/dev/null || true
```
The enhanced system includes cleanup of legacy dated directories from previous backup structure versions, ensuring a clean tar.gz-only backup directory.
## Configuration Files
### Performance Log Format
The performance log (`logs/plex-backup-performance.json`) contains entries like:
```json
[
{
"operation": "backup",
"duration_seconds": 45.3,
"timestamp": "2025-05-25T19:45:23-05:00"
},
{
"operation": "verification",
"duration_seconds": 12.8,
"timestamp": "2025-05-25T19:46:08-05:00"
}
]
```
## Usage Examples
### Basic Backup
```bash
./backup-plex.sh
```
Performs a standard backup with all enhanced features enabled.
### Integrity Check Only
```bash
./backup-plex.sh --check-integrity
```
Only checks database integrity without performing backup.
### Automated Backup with Notifications
```bash
./backup-plex.sh --non-interactive --auto-repair --webhook=https://notify.example.com/backup
```
Runs in automated mode with auto-repair and custom webhook notifications.
**Note**: If no `--webhook` option is specified, the script will use the default webhook URL (`https://notify.peterwood.rocks/lab`) for notifications.
### Performance-Optimized Backup
```bash
./backup-plex.sh --no-parallel --no-performance
```
Runs with parallel processing and performance monitoring disabled for maximum compatibility.
## Automation and Scheduling
### Cron Job Setup
For daily automated backups at 2 AM:
```bash
# Edit crontab
crontab -e
# Add this line for daily backup with email notifications
0 2 * * * /home/acedanger/shell/backup-plex.sh --non-interactive --auto-repair --email=admin@example.com 2>&1 | logger -t plex-backup
# Or for daily backup with default webhook notifications (https://notify.peterwood.rocks/lab)
0 2 * * * /home/acedanger/shell/backup-plex.sh --non-interactive --auto-repair 2>&1 | logger -t plex-backup
```
**Note**: The script will automatically use the default webhook URL for notifications unless a custom webhook is specified with `--webhook=URL`.
### Systemd Service
Create a systemd service for more control:
```ini
[Unit]
Description=Plex Backup Service
After=network.target
[Service]
Type=oneshot
User=root
ExecStart=/home/acedanger/shell/backup-plex.sh --non-interactive --auto-repair
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
### Systemd Timer
Create a timer for regular execution:
```ini
[Unit]
Description=Daily Plex Backup
Requires=plex-backup.service
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
```
## Monitoring and Alerts
### Performance Monitoring
The script automatically tracks:
- Backup operation duration
- Verification times
- Service start/stop times
- Overall script execution time
### Health Checks
Regular health monitoring can be implemented by checking:
```bash
# Check last backup success
jq -r '.[-1] | select(.operation == "total_script") | .timestamp' logs/plex-backup-performance.json
# Check average backup performance
jq '[.[] | select(.operation == "backup") | .duration_seconds] | add/length' logs/plex-backup-performance.json
```
## Troubleshooting
### Common Issues
1. **Permission Denied Errors**
- Ensure script runs with appropriate sudo permissions
- Check Plex file ownership and permissions
2. **WAL File Warnings**
- Now handled automatically by the enhanced script
- WAL checkpointing ensures data consistency
3. **Performance Issues**
- Use `--no-parallel` if concurrent operations cause problems
- Monitor performance logs for bottlenecks
4. **Notification Failures**
- Verify webhook URLs are accessible
- Check sendmail configuration for email notifications
### Debug Mode
Enable verbose logging by modifying the script or using:
```bash
bash -x ./backup-plex.sh --check-integrity
```
## Testing Framework
The script includes a comprehensive testing framework (`test-plex-backup.sh`):
### Running Tests
```bash
# Run all tests
./test-plex-backup.sh all
# Run only unit tests
./test-plex-backup.sh unit
# Run performance benchmarks
./test-plex-backup.sh performance
```
### Test Categories
- **Unit Tests**: Core functionality verification
- **Integration Tests**: Full system testing (requires Plex installation)
- **Performance Tests**: Benchmarking and performance validation
## Security Considerations
### File Permissions
- Backup files are created with appropriate permissions
- Sensitive files maintain original ownership and permissions
- Temporary files are properly cleaned up
### Network Security
- Webhook notifications use HTTPS when possible
- Email notifications respect system sendmail configuration
- No sensitive data is included in notifications
### Access Control
- Script requires appropriate sudo permissions
- Backup locations should have restricted access
- Log files contain operational data, not sensitive information
## Backup Strategy
The enhanced script implements a robust backup strategy with a streamlined tar.gz-only structure:
### Archive-Only Directory Structure
The new backup system eliminates intermediate dated directories and stores only compressed archives:
```text
/mnt/share/media/backups/plex/
├── plex-backup-20250125_143022.tar.gz # Latest backup
├── plex-backup-20250124_143011.tar.gz # Previous backup
├── plex-backup-20250123_143008.tar.gz # Older backup
└── logs/
├── backup_log_20250125_143022.md
└── plex-backup-performance.json
```
### Archive Naming Convention
Backup files follow the naming convention `plex-backup-YYYYMMDD_HHMMSS.tar.gz` for easy identification and sorting.
## Important Information
- Ensure that the [`plex.sh`](https://github.com/acedanger/shell/blob/main/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.
- **New Directory Structure**: The enhanced backup system stores only compressed `.tar.gz` files directly in the backup root directory, eliminating intermediate dated directories.
- **Archive Naming**: Backup files follow the naming convention `plex-backup-YYYYMMDD_HHMMSS.tar.gz` for easy identification and sorting.
- **Legacy Compatibility**: The system automatically cleans up old dated directories from previous backup versions during operation.
- The backup directory path is configurable through the `BACKUP_ROOT` variable. Modify this path as needed to fit your environment.
- The script logs important actions and errors to timestamped log files. Check the log files for details if any issues arise.
- **Backup Validation**: All archives undergo integrity checking to ensure backup reliability.
## Final Directory Structure
```text
/mnt/share/media/backups/plex/
├── plex-backup-20250125_143022.tar.gz # Latest backup
├── plex-backup-20250124_143011.tar.gz # Previous backup
├── plex-backup-20250123_143008.tar.gz # Older backup
└── logs/
├── backup_log_20250125_143022.md
└── plex-backup-performance.json
```
Backup files follow the pattern: `plex-backup-YYYYMMDD_HHMMSS.tar.gz`
- **YYYYMMDD**: Date of backup (e.g., 20250125)
- **HHMMSS**: Time of backup (e.g., 143022)
- **tar.gz**: Compressed archive format
### Key Improvements
1. **Direct Archive Creation**: No intermediate directories required
2. **Efficient Storage**: Only compressed files stored permanently
3. **Easy Identification**: Timestamp-based naming for sorting
4. **Legacy Cleanup**: Automatic removal of old dated directories
5. **Archive Validation**: Integrity checking of compressed files
### 3-2-1 Backup Rule
1. **3 Copies**: Original data + local backup + compressed archive
2. **2 Different Media**: Local disk + network storage capability
3. **1 Offsite**: Ready for remote synchronization
### Retention Policy
- Configurable maximum backup age (default: 30 days)
- Configurable maximum backup count (default: 10 backups)
- Automatic cleanup of old backups
### Verification Strategy
- Checksum verification for all backed up files
- Database integrity checks before and after operations
- Optional parallel verification for improved performance
## Migration from Legacy Script
To migrate from the original backup script:
1. **Backup Current Configuration**: Save any custom modifications
2. **Test New Script**: Run with `--check-integrity` first
3. **Update Automation**: Modify cron jobs to use new options
4. **Monitor Performance**: Check performance logs for optimization opportunities
The enhanced script maintains backward compatibility while adding significant new capabilities.

83
docs/plex-management.md
View File

@@ -1,83 +0,0 @@
# Plex Management Script Documentation
This document provides an overview and step-by-step explanation of the `plex.sh` script. This script is used to manage the Plex Media Server service on a systemd-based Linux distribution.
## Script Overview
The script performs the following main tasks:
1. Starts the Plex Media Server.
2. Stops the Plex Media Server.
3. Restarts the Plex Media Server.
4. Displays the current status of the Plex Media Server.
## Detailed Steps
### 1. Start Plex Media Server
```bash
start_plex() {
sudo systemctl start plexmediaserver
echo "Plex Media Server started."
}
```
This function starts the Plex Media Server using `systemctl`.
### 2. Stop Plex Media Server
```bash
stop_plex() {
sudo systemctl stop plexmediaserver
echo "Plex Media Server stopped."
}
```
This function stops the Plex Media Server using `systemctl`.
### 3. Restart Plex Media Server
```bash
restart_plex() {
sudo systemctl restart plexmediaserver
echo "Plex Media Server restarted."
}
```
This function restarts the Plex Media Server using `systemctl`.
### 4. Display Plex Media Server Status
```bash
status_plex() {
sudo systemctl status plexmediaserver
}
```
This function displays the current status of the Plex Media Server using `systemctl`.
## Usage
To use the script, run it with one of the following parameters:
```shell
./plex.sh {start|stop|restart|status}
```
- `start`: Starts the Plex Media Server.
- `stop`: Stops the Plex Media Server.
- `restart`: Restarts the Plex Media Server.
- `status`: Displays the current status of the Plex Media Server.
## Important Information
- Ensure that the script is executable. You can make it executable with the following command:
```shell
chmod +x plex.sh
```
- The script uses `systemctl` to manage the Plex Media Server service. Ensure that `systemctl` is available on your system.
- The script requires `sudo` privileges to manage the Plex Media Server service. Ensure that you have the necessary permissions to run the script with `sudo`.
By following this documentation, you should be able to understand and use the `plex.sh` script effectively.