95 lines
4 KiB
Markdown
95 lines
4 KiB
Markdown
# 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)
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
1. Allow inbound TCP on the agent port.
|
||
2. Allow inbound/outbound UDP/TCP for the games you host.
|
||
3. Allow outbound HTTPS to the panel so the agent can talk to `ogp_api.php`.
|
||
|
||
## Upgrades
|
||
|
||
1. `cd /opt/gsp-agent && git pull`
|
||
2. Stop the service (`sudo systemctl stop ogp_agent`).
|
||
3. Re-run `bash install.sh` if new files were added.
|
||
4. Start the service (`sudo systemctl start ogp_agent`).
|
||
5. 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:
|
||
|
||
1. managed screen session
|
||
2. tracked process PID(s)
|
||
3. 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.
|
||
|
||
## Related docs
|
||
|
||
- [`GSP/documentation/admin-guide.md`](https://github.com/GameServerPanel/GSP/tree/main/documentation) – Panel-side instructions plus XML authoring notes.
|
||
- [`GSP-Agent-Windows/documentation/agent-guide.md`](https://github.com/GameServerPanel/GSP-Agent-Windows/tree/main/documentation/agent-guide.md) – Windows counterpart.
|