Linux-Server-Management-Toolkit/docs/QUICK-MIGRATION-GUIDE.md

# Quick Migration Guide - Using New Variables

**Purpose**: Help existing scripts migrate from hardcoded paths to SYS_* variables
**Time to migrate**: 5 minutes per script
**Benefit**: Multi-platform compatibility with zero code branching

---

## Step 1: Add Variable Sourcing

Add to the top of any script that needs platform abstraction:

```bash
#!/bin/bash

# ... existing header comments ...

# Get platform information and variables
source "$(dirname "${BASH_SOURCE[0]}")/../lib/system-variables.sh"

# Now all SYS_* variables are available
```

---

## Step 2: Replace Hardcoded Paths

### Mail System Example

**BEFORE** (only works on Exim):
```bash
queue_count=$(exim -bpc)
queue_list=$(exim -bp)
exim -Mrm "$message_id"
```

**AFTER** (works on Exim, Postfix, or Sendmail):
```bash
queue_count=$(eval "$SYS_MAIL_CMD_QUEUE_COUNT")
queue_list=$(eval "$SYS_MAIL_CMD_QUEUE_LIST")
eval "$SYS_MAIL_CMD_QUEUE_REMOVE '$message_id'"
```

---

### Database Example

**BEFORE** (only works with MySQL at /usr/bin):
```bash
mysqldump -u root --all-databases > backup.sql
mysql -u root -e "SHOW DATABASES"
```

**AFTER** (works with MySQL or PostgreSQL):
```bash
$SYS_DB_DUMP_COMMAND -u root --all-databases > backup.sql
$SYS_DB_CLI_COMMAND -u root -c "SELECT datname FROM pg_database WHERE datistemplate=false"
```

---

### Domain Logs Example

**BEFORE** (hardcoded, wrong on Plesk <18.0.50 or InterWorx):
```bash
access_log="/var/log/apache2/domlogs/$domain"
error_log="${access_log}-error_log"
```

**AFTER** (works on all platforms):
```bash
# On cPanel
access_log="${SYS_CPANEL_DOMLOGS_PATTERN//\{DOMAIN\}/$domain}"

# Or if supporting multiple panels:
case "$SYS_CONTROL_PANEL" in
    cpanel)
        access_log="${SYS_CPANEL_DOMLOGS_PATTERN//\{DOMAIN\}/$domain}"
        error_log="${access_log}-error_log"
        ;;
    plesk)
        # Plesk version is auto-detected in variable
        access_log="${SYS_PLESK_DOMLOGS_PATTERN//\{DOMAIN\}/$domain}/access_log"
        error_log="${SYS_PLESK_DOMLOGS_PATTERN//\{DOMAIN\}/$domain}/error_log"
        ;;
    interworx)
        # Extract account from domain (first 8 chars)
        account="${domain:0:8}"
        access_log="${SYS_INTERWORX_DOMAIN_LOGS//\{ACCOUNT\}/$account//\{DOMAIN\}/$domain}/access.log"
        error_log="${SYS_INTERWORX_DOMAIN_LOGS//\{ACCOUNT\}/$account//\{DOMAIN\}/$domain}/error.log"
        ;;
esac
tail -f "$access_log"
```

---

### PHP Version Example

**BEFORE** (hardcoded for one version):
```bash
php="/opt/cpanel/ea-php81/root/usr/bin/php"  # Hardcoded! Breaks if cPanel updates
$php --version
```

**AFTER** (dynamic, works with any version):
```bash
# For a specific version
php81="${SYS_CPANEL_EAPHP_BINARY_PATTERN//\{VERSION\}/81}"
$php81 --version

# Or detect from domain configuration
config="/var/cpanel/userdata/$user/$domain.cache"
php_version=$(grep "php_version=" "$config" | cut -d= -f2)
php="${SYS_CPANEL_EAPHP_BINARY_PATTERN//\{VERSION\}/$php_version}"
$php --version
```

---

### Permission Check Example

**BEFORE** (hardcoded UID, different on each OS):
```bash
if [ "$(stat -c %u "$file")" -eq 48 ]; then  # 48 is RHEL, 33 is Debian!
    echo "Owned by Apache"
fi
```

**AFTER** (works on all OS):
```bash
if [ "$(stat -c %u "$file")" -eq "$SYS_WEB_UID" ]; then
    echo "Owned by web server"
fi
```

---

### Security Scanner Example

**BEFORE** (tries all scanners, fails if not installed):
```bash
/usr/bin/clamscan -r /home              # Fails if ClamAV not installed
/usr/local/maldetect/maldet -a /home   # Fails if Maldet not installed
/usr/bin/rkhunter --update             # Fails if RKHunter not installed
```

