Remote Scripts - GamePanelX

GamePanelX uses a collection of remote Bash scripts to manage game servers on distributed nodes. These scripts handle server creation, updates, restarts, and various administrative tasks. All scripts reside in the _SERVERS/scripts/ directory on each node.

Script Overview

Remote scripts are executed via SSH on the game server nodes and communicate back to the control panel through callback URLs. They provide the foundation for GamePanelX’s distributed architecture.

All remote scripts are designed to run under the game server user account, not as root. This provides security isolation between different server instances.

Core Scripts

CreateServer

Creates a new game server instance from a template. Parameters:

./CreateServer [OPTIONS]

Options:
  -u  Server username
  -i  Server IP address
  -p  Server port
  -x  Template ID
  -s  Start server after creation (yes/no)
  -w  Working directory
  -P  PID file location
  -o  Complete command line to run
  -c  Callback URL

Example Usage:

./CreateServer -u user123 -i 192.168.10.10 -p 27015 -x 27 \
  -s yes -P server.pid \
  -o './srcds_run -game cstrike -ip 192.168.10.10 -port 27015 +map de_dust2'

Workflow:

Directory Creation

Creates the server directory: $HOME/accounts/$username/$ip.$port

Template Extraction

Extracts the game files from the template archive:

tar -zxf $HOME/templates/$tpl_id.tar.gz -C $gpxdir/

Background Monitoring

Forks a background process to monitor extraction completion

Callback Notification

Sends status updates to the control panel via callback URL

Server Start

If -s yes is specified, automatically starts the server using the Restart script

Restart

Starts or restarts a game server instance. Parameters:

./Restart [OPTIONS]

Options:
  -u  Client's GPX username
  -i  Server IP address
  -p  Server port
  -P  Server PID filename (optional)
  -w  Working directory (optional)
  -s  Unsuspend server (optional)
  -o  Complete command line
  -c  Taskset CPU number/core (optional)
  -l  Enable logging (optional)

Example Usage:

./Restart -u user123 -i 192.168.10.10 -p 27015 \
  -w orangebox \
  -o './srcds_run -game cstrike +ip 192.168.10.10 -port 27015 +map de_dust2 +maxplayers 12'

Features:

Automatically stops existing server process
Supports GNU Screen for console access
Creates PID file for process tracking
Can pin server to specific CPU core with taskset
Handles working directory changes

CreateTemplate

Creates a compressed template archive from installed game files. Parameters:

./CreateTemplate [OPTIONS]

Options:
  -p  Path to game files (relative to $HOME)
  -i  Template ID
  -s  Start compression immediately (yes/no)
  -u  Callback URL
  -d  Debug mode (yes/no)

Example Usage:

./CreateTemplate -p tmp/24 -i 24 -s yes -u "http://panel.example.com/callback.php?id=24"

Process:

Validates source directory exists
Creates compressed tar.gz archive
Stores in $HOME/templates/$tpl_id.tar.gz
Sends progress updates via callback
Cleans up temporary files on completion

DeleteServer

Removes a game server instance and all associated files. Parameters:

./DeleteServer [OPTIONS]

Options:
  -u  Server username
  -i  Server IP address
  -p  Server port

Example Usage:

./DeleteServer -u user123 -i 192.168.10.10 -p 27015

This permanently deletes all server files. There is no recovery option.

Utility Scripts

CheckGame

Queries server status using appropriate protocol commands (rcon, query port, etc.).

./CheckGame -u user123 -i 192.168.10.10 -p 27015 -g csgo -P server.pid

ConfigUpdate

Updates configuration files with new values using pattern matching.

./ConfigUpdate -u user123 -i 192.168.10.10 -p 27015 \
  -f server.cfg -o "hostname" -n "My New Server Name"

Parameters:

-f Config file path
-o Old value or pattern to find
-n New value to set

CreateDirectory

Creates a new directory within a server’s file structure.

./CreateDirectory -u user123 -i 192.168.10.10 -p 27015 -d "custom_maps"

FileContent

Retrieves the contents of a server file (used by file manager).

./FileContent -u user123 -i 192.168.10.10 -p 27015 -f server.cfg

FileSave

Saves content to a server file (used by file editor).

./FileSave -u user123 -i 192.168.10.10 -p 27015 -f server.cfg -c "hostname My Server"

FileDelete

Deletes a file from the server.

./FileDelete -u user123 -i 192.168.10.10 -p 27015 -f oldfile.txt

Installation Scripts

AutoInstall

Automated game server installation using direct download mirrors. Parameters:

./AutoInstall [OPTIONS]

Options:
  -m  Mirror URL(s) - comma-separated for multiple mirrors
  -M  MD5 checksum of download
  -c  Command to run after download
  -i  Template ID
  -C  Callback URL
  -d  Debug mode

