================================================================================
                    SYSTEM VARIABLES QUICK REFERENCE
                   (All SYS_* variables available after
                 sourcing lib/system-variables.sh in launcher)
================================================================================

SOURCING IN YOUR SCRIPT:
    source "$SCRIPT_DIR/lib/system-variables.sh"

================================================================================
MAIL SYSTEM - Choose your system, use the variables
================================================================================

IF $SYS_MAIL_SYSTEM = "exim":
    $SYS_MAIL_BIN_EXIM              /usr/sbin/exim
    $SYS_MAIL_CMD_QUEUE_COUNT       exim -bpc
    $SYS_MAIL_CMD_QUEUE_LIST        exim -bp
    $SYS_MAIL_CMD_QUEUE_RETRY       exim -R
    $SYS_MAIL_CMD_QUEUE_REMOVE      exim -Mrm
    eval "$SYS_MAIL_CMD_QUEUE_COUNT" → (number of queued messages)

IF $SYS_MAIL_SYSTEM = "postfix":
    $SYS_MAIL_BIN_POSTFIX           /usr/sbin/postfix
    $SYS_MAIL_CMD_QUEUE_COUNT       mailq 2>/dev/null | tail -1
    $SYS_MAIL_CMD_QUEUE_LIST        mailq
    $SYS_MAIL_CMD_QUEUE_RETRY       postqueue -f
    $SYS_MAIL_CMD_QUEUE_REMOVE      postsuper -d

IF $SYS_MAIL_SYSTEM = "sendmail":
    $SYS_MAIL_BIN_SENDMAIL          /usr/sbin/sendmail
    $SYS_MAIL_CMD_QUEUE_COUNT       mailq 2>/dev/null | tail -1
    $SYS_MAIL_CMD_QUEUE_LIST        mailq
    $SYS_MAIL_CMD_QUEUE_RETRY       /usr/sbin/sendmail -q

$SYS_MAIL_SPOOL                     Directory with queued messages
$SYS_MAIL_UID / $SYS_MAIL_GID       Mail system user/group IDs

================================================================================
DATABASE SYSTEM - MySQL/MariaDB or PostgreSQL, same variables
================================================================================

$SYS_DB_CLI_COMMAND                 /usr/bin/mysql or /usr/bin/psql
$SYS_DB_DUMP_COMMAND                /usr/bin/mysqldump or /usr/bin/pg_dump
$SYS_DB_ADMIN_COMMAND               /usr/bin/mysqladmin or /usr/bin/pg_isready
$SYS_DB_CHECK_COMMAND               /usr/bin/mysqlcheck or /usr/bin/pg_check
$SYS_DB_REPAIR_COMMAND              mysqlcheck --repair or VACUUM FULL ANALYZE
$SYS_DB_OPTIMIZE_COMMAND            mysqlcheck --optimize or ANALYZE
$SYS_DB_STATUS_COMMAND              SHOW STATUS command or pg_isready
$SYS_DB_SHOW_DATABASES              List all databases
$SYS_DB_SHOW_TABLES                 List tables in database

$SYS_DB_UID / $SYS_DB_GID           Database system user/group IDs
$SYS_DB_SOCKET                      Unix socket path
$SYS_DB_CONFIG                      Configuration file path

================================================================================
SECURITY SCANNERS - Check if available, use if present
================================================================================

Check: if [ -n "$SYS_SCANNER_CLAMAV" ]; then ... fi

AVAILABLE SCANNERS:
    $SYS_SCANNER_CLAMAV             /usr/bin/clamscan (if installed)
    $SYS_SCANNER_CLAMUPDATE         /usr/bin/freshclam (if installed)
    $SYS_SCANNER_MALDET             /usr/local/maldetect/maldet (if installed)
    $SYS_SCANNER_RKHUNTER           /usr/bin/rkhunter (if installed)
    $SYS_SCANNER_IMUNIFY            /usr/bin/imunify360-agent (if installed)

RELATED:
    $SYS_SCANNER_CLAMAV_DB          /var/lib/clamav (ClamAV signature DB)
    $SYS_SCANNER_CLAMAV_LOG         /var/log/clamav/scan.log
    $SYS_SCANNER_MALDET_QUARANTINE  Quarantine directory
    $SYS_SCANNER_RKHUNTER_CONFIG    /etc/rkhunter.conf