**AFTER** (only runs installed scanners):
```bash
if [ -n "$SYS_SCANNER_CLAMAV" ]; then
    $SYS_SCANNER_CLAMAV -r /home
fi

if [ -n "$SYS_SCANNER_MALDET" ]; then
    $SYS_SCANNER_MALDET -a /home
fi

if [ -n "$SYS_SCANNER_RKHUNTER" ]; then
    $SYS_SCANNER_RKHUNTER --update
fi
```

---

## Step 3: Test on Multiple Platforms

After migration, test the script:

```bash
# Test on cPanel (SYS_CONTROL_PANEL will be "cpanel")
./your-script.sh

# To test as if it were Plesk (for code paths only):
export SYS_CONTROL_PANEL="plesk"
./your-script.sh
```

---

## Common Variable Replacements

### Quick Reference Table

| Old Hardcoded | New Variable | Use Case |
|---------------|--------------|----------|
| `/var/log/apache2/domlogs/$domain` | `$SYS_CPANEL_DOMLOGS_PATTERN` | cPanel domain logs |
| `/var/www/vhosts/DOMAIN/logs` | `$SYS_PLESK_DOMLOGS_PATTERN` | Plesk domain logs |
| `/opt/cpanel/ea-phpXX/...` | `$SYS_CPANEL_EAPHP_BINARY_PATTERN` | cPanel PHP binary |
| `/opt/plesk/php/X.Y/bin/php` | `$SYS_PLESK_PHP_BINARY_PATTERN` | Plesk PHP binary |
| `exim -bpc` | `eval "$SYS_MAIL_CMD_QUEUE_COUNT"` | Mail queue count |
| `mysqldump` | `$SYS_DB_DUMP_COMMAND` | Database backup |
| `uid=48` | `$SYS_WEB_UID` | Web server UID check |
| `/usr/bin/clamscan` | `$SYS_SCANNER_CLAMAV` | ClamAV scanner |
| `/etc/passwd` | `$SYS_AUTH_PASSWD_FILE` | User list |
| `/var/cpanel/userdata` | `$SYS_CPANEL_USERDATA_DIR` | cPanel config cache |

---

## Real-World Migration Examples

### Example 1: Mail Queue Inspector

**Original Script** (modules/email/mail-queue-inspector.sh):
```bash
#!/bin/bash

echo "=== Mail Queue Analysis ==="

# Check Exim queue
if command -v exim &>/dev/null; then
    count=$(exim -bpc)
    echo "Queued messages: $count"

    exim -bp | head -20
fi
```

**Migrated Script**:
```bash
#!/bin/bash

# Get system variables
source "$(dirname "${BASH_SOURCE[0]}")/../lib/system-variables.sh"

echo "=== Mail Queue Analysis ==="
echo "Mail System: $SYS_MAIL_SYSTEM"

# Works with Exim, Postfix, or Sendmail
count=$(eval "$SYS_MAIL_CMD_QUEUE_COUNT")
echo "Queued messages: $count"

eval "$SYS_MAIL_CMD_QUEUE_LIST" | head -20
```

**Benefit**: Script now works with any MTA without changes

---

### Example 2: Domain Log Analyzer

**Original Script**:
```bash
#!/bin/bash

domain=$1

# Only works on cPanel
access_log="/var/log/apache2/domlogs/$domain"
error_log="${access_log}-error_log"

tail -f "$access_log" &
tail -f "$error_log"
```

**Migrated Script**:
```bash
#!/bin/bash

source "$(dirname "${BASH_SOURCE[0]}")/../lib/system-variables.sh"

domain=$1

# Works on cPanel, Plesk, InterWorx
case "$SYS_CONTROL_PANEL" in
    cpanel)
        access_log="${SYS_CPANEL_DOMLOGS_PATTERN//\{DOMAIN\}/$domain}"
        error_log="${access_log}-error_log"
        ;;
    plesk)
        base="${SYS_PLESK_DOMLOGS_PATTERN//\{DOMAIN\}/$domain}"
        access_log="$base/access_log"
        error_log="$base/error_log"
        ;;
    interworx)
        account="${domain:0:8}"
        base="${SYS_INTERWORX_DOMAIN_LOGS//\{ACCOUNT\}/$account//\{DOMAIN\}/$domain}"
        access_log="$base/access.log"
        error_log="$base/error.log"
        ;;
    *)
        echo "Unsupported control panel"
        exit 1
        ;;
esac

[ -f "$access_log" ] && tail -f "$access_log" &
[ -f "$error_log" ] && tail -f "$error_log"
```

**Benefit**: Single script deploys to any panel

---

### Example 3: PHP Configuration Checker

**Original Script**:
```bash
#!/bin/bash

# Check PHP configuration - hardcoded paths
php74="/opt/cpanel/ea-php74/root/usr/bin/php"
php81="/opt/cpanel/ea-php81/root/usr/bin/php"

for php in "$php74" "$php81"; do
    if [ -x "$php" ]; then
        $php -i | grep "memory_limit"
    fi
done
```

