Getting started

Adding a node

A node is a machine that runs game servers. It runs the NGCP agent, which connects out to the controller over mutual TLS. Adding a node takes one command.

Before you start

• The node must reach the controller’s public URL (port 8080 or your HTTPS port) and the AgentLink address (port 8443). Check from the node:

  curl -fsS https://panel.example.com/healthz
  nc -vz panel.example.com 8443
  

  Invoke-RestMethod https://panel.example.com/healthz
  Test-NetConnection panel.example.com -Port 8443
  

• You need administrator (Windows) or root (Linux) rights on the node.

• Linux nodes that will run SteamCMD games need the 32-bit libraries; see Requirements.

1. Create an enrollment token

1. In the panel open Nodes and choose Add a node.
2. Pick the datacenter (or create one inline) and type the node’s name.
3. Keep the default validity of one hour (at most seven days).

The panel shows the token once, together with the CA hash (sha256:...) and ready-made commands for Windows and Linux. The token works one time only. Unused tokens are listed under Nodes and can be cancelled.

The CA hash pins the panel’s internal certificate authority: the agent refuses to enroll if the controller it reaches presents a different CA, and in that case the token is not used up.

2. Run the one-line installer

The panel serves installer scripts that download the agent package from the panel, check its SHA-256, install it and enroll the node.

Linux (as root):

curl -fsSL https://panel.example.com/install/agent.sh | sudo bash -s -- \
  --token ngcpe_... --ca-hash sha256:...

Windows (PowerShell as Administrator):

& ([scriptblock]::Create((irm https://panel.example.com/install/agent.ps1))) -Token ngcpe_... -CaHash sha256:...

Optional: --services-dir /srv/games (Linux) or -ServicesDir D:\games (Windows) to put game servers somewhere other than the default.

The scripts are only as trustworthy as the connection to the panel: serve the panel over HTTPS.

3. Check

The node appears as Online within a few seconds and shows CPU, memory and disks.

Other ways to add a node

• The panel’s own server: when the agent is installed next to the panel (NGCP Setup’s default on Windows, the appliance’s Panel and game servers on Linux), the panel’s setup offers This server runs game servers too. The agent then joins by itself; no token needed.
• NGCP Setup on another Windows computer: tick only Game servers and enter the panel’s address, the token and the CA hash under Options. Unattended: NGCP-Setup-X.Y.Z.exe /quiet InstallController=0 ControllerUrl=https://panel.example.com EnrollToken=ngcpe_... CaHash=sha256:...
• The Linux appliance with the role Game servers only: paste the Linux command from Add a node into its first-boot setup (or later: server menu, Join a panel). See The Linux appliance.

Manual installation

With the agent package

Install the package, then enroll with the command the panel showed:

sudo apt install ./ngcp-agent_X.Y.Z_amd64.deb      # or: sudo dnf install ./ngcp-agent-X.Y.Z-1.x86_64.rpm
sudo ngcp-agent enroll --controller https://panel.example.com --token ngcpe_... --ca-hash sha256:...
sudo systemctl restart ngcp-agent

The packaged service waits until the node is enrolled, so the order does not matter.

The Windows agent MSI can enroll during a silent install:

msiexec /i ngcp-agent-X.Y.Z-x64.msi /qn CONTROLLER_URL=https://panel.example.com ENROLL_TOKEN=ngcpe_... CA_HASH=sha256:... SERVICES_DIR=D:\games

The token is hidden from the MSI log. Without ENROLL_TOKEN the service waits for ngcp-agent enroll.

With the bare binary

Windows (PowerShell as Administrator):

mkdir C:\ngcp; cd C:\ngcp
# copy ngcp-agent.exe here
.\ngcp-agent.exe enroll --controller https://panel.example.com --token ngcpe_... --ca-hash sha256:...
.\ngcp-agent.exe service install

Linux (root):

sudo install -m 0755 ngcp-agent /usr/local/bin/ngcp-agent
sudo ngcp-agent enroll --controller https://panel.example.com --token ngcpe_... --ca-hash sha256:...
sudo ngcp-agent service install

service install registers and starts the Windows service or systemd unit. Use ngcp-agent service status|stop|start|uninstall to manage it. To replace an existing enrollment, add --force to enroll. Without a panel at hand, ngcpctl create-enroll-token creates tokens from the command line (Command line).

What the agent creates

The agent’s private key is generated on the node and never leaves it. The certificate the panel signs is bound to this node’s id; it is valid for two years.

agent.yaml

enroll writes agent.yaml in the data folder. Most fields are filled in by enrollment; these are the ones you may change (restart the agent afterwards):

Node firewall

Switch firewall management off for a node in its settings if you manage the firewall yourself. On Linux without ufw or firewalld the agent changes nothing; open the ports yourself.

Managing nodes

Open a node from Nodes to see its live CPU, memory, disks and network, its inventory and its settings.

• Mode: Active, Draining (keeps its game servers, takes no new ones) or Disabled (takes no new ones). Use Draining before maintenance.
• Settings: name, datacenter, port range (default 27000-29999), services directory, SteamCMD directory, firewall management. The services directory shown is the one the agent reports; change it in agent.yaml.
• Update the agent: sends a signed update to a connected agent. The agent checks the signature before downloading and the checksum after, swaps its binary and restarts through its service manager. Its game servers restart with it, so do this at a quiet time. On Windows the System event log records event 7031 (“terminated unexpectedly”) for this restart; that is expected. Agent builds come with the controller package; see Operations.
• Remove node: revokes the node’s certificate and disconnects it. This is final; to use the machine again, enroll it with a new token. Services on a removed node cannot be force-deleted yet.

Datacenters can be renamed or deleted when empty.

If the node does not come online

More in Troubleshooting.