# System Variables - Quick Reference Card

**Use this card when updating scripts to find the right variable to use**

---

## Just Add This to Your Script

```bash
#!/bin/bash
set -eo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
BASE_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
source "$BASE_DIR/lib/system-variables.sh"

# Now all SYS_* variables are available
```

---

## Lookup: What Variable Do I Need?

### "I need to read/write to ___"

#### Web Server Logs
| Task | Variable | Notes |
|------|----------|-------|
| Main access log | `$SYS_LOG_WEB_ACCESS` | Works on all platforms |
| Main error log | `$SYS_LOG_WEB_ERROR` | Works on all platforms |
| Domain-specific logs | `$SYS_LOG_WEB_DOMAIN_ACCESS` | cPanel, Plesk, InterWorx |
| Domain error logs | `$SYS_LOG_WEB_DOMAIN_ERROR` | cPanel, Plesk, InterWorx |

#### Auth/System Logs
| Task | Variable | Notes |
|------|----------|-------|
| SSH/sudo/login log | `$SYS_LOG_AUTH` | /var/log/auth.log or /var/log/secure |
| Failed logins (binary) | `$SYS_LOG_BTMP` | Binary file - use `lastb` |
| Successful logins (binary) | `$SYS_LOG_WTMP` | Binary file - use `last` |

#### Mail Logs
| Task | Variable | Notes |
|------|----------|-------|
| Mail server log | `$SYS_LOG_MAIL_MAIN` | Main mail log |
| Mail rejects (Exim) | `$SYS_LOG_MAIL_REJECT` | Only on Exim systems |
| Mail panic (Exim) | `$SYS_LOG_MAIL_PANIC` | Only on Exim systems |
| Mail queue directory | `$SYS_MAIL_QUEUE_DIR` | Varies by mail system |

#### Firewall Logs
| Task | Variable | Notes |
|------|----------|-------|
| Firewall log | `$SYS_LOG_FIREWALL` | CSF, firewalld, iptables, UFW |
| Firewall blocks | `$SYS_LOG_FIREWALL_BLOCK` | Block events (CSF only) |

#### Database Logs
| Task | Variable | Notes |
|------|----------|-------|
| MySQL error log | `$SYS_LOG_DB_ERROR` | Error and warnings |
| Slow query log | `$SYS_LOG_DB_SLOW` | Queries slower than threshold |

#### Control Panel Logs
| Task | Variable | Notes |
|------|----------|-------|
| cPanel WHM log | `$SYS_LOG_PANEL` | cPanel logs directory |
| cPanel access log | `$SYS_LOG_PANEL_ACCESS` | cPanel access log |
| cPanel error log | `$SYS_LOG_PANEL_ERROR` | cPanel error log |

#### Security/System Logs
| Task | Variable | Notes |
|------|----------|-------|
| System log | `$SYS_LOG_SYSTEM` | syslog or messages |
| Kernel log | `$SYS_LOG_KERN` | Kernel messages |
| Audit log | `$SYS_LOG_AUDIT` | SELinux/audit log |
| Package manager log | `$SYS_LOG_PKG_MGR` | apt or yum history |

#### Scanner Logs
| Task | Variable | Notes |
|------|----------|-------|
| ClamAV log | `$SYS_LOG_CLAMAV` | Antivirus |
| Maldet log | `$SYS_LOG_MALDET` | Linux Malware Detect |
| Rkhunter log | `$SYS_LOG_RKHUNTER` | Rootkit Hunter |
| Imunify log | `$SYS_LOG_IMUNIFY` | Imunify360 |

---

### "I need to connect to ___"

#### MySQL/MariaDB
| Task | Variable | Notes |
|------|----------|-------|
| Database socket | `$SYS_DB_SOCKET` | Use with `-S` flag in mysql |
| Database config | `$SYS_DB_CONFIG` | MySQL config file |
| Database error log | `$SYS_LOG_DB_ERROR` | Check for connection errors |

**Example:**
```bash
mysql -S "$SYS_DB_SOCKET" -u root -e "SHOW DATABASES"
tail -f "$SYS_LOG_DB_ERROR"
```

#### PostgreSQL
| Task | Variable | Notes |
|------|----------|-------|
| PostgreSQL socket | `$SYS_PG_SOCKET` | Socket directory |
| PostgreSQL config | `$SYS_PG_CONFIG` | PostgreSQL config dir |
| PostgreSQL data | `$SYS_PG_DATA_DIR` | Data directory |

---

### "I need to work with ___"

