Linux-Server-Management-Toolkit/DETECTION_TROUBLESHOOTING.md

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 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 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 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:

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:

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 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:

# 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:

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:

# 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 test-detection.sh verbose

Shows:

• Exact file paths where services found
• Version command outputs
• All detection attempts

Check Individual Services

Test command availability:

bash -c 'source lib/common-functions.sh; command_exists httpd && echo "httpd found" || echo "httpd NOT found"'

Manual Detection Testing

# 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:

# 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 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