# 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.

Source: https://featherpanel.com/docs/wings/node-backups/

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](https://featherpanel.com/docs/wings/server-backups)).

## Modes

| Mode | Contents |
|------|----------|
| `volumes` | Server files from `system.data` (default `/var/lib/featherpanel/volumes`) |
| `user_backups_only` | Server backups from `system.backup_directory` |
| `full` | Both of the above plus `/etc/featherpanel/config.yml` |

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

```bash
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](https://featherpanel.com/docs/cli/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.

| Type | Fields |
|------|--------|
| SFTP | host, port (default 22), username, password or private key with passphrase, base path |
| S3 | endpoint (empty for AWS), region (default `us-east-1`), bucket, prefix, access key, secret key, path-style addressing (on by default) |

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

```bash
# 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](https://featherpanel.com/docs/wings/api).

| Method | Path |
|--------|------|
| `POST` | `/api/system/node-backup` |
| `GET` | `/api/system/node-backups` |
| `GET` | `/api/system/node-backups/{uuid}` |
| `GET` | `/api/system/node-backups/{uuid}/download` |
| `DELETE` | `/api/system/node-backups/{uuid}` |
| `POST` | `/api/system/node-backup/restore` |

## Frequently asked questions

### Are node backups the same as server backups?

No. A server backup holds one server and is created by its users. A node backup is a single archive of everything on a node, made by an administrator. See Server backup drivers for the per-server kind.

### Do node backups include the database of the panel?

No. They only contain files on the Wings machine. Back up the panel separately, see Panel backups.