**Migrated Script**:
```bash
#!/bin/bash

source "$(dirname "${BASH_SOURCE[0]}")/../lib/system-variables.sh"

case "$SYS_CONTROL_PANEL" in
    cpanel)
        # cPanel: check all available ea-phpXX versions
        for version in 72 73 74 80 81 82 83; do
            php="${SYS_CPANEL_EAPHP_BINARY_PATTERN//\{VERSION\}/$version}"
            [ -x "$php" ] && echo "PHP $version:" && $php -i | grep "memory_limit"
        done
        ;;
    plesk)
        # Plesk: check all installed versions
        for version in 7.4 8.0 8.1 8.2 8.3; do
            php="${SYS_PLESK_PHP_BINARY_PATTERN//\{VERSION\}/$version}"
            [ -x "$php" ] && echo "PHP $version:" && $php -i | grep "memory_limit"
        done
        ;;
    interworx)
        # InterWorx: system PHP only
        $SYS_INTERWORX_PHP_SYSTEM -i | grep "memory_limit"
        ;;
esac
```

**Benefit**: Future-proof (automatically works with new PHP versions)

---

## Best Practices

### ✅ DO

- ✅ Always source `lib/system-variables.sh` at script start
- ✅ Use pattern substitution for dynamic values: `${var//\{PLACEHOLDER\}/value}`
- ✅ Check for optional tools before using: `if [ -n "$VAR" ]; then ...`
- ✅ Use `eval` for multi-argument commands: `eval "$SYS_MAIL_CMD_QUEUE_COUNT"`
- ✅ Document which platforms a migrated script supports
- ✅ Test on at least 2 different control panels (if possible)

### ❌ DON'T

- ❌ Don't hardcode paths like `/var/log/apache2/domlogs/`
- ❌ Don't assume a specific UID (use `$SYS_*_UID` instead)
- ❌ Don't hardcode `/opt/cpanel/` or `/opt/plesk/`
- ❌ Don't assume `/home/` is the user home (use `$SYS_USER_HOME_BASE`)
- ❌ Don't check `if [ "$UID" = "48" ]` (use `if [ "$UID" = "$SYS_WEB_UID" ]`)
- ❌ Don't assume MySQL socket location (use `$SYS_DB_SOCKET`)

---

## Testing Checklist

Before considering a script migrated, verify:

- [ ] Script sources `lib/system-variables.sh`
- [ ] No hardcoded `/home/`, `/var/www/`, or `/chroot/home/` paths
- [ ] No hardcoded PHP version paths
- [ ] No hardcoded mail system commands (using SYS_MAIL_* instead)
- [ ] No hardcoded UIDs (using SYS_*_UID instead)
- [ ] All optional tools checked with `if [ -n "$VAR" ]`
- [ ] All `eval` commands use proper quoting
- [ ] Script tested on actual platform (not just syntax check)

---

## Migration Priority

### Priority 1 (This Week)
- [ ] All email modules (mail-queue-inspector.sh, mail-log-analyzer.sh)
- [ ] All website domain-related scripts
- [ ] Any security modules that scan domains

### Priority 2 (This Month)
- [ ] All database modules
- [ ] All PHP analysis scripts
- [ ] All performance monitoring scripts

### Priority 3 (Ongoing)
- [ ] Any remaining hardcoded paths
- [ ] UID/GID checks
- [ ] Tool path assumptions

---

## Support & Questions

**Question**: What if my script needs to work on standalone systems (no control panel)?

**Answer**: Use empty variable checks:
```bash
if [ -z "$SYS_CPANEL_DOMLOGS_PATTERN" ]; then
    # No control panel - fallback to standard paths
    access_log="/var/log/apache2/$domain"
else
    # Use control-panel-aware variable
    access_log="${SYS_CPANEL_DOMLOGS_PATTERN//\{DOMAIN\}/$domain}"
fi
```

---

**Question**: Can I use these variables in cron jobs?

**Answer**: Yes, but source them first:
```bash
#!/bin/bash
source /root/server-toolkit/lib/system-variables.sh
# Now use SYS_* variables
```

---

**Question**: What if a variable is empty on my system?

**Answer**: It means that tool/feature isn't installed or available. Always check before using:
```bash
if [ -n "$SYS_SCANNER_CLAMAV" ]; then
    # ClamAV is available
    $SYS_SCANNER_CLAMAV -r /home
fi
```

---

## Summary

**Migrating to SYS_* variables is simple:**
1. Add `source lib/system-variables.sh` to your script
2. Replace hardcoded paths with variable substitution
3. Use `eval` for multi-argument commands
4. Check optional tools with `if [ -n "$VAR" ]`
5. Test on multiple platforms

**Result**: Single script works everywhere with zero branching logic