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