Linux Agent Operations Guide

Packaged copy of the instructions we keep in the staff wiki so you can view them offline or import them into any other knowledge base.

Purpose

The Linux agent (ogp_agent.pl) exposes the RPC endpoint that allows the GameServer Panel to install, start, stop, and monitor game servers on Linux hosts. Every host that runs customer games must run this service.

Supported platforms

Ubuntu 20.04/22.04/24.04 LTS
Debian 11/12
Rocky/AlmaLinux 8+
Any modern distribution with Perl 5.30+, GNU Screen, and rsync

Installation (Ubuntu example)

sudo apt update
sudo apt install -y git curl rsync screen perl libxml-parser-perl libpath-class-perl libarchive-zip-perl libhttp-daemon-perl
sudo git clone https://github.com/GameServerPanel/GSP-Agent-Linux.git /opt/gsp-agent
cd /opt/gsp-agent
sudo bash install.sh
sudo bash agent_conf.sh -s "root-password" -u ogp_agent

agent_conf.sh writes /home/ogp_agent/Cfg/Config.pm. Set:

Key	Description
`listen_ip`	Interface to bind (use `0.0.0.0` unless you want to restrict access).
`listen_port`	TCP port exposed to the panel. Default is `12679`.
`key`	Shared secret copied from the panel → Administration → Game Servers.
`web_api_url`	HTTPS URL to `ogp_api.php` on the panel.
`agent_event_url`	HTTPS URL to `agent_event_receiver.php` on the panel for lifecycle activity-log events.
`remote_server_id`	Panel remote server ID for this agent. Required for signed lifecycle event delivery.
`stats_db_*`	Optional MySQL credentials for the resource stats cron.

Service management

sudo cp systemd/ogp_agent.service /etc/systemd/system/
sudo sed -i "s#{OGP_AGENT_PATH}#/opt/gsp-agent#g" /etc/systemd/system/ogp_agent.service
sudo systemctl daemon-reload
sudo systemctl enable --now ogp_agent

Logs live next to the binaries (/opt/gsp-agent/ogp_agent.log). Individual game servers stream to their own console.log files inside each home folder.

Firewall checklist

Allow inbound TCP on the agent port.
Allow inbound/outbound UDP/TCP for the games you host.
Allow outbound HTTPS to the panel so the agent can talk to ogp_api.php.

Upgrades

cd /opt/gsp-agent && git pull
Stop the service (sudo systemctl stop ogp_agent).
Re-run bash install.sh if new files were added.
Start the service (sudo systemctl start ogp_agent).
Verify the panel shows the agent as “online”.

Troubleshooting

tail -f ogp_agent.log – handshake failures usually mean the encryption key or port mismatches the panel entry.
journalctl -u ogp_agent – capture Perl stack traces and missing dependency errors.
screen -ls – confirm customer servers are running in screen sessions.
nc -vz panel.example.com 12679 from the panel host – ensures the agent port is reachable.

Server lifecycle tracking

The Linux agent now keeps per-home PID metadata under:

runtime_status/pid-<home_id>.kv

This metadata is used by stop/restart verification in addition to screen and port checks.

Stop escalation now verifies all of the following are cleared before success:

managed screen session
tracked process PID(s)
listening game port

Lifecycle control no longer uses game-home SERVER_STOPPED marker files.

See docs/AGENT_ACTIVITY_EVENTS.md for Panel activity-log event delivery, offline queue behavior, and troubleshooting. Explicit stop intent and autorestart suppression are now controlled through agent-owned runtime status hints (STOPPING/STOPPED) and verified runtime checks.

Restart remains stop-first and waits 60 seconds, then re-verifies stop completion before starting again to avoid duplicate instances.

GSP/documentation/admin-guide.md – Panel-side instructions plus XML authoring notes.
GSP-Agent-Windows/documentation/agent-guide.md – Windows counterpart.

4 KiB Raw Permalink Blame History Unescape Escape