Windows Agent Operations Guide

This Markdown file mirrors the internal WDS wiki instructions so you can ship it with release archives or import it into any other knowledge base.

Workspace reference: GSP-WORKSPACE.md

Purpose

The Windows agent bundles Cygwin, Perl, GNU Screen, and helper scripts so the GameServer Panel can manage Windows Server 2019/2022 game hosts. It exposes the same RPC surface as the Linux agent and expects the same shared key.

Requirements

Windows Server 2019 or 2022 (English locale recommended)
Administrator privileges
Reliable network access to the panel on TCP 12679 (or whatever port you configure)
Outbound HTTPS so the agent can talk to ogp_api.php

Installation workflow

Clone or download the repository to C:\\gsp-agent.
Run Install\\onceinstall_agent.bat as Administrator. The script:
- Installs Cygwin with Perl, rsync, wget, screen, zip/unzip, git, etc.
- Creates the gameserver Windows account and grants “Log on as a service”.
- Unpacks the latest agent files into C:\\OGP.
- Registers the Windows Task Scheduler entry that boots the agent at startup.
Open the bundled Cygwin terminal and configure the agent:
```
cd /OGP
bash agent_conf.sh -p "gameserverPassword"
```
Edit configuration – /OGP/Cfg/Config.pm mirrors the Linux agent. Set listen_ip, listen_port, key, web_api_url, agent_event_url, remote_server_id, and (optionally) the stats database credentials.
Start the service – The installer already created a scheduled task (“OGP agent start on boot”). Run it immediately from Task Scheduler or execute schtasks /Run /tn "OGP agent start on boot".

Updating the agent

Manual update:

Stop the scheduled task or kill any running ogp_agent.pl processes.
Pull the latest files (git pull inside C:\\gsp-agent or download the release ZIP again).
Copy updated files into C:\\OGP.
Re-run rebase_post_ins.bat if new Cygwin DLLs were added.
Start the agent task again.

Restart-time auto-update:

Edit /OGP/Cfg/bash_prefs.cfg.
Set agent_auto_update=1.

Keep the default Forgejo values unless you are testing another branch:

agent_update_repo_url=http://forge.runlevelsystems.com/dev/GSP.git
agent_update_branch=Panel-unstable
agent_update_raw_url=http://forge.runlevelsystems.com/dev/GSP/raw/branch/Panel-unstable/Agent-Windows/OGP64/OGP/ogp_agent.pl

Restart the agent with C:\\OGP64\\agent_start.bat or C:\\OGP64\\OGP\\Install\\agent_start.bat.

The updater downloads to a temporary file, rejects empty files, HTML error pages, Not found responses, and files without the expected Perl agent markers, then runs perl -c before replacing /OGP/ogp_agent.pl. Failed auto-update attempts are non-fatal and continue with the last known good agent. The restart-time updater is allowlisted to /OGP/ogp_agent.pl only and must not overwrite /OGP/Cfg/*, service settings, passwords, server data, or logs.

Logging & troubleshooting

Main log: C:\\OGP\\ogp_agent.log
PID files: ogp_agent_run.pid (wrapper) and ogp_agent.pid (Perl daemon)
Customer servers run inside GNU Screen sessions—attach via C:\\OGP\\bin\\screen -r ogp_agent
Server readiness uses the server_status RPC and validates only the game/query/RCON ports supplied by the Panel.
Port validation settings live in /OGP/Cfg/Preferences.pm: PortValidationEnabled, StartupValidationTimeoutSeconds, and PortCheckIntervalSeconds.
Panel activity-log lifecycle event delivery is documented in docs/AGENT_ACTIVITY_EVENTS.md.
Port validation smoke test: bash /OGP/tests/port_validation_smoke.sh 2302/udp 2303/udp.
Firewall: open TCP 12679 (or your configured port) and any game-specific ports before provisioning.
Authentication errors almost always mean the key in Cfg/Config.pm does not match the value stored in the panel → Administration → Servers.
/OGP/Cfg/bash_prefs.cfg must use LF line endings and no leading whitespace before assignments. The launcher normalizes this automatically before sourcing the file.
./ogp_agent.pl: line 1: Not: command not found means the agent file was replaced with text/HTTP error content. Restore a backup or enable auto-update after confirming the Forgejo raw URL above is reachable.
The user name could not be found. NET HELPMSG 2221. came from the legacy root launcher that queried cyg_server. Use the maintained launchers above; they do not require that user for manual foreground startup.

Usage tips

Always run the installer as Administrator so it can write to Program Files, register services, and manage the gameserver account.
Keep the team@worlddomination.dev mailbox handy for provider login challenges when managing Windows hosts.
The Linux agent docs live in GSP-Agent-Linux/documentation/agent-guide.md and the panel XML reference is in GSP/documentation/.

4.9 KiB Raw Permalink Blame History Unescape Escape