CONTROL PANEL SECURITY TOOLS:
    IF $SYS_CONTROL_PANEL = "cpanel":
        $SYS_CPANEL_WHMAPI              WHM API endpoint
        $SYS_CPANEL_UAPI                cPanel User API endpoint
        $SYS_CPANEL_HULK                /usr/sbin/csf (if using CSF)
        $SYS_CPANEL_SCAN_TOOL           Security scan utility
        $SYS_CPANEL_MALWARE_SCANNER     Malware detection tool

    IF $SYS_CONTROL_PANEL = "plesk":
        $SYS_PLESK_API                  Plesk API
        $SYS_PLESK_ADMIN_API            Admin API
        $SYS_PLESK_EXTENSION_API        Extension API

    IF $SYS_CONTROL_PANEL = "interworx":
        $SYS_INTERWORX_BIN              /home/interworx/bin
        $SYS_INTERWORX_NODEWORX         NodeWorx CLI
        $SYS_INTERWORX_SITEWORX         SiteWorx CLI

SYSTEM SECURITY:
    if [ -n "$SYS_FAIL2BAN_CLIENT" ]; then
        $SYS_FAIL2BAN_CLIENT            Fail2Ban CLI
        $SYS_FAIL2BAN_CONFIG            /etc/fail2ban
    fi

    if [ -n "$SYS_SELINUX_ENABLED" ]; then
        $SYS_SELINUX_STATUS             Current SELinux mode
        $SYS_SELINUX_CONFIG             /etc/selinux/config
    fi

    if [ -n "$SYS_APPARMOR_ENABLED" ]; then
        $SYS_APPARMOR_CONFIG            /etc/apparmor
    fi

================================================================================
AUTHENTICATION & SYSTEM FILES
================================================================================

STANDARD FILES (all systems):
    $SYS_AUTH_PASSWD_FILE               /etc/passwd
    $SYS_AUTH_SHADOW_FILE               /etc/shadow
    $SYS_AUTH_GROUP_FILE                /etc/group
    $SYS_AUTH_GSHADOW_FILE              /etc/gshadow
    $SYS_AUTH_SUDOERS_FILE              /etc/sudoers
    $SYS_AUTH_SUDOERS_DIR               /etc/sudoers.d
    $SYS_AUTH_SSH_CONFIG                /etc/ssh/sshd_config
    $SYS_AUTH_PAM_DIR                   /etc/pam.d
    $SYS_AUTH_HOSTS_ALLOW               /etc/hosts.allow
    $SYS_AUTH_HOSTS_DENY                /etc/hosts.deny

CRON & LOGS:
    $SYS_AUTH_CRONTAB_DIR               /var/spool/cron or /var/spool/cron/crontabs
    $SYS_LOG_CRON                       /var/log/cron (RHEL) or /var/log/syslog (Debian)

================================================================================
USER & GROUP IDS (for permission checks)
================================================================================

WEB SERVER:
    $SYS_WEB_UID                        Numeric UID (33 on Debian, 48 on RHEL)
    $SYS_WEB_GID                        Numeric GID
    Example: if [ "$file_uid" -eq "$SYS_WEB_UID" ]; then ... fi

DATABASE:
    $SYS_DB_UID                         Numeric UID (usually 986 for MySQL)
    $SYS_DB_GID                         Numeric GID

MAIL SYSTEM:
    $SYS_MAIL_UID                       Numeric UID (8 on most systems)
    $SYS_MAIL_GID                       Numeric GID

CONTROL PANEL SYSTEM USERS:
    $SYS_CPANEL_SYSTEM_UID              cPanel system user UID
    $SYS_PLESK_SYSTEM_UID               Plesk system user UID
    $SYS_INTERWORX_SYSTEM_UID           InterWorx system user UID

================================================================================
SYSTEM DETECTION (populated by launcher.sh)
================================================================================

PLATFORM INFO:
    $SYS_CONTROL_PANEL                  cpanel, plesk, interworx, or ""
    $SYS_CONTROL_PANEL_VERSION          Version number
    $SYS_OS_TYPE                        centos, ubuntu, debian, almalinux, cloudlinux
    $SYS_OS_VERSION                     Version number
    $SYS_WEB_SERVER                     apache, nginx, litespeed, openlitespeed
    $SYS_WEB_SERVER_VERSION             Version number
    $SYS_DB_TYPE                        mysql, postgresql
    $SYS_DB_VERSION                     Version number
    $SYS_MAIL_SYSTEM                    exim, postfix, sendmail
    $SYS_FIREWALL                       csf, firewalld, iptables, ufw, imunify, plesk
    $SYS_FIREWALL_VERSION               Version number

PATHS:
    $SYS_LOG_DIR                        Base log directory
    $SYS_USER_HOME_BASE                 /home or /var/www/vhosts or /chroot/home
    $SYS_DB_SOCKET                      MySQL socket
    $SYS_DB_CONFIG                      MySQL config file

