mirror of
https://github.com/acedanger/shell.git
synced 2025-12-06 02:20:11 -08:00
294 lines
7.9 KiB
Markdown
294 lines
7.9 KiB
Markdown
# Plex Backup and Management Scripts
|
|
|
|
This directory contains all scripts and documentation related to Plex Media Server backup, restoration, validation, and management.
|
|
|
|
## Scripts Overview
|
|
|
|
### Core Backup Scripts
|
|
|
|
#### `backup-plex.sh`
|
|
|
|
**Enhanced Plex backup script with advanced features**
|
|
|
|
- **Full backup operations** with integrity verification
|
|
- **Performance monitoring** with JSON-based logging
|
|
- **WAL file handling** for SQLite databases
|
|
- **Database integrity checks** with automated repair options
|
|
- **Parallel processing** for improved performance
|
|
- **Multi-channel notifications** (console, webhook, email)
|
|
- **Comprehensive logging** with color-coded output
|
|
|
|
**Usage:**
|
|
|
|
```bash
|
|
./backup-plex.sh # Standard backup
|
|
./backup-plex.sh --check-integrity # Integrity check only
|
|
./backup-plex.sh --non-interactive # Automated mode
|
|
./backup-plex.sh --auto-repair # Auto-repair database issues
|
|
```
|
|
|
|
#### `restore-plex.sh`
|
|
|
|
**Safe restoration script with validation**
|
|
|
|
- **Backup validation** before restoration
|
|
- **Dry-run mode** for testing
|
|
- **Current data backup** before restoration
|
|
- **Interactive backup selection**
|
|
|
|
**Usage:**
|
|
|
|
```bash
|
|
./restore-plex.sh # List available backups
|
|
./restore-plex.sh plex-backup-20250125_143022.tar.gz # Restore specific backup
|
|
./restore-plex.sh --dry-run backup-file.tar.gz # Test restoration
|
|
```
|
|
|
|
#### `validate-plex-backups.sh`
|
|
|
|
**Backup validation and health monitoring**
|
|
|
|
- **Archive integrity checking**
|
|
- **Backup freshness validation**
|
|
- **Comprehensive reporting**
|
|
- **Automated fix suggestions**
|
|
|
|
**Usage:**
|
|
|
|
```bash
|
|
./validate-plex-backups.sh # Validate all backups
|
|
./validate-plex-backups.sh --report # Generate detailed report
|
|
./validate-plex-backups.sh --fix # Auto-fix issues where possible
|
|
```
|
|
|
|
### Testing and Monitoring
|
|
|
|
#### `test-plex-backup.sh`
|
|
|
|
**Comprehensive testing framework**
|
|
|
|
- **Unit tests** for core functionality
|
|
- **Integration tests** for full system testing
|
|
- **Performance benchmarks**
|
|
|
|
**Usage:**
|
|
|
|
```bash
|
|
./test-plex-backup.sh all # Run all tests
|
|
./test-plex-backup.sh unit # Unit tests only
|
|
./test-plex-backup.sh performance # Performance benchmarks
|
|
```
|
|
|
|
#### `integration-test-plex.sh`
|
|
|
|
**Integration testing for Plex backup system**
|
|
|
|
- **End-to-end testing**
|
|
- **System integration validation**
|
|
- **Environment compatibility checks**
|
|
|
|
#### `monitor-plex-backup.sh`
|
|
|
|
**Real-time backup monitoring**
|
|
|
|
- **Live backup status**
|
|
- **Performance metrics**
|
|
- **Error detection and alerting**
|
|
|
|
### Utility Scripts
|
|
|
|
#### `plex.sh`
|
|
|
|
**Plex Media Server service management**
|
|
|
|
- **Service start/stop/restart**
|
|
- **Status monitoring**
|
|
- **Safe service management**
|
|
|
|
#### `plex-recent-additions.sh`
|
|
|
|
**Recent media additions reporting**
|
|
|
|
- **New content detection**
|
|
- **Addition summaries**
|
|
- **Media library analytics**
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
Key configuration parameters in `backup-plex.sh`:
|
|
|
|
```bash
|
|
# Retention settings
|
|
MAX_BACKUP_AGE_DAYS=30 # Remove backups older than 30 days
|
|
MAX_BACKUPS_TO_KEEP=10 # Keep maximum of 10 backup archives
|
|
|
|
# Directory settings
|
|
BACKUP_ROOT="/mnt/share/media/backups/plex"
|
|
LOG_ROOT="/mnt/share/media/backups/logs"
|
|
|
|
# Feature toggles
|
|
PARALLEL_VERIFICATION=true # Enable parallel verification
|
|
PERFORMANCE_MONITORING=true # Track performance metrics
|
|
AUTO_REPAIR=false # Automatic database repair
|
|
```
|
|
|
|
### Backup Strategy
|
|
|
|
The enhanced backup system implements:
|
|
|
|
- **Archive-only structure**: Direct `.tar.gz` storage
|
|
- **Timestamp naming**: `plex-backup-YYYYMMDD_HHMMSS.tar.gz`
|
|
- **Automatic cleanup**: Age and count-based retention
|
|
- **Integrity validation**: Comprehensive archive verification
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
/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
|
|
```
|
|
|
|
## Enhanced Features
|
|
|
|
### Performance Monitoring
|
|
|
|
- **JSON performance logs**: All operations timed and logged
|
|
- **Performance reports**: Automatic generation of metrics
|
|
- **Operation tracking**: Backup, verification, service management times
|
|
|
|
### Database Management
|
|
|
|
- **Integrity checking**: Comprehensive SQLite database validation
|
|
- **Automated repair**: Optional auto-repair of corruption
|
|
- **WAL file handling**: Proper SQLite Write-Ahead Logging management
|
|
|
|
### Notification System
|
|
|
|
- **Console output**: Color-coded status messages
|
|
- **Webhook notifications**: Custom webhook URL support
|
|
- **Email notifications**: SMTP-based email alerts
|
|
- **Default webhook**: Automatic notifications to configured endpoint
|
|
|
|
### Safety Features
|
|
|
|
- **Pre-flight checks**: Disk space and system validation
|
|
- **Service management**: Safe Plex service start/stop
|
|
- **Backup verification**: Checksum and integrity validation
|
|
- **Error handling**: Comprehensive error detection and recovery
|
|
|
|
## Automation and Scheduling
|
|
|
|
### Cron Integration
|
|
|
|
Example crontab entries for automated operations:
|
|
|
|
```bash
|
|
# Daily Plex backup at 04:15
|
|
15 4 * * * /home/acedanger/shell/plex/backup-plex.sh --non-interactive --auto-repair 2>&1 | logger -t plex-backup -p user.info
|
|
|
|
# Daily validation at 07:00
|
|
0 7 * * * /home/acedanger/shell/plex/validate-plex-backups.sh --fix 2>&1 | logger -t plex-validation -p user.info
|
|
```
|
|
|
|
### Log Monitoring
|
|
|
|
Monitor backup operations with:
|
|
|
|
```bash
|
|
# Real-time monitoring
|
|
sudo journalctl -f -t plex-backup -t plex-validation
|
|
|
|
# Historical analysis
|
|
sudo journalctl --since '24 hours ago' -t plex-backup
|
|
|
|
# Performance analysis
|
|
jq '.[] | select(.operation == "backup") | .duration_seconds' logs/plex-backup-performance.json
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Database corruption**: Use `--auto-repair` flag or manual repair
|
|
2. **Insufficient disk space**: Check space requirements (2x backup size)
|
|
3. **Service management**: Ensure Plex service accessibility
|
|
4. **Archive validation**: Use validation script for integrity checks
|
|
|
|
### Debug Mode
|
|
|
|
Enable verbose logging:
|
|
|
|
```bash
|
|
# Add environment variable for debug output
|
|
PLEX_DEBUG=true ./backup-plex.sh
|
|
```
|
|
|
|
### Log Analysis
|
|
|
|
```bash
|
|
# Check backup success rate
|
|
grep "SUCCESS" logs/plex-backup-*.log | wc -l
|
|
|
|
# Analyze errors
|
|
grep "ERROR" logs/plex-backup-*.log | tail -10
|
|
|
|
# Performance trends
|
|
jq '[.[] | select(.operation == "backup") | .duration_seconds] | add/length' logs/plex-backup-performance.json
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
### File Permissions
|
|
|
|
- Backup files created with appropriate permissions
|
|
- Sensitive files maintain original ownership
|
|
- Temporary files properly cleaned up
|
|
|
|
### Access Control
|
|
|
|
- Script requires appropriate sudo permissions
|
|
- Backup locations should have restricted access
|
|
- Log files contain operational data only
|
|
|
|
### Network Security
|
|
|
|
- Webhook notifications use HTTPS when possible
|
|
- No sensitive data included in notifications
|
|
- Email notifications respect system configuration
|
|
|
|
## Documentation
|
|
|
|
### Detailed Documentation
|
|
|
|
- **[plex-backup.md](./plex-backup.md)**: Comprehensive backup script documentation
|
|
- **[plex-management.md](./plex-management.md)**: Plex management and administration guide
|
|
|
|
### Integration Notes
|
|
|
|
- All scripts follow repository coding standards
|
|
- Consistent logging and error handling
|
|
- Color-coded output for readability
|
|
- Comprehensive help systems
|
|
|
|
## Migration Notes
|
|
|
|
When migrating from legacy backup scripts:
|
|
|
|
1. **Backup current configuration**: Save any custom modifications
|
|
2. **Test new scripts**: Run with `--check-integrity` first
|
|
3. **Update automation**: Modify cron jobs to use new options
|
|
4. **Monitor performance**: Check performance logs for optimization
|
|
|
|
The enhanced scripts maintain backward compatibility while adding significant new capabilities.
|
|
|
|
---
|
|
|
|
*For additional support and advanced configuration options, refer to the detailed documentation files in this directory.*
|