Node backups

Back up a whole FeatherWings node, schedule node backups to SFTP or S3 from the panel, and move a node to a new machine with a migration package.

A node backup is one .tar.gz archive of a Wings machine. It is separate from the backups users make of their own servers (see Server backup drivers).

Modes

Archives are written to system.node_backup_directory, by default /var/lib/featherpanel/wings_backup. That folder is outside the volumes, so it cannot be reached over SFTP. Each archive has a .meta.json file next to it with its mode, status, size and SHA-1 checksum.

From the command line

featherwings node-backup create --mode full
featherwings node-backup list
featherwings node-backup restore <uuid>
featherwings node-backup delete <uuid>

create defaults to --mode volumes. Stop game servers first if you need a consistent copy, Wings reads the files while they may still be written to.

A restore extracts the archive back into place: volumes/ into system.data, backups/ into system.backup_directory (skipped for a volumes archive) and config/config.yml to the config path. It refuses to extract more than 50 GiB in total, as a guard against corrupt or hostile archives.

The panel installer offers the same actions under Wings, Backup Manager.

Scheduled backups from the panel

Admin, Wings Backups (permission admin.wings.backups.view to look, admin.wings.backups.manage to change) uploads node backups to remote storage on a schedule.

Destinations

A destination is an SFTP server or an S3 bucket. Credentials are stored encrypted.

Use Test on a destination to check the credentials. The result and time are saved with the destination.

Policies

A policy picks the nodes (all nodes or a list), the mode, a primary destination, optional mirror destinations and a cron schedule (minute, hour, day of month, month, day of week, plus a time zone). It also has a retention in days (default 90) and an option to delete the local archive once it is uploaded (on by default).

The node-backup-agent-processor cron task runs every minute and starts each policy that is due. You can also start one with Run now. For every node in the policy the panel:

1. Skips the node if Wings does not answer.
2. Asks Wings to create a backup in the policy mode and waits up to an hour for it to finish.
3. Downloads the archive and uploads it to wings/<node uuid>/<UTC date>_<mode>.tar.gz on the primary destination and every mirror.
4. Deletes the archive on the node when the policy says so.

After the run, objects under wings/ older than the retention period are deleted from the policy destinations. A retention of 0 keeps everything. Each run is listed under the policy with its status (completed, partial or failed) and one line per node. A policy left in the processing state for more than 120 minutes is reset by the cron task.

Moving a node to a new machine

# old machine
featherwings node-backup export --out /var/lib/featherpanel/wings_migrations

# new machine, after installing FeatherWings
featherwings node-backup import --file /var/lib/featherpanel/wings_migrations/featherwings_migration_<date>.tar.gz

export makes a full archive with migration notes inside and copies it to the --out folder as featherwings_migration_<date>.tar.gz. Copy the file to the new machine, import it, then update the node’s IP or FQDN in the panel if it changed and restart featherwings.

HTTP API

The panel uses these endpoints with the node token. They are listed with all others in the Wings HTTP API reference.