SERVICE NAMES:
    $SYS_WEB_SERVICE                    apache2 or httpd
    $SYS_WEB_USER                       www-data or apache
    $SYS_DB_SERVICE                     mysqld or mysql
    $SYS_MAIL_SERVICE                   exim4 or postfix
    $SYS_FIREWALL_SERVICE               csf or firewalld or ufw
    $SYS_INIT_SYSTEM                    systemd or sysvinit

================================================================================
FIREWALL OPERATIONS (always available)
================================================================================

Source the library:
    source lib/system-variables.sh

Functions available:
    firewall_block_ip "192.168.1.100"
        Returns: 0 on success, 1 on failure

    firewall_unblock_ip "192.168.1.100"
        Returns: 0 always

    firewall_is_blocked "192.168.1.100"
        Returns: 0 if blocked, 1 if not

    firewall_bulk_block_ips "192.168.1.1\n192.168.1.2\n192.168.1.3"
        Returns: "Blocked: N, Failed: M"

Supports: CSF, firewalld, iptables, UFW, Imunify360, Plesk Firewall
Uses ipset for bulk operations (1000+ IPs in <2 seconds)

================================================================================
COMMON PATTERNS
================================================================================

1. USE OPTIONAL TOOLS SAFELY:
    if [ -n "$SYS_SCANNER_CLAMAV" ]; then
        $SYS_SCANNER_CLAMAV -r /home
    fi

2. USE MAIL COMMANDS ON ANY MTA:
    eval "$SYS_MAIL_CMD_QUEUE_COUNT"
    eval "$SYS_MAIL_CMD_QUEUE_LIST"

3. USE DATABASE COMMANDS ON ANY DB:
    $SYS_DB_DUMP_COMMAND database_name > backup.sql
    $SYS_DB_CHECK_COMMAND -u root

4. CHECK FILE OWNERSHIP ACROSS OSes:
    if [ "$(stat -c %u /path)" -eq "$SYS_WEB_UID" ]; then
        echo "Owned by web server"
    fi

5. BLOCK IPS ACROSS FIREWALLS:
    while read ip; do
        firewall_block_ip "$ip"
    done < suspicious_ips.txt

================================================================================
PLATFORM DETECTION QUICK REFERENCE
================================================================================

IF cPanel:          SYS_CONTROL_PANEL="cpanel"
  - User homes: /home/USERNAME
  - Web docroot: /home/USERNAME/public_html
  - Panel paths: SYS_CPANEL_*
  - Logs: SYS_LOG_* (auto-detected)

IF Plesk:           SYS_CONTROL_PANEL="plesk"
  - User homes: /var/www/vhosts/USERNAME
  - Web docroot: /var/www/vhosts/DOMAIN/httpdocs
  - Panel paths: SYS_PLESK_*
  - Logs: SYS_LOG_* (auto-detected)

IF InterWorx:       SYS_CONTROL_PANEL="interworx"
  - User homes: /chroot/home/USERNAME
  - Web docroot: /home/USERNAME/DOMAIN/html
  - Panel paths: SYS_INTERWORX_*
  - Logs: SYS_LOG_* (auto-detected)

IF RHEL/CentOS:     SYS_OS_TYPE="centos" or "almalinux"
  - Apache: /usr/sbin/httpd, user=apache, uid=48
  - MySQL socket: /var/lib/mysql/mysql.sock
  - Logs: /var/log/

IF Ubuntu/Debian:   SYS_OS_TYPE="ubuntu" or "debian"
  - Apache: /usr/sbin/apache2, user=www-data, uid=33
  - MySQL socket: /var/run/mysqld/mysqld.sock
  - Logs: /var/log/

================================================================================
TROUBLESHOOTING
================================================================================

Variables are empty or not set?
  → launcher.sh must run full detection first
  → Make sure to source lib/system-variables.sh, not individual files

Tool path is empty (e.g., $SYS_SCANNER_CLAMAV)?
  → Tool is not installed on this system
  → Always check: if [ -n "$VAR" ]; then use it; fi

Commands don't work as expected?
  → Try: eval "$SYS_MAIL_CMD_QUEUE_COUNT" (instead of just $SYS_MAIL_CMD_QUEUE_COUNT)
  → eval is needed for commands with arguments

Wrong UID detected?
  → Check: id -u web_user_name
  → Report if doesn't match $SYS_WEB_UID

================================================================================
For detailed documentation, see:
  - MAIL-DATABASE-TOOLS-VARIABLES.md (full reference)
  - MISSING-VARIABLES-COMPLETE.md (implementation details)
  - IMPLEMENTATION-READY.md (status & integration guide)
================================================================================