#### User Home Directories
| Task | Variable | Notes |
|------|----------|-------|
| Base home path | `$SYS_USER_HOME_BASE` | /home or /var/www/vhosts or /chroot/home |
| cPanel users dir | `$SYS_CPANEL_USERS_DIR` | /var/cpanel/users (cPanel only) |
| cPanel user data | `$SYS_CPANEL_USERDATA_DIR` | /var/cpanel/userdata (cPanel only) |
| Plesk vhosts base | `$SYS_PLESK_VHOSTS_BASE` | /var/www/vhosts (Plesk only) |
| InterWorx chroot | `$SYS_INTERWORX_CHROOT_BASE` | /chroot/home (InterWorx only) |

#### cPanel Specific
| Task | Variable | Notes |
|------|----------|-------|
| cPanel version | `$SYS_CPANEL_VERSION_FILE` | Read to get version |
| cPanel scripts | `$SYS_CPANEL_SCRIPTS_DIR` | cPanel scripts directory |
| cPanel tools | `$SYS_CPANEL_HULK_CTL` | cPHulk control tool |
| cPanel main IP | `$SYS_CPANEL_MAINIP_FILE` | Read to get main IP |
| Domain logs | `$SYS_CPANEL_DOMAIN_LOGS` | Per-domain log directory |

#### Plesk Specific
| Task | Variable | Notes |
|------|----------|-------|
| Plesk version | `$SYS_PLESK_VERSION_FILE` | Read to get version |
| Plesk log version | `$SYS_PLESK_LOG_STRUCTURE` | "new" (18.0.50+) or "old" |
| Plesk logs base | `$SYS_PLESK_VHOSTS_LOGS_BASE` | /var/www/vhosts/system or /var/www/vhosts |

#### InterWorx Specific
| Task | Variable | Notes |
|------|----------|-------|
| InterWorx logs | `$SYS_INTERWORX_LOGS_DIR` | InterWorx log directory |
| iworx log | `$SYS_INTERWORX_IWORX_LOG` | Panel log |
| siteworx log | `$SYS_INTERWORX_SITEWORX_LOG` | Site log |

---

### "I need to manage a service"

#### Service Names
| Service | Variable | Values |
|---------|----------|--------|
| Web server | `$SYS_WEB_SERVICE` | "httpd", "apache2", "nginx", "lsws" |
| Database | `$SYS_DB_SERVICE` | "mysqld", "mariadb", "postgresql" |
| Mail | `$SYS_MAIL_SERVICE` | "exim", "postfix", "sendmail" |
| SSH | `$SYS_AUTH_SERVICE` | "sshd" |
| Firewall | `$SYS_FIREWALL_SERVICE` | "csf", "firewalld", etc. |

**Use with:**
```bash
restart_service "$SYS_WEB_SERVICE"
is_service_running "$SYS_DB_SERVICE"
```

#### Service Control Commands
| Task | Variable | Usage |
|------|----------|-------|
| Restart | `$SYS_SERVICE_RESTART` | `"$SYS_SERVICE_RESTART" "$SYS_WEB_SERVICE"` |
| Start | `$SYS_SERVICE_START` | `"$SYS_SERVICE_START" "$SYS_WEB_SERVICE"` |
| Stop | `$SYS_SERVICE_STOP` | `"$SYS_SERVICE_STOP" "$SYS_WEB_SERVICE"` |
| Status | `$SYS_SERVICE_STATUS` | `"$SYS_SERVICE_STATUS" "$SYS_WEB_SERVICE"` |
| Enable | `$SYS_SERVICE_ENABLE` | `"$SYS_SERVICE_ENABLE" "$SYS_WEB_SERVICE"` |

**Or use convenience function:**
```bash
restart_service "$SYS_WEB_SERVICE"  # Works on all systems
```

---

### "I need to check/install/configure ___"

#### Web Server Configuration
| Task | Variable | Notes |
|------|----------|-------|
| Apache main config | `$SYS_APACHE_MAIN_CONFIG` | Apache only |
| Apache config dir | `$SYS_APACHE_CONFIG_DIR` | Apache only |
| Apache mods enabled | `$SYS_APACHE_MODS_DIR` | Apache only |
| Nginx main config | `$SYS_NGINX_MAIN_CONFIG` | Nginx only |
| Nginx config dir | `$SYS_NGINX_CONFIG_DIR` | Nginx only |

#### Security/Firewall Configuration
| Task | Variable | Notes |
|------|----------|-------|
| ModSecurity config | `$SYS_MODSECURITY_CONF` | If installed |
| CSF config | `$SYS_CSF_CONFIG` | CSF firewall |
| CSF allow list | `$SYS_CSF_ALLOW` | CSF whitelist |
| CSF deny list | `$SYS_CSF_DENY` | CSF blacklist |

