ARCHITECTURE: Multi-Control-Panel Design Standards

Created comprehensive architecture and quick reference documentation. NEW DOCUMENTS: 1. MULTI_CONTROL_PANEL_ARCHITECTURE.md (6500+ words) Defines MANDATORY patterns for all future development: - Core principles (never hardcode, use abstractions, conditionals) - Standard library usage (system-detect.sh, user-manager.sh) - Path mapping reference (all panels) - Standard code patterns (log discovery, docroot, domain→user) - Module classification (A/B/C/D) - Testing requirements - Code review checklist - Migration guide - Common mistakes to avoid Every developer must follow these patterns! 2. CONTROL_PANEL_QUICK_REFERENCE.md (8000+ words) Fast lookup while coding: - Panel detection methods - Complete file system path mappings - Configuration file locations - CLI tools & API commands - Database prefix patterns (CRITICAL for InterWorx!) - PHP configuration per panel - Email, FTP, security features - WordPress detection patterns - Process ownership - Code snippets for common tasks - Panel-specific quirks/gotchas - Migration implications Covers: cPanel, Plesk, InterWorx, Standalone PURPOSE: These documents establish a STANDARD ARCHITECTURE before completing InterWorx support. All modules will be refactored to follow these patterns, making it trivial to add DirectAdmin, CyberPanel, etc. KEY PATTERNS ESTABLISHED: - Never hardcode paths → use SYS_LOG_DIR, get_user_info() - Wrap API calls → check SYS_CONTROL_PANEL first - Design for extension → case statements for panels - Test on all platforms → cPanel regression required MODULE CLASSIFICATION: - Class A: Panel agnostic (no special handling) - Class B: Needs system detection (SYS_LOG_DIR) - Class C: Needs user/domain management (get_user_info) - Class D: Panel-specific (document limitations) CRITICAL GOTCHAS DOCUMENTED: - InterWorx database prefix uses DOMAIN not USERNAME! - Plesk has no shared hosting (domain-centric) - cPanel addon domains share public_html - InterWorx logs are per-domain in user home NEXT STEPS: 1. Update existing modules to follow patterns 2. Complete InterWorx support systematically 3. Expand Plesk support 4. Add DirectAdmin/CyberPanel This is the foundation for true multi-panel architecture!
2025-11-19 19:52:16 -05:00
parent 9b4a6ec5e1
commit 052a311907
2 changed files with 1032 additions and 0 deletions
@@ -0,0 +1,495 @@
+# Control Panel Quick Reference Guide
+**Version:** 1.0
+**Purpose:** Fast lookup of control panel differences while coding
+
+---
+
+## Quick Panel Detection
+
+```bash
+# cPanel
+[ -f "/usr/local/cpanel/version" ]                    # Version file
+[ -f "/etc/userdatadomains" ]                          # User/domain mapping
+command -v whmapi1                                     # WHM API
+
+# Plesk
+[ -f "/usr/local/psa/version" ]                        # Version file
+command -v plesk                                       # Plesk CLI
+
+# InterWorx
+[ -d "/usr/local/interworx" ]                          # Install directory
+[ -f "/etc/interworx/iworx.ini" ]                      # Config file
+[ -x "/usr/local/interworx/bin/listaccounts.pex" ]    # CLI tool
+```
+
+---
+
+## File System Paths
+
+### User Home Directories
+| Panel | Path | Notes |
+|-------|------|-------|
+| **cPanel** | `/home/username` | Standard Linux |
+| **Plesk** | `/var/www/vhosts/domain.com` | Domain-centric |
+| **InterWorx** | `/home/username` | Standard Linux |
+
+### Document Roots
+| Panel | Primary Site | Addon Domain | Subdomain |
+|-------|-------------|--------------|-----------|
+| **cPanel** | `/home/user/public_html` | `/home/user/public_html/addon` | `/home/user/public_html/sub` |
+| **Plesk** | `/var/www/vhosts/domain/httpdocs` | N/A (separate subscription) | `/var/www/vhosts/domain/sub.domain/httpdocs` |
+| **InterWorx** | `/home/user/domain.com/html` | `/home/user/addon.com/html` | `/home/user/domain.com/sub/html` |
+
+### Access Logs
+| Panel | Location | Filename Pattern |
+|-------|----------|------------------|
+| **cPanel** | `/var/log/apache2/domlogs/` or `/usr/local/apache/domlogs/` | `domain.com`, `domain.com-ssl_log` |
+| **Plesk** | `/var/www/vhosts/system/domain.com/logs/` | `access_log`, `access_ssl_log` |
+| **InterWorx** | `/home/user/var/domain.com/logs/` | `access_log` (combined HTTP+HTTPS) |
+
+### Error Logs
+| Panel | Location | Notes |
+|-------|----------|-------|
+| **cPanel** | `/var/log/apache2/domlogs/domain-error_log` | Centralized per-domain |
+| **Plesk** | `/var/www/vhosts/system/domain.com/logs/error_log` | Per-domain |
+| **InterWorx** | `/home/user/var/domain.com/logs/error_log` | Per-domain in user home |
+
+### PHP Error Logs
+| Panel | Location | Notes |
+|-------|----------|-------|
+| **cPanel** | `/home/user/public_html/error_log` | In document root |
+| **Plesk** | `/var/www/vhosts/domain/httpdocs/error_log` | In document root |
+| **InterWorx** | `/home/user/domain.com/html/error_log` | In document root |
+
+### SSL Certificates
+| Panel | Location | Format |
+|-------|----------|--------|
+| **cPanel** | `/etc/letsencrypt/live/domain.com/` or `/var/cpanel/ssl/` | Let's Encrypt or AutoSSL |
+| **Plesk** | `/etc/letsencrypt/live/domain.com/` | Let's Encrypt |
+| **InterWorx** | `/etc/letsencrypt/live/domain.com/` | Let's Encrypt |
+
+### Mail Directories
+| Panel | Location | Structure |
+|-------|----------|-----------|
+| **cPanel** | `/home/user/mail/domain.com/account/` | Per-domain folders |
+| **Plesk** | `/var/qmail/mailnames/domain.com/account/` | Qmail structure |
+| **InterWorx** | `/home/user/var/domain.com/mail/account/` | Per-domain in user home |
+
+### Cron Jobs
+| Panel | Location | Format |
+|-------|----------|--------|
+| **cPanel** | `/var/spool/cron/username` | Standard crontab |
+| **Plesk** | `/var/spool/cron/username` | Standard crontab |
+| **InterWorx** | `/var/spool/cron/username` | Standard crontab |
+
+---
+
+## Configuration Files
+
+### User Configuration
+| Panel | Location | Format | Contains |
+|-------|----------|--------|----------|
+| **cPanel** | `/var/cpanel/users/username` | Key-value | DNS, IP, disk quota, domains |
+| **Plesk** | Plesk Database | SQL | All config in MySQL/PostgreSQL |
+| **InterWorx** | NodeWorx Database + vhost configs | Mixed | listaccounts.pex CLI or DB queries |
+
+### Domain Configuration
+| Panel | Location | Format | Contains |
+|-------|----------|--------|----------|
+| **cPanel** | `/var/cpanel/userdata/user/domain.com` | Apache-like | DocumentRoot, ServerAlias, PHP handlers |
+| **Plesk** | Plesk Database | SQL | Vhost config in database |
+| **InterWorx** | `/etc/httpd/conf.d/vhost_domain.com.conf` | Apache vhost | Auto-generated from templates |
+
+### Apache Main Config
+| Panel | Include Location | How Domains Added |
+|-------|------------------|-------------------|
+| **cPanel** | `/etc/apache2/conf.d/includes/` | Auto-generated from userdata |
+| **Plesk** | `/etc/httpd/conf.d/zz*.conf` | Generated from Plesk DB |
+| **InterWorx** | `/etc/httpd/conf.d/vhost_*.conf` | One file per domain |
+
+---
+
+## Database Management
+
+### Database Prefixes
+| Panel | Prefix Pattern | Example | Max Prefix Length |
+|-------|----------------|---------|-------------------|
+| **cPanel** | `username_` | `johndoe_wordpress` | 16 chars total (7 for username + _ + 8 for dbname) |
+| **Plesk** | None (user-scoped) | `wordpress` | No prefix |
+| **InterWorx** | `first8charsOfDomain_` | `examplec_wordpress` | First 8 chars of domain (dots removed) |
+
+### MySQL User Prefixes
+| Panel | User Pattern | Example | Notes |
+|-------|--------------|---------|-------|
+| **cPanel** | `username_` | `johndoe_wpuser` | Same as database prefix |
+| **Plesk** | None | `wpuser` | Scoped to database |
+| **InterWorx** | `first8charsOfDomain_` | `examplec_wpuser` | Same as database prefix |
+
+### Database File Locations
+| Panel | Data Directory | Notes |
+|-------|----------------|-------|
+| **cPanel** | `/var/lib/mysql/` | Standard MySQL |
+| **Plesk** | `/var/lib/mysql/` | Standard MySQL |
+| **InterWorx** | `/var/lib/mysql/` | Standard MySQL |
+
+---
+
+## CLI Tools & APIs
+
+### WHM/Root Level APIs
+| Panel | Tool | Example Command | Auth Required |
+|-------|------|-----------------|---------------|
+| **cPanel** | `whmapi1` | `whmapi1 listaccts` | Root or API token |
+| **Plesk** | `plesk bin server` | `plesk bin server --info` | Root |
+| **InterWorx** | `nodeworx` | `nodeworx -u -n -c Siteworx -a listAccounts` | Root + setup |
+
+### User-Level APIs
+| Panel | Tool | Example Command | Auth Required |
+|-------|------|-----------------|---------------|
+| **cPanel** | `uapi` | `uapi --user=john DomainInfo list_domains` | User or API token |
+| **Plesk** | `plesk bin subscription` | `plesk bin subscription --list` | Root |
+| **InterWorx** | `siteworx` | `siteworx -u -n -c Siteworx -a listDomains` | User + setup |
+
+### Account Listing
+| Panel | Command | Output Format |
+|-------|---------|---------------|
+| **cPanel** | `whmapi1 listaccts` | JSON |
+| **cPanel** | `/etc/trueuserdomains` | Text: `domain.com: username` |
+| **cPanel** | `/etc/userdatadomains` | Text: `domain: user==owner==main==domain==docroot` |
+| **Plesk** | `plesk bin subscription --list` | Text list of domains |
+| **InterWorx** | `/usr/local/interworx/bin/listaccounts.pex` | Text: `username domain.com` |
+
+### Domain Listing (for specific user)
+| Panel | Command | Output |
+|-------|---------|--------|
+| **cPanel** | `grep "^DNS" /var/cpanel/users/$user` | DNS records from user file |
+| **cPanel** | `grep ":${user}==" /etc/userdatadomains` | All domains for user |
+| **Plesk** | `plesk bin subscription --list` | All subscriptions (filter by owner) |
+| **InterWorx** | `listaccounts.pex` then parse vhosts | Username + primary domain |
+
+### Database Listing
+| Panel | Command | Notes |
+|-------|---------|-------|
+| **cPanel** | `mysql -e "SHOW DATABASES" \| grep "^${username}_"` | Filter by prefix |
+| **Plesk** | `plesk bin database --list` | All databases (filter by domain) |
+| **InterWorx** | `mysql -e "SHOW DATABASES" \| grep "^${domain_prefix}_"` | **Use domain prefix!** |
+
+---
+
+## PHP Configuration
+
+### PHP Handler Types
+| Panel | Handlers Supported | Default | Location |
+|-------|-------------------|---------|----------|
+| **cPanel** | DSO, suPHP, FastCGI, FPM | EasyApache 4 FPM | `/opt/cpanel/ea-php*/` |
+| **Plesk** | Apache module, FPM, FastCGI | FPM | `/opt/plesk/php/*/` |
+| **InterWorx** | mod_php, FPM, FastCGI | FPM | `/etc/php-fpm.d/` |
+
+### PHP.INI Locations
+| Panel | Global | Per-Domain | Per-Directory |
+|-------|--------|------------|---------------|
+| **cPanel** | `/opt/cpanel/ea-php*/root/etc/php.ini` | `/home/user/.php.ini` | `/home/user/public_html/.user.ini` |
+| **Plesk** | `/etc/php.ini` | `/var/www/vhosts/system/domain/conf/php.ini` | `.user.ini` in directory |
+| **InterWorx** | `/etc/php.ini` | `/home/user/domain/conf/php.ini` | `.user.ini` in directory |
+
+### PHP Version Selection
+| Panel | Mechanism | Granularity |
+|-------|-----------|-------------|
+| **cPanel** | MultiPHP Manager (WHM) or `.htaccess` | Per-domain or per-directory |
+| **Plesk** | Plesk Panel or plesk CLI | Per-domain or per-subdirectory |
+| **InterWorx** | SiteWorx Panel or php-fpm pools | Per-domain |
+
+---
+
+## Email Configuration
+
+### Mail Server Software
+| Panel | MTA | POP3/IMAP | Webmail |
+|-------|-----|-----------|---------|
+| **cPanel** | Exim | Dovecot | Horde, RoundCube, SquirrelMail |
+| **Plesk** | Postfix or Qmail | Dovecot or Courier | RoundCube, Horde |
+| **InterWorx** | Postfix | Dovecot | RoundCube, SquirrelMail |
+
+### Email Account Locations
+| Panel | Config Location | Password Storage |
+|-------|-----------------|------------------|
+| **cPanel** | `/home/user/etc/domain/passwd` | Shadow file in etc/ |
+| **Plesk** | Plesk Database | Database |
+| **InterWorx** | `/home/user/var/domain/mail/` | Database + files |
+
+---
+
+## FTP Configuration
+
+### FTP Server
+| Panel | FTP Daemon | Config Location |
+|-------|------------|-----------------|
+| **cPanel** | Pure-FTPd or ProFTPD | `/etc/pure-ftpd.conf` or `/etc/proftpd.conf` |
+| **Plesk** | ProFTPD | `/etc/proftpd.conf` |
+| **InterWorx** | ProFTPD | `/etc/proftpd.conf` |
+
+### FTP Account Listing
+| Panel | Location | Format |
+|-------|----------|--------|
+| **cPanel** | `/etc/proftpd/$user` or Pure-FTPd DB | Config files or virtual users |
+| **Plesk** | Plesk Database | SQL |
+| **InterWorx** | `/etc/proftpd.conf` includes | Parsed from config |
+
+---
+
+## Security Features
+
+### Brute Force Protection
+| Panel | Feature | How it Works | CLI Access |
+|-------|---------|--------------|------------|
+| **cPanel** | cPHulk | Tracks failed logins, bans IPs | `whmapi1 cphulkd_*` |
+| **Plesk** | fail2ban | Monitors logs, uses iptables | `fail2ban-client` |
+| **InterWorx** | ModSecurity + fail2ban | WAF + log monitoring | `fail2ban-client` |
+
+### Firewall Integration
+| Panel | Default Firewall | Location |
+|-------|-----------------|----------|
+| **cPanel** | CSF (optional) or firewalld | `/etc/csf/` or `firewall-cmd` |
+| **Plesk** | firewalld or iptables | `firewall-cmd` or `/etc/sysconfig/iptables` |
+| **InterWorx** | firewalld or iptables | `firewall-cmd` or `/etc/sysconfig/iptables` |
+
+### ModSecurity
+| Panel | Enabled by Default | Config Location |
+|-------|-------------------|-----------------|
+| **cPanel** | Optional (EasyApache 4) | `/etc/apache2/conf.d/modsec/` |
+| **Plesk** | Optional (Extensions) | `/etc/httpd/conf.d/mod_security.conf` |
+| **InterWorx** | Optional | `/etc/httpd/conf.d/mod_security.conf` |
+
+---
+
+## Backup Systems
+
+### Native Backup Tools
+| Panel | Tool | Backup Location | Incremental Support |
+|-------|------|-----------------|---------------------|
+| **cPanel** | cPanel Backup | `/backup/` | Yes (JetBackup addon) |
+| **Plesk** | Plesk Backup Manager | `/var/lib/psa/dumps/` | No (full only) |
+| **InterWorx** | NodeWorx Backup | `/backup/` or custom | Yes |
+
+### Backup File Format
+| Panel | Format | Compression | Includes |
+|-------|--------|-------------|----------|
+| **cPanel** | tar.gz | gzip | Home dir, DBs, email, config |
+| **Plesk** | tar | Optional gzip | Subscription data, DBs, mail |
+| **InterWorx** | tar.gz | gzip | SiteWorx account, DBs, email |
+
+---
+
+## WordPress Detection
+
+### wp-config.php Locations
+```bash
+# cPanel
+find /home/*/public_html -name "wp-config.php"
+find /home/*/public_html/* -name "wp-config.php"  # Addon domains
+
+# Plesk
+find /var/www/vhosts/*/httpdocs -name "wp-config.php"
+
+# InterWorx
+find /home/*/*/html -name "wp-config.php"
+```
+
+### WordPress Paths by Panel
+| Panel | Single Site | Multisite | Addon Domain WP |
+|-------|------------|-----------|-----------------|
+| **cPanel** | `/home/user/public_html/` | `/home/user/public_html/wp/` | `/home/user/public_html/addon/` |
+| **Plesk** | `/var/www/vhosts/domain/httpdocs/` | `/var/www/vhosts/domain/httpdocs/wp/` | N/A (separate subscription) |
+| **InterWorx** | `/home/user/domain.com/html/` | `/home/user/domain.com/html/wp/` | `/home/user/addon.com/html/` |
+
+---
+
+## Common File Patterns
+
+### .htaccess Locations
+```bash
+# All panels - in document root
+/home/user/public_html/.htaccess          # cPanel primary
+/home/user/domain.com/html/.htaccess      # InterWorx
+/var/www/vhosts/domain/httpdocs/.htaccess # Plesk
+```
+
+### robots.txt Locations
+```bash
+# Same as .htaccess
+# In document root
+```
+
+### Log Rotation
+| Panel | Rotation Config | Default Retention |
+|-------|----------------|-------------------|
+| **cPanel** | `/etc/logrotate.d/cpanel` | 30 days |
+| **Plesk** | `/etc/logrotate.d/plesk` | Varies |
+| **InterWorx** | `/etc/logrotate.d/interworx` | 30 days |
+
+---
+
+## Process Ownership
+
+### Apache/Web Server Processes
+| Panel | User | Group | Notes |
+|-------|------|-------|-------|
+| **cPanel** | `nobody` (main) | `nobody` | Requests run as user via suEXEC/suPHP/FPM |
+| **Plesk** | `apache` or `www-data` | `apache` or `www-data` | Depends on OS |
+| **InterWorx** | `apache` | `apache` | Requests run as user via suEXEC/FPM |
+
+### PHP-FPM Pools
+| Panel | Pool Config | User/Group |
+|-------|-------------|------------|
+| **cPanel** | `/opt/cpanel/ea-php*/root/etc/php-fpm.d/` | Per-user pools (username:username) |
+| **Plesk** | `/etc/php-fpm.d/` | Per-domain pools |
+| **InterWorx** | `/etc/php-fpm.d/` | Per-domain pools (username:username) |
+
+---
+
+## Quick Code Snippets
+
+### Get All Users
+```bash
+# cPanel
+cat /etc/trueuserowners | cut -d: -f2 | sort -u
+
+# Plesk
+plesk bin subscription --list | awk '{print $1}'
+
+# InterWorx
+/usr/local/interworx/bin/listaccounts.pex --output user
+```
+
+### Get Domains for User
+```bash
+# cPanel
+grep "^DNS" /var/cpanel/users/$user | awk '{print $2}'
+
+# Plesk
+plesk bin subscription --list -o $user
+
+# InterWorx
+grep -l "SuexecUserGroup ${user}" /etc/httpd/conf.d/vhost_*.conf | \
+    sed 's|.*/vhost_||; s|\.conf$||'
+```
+
+### Get Disk Usage for User
+```bash
+# All panels (if user has /home directory)
+du -sh /home/$user
+
+# cPanel (from quota)
+quota -u $user | tail -1 | awk '{print $2}'
+
+# Plesk
+plesk bin subscription --info domain.com | grep "Disk space used"
+```
+
+### Check if Domain Exists
+```bash
+# cPanel
+grep -q "^${domain}:" /etc/userdatadomains
+
+# Plesk
+plesk bin subscription --info "$domain" &>/dev/null
+
+# InterWorx
+[ -f "/etc/httpd/conf.d/vhost_${domain}.conf" ]
+```
+
+---
+
+## Panel-Specific Quirks
+
+### cPanel Gotchas
+- **Addon domains** share public_html with primary domain
+- **Parked domains** are aliases (same document root as primary)
+- **Database names** limited to 64 chars (including prefix!)
+- **User passwords** != database passwords != FTP passwords
+- **Main IP** stored in `/var/cpanel/mainip`
+
+### Plesk Gotchas
+- **Each domain** is a separate subscription (even for same owner)
+- **No shared hosting** structure (each domain isolated)
+- **Database prefixes** don't exist (databases scoped to subscription)
+- **Mail users** are separate from system users
+- **CLI requires** lots of `--info` calls (no simple config files)
+
+### InterWorx Gotchas
+- **Database prefix** is domain-based, NOT username-based!
+- **Logs are per-domain** in user home (not centralized)
+- **No separate** HTTP/HTTPS logs (combined in access_log)
+- **Domain config** is one vhost file per domain
+- **Listaccounts.pex** only returns username + primary domain (not addon domains)
+
+---
+
+## Migration Implications
+
+### cPanel → InterWorx
+- ✅ User home structure similar
+- ⚠️ Document root changes (public_html → domain.com/html)
+- ⚠️ Database prefixes change (username_ → domain_)
+- ⚠️ Log locations move to user home
+- ✅ Email structure compatible with migration
+
+### cPanel → Plesk
+- ❌ Completely different structure
+- ❌ Domain-centric vs user-centric
+- ❌ No shared hosting model
+- ❌ Requires full account restructure
+
+### Plesk → InterWorx
+- ⚠️ Structure change (vhosts → home)
+- ⚠️ Database prefix added
+- ✅ Can map subscriptions to users
+- ⚠️ Mail system different
+
+---
+
+## Testing Commands
+
+### Verify Panel Detection
+```bash
+# Should return: cpanel, plesk, interworx, or none
+source /root/server-toolkit/lib/system-detect.sh
+echo $SYS_CONTROL_PANEL
+```
+
+### Verify Log Discovery
+```bash
+source /root/server-toolkit/lib/system-detect.sh
+echo $SYS_LOG_DIR
+ls -la "$SYS_LOG_DIR" | head
+```
+
+### Verify User Functions
+```bash
+source /root/server-toolkit/lib/user-manager.sh
+eval $(get_user_info "someuser")
+echo "User: $USERNAME"
+echo "Primary: $PRIMARY_DOMAIN"
+echo "All domains: $ALL_DOMAINS"
+```
+
+---
+
+## References
+
+### Official Documentation
+- cPanel: https://docs.cpanel.net/
+- Plesk: https://docs.plesk.com/
+- InterWorx: https://www.interworx.com/support/docs/
+
+### Useful Files to Study
+- `/etc/userdatadomains` (cPanel domain mapping)
+- `/etc/trueuserowners` (cPanel user→domain)
+- `/etc/trueuserdomains` (cPanel domain→user)
+- `/etc/httpd/conf.d/vhost_*.conf` (InterWorx vhosts)
+- `/var/www/vhosts/` (Plesk structure)
+
+---
+
+**Last Updated:** 2025-11-19
+**Maintainer:** Server Toolkit Team