Automation

Backups

NGCP backs up a service’s files to a backup target: a folder on the node, an SFTP server, or S3-compatible object storage. Backups are made and restored by the node’s agent, which streams the archive straight to the target without a temporary copy on disk.

Administrators manage targets on the Backups page (left menu). Each service has a Backups tab for manual backups, restores and deletes; the service’s Schedule tab sets up regular ones.

Backup targets

Targets are managed by administrators (permission backups:global, which Admins and SuperAdmins have). Each target has a name, a kind, its connection settings, retention, and a switch user selectable: when on, service owners and sub-users may back up to it; when off, only administrators can use it.

Local folder

An absolute folder on the node that runs the service, for example /srv/backups or D:\Backups. Each node writes to its own disk, so this protects against mistakes, not against losing the node. Combine it with an off-site target.

SFTP

Get the fingerprint on the SFTP server itself:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

or from another machine you trust:

ssh-keyscan -t ed25519 backup.example.com | ssh-keygen -lf -

Use the SHA256:... part.

S3-compatible storage

Works with AWS S3, MinIO, Backblaze B2, Wasabi and other S3-compatible services. Large backups are uploaded in parts.

Endpoint examples:

Secrets

Passwords, private keys and secret keys are sealed with the panel’s master key (AES-256-GCM) and are write-only: the API only says whether one is set. They are sent to a node only when that node needs them: with a manual backup, restore or delete command, and inside the spec of services that have a scheduled backup to that target.

Retention

Retention is applied per service, right after each successful backup to that target. A backup is deleted when it is older than keep_days or when there are already keep_last newer ones. The backup just made is never deleted. With both at 0 nothing is ever deleted.

Example: add an S3 target

curl -s -X POST https://panel.example.com/api/v1/backup-targets \
  -H "Authorization: Bearer ngcpk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "Off-site S3",
    "kind": "s3",
    "config": {"endpoint": "s3.eu-central-1.amazonaws.com", "bucket": "ngcp-backups",
               "region": "eu-central-1", "access_key": "AKIA...", "use_tls": true, "prefix": "ngcp"},
    "secret_key": "...",
    "keep_last": 14,
    "keep_days": 30,
    "user_selectable": true
  }'

Changing a target sends the new settings to the services that use it. A target cannot be removed while a scheduled task backs up to it (“N scheduled tasks back up to this target”). Removing a target leaves its backups where they are; the panel can no longer restore them.

What a backup contains

A backup is one .tar.gz of the service’s install directory, filtered by the game definition’s backup rules:

• include globs: only these files (empty = everything);
• exclude globs: never these files.

Never included: symbolic links, devices and the agent’s own .ngcp folder.

Files that the running game keeps locked (common on Windows) cannot be read. They are skipped and the backup reports “N files could not be read (in use?) and are not in the backup”. The backup still completes.

Backups are stored as:

<prefix>/svc-<service id>/<UTC time>-<random>.tar.gz
e.g. ngcp/svc-12/20261106T060000Z-a1b2c3.tar.gz

The archive is a standard tar.gz: you can open it with any archive tool if the panel is gone.

Consistent backups

A backup runs while the server keeps running. For games that keep their world in memory, make sure it is saved first:

• A game definition can have a before_backup hook, a script that runs as the service account before every backup (for example a save command). See Writing game definitions.
• Or schedule an rcon task a minute before the backup task, for example save-all for Minecraft.
• Or back up a stopped server: schedule stop, then backup, then start.

Making a backup

Manual backups need the service permission backups and the node must be online. The service can be running. A backup cannot be started while the service is installing or being deleted, and only one backup or restore runs per service at a time.

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

The answer is 202 Accepted with the new backup in state pending. It moves to running and then completed (with its size) or failed (with the reason). The service console shows “backup to started” and the result. Scheduled backups use the backup action of scheduled tasks.

List a service’s backups (and the targets you may use):

curl -s https://panel.example.com/api/v1/services/12/backups -H "Authorization: Bearer ngcpk_..."

Restoring a backup

Restoring needs the service permission backups. Only a completed backup whose target still exists can be restored, and not while the service is installing, suspended or being deleted.

curl -s -X POST https://panel.example.com/api/v1/services/12/backups/345/restore \
  -H "Authorization: Bearer ngcpk_..."

What happens:

1. The agent stops the service.
2. It downloads and unpacks the backup into a staging folder inside the service directory. If the download or unpacking fails, nothing has been changed and the server is as it was.
3. It deletes the files the backup rules cover and moves the restored files in. Files outside the backup rules (for example ArmA’s mods/ folder or the game binaries) are left alone.
4. It gives all files back to the service’s account.
5. If the service was running before, it starts it again.

The backup shows restore_status running, then completed or failed. Notifications restore.completed / restore.failed can tell you.

Deleting a backup

curl -s -X DELETE https://panel.example.com/api/v1/services/12/backups/345 -H "Authorization: Bearer ngcpk_..."

The agent removes the file from the target. A backup that never completed, or whose target was removed, is only forgotten by the panel. A backup cannot be deleted while it is being made or restored.

Notifications

Webhooks can subscribe to backup.completed, backup.failed, restore.completed and restore.failed. See Notifications.

Backing up the panel itself

Service backups do not include the panel’s own database or master key. See Operations.