# Plex Management Script Documentation **Author:** Peter Wood This document provides comprehensive documentation for the modern `plex.sh` script, featuring enhanced service management with progress indicators, dependency validation, safety checks, and comprehensive error handling. ## Script Overview **Author:** Peter Wood The enhanced `plex.sh` script is a modern Plex service management tool that performs the following advanced tasks: 1. **Smart Service Management**: Intelligent start/stop/restart operations with dependency checking 2. **Library Scanner Integration**: Integrated access to comprehensive library scanning operations 3. **Enhanced Status Display**: Detailed service status with health indicators and port monitoring 4. **Safety Validation**: Pre-operation checks and post-operation verification 5. **Progress Indicators**: Visual feedback for all operations with timing information 6. **Comprehensive Logging**: Detailed logging with color-coded output and timestamps 7. **Configuration Validation**: Checks for common configuration issues 8. **Network Monitoring**: Port availability and network configuration validation 9. **Process Management**: Advanced process monitoring and cleanup capabilities 10. **Recovery Operations**: Automatic recovery from common service issues 11. **Performance Monitoring**: Service health and resource usage tracking ## Related Scripts in the Plex Ecosystem This script is part of a comprehensive Plex management suite: ### Core Management Scripts - **`plex.sh`** (this script) - Service management and control - **`scan-plex-libraries.sh`** ⭐ **NEW** - Comprehensive library scanning and metadata management - **`backup-plex.sh`** - Database backup with integrity checking and auto-repair - **`restore-plex.sh`** - Safe database restoration with validation ### Recovery and Maintenance Scripts - **`recover-plex-database.sh`** - Advanced database recovery operations - **`icu-aware-recovery.sh`** - ICU-aware database recovery for Unicode issues - **`nuclear-plex-recovery.sh`** - Last-resort database replacement and recovery - **`validate-plex-recovery.sh`** - Recovery operation validation and verification ### Monitoring and Testing Scripts - **`monitor-plex-backup.sh`** - Real-time backup monitoring dashboard - **`validate-plex-backups.sh`** - Backup validation and health monitoring - **`test-plex-backup.sh`** - Comprehensive backup testing suite - **`integration-test-plex.sh`** - End-to-end integration testing ### Utility Scripts - **`plex-recent-additions.sh`** - Recent media additions reporting and statistics ## Library Scanner Integration ⭐ **NEW** ### Overview The `plex.sh` script now includes integrated access to comprehensive library scanning functionality through the new `scan-plex-libraries.sh` script. This integration provides seamless access to all Plex Media Scanner operations directly from the main management interface. ### Library Scanner Features The integrated library scanner provides: - **Library Management**: List all Plex library sections with IDs and names - **Media Scanning**: Scan for new media files (individual libraries or all at once) - **Metadata Refresh**: Refresh library metadata with force options for complete rebuilds - **Deep Analysis**: Comprehensive media analysis for codec information and metadata - **Thumbnail Generation**: Generate preview thumbnails and fanart images - **Library Structure**: Display hierarchical library structure and organization - **Interactive Mode**: User-friendly menu system for easy library management - **Batch Operations**: Perform operations on all libraries or specific selections - **Error Handling**: Comprehensive validation and error reporting - **Service Integration**: Automatic Plex service status validation before operations ### Scanner Integration Commands The library scanner is accessible through the main `plex.sh` script: ```bash # Launch interactive scanner interface ./plex.sh scan # Pass commands directly to scanner ./plex.sh scan list # List all libraries ./plex.sh scan scan # Scan all libraries for new media ./plex.sh scan scan 29 # Scan specific library (ID 29) ./plex.sh scan refresh 29 true # Force refresh specific library ./plex.sh scan analyze 29 true # Deep analyze specific library ./plex.sh scan generate 29 # Generate thumbnails for library ./plex.sh scan tree 29 # Show library structure ``` ### Direct Scanner Access The scanner can also be accessed directly: ```bash # Direct script execution ./scan-plex-libraries.sh interactive # Interactive mode ./scan-plex-libraries.sh list # List libraries ./scan-plex-libraries.sh scan # Scan all libraries ./scan-plex-libraries.sh -v scan 29 # Verbose scan of specific library # Via aliases (if shell configuration is loaded) plex-scan # Launch via plex.sh integration plex-scanner list # Direct scanner access plex-scanner scan 29 # Direct scan of specific library ``` ### Scanner Command Reference #### Core Scanner Commands - **`list`** - Display all available library sections with IDs and names - **`scan [section_id]`** - Scan for new media files (all libraries if no ID specified) - **`refresh [section_id] [force]`** - Refresh metadata (set force=true for complete refresh) - **`analyze [section_id] [deep]`** - Analyze media files (set deep=true for comprehensive analysis) - **`generate [section_id]`** - Generate thumbnails and fanart images - **`tree `** - Display hierarchical library structure (requires section ID) - **`interactive`** - Launch interactive menu system #### Scanner Options - **`-v, --verbose`** - Enable verbose output for detailed operation information - **`-h, --help`** - Display comprehensive help and usage information #### Example Scanner Operations ```bash # List all available libraries with their section IDs $ ./plex.sh scan list Available Library Sections: ========================= 29: Movies 30: TV Shows 31: Music # Scan Movies library for new content $ ./plex.sh scan scan 29 [>] Scanning library section 29 for new media... [✓] Library section 29 scan completed # Force refresh all libraries (complete metadata rebuild) $ ./plex.sh scan refresh "" true [~] Refreshing metadata for all libraries... [i] Refreshing section 29... [✓] Section 29 refreshed successfully [i] Refreshing section 30... [✓] Section 30 refreshed successfully [✓] All libraries refreshed successfully # Deep analyze TV Shows library $ ./plex.sh scan analyze 30 true [?] Analyzing media in library section 30... [✓] Library section 30 analysis completed # Generate thumbnails for Movies library $ ./plex.sh scan generate 29 [*] Generating thumbnails for library section 29... [✓] Thumbnails generated for library section 29 ``` ### Interactive Scanner Mode The interactive mode provides a user-friendly menu system: ```bash $ ./plex.sh scan 🎬 Plex Library Scanner - Interactive Mode Select an operation to perform: Available Operations: 1) List all libraries 2) Scan libraries for new media 3) Refresh library metadata 4) Analyze library media 5) Generate thumbnails 6) Show library tree q) Quit Choose an option [1-6,q]: 2 Scan Options: 1) Scan all libraries 2) Scan specific library Choose [1-2]: 1 [>] Scanning all libraries for new media... [✓] All libraries scanned successfully ``` ### Scanner Error Handling and Validation The library scanner includes comprehensive error handling: - **Service Validation**: Automatically checks if Plex Media Server is running - **Scanner Detection**: Locates Plex Media Scanner binary across different installation paths - **Section ID Validation**: Verifies library section IDs exist before operations - **Operation Verification**: Confirms successful completion of all scanner operations - **Graceful Failure**: Provides helpful error messages and recovery suggestions ### Scanner Logging and Monitoring All scanner operations are logged: - **Operation Logs**: Detailed logs written to `/home/acedanger/shell/logs/plex-scanner.log` - **Timestamp Tracking**: All operations include precise timestamps - **Verbose Mode**: Enhanced debugging information available with `-v` flag - **Status Reporting**: Real-time status updates during long-running operations ### Scanner Performance Considerations For optimal performance: - **Large Libraries**: Scanner operations may take considerable time for large media collections - **Deep Analysis**: Deep analysis is resource-intensive, use selectively - **Concurrent Operations**: Avoid running multiple scanner operations simultaneously - **System Resources**: Scanner operations can be CPU and I/O intensive during execution ### Scanner Best Practices Recommended usage patterns: 1. **Regular Scanning**: Set up regular scans for libraries with frequent media additions 2. **Selective Operations**: Use specific section IDs for targeted operations when possible 3. **Monitor Progress**: Use verbose mode to understand operation progress and impact 4. **Service Health**: Ensure Plex service is healthy before performing scanner operations 5. **Batch Operations**: For multiple libraries, consider using "scan all" for efficiency ### Scanner Troubleshooting Common issues and solutions: 1. **"Plex Media Server is not running"** - Start Plex: `./plex.sh start` - Verify status: `./plex.sh status` 2. **"Plex Media Scanner binary not found"** - Verify Plex installation is complete - Check if binary exists in standard locations - Ensure proper system PATH configuration 3. **"Section ID not found"** - Use `./plex.sh scan list` to see valid section IDs - Verify the library hasn't been deleted or renamed 4. **Scanner operations timeout or fail** - Check system resources (CPU, memory, disk I/O) - Verify media files are accessible and not corrupted - Review scanner logs for detailed error information ### Scanner Bash Completion ⭐ **NEW** The library scanner includes comprehensive bash completion support: #### Tab Completion Features - **Command Completion**: Tab completion for all scanner commands and options - **Context-Aware**: Different completions based on command context - **Boolean Flags**: Smart completion for `true`/`false` values where applicable - **Alias Support**: Completion works with all plex-related aliases #### Example Tab Completion Usage ```bash # Main plex.sh command completion $ ./plex.sh start stop restart status scan repair nuclear help # Scanner sub-command completion $ ./plex.sh scan list scan refresh analyze generate tree interactive -v --verbose -h --help # Boolean flag completion for refresh and analyze $ ./plex.sh scan refresh 29 true false $ ./plex.sh scan analyze 29 true false # Direct scanner completion $ ./scan-plex-libraries.sh list scan refresh analyze generate tree interactive # Alias completion $ plex-scan list scan refresh analyze generate tree interactive $ plex-scanner list scan refresh analyze generate tree interactive ``` #### Completion Installation Bash completion is automatically installed by the setup scripts: - **Automatic Setup**: Installed by `bootstrap.sh` and `setup.sh` - **Shell Integration**: Sourced in `.zshrc` for immediate availability - **Alias Support**: Works with all plex-related aliases (`plex`, `plex-scan`, `plex-scanner`, etc.) #### Manual Completion Setup If needed, completion can be enabled manually: ```bash # Enable bash completion in zsh autoload -U +X bashcompinit && bashcompinit autoload -U compinit && compinit -u # Source the completion script source /home/acedanger/shell/completions/plex-scripts-completion.bash ``` ## Enhanced Features ### Smart Terminal Detection and Color Output The script includes intelligent terminal detection and color management: - **Automatic Color Detection**: Detects terminal capabilities and adjusts output accordingly - **Environment Variable Support**: Respects `NO_COLOR` environment variable for accessibility - **Porcelain Mode**: `--porcelain` or `-p` provides machine-readable output for automation - **ANSI Escape Handling**: Properly handles color codes when called from other scripts ### System Integration and Automation - **update.sh Integration**: Automatically called during system updates with simple output mode - **Non-Interactive Operation**: Designed to work seamlessly when called from other scripts - **Service Presence Detection**: Gracefully handles systems without Plex installed - **Root User Prevention**: Explicitly prevents running as root for security ### Environment Variables The script supports several environment variables for customization: ```bash # Disable color output entirely NO_COLOR=1 ./plex.sh status # Force porcelain mode for machine-readable output ./plex.sh --porcelain start # Check terminal capabilities TERM=dumb ./plex.sh status # Forces simple output ``` ### Smart Service Management The enhanced script includes intelligent service operations: - **Dependency Validation**: Checks for required services and dependencies before operations - **Safe Stop Operations**: Graceful shutdown with proper wait times and verification - **Intelligent Restart**: Combines stop and start operations with validation between steps - **Service Health Checks**: Comprehensive status validation beyond simple systemctl status ### Progress Indicators and User Experience - **Visual Progress**: Real-time progress indicators for all operations - **Timing Information**: Displays operation duration and timestamps - **Color-coded Output**: Success (green), error (red), warning (yellow), info (blue) - **Clear Status Messages**: Descriptive messages for all operations and their outcomes ### Advanced Status Display The `status` command provides comprehensive information: ```bash ./plex.sh status ``` Shows: - Service status and health - Process information and resource usage - Network port availability (32400/tcp) - Configuration file validation - Recent log entries and error conditions - Performance metrics and uptime information ### Safety and Validation Features - **Pre-operation Checks**: Validates system state before making changes - **Post-operation Verification**: Confirms operations completed successfully - **Configuration Validation**: Checks for common configuration issues - **Network Validation**: Verifies port availability and network configuration - **Recovery Capabilities**: Automatic recovery from common service issues ## Command Line Usage ### Basic Operations ```bash # Start Plex Media Server ./plex.sh start # Stop Plex Media Server ./plex.sh stop # Restart Plex Media Server ./plex.sh restart # Display comprehensive status ./plex.sh status # Launch library scanner ./plex.sh scan ``` ### Available Commands The script supports the following commands: ```bash # Basic service operations ./plex.sh start # Start Plex Media Server ./plex.sh stop # Stop Plex Media Server ./plex.sh restart # Restart Plex Media Server (also accepts 'reload') ./plex.sh status # Show detailed service status (also accepts 'info') ./plex.sh scan # Launch library scanner (NEW) ./plex.sh logs # Display recent Plex Media Server logs ./plex.sh help # Show help message (also accepts '--help' or '-h') # Library scanner operations (NEW) ./plex.sh scan # Interactive scanner mode ./plex.sh scan list # List all library sections ./plex.sh scan scan # Scan all libraries for new media ./plex.sh scan scan 29 # Scan specific library (ID 29) ./plex.sh scan refresh 29 true # Force refresh specific library ./plex.sh scan analyze 29 true # Deep analyze specific library ./plex.sh scan generate 29 # Generate thumbnails for library ./plex.sh scan tree 29 # Show library structure # Logs command with options ./plex.sh logs # Display last 20 lines of Plex logs ./plex.sh logs -n 50 # Display last 50 lines of Plex logs ./plex.sh logs -f # Follow logs in real-time ./plex.sh logs --follow --lines 100 # Follow logs with custom line count # Porcelain mode for machine-readable output ./plex.sh --porcelain start # Machine-readable service output ./plex.sh --porcelain status # Machine-readable status output # Environment variable examples NO_COLOR=1 ./plex.sh status # Disable colors ./plex.sh --porcelain start # Machine-readable output ``` **Note**: The script automatically detects when it's being called from other scripts (like `update.sh`) and adjusts its output accordingly. ### Integration with Other Scripts The `plex.sh` script is designed to work seamlessly with other Plex management scripts and system automation: ```bash # Used by update.sh during system updates (automatic porcelain output) ./update.sh # Automatically calls plex.sh --porcelain stop/start # Used by backup script for safe service management ./backup-plex.sh # Automatically calls plex.sh stop/start # Used by recovery scripts for service control ./recover-plex-database.sh # Uses plex.sh for service management # Library scanner integration with service management ./plex.sh scan scan # Scan all libraries ./plex.sh scan refresh "" true # Force refresh all libraries after service restart # Manual integration with porcelain output ./plex.sh --porcelain start # For use in scripts/automation # Scanner integration in maintenance scripts ./plex.sh scan scan # Regular media scanning ./plex.sh scan analyze # Weekly deep analysis ./plex.sh scan generate # Thumbnail regeneration ``` ### Security and Safety Features - **Root Prevention**: Script refuses to run as root user for security - **Safe Defaults**: Uses conservative settings for service operations - **Error Handling**: Comprehensive error checking and reporting - **Graceful Degradation**: Works on systems without Plex installed ## Detailed Operation Steps ### Start Operation Process 1. **Pre-start Validation** - Check if service is already running - Validate system dependencies - Check port availability (32400/tcp) - Verify configuration files 2. **Service Start** - Execute systemctl start command - Monitor startup progress - Display progress indicators 3. **Post-start Verification** - Confirm service is active - Verify network port is accessible - Check process health - Display success confirmation ### Stop Operation Process 1. **Pre-stop Checks** - Verify service is currently running - Check for active connections - Prepare for graceful shutdown 2. **Graceful Shutdown** - Send stop signal to service - Allow proper shutdown time - Monitor shutdown progress 3. **Verification and Cleanup** - Confirm service has stopped - Verify process termination - Clean up any remaining resources ### Status Operation Details The status command provides comprehensive system information: - **Service Status**: Active/inactive state and health - **Process Information**: PID, memory usage, CPU utilization - **Network Status**: Port availability and connection status - **Configuration**: Validation of key configuration files - **Recent Activity**: Latest log entries and system events - **Performance Metrics**: Uptime, resource usage, response times ### Logs Operation Details The logs command provides flexible log viewing capabilities: ```bash # Basic log viewing (last 20 lines) ./plex.sh logs # Custom line count ./plex.sh logs -n 50 ./plex.sh logs --lines 100 # Real-time log following ./plex.sh logs -f ./plex.sh logs --follow # Combined options ./plex.sh logs --follow --lines 50 ``` **Logs Command Features:** - **Flexible Line Count**: Specify number of log lines to display (default: 20) - **Real-time Following**: Use `-f` or `--follow` to tail logs in real-time - **Systemd Integration**: Uses `journalctl` for reliable log access - **Porcelain Mode Support**: Works with `--porcelain` for script automation - **Error Handling**: Graceful handling when service is not available **Logs Command Options:** - `-n, --lines NUMBER`: Number of log lines to display (default: 20) - `-f, --follow`: Follow logs in real-time (like `tail -f`) - Can be combined with global `--porcelain` option for clean output ## Configuration and Dependencies ### Environment Variable Configuration The script respects several environment variables for customization: - **`NO_COLOR`**: Set to `1` to disable all color output (accessibility compliance) - **`--porcelain`**: Command-line option to force machine-readable output (for automation) - **`TERM`**: Automatically detected; `dumb` terminals get simple output ### System Requirements - **Operating System**: systemd-based Linux distribution - **Permissions**: sudo access for systemctl operations (script prevents running as root) - **Network**: Port 32400/tcp available for Plex communications - **Dependencies**: systemctl, basic shell utilities - **Service**: plexmediaserver.service (gracefully handles absence) ### Configuration Validation The script validates key configuration elements: - **Service Definition**: Ensures plexmediaserver.service is properly configured - **Network Configuration**: Validates port availability and network bindings - **File Permissions**: Checks critical file and directory permissions - **Process Limits**: Verifies system resource limits are appropriate ### Integration Points The script integrates with the broader Plex management ecosystem: - **Backup Operations**: Called by `backup-plex.sh` for safe service management - **Recovery Procedures**: Used by recovery scripts for controlled service restart - **Testing Framework**: Utilized by integration tests for service validation - **Monitoring Systems**: Provides status information for monitoring dashboards ### System Update Integration The script is designed to work seamlessly with system update processes: - **Automatic Integration**: Called by `update.sh` during system updates - **Service Management**: Safely stops Plex before package updates, restarts after completion - **Porcelain Mode**: Uses `--porcelain` for clean, log-friendly output - **Graceful Handling**: Properly handles systems without Plex installed - **Error Prevention**: Prevents interruption of package manager operations Example system update integration: ```bash # In update.sh - automatically stops Plex before updates /home/acedanger/shell/plex/plex.sh --porcelain stop # Package updates occur here... # In update.sh - automatically starts Plex after updates /home/acedanger/shell/plex/plex.sh --porcelain start ``` This integration ensures that Plex databases and processes don't interfere with system package updates while maintaining service availability. ## Error Handling and Troubleshooting ### Common Issues and Solutions 1. **Service Won't Start** - Check configuration files for syntax errors - Verify port 32400 is not in use by another process - Confirm Plex user has necessary permissions - Review system logs for specific error messages 2. **Service Won't Stop** - Check for active media streaming sessions - Verify no stuck processes are preventing shutdown - Use `--force` option for forced termination if necessary - Review process tree for dependent processes 3. **Network Issues** - Confirm firewall settings allow port 32400 - Check network interface configuration - Verify DNS resolution if using remote access - Test local network connectivity ### Debug Mode Enable verbose logging for troubleshooting: ```bash # Run with enhanced debugging ./plex.sh status --debug # Check system integration ./plex.sh start --validate --debug ``` ## Security Considerations ### Access Control - Script requires sudo privileges for systemctl operations - Service runs under dedicated plex user account - Network access restricted to required ports only - Configuration files protected with appropriate permissions ### Best Practices - Regularly update Plex Media Server software - Monitor service logs for security events - Restrict network access to trusted networks - Use strong authentication for remote access - Regularly backup configuration and databases ## Performance Optimization ### Service Tuning The script supports performance optimization through: - **Process Priority**: Adjusts service priority for optimal performance - **Resource Limits**: Configures appropriate memory and CPU limits - **Network Tuning**: Optimizes network buffer sizes and timeouts - **Disk I/O**: Configures efficient disk access patterns ### Monitoring Integration Integrates with monitoring systems: - **Prometheus Metrics**: Exports service metrics for monitoring - **Log Aggregation**: Structured logging for centralized analysis - **Health Checks**: Regular health validation for proactive monitoring - **Performance Tracking**: Resource usage tracking and alerting ## Automation and Scheduling ### Systemd Integration The script works seamlessly with systemd: ```bash # Enable automatic startup sudo systemctl enable plexmediaserver # Check service dependencies systemctl list-dependencies plexmediaserver ``` ### Cron Integration For scheduled operations: ```bash # Weekly service restart for maintenance 0 3 * * 0 /home/acedanger/shell/plex/plex.sh restart --safe # Daily health check 0 6 * * * /home/acedanger/shell/plex/plex.sh status --validate # Automated library scanning (NEW) 0 4 * * * /home/acedanger/shell/plex/plex.sh scan scan # Daily scan for new media 0 2 * * 0 /home/acedanger/shell/plex/plex.sh scan refresh "" true # Weekly metadata refresh 0 1 * * 1 /home/acedanger/shell/plex/plex.sh scan analyze # Weekly media analysis ``` ## Exit Codes and Return Values The script uses standard exit codes for automation: - **0**: Operation completed successfully - **1**: General error or operation failed - **2**: Invalid command line arguments - **3**: Service operation timeout - **4**: Permission denied or insufficient privileges - **5**: Network or connectivity issues - **6**: Configuration validation failed - **7**: Dependency check failed These exit codes enable reliable automation and error handling in larger scripts and systems. ## Important Information ### Prerequisites - Ensure that the script is executable: ```bash 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. ### Script Integration This script is designed to work as part of the broader Plex management ecosystem: - **Backup Integration**: Automatically called by backup scripts for safe service management - **Recovery Integration**: Used by recovery scripts for controlled service operations - **Testing Integration**: Utilized by testing frameworks for service validation - **Monitoring Integration**: Provides status information for monitoring systems ### Compatibility - **Operating Systems**: Tested on Ubuntu 20.04+, Debian 10+, CentOS 8+ - **Plex Versions**: Compatible with Plex Media Server 1.25.0 and later - **Dependencies**: Minimal external dependencies for maximum compatibility - **Architecture**: Supports both x86_64 and ARM64 architectures By following this documentation, you should be able to effectively use the enhanced `plex.sh` script as part of your comprehensive Plex media server management strategy.