Administration

Operations

Running NGCP day to day: upgrades, backing up the panel, logs, health checks and removal.

Upgrading

The controller

Install the newer package over the old one. Configuration, keys, the database and game files stay.

sudo apt install ./ngcp-controller_X.Y.Z_amd64.deb
sudo dnf install ./ngcp-controller-X.Y.Z-1.x86_64.rpm

msiexec /i ngcp-controller-X.Y.Z-x64.msi /qn

On start the controller applies pending database migrations (NGCP_AUTO_MIGRATE=true, which the setup writes). Without it, a controller on an older schema refuses to start with “run ngcpctl migrate or start with -auto-migrate”. A controller older than its database refuses to start too (“database schema N is newer than this binary”): do not downgrade without restoring a database backup.

Game servers keep running during a controller upgrade; agents reconnect within seconds. Shipped game definitions are refreshed when the new version brings a higher definition version; your custom definitions are never touched.

Back up the database and master key before every upgrade. Upgrades between package versions have not been tested much yet (0.6.0 was the first packaged release).

The agents

The controller package carries the matching agent builds. Update each node from its page in Nodes with Update the agent. The update is signed and checked, the agent restarts through its service manager, and its game servers restart with it (players are dropped for a short time). Do it in a quiet hour.

You can also install the newer agent package on the node directly; the enrollment is kept.

Backing up the panel

Service backups (Backups) protect game files. The panel itself needs its own backup of:

Store the master key separately from the database dump.

Dumping the database

Linux, built-in database:

sudo -u ngcp pg_dump -Fc -d ngcp > /root/ngcp-$(date +%F).dump

Windows, built-in database (PowerShell as Administrator):

$cfg = 'C:\ProgramData\NGCP\Controller\controller.env'
$url = (Select-String -Path $cfg -Pattern '^NGCP_DATABASE_URL=').Line.Substring(18)
& 'C:\Program Files\NGCP Controller\pgsql\bin\pg_dump.exe' --format=custom --file "D:\Backups\ngcp-$(Get-Date -Format yyyy-MM-dd).dump" --dbname $url
Copy-Item C:\ProgramData\NGCP\Controller\master.key D:\Backups\keys\

Docker:

docker compose exec -T db pg_dump -U ngcp -Fc ngcp > ngcp-$(date +%F).dump

An existing PostgreSQL: use your usual pg_dump or backup tooling.

Run this on a timer on the controller host (cron or a Windows scheduled task) and copy the dumps off the machine.

Restoring the panel

1. Install the same controller version (or newer) on the target machine, but do not run the setup yet.

2. Put back controller.env, master.key and the TLS files.

3. Restore the dump into an empty database and make sure NGCP_DATABASE_URL points at it:

   sudo -u ngcp pg_restore --clean --if-exists --no-owner -d ngcp /root/ngcp-2026-11-06.dump
   

4. Start the controller. Keep the same agent address (DNS name and port 8443): agents reconnect on their own because the CA and their certificates are in the restored database.

When an agent reports a service the restored database does not know (created after the dump), the controller stops that service on the node and forgets it, but leaves its files. Services that were deleted after the dump come back in the panel; delete them again.

Logs

More detail: set NGCP_LOG_LEVEL=debug in controller.env or log_level: debug in the agent’s agent.yaml and restart.

journalctl -u ngcp-controller -f
journalctl -u ngcp-agent --since "1 hour ago"

Get-Content C:\ProgramData\NGCP\agent.log -Tail 50 -Wait

The Audit log in the panel records who did what; logs record what the programs did.

Health checks

curl -fsS https://panel.example.com/healthz

Housekeeping the controller does by itself

• Expired sessions and two-step challenges are deleted every hour.
• Scheduled-task run history older than 90 days is deleted.
• Notification deliveries older than 30 days are deleted.
• Staged uploads nobody finished are deleted by the node after a day.

The audit log and metric samples are kept; retention and down-sampling for metrics are planned.

Controller service commands

sudo systemctl restart ngcp-controller
sudo ngcp-controller setup-url        # setup page address (only before the setup is done)

Restart-Service NGCPController
& 'C:\Program Files\NGCP Controller\ngcp-controller.exe' service status

Uninstalling

Controller

• Windows: remove NGCP Controller in Settings -> Apps. The services and program folder go; C:\ProgramData\NGCP\Controller (configuration, master key, built-in database data) stays. Delete that folder too for a complete removal.

• Linux: sudo apt remove ngcp-controller or sudo dnf remove ngcp-controller. /etc/ngcp and the database stay. For a complete removal:

  sudo -u postgres dropdb ngcp
  sudo -u postgres dropuser ngcp
  sudo rm -rf /etc/ngcp /var/lib/ngcp-controller
  

A reinstall over kept data comes back in normal mode with everything as it was.

Agent

Removing the agent package stops the agent and therefore its game servers. Enrollment data, service accounts and game files stay. For a clean node:

1. Delete the node’s services in the panel (this removes their files, accounts and firewall rules) or move what you need off the node first.
2. Remove the node in the panel (Remove node).
3. Uninstall the agent (Settings -> Apps -> NGCP Agent, or sudo apt remove ngcp-agent).
4. Delete the data and services folders: C:\ProgramData\NGCP and C:\ngcp, or /var/lib/ngcp and /opt/ngcp.