From 74467bc49e01c517580c6945bf11fb9d9f947c3e Mon Sep 17 00:00:00 2001 From: Developer Date: Fri, 20 Mar 2026 01:45:02 -0400 Subject: [PATCH] Add comprehensive detection troubleshooting guide DOCUMENTATION: - DETECTION_TROUBLESHOOTING.md: Complete troubleshooting guide - How detection works step-by-step - Common issues on AlmaLinux, CentOS, Ubuntu, Debian - OS-specific solutions and file paths - Diagnostic commands and usage examples COVERS: - Quick start: How to check what was detected - Specific issues: Apache, MySQL, Nginx, Firewall not detected - Silent detection problems (cache-related) - Advanced debugging and manual testing - How to report detection issues QUICK REFERENCE: bash launcher.sh --detect-only # Check what was detected bash test-detection.sh # Full diagnostic bash test-detection.sh verbose # Detailed diagnostic --- DETECTION_TROUBLESHOOTING.md | 354 +++++++++++++++++++++++++++++++++++ 1 file changed, 354 insertions(+) create mode 100644 DETECTION_TROUBLESHOOTING.md diff --git a/DETECTION_TROUBLESHOOTING.md b/DETECTION_TROUBLESHOOTING.md new file mode 100644 index 0000000..6e2e8f4 --- /dev/null +++ b/DETECTION_TROUBLESHOOTING.md @@ -0,0 +1,354 @@ +# System Detection Troubleshooting Guide + +## Overview + +The Server Toolkit automatically detects your system configuration on startup: +- Operating System (CentOS, AlmaLinux, Rocky Linux, Ubuntu, Debian, etc.) +- Control Panel (cPanel, Plesk, InterWorx, or Standalone) +- Web Server (Apache/httpd, Nginx, LiteSpeed, etc.) +- Database (MySQL, MariaDB, PostgreSQL) +- Firewall (CSF, firewalld, iptables, UFW) +- PHP versions available on system + +If you're not seeing these detected correctly, use these diagnostic tools. + +--- + +## Quick Start: Test Detection + +### Option 1: Check What Was Detected (Fastest) + +```bash +bash launcher.sh --detect-only +``` + +This shows your current system configuration in a clean format: +``` +Control Panel: cpanel 11.134.0.11 +Operating System: almalinux 9.7 +Web Server: apache 2.4.66 +Database: mariadb 10.6.25 +Firewall: csf 16.12 (no) +PHP Versions: 8.0.30 8.1.34 8.2.30 +``` + +### Option 2: Run Full Diagnostic (More Detailed) + +```bash +bash test-detection.sh +``` + +This performs step-by-step testing: +- [STEP 1] Tests if commands exist on system +- [STEP 2] Attempts version detection for each service +- [STEP 3] Tests control panel detection +- [STEP 4] Tests OS detection +- [STEP 5] Tests firewall detection +- [STEP 6] Runs full system detection +- [STEP 7] Displays detected variables +- [STEP 8] Summary with warnings + +### Option 3: Verbose Diagnostic (Maximum Detail) + +```bash +bash test-detection.sh verbose +``` + +Same as above, but also shows file paths and exact locations where services were found. + +--- + +## Specific Issues & Solutions + +### Issue: Apache/httpd Not Detected + +**Test:** +```bash +which httpd +httpd -v +``` + +**If httpd is not found:** +- Apache/httpd may not be installed +- Check: `yum list installed | grep httpd` (RHEL/CentOS/AlmaLinux) +- Check: `apt list --installed | grep apache2` (Ubuntu/Debian) + +**If httpd exists but not detected:** +1. Run diagnostic: `bash test-detection.sh` +2. Check STEP 1 output for "✓ Apache (httpd)" +3. If found but not detected in STEP 6, report the issue + +**On AlmaLinux/Rocky (IMPORTANT):** +- AlmaLinux uses `httpd` (not `apache2` like Debian) +- Toolkit checks for BOTH, so this should work +- If still not working, verify: `command -v httpd` + +--- + +### Issue: MySQL/MariaDB Not Detected + +**Test:** +```bash +which mysql +mysql --version +``` + +**If mysql is not found:** +- MySQL/MariaDB may not be installed +- Check: `yum list installed | grep -i mysql` (RHEL-based) +- Check: `apt list --installed | grep mysql` (Debian-based) + +**If mysql exists but not detected:** +1. Run: `bash test-detection.sh verbose` +2. Check STEP 2 "MySQL/MariaDB Version Detection" output +3. Verify output of: `mysql --version` +4. If command works but detection fails, report issue + +--- + +### Issue: Nginx/Apache Both Missing + +**On Standalone Servers:** +- Web server MUST be installed for most toolkit features +- Install Apache: `yum install httpd` or `apt install apache2` +- Install Nginx: `yum install nginx` or `apt install nginx` + +**Verify installation:** +```bash +bash launcher.sh --detect-only +``` + +--- + +### Issue: Firewall Not Detected + +**Possible causes:** +1. No firewall installed (acceptable on standalone) +2. Firewall installed but toolkit doesn't detect it yet + +**Check available firewalls:** +```bash +# CSF (ConfigServer Firewall) +[ -f /etc/csf/csf.conf ] && echo "CSF found" || echo "CSF not found" + +# firewalld +command -v firewall-cmd && echo "firewalld found" || echo "firewalld not found" + +# iptables +command -v iptables && echo "iptables found" || echo "iptables not found" + +# UFW (Ubuntu) +command -v ufw && echo "UFW found" || echo "UFW not found" +``` + +--- + +### Issue: Control Panel Not Detected on Standalone + +**This is NORMAL** - standalone servers have no control panel. + +Expected output: +``` +Control Panel: none +``` + +The toolkit should still work fine with: +- `SYS_LOG_DIR="/var/log/apache2"` (or `/var/log/httpd`) +- `SYS_USER_HOME_BASE="/home"` + +--- + +### Issue: OS Not Detected + +**Test:** +```bash +cat /etc/os-release +# or +cat /etc/redhat-release +``` + +**Supported OSes:** +- ✅ CentOS 7, 8, 9 +- ✅ AlmaLinux 8, 9 +- ✅ Rocky Linux 8, 9 +- ✅ CloudLinux 7, 8, 9 +- ✅ Ubuntu 20.04, 22.04, 24.04 +- ✅ Debian 11, 12 + +If your OS isn't showing, it may not be in the detection list. + +--- + +## How Detection Works + +### Detection Sequence + +1. **Common Functions Loaded** (`lib/common-functions.sh`) + - Defines helper functions like `command_exists` + - Defines print functions for output + +2. **System Detect Library Loaded** (`lib/system-detect.sh`) + - Detects control panel (`/usr/local/cpanel/version`, etc.) + - Detects OS (`/etc/os-release`) + - Detects web server (checks for `httpd`, `apache2`, `nginx`, etc.) + - Detects database (`mysql --version`) + - Detects PHP versions + - Detects firewall (CSF, firewalld, iptables, UFW) + +3. **Variables Set** + - `SYS_CONTROL_PANEL`: cpanel, plesk, interworx, or none + - `SYS_OS_TYPE`: almalinux, ubuntu, etc. + - `SYS_WEB_SERVER`: apache, nginx, litespeed, or unknown + - `SYS_DB_TYPE`: mysql, mariadb, postgresql, or none + - `SYS_FIREWALL`: csf, firewalld, iptables, ufw, or none + - `SYS_PHP_VERSIONS`: Array of detected PHP versions + - `SYS_DETECTION_COMPLETE`: Set to "yes" when done + +4. **Detection Cached** + - Results cached in `.sysref.beta` + - Cache expires after 1 hour + - Cache prevents re-detection on subsequent runs + - Force refresh with: `bash launcher.sh --detect-only` + +--- + +## Silent Detection Issues + +### Why You Might Not See Detection Output + +**Issue:** You run the toolkit, but don't see what was detected. + +**Cause:** Detection output only shows when cache needs rebuilding (first run or after 1 hour). + +**Solution:** Use diagnostic tools: +```bash +# See what WAS detected (even if cache is fresh) +bash launcher.sh --detect-only + +# Run full diagnostic +bash test-detection.sh +``` + +--- + +## Debugging Tips + +### Enable Verbose Output + +Run diagnostic with `verbose` flag: +```bash +bash test-detection.sh verbose +``` + +Shows: +- Exact file paths where services found +- Version command outputs +- All detection attempts + +### Check Individual Services + +Test command availability: +```bash +bash -c 'source lib/common-functions.sh; command_exists httpd && echo "httpd found" || echo "httpd NOT found"' +``` + +### Manual Detection Testing + +```bash +# Load detection library +source lib/system-detect.sh + +# Run individual detections +detect_control_panel +detect_os +detect_web_server +detect_database +detect_firewall + +# Check results +echo "Web Server: $SYS_WEB_SERVER" +echo "Database: $SYS_DB_TYPE" +echo "Firewall: $SYS_FIREWALL" +``` + +--- + +## Common Issues on Specific OSes + +### AlmaLinux / Rocky Linux + +**Apache Binary Name:** +- Uses `httpd` (not `apache2`) +- Toolkit checks for BOTH, so should work +- Verify: `which httpd` + +**MySQL/MariaDB:** +- Usually comes pre-installed +- Check: `rpm -qa | grep -i mariadb` + +**File Paths:** +- Logs: `/var/log/apache2/domlogs` (cPanel) or `/var/log/httpd/` +- Apache config: `/etc/httpd/conf/` + +### Ubuntu / Debian + +**Apache Binary Name:** +- Uses `apache2` (not `httpd`) +- Toolkit checks for BOTH, so should work +- Verify: `which apache2` + +**MySQL/MariaDB:** +- Usually comes pre-installed +- Check: `dpkg -l | grep -i mysql` + +**File Paths:** +- Logs: `/var/log/apache2/` +- MySQL socket: `/var/run/mysqld/mysqld.sock` (not `/var/lib/mysql/mysql.sock`) + +--- + +## Advanced: Clear Cache and Force Re-detection + +If detection seems stuck with old values: + +```bash +# Method 1: Use diagnostic tool (forces fresh detection) +bash launcher.sh --detect-only + +# Method 2: Manually clear cache and run launcher +rm -f .sysref.beta .sysref.beta.timestamp +bash launcher.sh +``` + +--- + +## Report a Detection Issue + +If detection still fails after trying these steps: + +1. Run full diagnostic: + ```bash + bash test-detection.sh verbose > /tmp/detection-report.txt 2>&1 + cat /tmp/detection-report.txt + ``` + +2. Include output showing: + - Which services exist but aren't detected + - What commands work manually but fail in detection + - Your OS type and version + +--- + +## Summary + +| Command | When to Use | +|---------|------------| +| `bash launcher.sh --detect-only` | Quick check of detected config | +| `bash test-detection.sh` | Full diagnostic with step-by-step testing | +| `bash test-detection.sh verbose` | Detailed diagnostic with paths and outputs | +| `rm -f .sysref.beta*; bash launcher.sh` | Force fresh detection and rebuild cache | + +--- + +**Last Updated:** 2026-03-20 +**Tested On:** AlmaLinux 9.7, CentOS 9, Ubuntu 22.04