Example Usage:

./AutoInstall \
  -m "http://example.com/gamefiles.gz,http://mirror2.com/gamefiles.gz" \
  -M 920df382ab316eca2d5e57fc5581f577 \
  -c "gunzip gamefiles.gz ; mv gamefiles/* . ; rm -fr gamefiles" \
  -i 24 \
  -C "http://panel.example.com/callback.php" \
  >> /dev/null 2>&1 &

Workflow:

Download

Downloads game files from provided mirror(s), trying each in order if one fails

Verification

Verifies MD5 checksum matches expected value

Extraction

Runs the provided command to extract/organize files

Template Creation

Automatically calls CreateTemplate to archive the installation

See SteamCMD Integration for Steam-specific installation scripts.

User Management Scripts

CreateUser

Creates a new system user account for game servers.

./CreateUser -u newuser123 -p "SecurePassword"

DeleteUser

Removes a system user account.

./DeleteUser -u olduser123

ChangePassword

Changes a user’s password.

./ChangePassword -u user123 -p "NewSecurePassword"

Status Checking Scripts

CheckCreateServerStatus

Monitors the progress of server creation.

./CheckCreateServerStatus -u user123 -i 192.168.10.10 -p 27015

Returns:

complete - Server creation finished
running - Still extracting template
failed - An error occurred

CheckUpdateStatus

Monitors game server update progress.

./CheckUpdateStatus -u user123 -i 192.168.10.10 -p 27015

CheckInstall

Checks if a server installation is complete.

./CheckInstall -u user123 -i 192.168.10.10 -p 27015

CheckTemplateStatus

Monitors template creation progress.

./CheckTemplateStatus -i 24

Returns percentage complete or status message.

Script Communication

Callback URLs

Most scripts support callback URLs for status updates:

callback_url="http://panel.example.com/callback.php?id=123&token=abc"
$cback "$callback_url&do=status&update=complete"

Common Callback Parameters:

do=status - Status update type
update= - Status value (complete, failed, running)
percent= - Progress percentage (for downloads/extractions)
error= - Error message if failed

Logging

Scripts log to standardized locations:

$HOME/logs/servers.log      # Server operations
$HOME/logs/steam.log         # Steam installations
$HOME/logs/templates.log     # Template creation

Log Entry Format:

(date) (hostname) ScriptName: Action description

Example:

(2026-03-05 10:30:45) node1.example.com CreateServer: Creating server directory /home/gpxuser/accounts/user123/192.168.1.100.27015 ...

PID File Management

Scripts create PID files to track running processes:

# Server PID
echo $pid > $gpxdir/.gpxserver.pid

# Screen session PID
echo $screen_pid > $gpxdir/.gpxscreen.pid

# Update process PID
echo $steam_pid > $gpxdir/.gpxupdatepid

PID File Locations:

.gpxserver.pid - Main server process ID
.gpxscreen.pid - GNU Screen session ID
.gpxsteam.pid - Steam update process ID
.gpxupdatepid - Generic update process ID

Process Management

GNU Screen Integration

Scripts prefer GNU Screen for server processes when available:

if [ "$(which screen 2>&1 | grep 'no screen in')" ]
then
    # No screen, run directly
    $srv_cmd_line >> $serverlog 2>&1 &
else
    # Use screen for console access
    screen -d -m -S "$srv_ip.$srv_port" $srv_cmd_line
fi

Benefits of Screen:

Access server console remotely
Persistent sessions
Easy process management

Screen Session Naming:

<IP>.<PORT>
Example: 192.168.1.100.27015

Taskset CPU Pinning

Optionally pin servers to specific CPU cores:

if [ "$taskset_cpu" ]
then
    taskset -c $taskset_cpu $srv_cmd_line &
else
    $srv_cmd_line &
fi

Example Usage:

# Pin to CPU core 2
./Restart -u user123 -i 192.168.1.100 -p 27015 -c 2 -o "./hlds_run ..."

Best Practices

Always use absolute paths in callbacks

# ✅ Good
callback_url="http://panel.example.com/callback.php?id=123"

# ❌ Bad
callback_url="callback.php?id=123"

Handle errors gracefully

if [ ! -d $server_dir ]
then
    echo "Error: Server directory does not exist"
    $cback "$callback_url&do=status&update=failed&error=missing_dir"
    exit 1
fi

Clean up temporary files

# Clean up after operations
rm -f /tmp/tempfile_${tpl_id}
rm -rf $HOME/tmp/$tpl_id

Use background processes for long operations