#### SSL/TLS Certificates
| Task | Variable | Notes |
|------|----------|-------|
| Certificate dir | `$SYS_SSL_CERT_DIR` | /etc/ssl/certs |
| Private keys dir | `$SYS_SSL_KEY_DIR` | /etc/ssl/private |
| Let's Encrypt live | `$SYS_LETSENCRYPT_LIVE` | Live certificates |
| cPanel SSL dir | `$SYS_CPANEL_SSL_DIR` | cPanel only |

#### Package Manager
| Task | Variable | Notes |
|------|----------|-------|
| Install cmd | `$SYS_PKG_MANAGER_INSTALL` | With flags |
| Remove cmd | `$SYS_PKG_MANAGER_REMOVE` | With flags |
| Update cmd | `$SYS_PKG_MANAGER_UPDATE` | With flags |
| Cache dir | `$SYS_PACKAGE_CACHE` | /var/cache/apt or /var/cache/yum |

---

## Detection Variables (For Conditionals)

```bash
# What platform detected?
if [ "$SYS_CONTROL_PANEL" = "cpanel" ]; then
    # cPanel-specific code
fi

# What OS?
if [ "$SYS_OS_TYPE" = "ubuntu" ]; then
    # Debian-specific code
fi

# What web server?
if [ "$SYS_WEB_SERVER" = "nginx" ]; then
    # Nginx-specific code
fi

# What database?
if [ "$SYS_DB_TYPE" = "postgresql" ]; then
    # PostgreSQL-specific code
fi

# What init system?
if [ "$SYS_INIT_SYSTEM" = "systemd" ]; then
    # systemd-specific code
fi
```

---

## Common Patterns

### Check if service is installed
```bash
if [ -n "$SYS_WEB_SERVICE" ]; then
    echo "Web server installed: $SYS_WEB_SERVICE"
fi
```

### Check if log file exists and is readable
```bash
if [ -f "$SYS_LOG_WEB_ERROR" ]; then
    tail -f "$SYS_LOG_WEB_ERROR"
fi
```

### Work with domain-specific logs (varies by platform)
```bash
if [ -n "$SYS_LOG_WEB_DOMAIN_ACCESS" ]; then
    find "$SYS_LOG_WEB_DOMAIN_ACCESS" -name "*.log"
fi
```

### Database operations
```bash
# Read-only check
mysql -S "$SYS_DB_SOCKET" -u root -e "SELECT COUNT(*) FROM information_schema.SCHEMATA"

# Monitor errors
tail -f "$SYS_LOG_DB_ERROR"
```

### Service management
```bash
# Restart web server (works on systemd and sysvinit)
restart_service "$SYS_WEB_SERVICE"

# Or manual
"$SYS_SERVICE_RESTART" "$SYS_WEB_SERVICE"
```

### cPanel operations
```bash
# List all users (cPanel)
if [ "$SYS_CONTROL_PANEL" = "cpanel" ]; then
    ls "$SYS_CPANEL_USERS_DIR"
fi
```

---

## Error Handling Template

```bash
#!/bin/bash
set -eo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
BASE_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
source "$BASE_DIR/lib/system-variables.sh"

# Check if required log exists
if [ -z "$SYS_LOG_WEB_ACCESS" ] || [ ! -f "$SYS_LOG_WEB_ACCESS" ]; then
    echo "ERROR: Web access log not found at $SYS_LOG_WEB_ACCESS"
    exit 1
fi

# Check if required variable is set
if [ -z "$SYS_DB_SOCKET" ]; then
    echo "ERROR: Database not detected on this system"
    exit 1
fi

# Your script code here
```

---

## When Variables Are Empty

Some variables may be empty on certain systems:

| Variable | Empty When |
|----------|-----------|
| `SYS_CPANEL_*` | Not on cPanel |
| `SYS_PLESK_*` | Not on Plesk |
| `SYS_INTERWORX_*` | Not on InterWorx |
| `SYS_LOG_MAIL_REJECT` | Not Exim mail system |
| `SYS_LOG_DB_SLOW` | Database not detected |
| `SYS_NGINX_*` | Not using Nginx |
| `SYS_APACHE_*` | Not using Apache |

**Always check before using:**
```bash
if [ -n "$SYS_CPANEL_USERS_DIR" ]; then
    # cPanel specific code
fi
```

---

## Full Reference

For complete documentation with examples, see:
- `docs/SYSTEM-VARIABLES-REFERENCE.md` - All 140+ variables documented
- `docs/SYSTEM-VARIABLES-MAPPING-COMPLETE.md` - Coverage and examples
- `docs/SYSTEM-VARIABLES-READY-FOR-UPDATES.md` - Migration guide