# Back up and restore an instance

> Create full backups of an instance, restore one over its disk, and delete the backups you no longer need.

Source: https://docs.coritan.com/cloud-compute/backups/

In the dashboard:

- /dashboard/compute/…/backups: https://www.coritan.com/dashboard/compute

A *backup* is a full copy of an instance's disk, saved as a compressed archive. Restore a backup to put the disk back the way it was when we made the copy. An instance can hold 16 backups.

Each backup is an archive of its own, apart from the disk it copies. When you [rebuild](/cloud-compute/rebuild/) the instance, its backups stay, and you can restore one over the new disk. Cancelling the instance deletes its backups. For quick restore points on the same disk, [take a snapshot](/cloud-compute/snapshots/).

## Before you begin

- The instance is not suspended.
- No other backup, restore or backup deletion is running on the instance. They run one at a time.
- The instance has not used more than its monthly traffic allowance. We make no backups of an instance that is over it until the next month starts. [How instance traffic is counted](/cloud-compute/traffic/) explains the allowance.

## Create a backup

1. In the [dashboard](https://www.coritan.com/dashboard/compute), go to **Cloud Compute**, open the instance and select the **Backups** tab.
2. Select **Create backup…**.
3. Optionally, add a **Note** of up to 255 characters, such as `Before the database migration`. The table shows the note as the backup's name.
4. Under **Mode**, choose how we copy a running instance:
   - **Snapshot (no downtime)** copies the disk while the instance keeps running. It is the default, and it suits most workloads.
   - **Suspend** pauses the instance while we start the copy, then resumes it.
   - **Stop** shuts the instance down, starts the copy and boots the instance again. It gives the most consistent copy, with the longest pause.

   When the instance is stopped, every mode gives the same consistent copy.
5. Under **Compression**, keep **zstd (fast, recommended)** unless you have a reason to change it. **lzo (fastest, larger)** and **gzip (smallest, slowest)** trade speed against size, and **None** stores the copy uncompressed.
6. Select **Start backup**.

The backup appears at the top of the table with the status `Creating`. You can leave the page while it runs. Reload the page to see its progress.

## Restore a backup

Restoring replaces the instance's disk with the backup and loses everything written to the disk since the backup was made.

1. On the **Backups** tab, open the menu at the end of a `Completed` backup's row and select **Restore backup…**.
2. Type `restore` to confirm, then select **Restore backup**.

We stop the instance and write the backup over its disk. When the disk is ready, we start the instance, even if it was stopped before. The backup shows `Restoring` until then, and stays in the table afterwards.

A restore also brings back what the instance was like at the moment of the backup: its password, SSH keys, hostname, network settings and size. After the restore:

- If you changed the password, SSH keys or hostname since the backup, set them again on the [Access tab](/cloud-compute/access/).
- If the instance's address changed since the backup, [regenerate cloud-init](/cloud-compute/access/#regenerate-cloud-init) and restart the instance from the header.
- If you changed the plan since the backup, [contact support](/support/) so we can apply it to the instance again.
- Take new snapshots. The restore replaces the disk that the instance's snapshots belong to, and rolling back to one of them fails.

> [!WARNING]
> Create a fresh backup or snapshot first if you might need the disk's current state.

## Delete a backup

1. On the **Backups** tab, open the menu at the end of the backup's row and select **Delete backup…**.
2. Type `delete` to confirm, then select **Delete backup**.

We delete the archive from backup storage, and the backup leaves the table once it is gone. You cannot undo this.

A backup that shows `Failed` stored nothing. Select **Remove backup…** on its row, then **Remove backup**, to take it off the list.

## Result

The table lists each backup with its **Status**, its **Size** and when it was **Created**, with how long it took under the date. A backup without a note is named by its number, such as `Backup #12`. `Creating`, `Completed` and `Restoring` backups count toward the 16 an instance can hold. `Failed` backups do not.

## Troubleshooting

**Create backup…** is greyed out
: A backup or restore is already running on the instance, or the instance is suspended. Wait for the running one to finish, then reload the page. If the instance is suspended, the alert at the top of the page says why, and you can create backups again once the suspension ends.

`A backup or restore is already in progress on this instance`
: A backup, a restore or a deletion is running on the instance. Wait for it to finish, reload the page and try again.

`Backup limit of 16 reached`
: The instance holds 16 backups. Delete one you no longer need, then create the new one.

`Monthly traffic quota exceeded; backups are blocked until the next period`
: The instance has used more than its traffic allowance this month. You can create backups again when the next month starts. The **Bandwidth** card on the **Console** tab shows the date it resets.

`Too many requests for this action. Please wait and try again.`
: You started more than 8 backups, or more than 8 restores, of the instance within five minutes. Wait a few minutes and try again.

`Cannot delete a backup while it is still running`
: The backup is still being created or restored. Wait until it shows `Completed`, then delete it.

The backup shows `Failed`
: We could not finish the copy. Remove the failed backup and create a new one. If backups keep failing, [contact support](/support/) with the instance's hostname.

The instance does not come back after a restore
: Open the **Console** tab to see what the instance is doing. If it is stopped, start it from the header.

A second floating IP does not answer after a restore
: The restore brings back the network settings from the moment of the backup. For each other floating IP on the instance, [detach it and attach it again](/floating-ips/attach-and-detach/), then restart the instance from the header.

## Related

- [Take and roll back instance snapshots](/cloud-compute/snapshots/) for quick restore points on the same disk.
- [Rebuild an instance](/cloud-compute/rebuild/) explains what a rebuild keeps and erases.
- [How instance traffic is counted](/cloud-compute/traffic/) explains the monthly allowance that backups depend on.
- [Cloud Compute limits](/cloud-compute/limits/) lists the backup limits with the others.

## With the API

`GET /api/v1/client/vps/{uuid}/backups` lists the instance's backups, newest first. Each has an `id`, a `note`, a `status`, `size_bytes`, `created_at` and `completed_at`, and `proxmox_volid`, the archive's name in backup storage. `status` is `creating`, `completed`, `failed`, `restoring` or `deleting`.

`POST /api/v1/client/vps/{uuid}/backups` starts a backup. Every field is optional:

- `note`: up to 255 characters.
- `mode`: `snapshot` (the default), `suspend` or `stop`.
- `compress`: `zstd` (the default), `lzo`, `gzip`, or `0` for none.

```bash
curl -X POST https://api.coritan.com/api/v1/client/vps/$INSTANCE_UUID/backups \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note": "Before the database migration", "mode": "snapshot", "compress": "zstd"}'
```

```json
{"backup_id": 12, "status": "creating", "mode": "snapshot"}
```

The request returns as soon as we queue the backup. List the backups again until its `status` is `completed` or `failed`.

`POST /api/v1/client/vps/{uuid}/backups/{backup_id}/restore` takes no body and restores a `completed` backup. It answers `{"status": "restore_queued"}`. The backup's `status` is `restoring` until the instance runs again, then returns to `completed`. `GET /api/v1/client/vps/{uuid}/tasks` shows the host's `qmrestore` task and then its `qmstart` task.

`DELETE /api/v1/client/vps/{uuid}/backups/{backup_id}` deletes a backup and answers `{"status": "delete_queued"}`. The backup shows `deleting` until we remove it from the list.

These requests can answer:

- `400` with `mode must be snapshot, suspend, or stop` for another `mode`.
- `403` with `Monthly traffic quota exceeded; backups are blocked until the next period` when you start a backup of an instance that is over its allowance.
- `404` with `Backup not found` when the instance has no backup with that `id`, or `Backup not found or not completed` when you restore a backup that is not `completed`.
- `409` with `A backup or restore is already in progress on this instance`, `Backup limit of 16 reached` or `Cannot delete a backup while it is still running`.
- `409` while we move the instance to another host: `Instance is migrating` for a new backup, and a message that starts `Cannot restore` or `Cannot delete a backup` for the others.
- `429` for more than 8 new backups, or more than 8 restores, of one instance in five minutes, as [Rate limits](/api/rate-limits/) describes.

The [Cloud Compute API reference](/api/reference/client/cloud-compute/#op-post-api-v1-client-vps-uuid-backups) lists every field.

## API

- `GET /api/v1/client/vps/{uuid}/backups`: List backups for this instance (https://docs.coritan.com/api/reference/client/cloud-compute/#op-get-api-v1-client-vps-uuid-backups)
- `POST /api/v1/client/vps/{uuid}/backups`: Create a new backup of this instance (https://docs.coritan.com/api/reference/client/cloud-compute/#op-post-api-v1-client-vps-uuid-backups)
- `DELETE /api/v1/client/vps/{uuid}/backups/{backup_id}`: Delete a backup (https://docs.coritan.com/api/reference/client/cloud-compute/#op-delete-api-v1-client-vps-uuid-backups-backup-id)
- `POST /api/v1/client/vps/{uuid}/backups/{backup_id}/restore`: Restore from a backup (https://docs.coritan.com/api/reference/client/cloud-compute/#op-post-api-v1-client-vps-uuid-backups-backup-id-restore)