Linux-Server-Management-Toolkit/testing/README.md

# Multi-Panel Testing & Validation Guide

## Overview

This directory contains automated validation scripts to test the multi-panel refactoring work on real InterWorx and Plesk servers.

**Status**: All 38 modules have been refactored for multi-panel support (100% complete)

**Supported Panels**:
- ✅ **cPanel** - Fully tested and working (primary platform)
- 🧪 **InterWorx** - Refactored, needs validation
- 🧪 **Plesk** - Refactored, needs validation
- ✅ **Standalone Apache** - Basic support working

---

## Quick Start

### On InterWorx Server:
```bash
# Copy validation script to InterWorx server
scp testing/validate-interworx.sh root@interworx-server:/tmp/

# SSH to server and run
ssh root@interworx-server
chmod +x /tmp/validate-interworx.sh
/tmp/validate-interworx.sh

# Review results
cat /tmp/interworx-validation-results.txt
```

### On Plesk Server:
```bash
# Copy validation script to Plesk server
scp testing/validate-plesk.sh root@plesk-server:/tmp/

# SSH to server and run
ssh root@plesk-server
chmod +x /tmp/validate-plesk.sh
/tmp/validate-plesk.sh

# Review results
cat /tmp/plesk-validation-results.txt
```

---

## What Gets Validated

### InterWorx Validation (`validate-interworx.sh`)

Tests 10 critical areas:

1. **Control Panel Detection**
   - Verifies `/usr/local/interworx` exists
   - Checks InterWorx version
   - Validates installation

2. **File System Structure**
   - Document root: `/home/USER/DOMAIN/html/` ✅ (verified from official docs)
   - Home directories: `/home/USER/`
   - Domain structure detection

3. **Log File Locations**
   - Access logs: `/home/USER/var/DOMAIN/logs/access_log` ✅ (verified)
   - Error logs: `/home/USER/var/DOMAIN/logs/error_log` ✅ (verified)
   - Transfer logs: `/home/USER/var/DOMAIN/logs/transfer.log` ✅ (verified)

4. **Domain → User Mapping**
   - Tests vhost config parsing: `/etc/httpd/conf.d/vhost_*.conf`
   - Validates `ServerName` + `SuexecUserGroup` lookup method

5. **User → Domains Mapping**
   - Method 1: Parse vhost configs for user
   - Method 2: Filesystem discovery
   - Compares both methods

6. **Database Prefix Pattern**
   - **VERIFIED**: Uses `username_` prefix (same as cPanel)
   - Source: https://appendix.interworx.com/current/siteworx/mysql/database-guide.html
   - Tests against real databases

7. **Cron System**
   - Validates standard `crontab -u USER` works
   - Checks `/var/spool/cron` directory

8. **PHP Configuration**
   - Lists available PHP versions
   - Checks PHP-FPM pool configs
   - Tests vhost PHP handler settings

9. **WordPress Detection**
   - Searches for `wp-config.php` files
   - Validates path pattern: `/home/USER/DOMAIN/html/wp-config.php`
   - Tests user/domain extraction from path

10. **InterWorx CLI Tools**
    - Checks for nodeworx/siteworx commands
    - Lists available CLI tools

### Plesk Validation (`validate-plesk.sh`)

Tests 12 critical areas:

1. **Control Panel Detection**
   - Verifies `/usr/local/psa` exists
   - Checks `plesk` command availability
   - Gets Plesk version

2. **File System Structure**
   - Document root: `/var/www/vhosts/DOMAIN/httpdocs/`
   - Domain root: `/var/www/vhosts/DOMAIN/`
   - Directory structure validation

3. **Log File Locations**
   - Access logs: `/var/www/vhosts/system/DOMAIN/logs/access_log`
   - SSL access logs: `/var/www/vhosts/system/DOMAIN/logs/access_ssl_log`
   - Error logs: `/var/www/vhosts/system/DOMAIN/logs/error_log`
   - PHP error logs: `/var/www/vhosts/DOMAIN/httpdocs/error_log`

4. **Plesk bin Commands**
   - Tests `plesk bin subscription` command
   - Lists available commands

5. **Domain → User Mapping**
   - Tests `plesk bin subscription --info DOMAIN`
   - Validates `Owner:` field extraction
   - Checks for alternative `Login:` field

6. **User → Domains Mapping**
   - Tests `plesk bin subscription --list -owner USERNAME`
   - Alternative: filesystem discovery

7. **Database Prefix Pattern**
   - **TO VERIFY**: Appears to use NO PREFIX (bare database names)
   - Tests real database list
   - Checks for prefix patterns

8. **System User for Web Processes**
   - **CRITICAL**: Determines what user runs PHP/Apache
   - Checks PHP-FPM process ownership
   - Tests Apache process user
   - Important for cron job management!

9. **Cron System**
   - Tests standard `crontab -u USER`
   - Checks for `plesk bin cron` (Plesk custom cron)
   - **TO VERIFY**: Which cron system to use?

10. **PHP Configuration**
    - Checks `/opt/plesk/php` directory
    - Lists PHP versions
    - Tests PHP handler per domain

