Introduction

Concepts

This page explains the words NGCP uses. The rest of the docs assume you know them.

Controller

The controller (ngcp-controller) is the panel. It:

• serves the web interface, the REST API (/api/v1/...) and a WebSocket (/ws) for live updates and consoles;
• stores accounts, nodes, services, game definitions, schedules, backup records and the audit log in PostgreSQL;
• holds the secrets (Steam passwords, backup credentials, two-factor seeds, the internal certificate authority), sealed with the master key;
• listens for agents on the AgentLink port (8443 by default).

There is one controller per installation. Running two controllers against one database for high availability is not supported yet.

Nodes and datacenters

A node is a machine that runs game servers. It runs the agent (ngcp-agent) as a system service: the Windows service NGCP Agent or the systemd unit ngcp-agent. The agent connects out to the controller, so a node needs no inbound port except the game ports and SFTP.

A datacenter is a group of nodes, usually one location. Every node belongs to one. The first-run setup creates a datacenter called Default; rename it or add more under Nodes.

A node has an operator mode:

The mode survives disconnects. Whether the agent is connected right now is shown separately (Online / Offline).

Services

A service is one game server instance: for example “ArmA 3 - Friday ops” on node game-01. A service has:

• a game (its game definition) and a node;
• an owner (a panel user) and optionally sub-users with limited rights;
• a block of ports, a player slot count and its variables (server name, passwords, mods…);
• an install directory <services dir>/svc-<id> on the node, and an operating-system account ngcp_s<id> that owns that directory and runs the game;
• optional limits (CPU, memory, disk quota) and a crash policy.

One service can run several processes: the main server, headless clients (ArmA 3) and sidecars. They start, stop and restart together.

Game definitions

A game definition is a YAML file that tells NGCP everything about a game: which platforms it runs on, how to install and update it (SteamCMD, downloads, git, scripts, files), which ports and variables it has, how to start each process, which config files have forms, how to reach its remote console and status query, and what to back up. See Writing game definitions and the shipped games.

Definitions shipped with NGCP are built-in and are refreshed when you upgrade. A definition you upload or change in the panel becomes custom and is never overwritten by an upgrade. Every saved version is kept, so you can compare versions.

Isolation

The agent runs as LocalSystem (Windows) or root (Linux) because it creates accounts, limits and firewall rules. Game servers never run as the agent:

• Windows: each service gets a local account ngcp_s<id> with a random password (sealed with DPAPI), allowed only to log on as a batch job. Its processes run inside a Job Object with memory, CPU-rate and process-count limits. The install directory is readable only by SYSTEM, Administrators and that account.
• Linux: each service gets a locked system user ngcp_s<id> (no shell, no home). The install tree is owned by it with mode 0750. Its processes run in their own cgroup v2 (cpu.max, memory.max, pids.max), so stopping a service kills every process it started.

HOME, TEMP and similar variables point into the service’s own directory (.home, .tmp). SteamCMD runs under a separate per-node account, ngcp_steam, so game servers cannot read the cached Steam login. Details: Security.

Desired state and observed state

The controller owns what a service should be (its spec: game, ports, variables, limits, schedules, and whether it should be running). The agent owns what is actually happening (the processes). The agent reports state changes; the panel shows them.

This split has practical consequences:

• The controller can restart at any time. Game servers keep running. When an agent reconnects, the controller sends every service’s current spec again; the agent applies only what changed.
• The agent keeps running servers without the controller. It stores each spec on disk and starts every service that should be running when it starts itself.
• Scheduled tasks run on the node, from the stored spec, so a 06:00 restart happens even if the controller is down. See Scheduled tasks.
• Changes to an offline node wait. A service on an offline node cannot be started or stopped. A delete is finished when the node comes back.
• Updating the agent restarts game servers on that node: game processes do not outlive the agent. Plan agent updates for a quiet time.

Ports

A service gets its ports as one block from the node’s port range (27000-29999 by default): a base port plus the fixed offsets the game needs (for ArmA 3: game, +1 query, +2 Steam, +3 voice, +4 BattlEye, +5 RCON). If the game’s usual default port fits inside the node’s range and is free, it is used. Ports used by programs outside NGCP are not detected, so keep other software out of the node’s port range.

Service status

Permissions in one paragraph

Each account has a role (SuperAdmin, Admin, Reseller, User, Sub-user) that grants global permissions such as nodes:write or services:create. Access to a single service is decided by service permissions (view, control, console, files, config, mods, schedule, backups, settings, subusers, reinstall): owners and administrators have all of them; sub-users only what they are granted. See Users and permissions.