# Fork long operations to background
{
    # Long running task here
    ./steamcmd.sh +app_update 740 validate
    
    # Callback when done
    $cback "$callback_url&do=status&update=complete"
} >> /dev/null 2>&1 &

echo "success"  # Return immediately to PHP

Security Considerations

Remote scripts execute with the privileges of the game server user. Never run these scripts as root.

Security Features:

Scripts use relative paths from $HOME
No scripts execute arbitrary PHP code
File operations restricted to user’s directories
Password parameters should be passed securely
Callback URLs should include authentication tokens

Protecting Scripts:

# _SERVERS/scripts/.htaccess
Order Deny,Allow
Deny from all

Debugging Scripts

Enable debug mode with the -d yes parameter:

./CreateServer -u user123 -i 192.168.1.100 -p 27015 -x 24 -d yes

Debug output includes:

Detailed variable values
Each step of execution
Full error messages
Timing information

Manual Script Testing:

# SSH to game server node as game user
ssh [email protected]

# Navigate to scripts directory
cd scripts/

# Run script manually with test parameters
./CreateServer -u testuser -i 127.0.0.1 -p 27015 -x 24

Common Issues

Permission denied errors

Ensure scripts are executable:

chmod +x $HOME/scripts/*

Missing GNU Screen

Install screen package or scripts will fall back to direct execution:

# Ubuntu/Debian
sudo apt-get install screen

# CentOS/RHEL
sudo yum install screen

Callback failures

Verify network connectivity from node to control panel:

wget -qO- "http://panel.example.com/callback.php?test=1"

PID file issues

Clean stale PID files if processes aren’t tracked correctly:

rm -f $HOME/accounts/user123/192.168.1.100.27015/.gpx*.pid

Advanced Usage

Custom Script Parameters

Extend existing scripts by adding custom parameters:

custom_param=

while getopts "u:i:p:x:C:" OPTION
do
    case $OPTION in
        C)
            custom_param=$OPTARG
            ;;
    esac
done

# Use custom parameter in your logic
if [ "$custom_param" == "special" ]
then
    # Custom behavior
fi

Chain Script Operations

Execute multiple scripts in sequence:

# Create server and immediately start it
$HOME/scripts/CreateServer -u user123 -i 192.168.1.100 -p 27015 -x 24 && \
$HOME/scripts/Restart -u user123 -i 192.168.1.100 -p 27015 -o "./server_start.sh"

Script Exit Codes

Use proper exit codes for automation:

# Success
echo "success"
exit 0

# Failure
echo "failed"
exit 1

Reference

Script Version

Current remote scripts version: v3.0.14 Version information is included in each script header:

#!/bin/bash
#
# GamePanelX
# Remote scripts v3.0.14

Standard Variables

Common variables used across scripts:

$HOME              # User home directory
$srv_username      # Server owner username
$srv_ip            # Server IP address
$srv_port          # Server port
$gpxdir            # Server directory path
$callback_url      # Control panel callback URL
$cback             # Callback command (wget -qO-)

Get Started

Core Features

Administration

Client Portal

Server Management

Advanced

​Script Overview

​Core Scripts

​CreateServer

​Restart

​CreateTemplate

​DeleteServer

​Utility Scripts

​CheckGame

​ConfigUpdate

​CreateDirectory

​FileContent

​FileSave

​FileDelete

​Installation Scripts

​AutoInstall

​User Management Scripts

​CreateUser

​DeleteUser

​ChangePassword

​Status Checking Scripts

​CheckCreateServerStatus

​CheckUpdateStatus

​CheckInstall

​CheckTemplateStatus

​Script Communication

​Callback URLs

​Logging

​PID File Management

​Process Management

​GNU Screen Integration

​Taskset CPU Pinning

​Best Practices

​Security Considerations

​Debugging Scripts

​Common Issues

​Advanced Usage

​Custom Script Parameters

​Chain Script Operations

​Script Exit Codes

​Reference

​Script Version

​Standard Variables

Build docs developers (and LLMs) love

Script Overview

Core Scripts

CreateServer

Restart

CreateTemplate

DeleteServer

Utility Scripts

CheckGame

ConfigUpdate

CreateDirectory

FileContent

FileSave

FileDelete

Installation Scripts

AutoInstall

User Management Scripts

CreateUser

DeleteUser

ChangePassword

Status Checking Scripts

CheckCreateServerStatus

CheckUpdateStatus

CheckInstall

CheckTemplateStatus

Script Communication

Callback URLs

Logging

PID File Management

Process Management

GNU Screen Integration

Taskset CPU Pinning

Best Practices

Security Considerations

Debugging Scripts

Common Issues

Advanced Usage

Custom Script Parameters

Chain Script Operations

Script Exit Codes

Reference

Script Version

Standard Variables