11. **WordPress Detection**
    - Searches for `wp-config.php` files
    - Validates path pattern: `/var/www/vhosts/DOMAIN/httpdocs/wp-config.php`
    - Tests domain/owner extraction

12. **Apache/Web Server Configuration**
    - Checks for nginx (Plesk often uses nginx + Apache)
    - Validates config directories

---

## Validation Results

Each script produces:
- **Color-coded console output** (green=pass, red=fail, yellow=warn)
- **Detailed results file** in `/tmp/`
- **Test summary** with pass/fail/warn counts

### Exit Codes:
- `0` = All critical tests passed
- `1` = Some tests failed (review required)

---

## What to Look For

### ✅ PASS - Good!
- All assumptions verified
- Paths exist and match expected patterns
- Commands work as expected

### ⚠️ WARN - Investigate
- Feature exists but may not be configured yet
- Alternative methods available
- Non-critical differences found

### ✗ FAIL - Action Required
- Assumption is wrong
- Required file/command missing
- Pattern doesn't match expectations
- **Report back to development team!**

---

## Critical Items to Verify

### InterWorx - RESOLVED ✅
- ✅ File paths (verified from official docs)
- ✅ Database prefix pattern (`username_` confirmed)
- ⏳ Domain→User lookup (needs real server test)
- ⏳ User→Domains lookup (needs real server test)

### Plesk - NEEDS VERIFICATION 🧪
- ❓ Database prefix (appears to be NO PREFIX)
- ❓ System user for cron jobs (www-data? apache? per-domain user?)
- ❓ Cron system (standard vs `plesk bin cron`)
- ❓ PHP handler selection per domain
- ⏳ All lookup methods (needs real server test)

---

## After Running Validation

### 1. Review Results File
```bash
# InterWorx
cat /tmp/interworx-validation-results.txt | grep -E "PASS|FAIL|WARN" | sort | uniq -c

# Plesk
cat /tmp/plesk-validation-results.txt | grep -E "PASS|FAIL|WARN" | sort | uniq -c
```

### 2. Report Issues
If you find **FAIL** results:

1. Copy the full results file
2. Note the specific test that failed
3. Check if it's a critical assumption (database prefix, file paths, lookups)
4. Report back with:
   - Panel type and version
   - Failed test name
   - Actual vs expected behavior
   - Full error output

### 3. Test Actual Modules
After validation passes, test real modules:

#### Simple Tests First:
```bash
# Test log discovery
./modules/security/tail-apache-access.sh

# Test traffic monitoring
./modules/security/web-traffic-monitor.sh

# Test error analysis
./modules/website/website-error-analyzer.sh
```

#### Complex Tests:
```bash
# Test WordPress cron (most complex)
./modules/website/wordpress/wordpress-cron-manager.sh --list

# Test 500 error tracking
./modules/website/500-error-tracker.sh
```

---

## Testing Priority

### Phase 1: Validation Scripts ⏳
Run `validate-interworx.sh` and `validate-plesk.sh` on real servers

**Goal**: Verify all file paths, commands, and lookup methods work

### Phase 2: Simple Module Testing
Test Class B modules (system detection only):
- `tail-apache-access.sh`
- `tail-apache-error.sh`
- `web-traffic-monitor.sh`

**Goal**: Verify SYS_LOG_DIR detection and log discovery works

### Phase 3: Complex Module Testing
Test Class C modules (user/domain management):
- `website-error-analyzer.sh`
- `500-error-tracker.sh`
- `wordpress-cron-manager.sh` (most complex!)

**Goal**: Verify all lookup methods and multi-panel logic works

### Phase 4: Production Readiness
- Fix any issues found
- Update documentation
- Add any missing edge cases
- Performance testing

---

## Known Issues & Limitations

### InterWorx
- Database prefix pattern was documented incorrectly (now fixed)
- All other assumptions verified from official documentation
- Needs real server testing to confirm

### Plesk
- Database prefix pattern unclear (appears to be NO PREFIX)
- System user for cron jobs unknown (affects wordpress-cron-manager.sh)
- May use custom cron system (`plesk bin cron`)
- All assumptions need real server verification

### All Panels
- Scripts assume bash 4.0+
- Some features are cPanel-only (clearly marked with panel checks)
- Acronis backup modules have not been tested on non-cPanel systems

---

## Next Steps

1. **Get access to test servers**
   - InterWorx test server
   - Plesk test server (both RHEL and Debian-based)

2. **Run validation scripts**
   - Execute both validators
   - Collect results
   - Document any failures

3. **Fix issues found**
   - Update code if assumptions are wrong
   - Adjust case statements as needed
   - Update REFDB_FORMAT.txt documentation

4. **Test real modules**
   - Start with simple scripts
   - Progress to complex scripts
   - Test edge cases

5. **Update documentation**
   - Document verified behaviors
   - Add platform-specific notes
   - Update testing requirements

---

## Contact

For questions or to report validation results, contact the development team with:
- Full validation results file
- Panel type and version
- Any errors or unexpected behavior
- Suggestions for improvements

---

**Last Updated**: 2025-11-20
**Refactoring Status**: 100% complete (38/38 modules)
**Validation Status**: Scripts ready, awaiting test server access