Running game servers

RCON and player counts

Many game servers have a remote console (RCON) for admin commands, and answer a status query with their player count. NGCP uses both: an RCON console in the panel, graceful stops and player warnings over RCON, and player counts on each service.

Which protocols a game uses is set in its game definition (rcon and query sections). The agent always talks to the game on 127.0.0.1 on the node, so the RCON port does not need to be open to the internet; keep it closed.

Supported protocols

RCON type	Games (examples)	Notes
`source`	Counter-Strike 2 and other Source-engine servers	Valve Source RCON over TCP.
`battleye`	ArmA 3, DayZ	BattlEye RCon over UDP.
`minecraft`	Minecraft: Java Edition	Minecraft RCON (Source-style) over TCP.
`ts3query`	TeamSpeak 3	ServerQuery; logs in as `serveradmin` unless the definition names another user.

Query type	What it returns
`a2s`	Steam server query (A2S_INFO): players, max players, server name, map, version. Used by Source games, ArmA 3, Valheim and many others.
`minecraft`	Minecraft server-list ping: players, max players, message of the day, version.
`generic`	Only whether the port accepts a TCP connection (online / offline).

The shipped definitions use: ArmA 3 BattlEye RCon + A2S; Minecraft RCON + Minecraft ping; Counter-Strike 2 Source RCON + A2S; Valheim A2S only (no RCON).

RCON passwords come from service variables that NGCP generates at creation (for example be_password for ArmA 3, rcon_password for Minecraft and CS2) and writes into the game’s config through bound settings. You do not need to set them by hand.

The RCON console

Each service whose game has an rcon section has an RCON console, next to the normal console. Open the service’s Console tab and switch from Server console to RCON. The switch is shown for games with RCON; commands can be sent while the server is running. Using it needs the service permission console.

One command per line, at most 512 characters, no control characters.
The service must be running (or starting) and its node online.
The answer is shown when the game replies (up to 30 seconds; the output is capped at 256 KiB).
Every command is recorded in the audit log (service.rcon, with the command text).

curl -s -X POST https://panel.example.com/api/v1/services/12/rcon \
  -H "Authorization: Bearer ngcpk_..." -H "Content-Type: application/json" \
  -d '{"command": "players"}'

{"output": "Players on server:\n[#] [IP Address]:[Port] [Ping] [GUID] [Name]\n...", "at": "2026-11-06T18:00:00Z"}

Error message	Meaning
`this game has no remote console`	The game definition has no `rcon` section.
`the service is not running`	Start the server first.
`the game rejected the RCON password`	The password in the game’s config differs from the panel’s. Restart the server so bound settings are written again, or check a hand-edited config.
`the game did not answer (is RCON enabled and the server up?)`	RCON is off in the game’s config, the game is still starting, or the port is wrong.
`the service's node is offline`	The node’s agent is not connected.

Graceful stop over RCON

A process can be stopped with an RCON command instead of (or as well as) a console command, through stop.rcon in the game definition. ArmA 3 uses #shutdown:

stop: {rcon: "#shutdown", timeout_sec: 15}

On Stop the agent sends the command, writes “sent #shutdown over RCON” to the console and waits up to timeout_sec. If the game has not exited by then, the agent terminates it and, five seconds later, kills whatever is left. If the RCON command fails, the console says why and the timeout still applies, so a stop always finishes.

Helper processes such as ArmA headless clients have no stop command of their own. As soon as the main server has exited, the agent ends them too, so the stop does not wait for the timeout. On an ArmA 3 server with two headless clients a stop takes about three seconds.

Player warnings

Scheduled restarts, stops and updates can warn players a few minutes ahead (see Scheduled tasks). The warning is sent over RCON with the game’s “say” command:

RCON type	Command sent
`battleye`	`say -1 <message>`
`source`, `minecraft`	`say <message>`
`ts3query`	`gm msg=<message>`

Games without RCON cannot be warned; the task still runs.

Player counts

While a service runs, the agent queries it every 5 seconds (each query times out after 3 seconds) and reports:

Field	Meaning
`players`, `max_players`	Players online and the maximum the game reports. Empty when unknown (stopped, no query, or no answer).
`query_name`	The server name the game reports.
`query_map`	The current map.
`query_at`	When the last answer came.

These fields are part of the service in the API (GET /api/v1/services/{id}) and of the live service:<id> WebSocket events. The player count is also stored with each CPU / memory sample, so GET /api/v1/services/{id}/metrics returns it over time. The service header and the services list show “players / max”, and the Overview tab has a “Players online” chart.

The player count is also what only when empty in scheduled tasks uses: a restart is skipped while players are online. When the count is unknown, the task runs.

The query runs on the node itself, so a working count does not prove that players outside can reach the server. Test that from another network with the game’s server browser.