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:

#!/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):

queue_count=$(exim -bpc)
queue_list=$(exim -bp)
exim -Mrm "$message_id"

AFTER (works on Exim, Postfix, or Sendmail):

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):

mysqldump -u root --all-databases > backup.sql
mysql -u root -e "SHOW DATABASES"

AFTER (works with MySQL or PostgreSQL):

$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):

access_log="/var/log/apache2/domlogs/$domain"
error_log="${access_log}-error_log"

AFTER (works on all platforms):

# 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):

php="/opt/cpanel/ea-php81/root/usr/bin/php"  # Hardcoded! Breaks if cPanel updates
$php --version

AFTER (dynamic, works with any version):

# 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):

if [ "$(stat -c %u "$file")" -eq 48 ]; then  # 48 is RHEL, 33 is Debian!
    echo "Owned by Apache"
fi

AFTER (works on all OS):

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):

/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):

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:

# 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):

#!/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:

#!/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:

#!/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:

#!/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:

#!/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:

#!/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:

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:

#!/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:

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