mirror of
https://github.com/acedanger/shell.git
synced 2025-12-06 00:00:13 -08:00
Commit local changes before merging with remote
This commit is contained in:
Peter Wood
294
plex/README.md
Normal file
294
plex/README.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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
|
||||
└── plex-backup.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.*
|
||||
Reference in New Issue
Block a user