Backups and restore

Make a backup

Website
ghost

Make hosted or local backups on the instance’s Backups tab, directly on the website. It offers a local backup only where the instance’s host has room for one of its disk, and shows what a backup costs per GiB to create, to restore and for storage. Making one accepts at most the charge for a backup as large as the disk, and needs that much available and $1 beside.

ghost backup create <INSTANCE_UUID> --destination local --wait
ghost backup create <INSTANCE_UUID> --destination hosted --wait

backup create prints what it costs before it signs the charge: a backup’s price per GiB and the most it can cost for the instance’s disk, with the storage and restore prices it will keep.

Destination	Where it is kept	Restores to
`local`	On a drive of the instance’s host	Its original host only
`hosted`	Independent off-host storage: the platform’s object storage nearest to the instance’s host by distance, currently in Frankfurt (Germany), Los Angeles (USA), or Singapore	Any architecture-compatible offering

What a backup costs, and when it is charged, is under Backups on the pricing page.

Hosted backups

A hosted backup stays where it is kept: its restores and the instances created from it read it from there, and when that storage is unavailable the backup fails rather than going elsewhere.
The host encrypts it before it leaves. The website creates hosted backups itself, encrypted to the account’s current recovery public key.
It uploads at up to its host’s backup upload limit, which all hosted backups of the host share: 32 Mbit/s, about 4 MB/s, unless the provider set another.

How a backup is made

The source hypervisor compresses and encrypts each local or hosted backup while streaming it from the instance, and stores all-zero regions of the disk without data.
Backups and restores are bounded streams rather than full temporary disk copies. Running instances use a point-in-time pull backup; stopped instances use a read-only disk export.
A backup keeps the firmware, BIOS or UEFI, that its instance booted with.

Backing up a running instance

A running instance can always be backed up, and keeps running meanwhile.

Its host keeps 16 GiB for the blocks the instance overwrites during the backup.
An instance that overwrites more than that before the backup has read its disk is paused until it has, and resumed then: nothing it wrote is lost, but it does not answer meanwhile, for as long as the rest of the backup takes. The job’s result says whether that happened (upload_parts.guest_paused).
Back up an instance that writes a lot while it is stopped, or when it writes least.
A stopped instance’s backup needs no room for writes, so its hosted backup keeps nothing on the host. The instance cannot be started until its backup has finished.

Waiting for a turn

A host makes two backups or restores at a time, of running instances or stopped ones. A further one is accepted and waits for its turn, and its job says so and how many are ahead of it, for example waiting for a backup slot on its host, which works on 2 backups or restores at a time; 1 ahead. On the website, its progress line says so.

The backups of running instances also take turns at the host’s two 16 GiB scratches, so a third such backup can wait for one.
An instance takes no other job while its backup waits or runs.

State	Meaning
`queued`	Waiting for its turn
`staging`	The host has begun it
`uploading`	A hosted backup uploads and finishes
`available`	Done

When a local backup does not fit

A local backup reserves room for its artifact, about the root disk, in the host’s backup storage. Each offering’s backup_limits says which backups fit on every one of its hosts while nothing else holds that storage: local_running, local_stopped, and hosted_running. A local backup the host cannot take is refused with a message that names the sizes and what would fit, and says whether a hosted backup would fit:

Code	Meaning	What to do
`local_backups_unavailable`	The host has no backup storage and keeps no local backup of any size	Use `--destination hosted`
`backup_too_large_for_host`	No backup storage of the host could hold a local backup’s artifact even when empty	Use `--destination hosted`
`backup_storage_busy`	Other local backups fill that storage	When some are still running, retry once they finish. Stored local backups keep their room until they are deleted, so otherwise delete a local backup of yours on that host, or use `--destination hosted`

Cancel beside the backup on the instance’s Backups tab and the Backups page, or Cancel backup on the backup’s own page, withdraws a backup that still waits for its turn.

ghost backup cancel <BACKUP_UUID>

A backup that still waits is cancelled at once and costs nothing, and the instance takes other jobs again. The backup then counts as deleted, and its job, which the command names, as cancelled.
A backup the host has begun is refused with backup_started; it runs to its end, and you can delete it then.
Only the platform’s operator can cancel a backup the host has begun: if one holds your instance too long, open a support ticket. Such a backup reads failed (on the website, it shows as failed), its job is cancelled with cancelled_by_operator, and nothing is charged for it.

List and inspect backups

ghost backup list
ghost backup list <INSTANCE_UUID>
ghost backup list --all
ghost backup get <BACKUP_UUID>

The website’s Backups page lists your backups, and each backup has its own page (/backups/BACKUP_ID).

backup list leaves deleted backups out unless you pass --all (include_deleted=true in the API).
For reading it prints one line per backup: its ID, its instance’s name, status, destination (hosted or local), image, size, and creation time, and its purpose when it is not a regular backup.
backup get, a deleted backup included, and --json show all of it: its disk size, the smallest root it restores to, the firmware and image its instance had when it was taken, the hostname the instance had then (hostname) and its name, hostname and state now, its prices, the fingerprint of the key a hosted backup is encrypted for, and for a local backup the host and location that store it.
In JSON a hosted backup’s destination reads gigahost_s3.
A backup knows its instance, so backup cancel, backup restore and backup delete take the backup’s UUID alone; for the latter two the older form with the instance’s UUID first still works.

Final recovery backups

The Backups page highlights final recovery backups left after balance exhaustion; see If your balance runs low.

Restore over the instance

Website
ghost

Restoring a local backup over its instance is direct. A hosted backup’s restore opens an approval page.

ghost backup restore <BACKUP_UUID> --yes --wait

backup restore prints the restore charge before it signs it.

Only an available backup can be restored or give a new instance: ghost refuses any other before it signs anything, with backup_not_available, and says to retry once a backup still being made, or restored, is done.
A restore also gives the instance the backup’s image in ghost instance get.
While a restore writes the instance’s disk, the instance reads provisioning, as during a reinstall.
A restore writes only the data the backup holds, so it takes about as long as that data, not as the disk is large.
Restores retain the backed-up users and SSH keys; they do not install fresh ones. A restore over the original instance keeps its hostname, network configuration, SSH host keys, and /etc/machine-id.

Firmware

A backup restores over its original instance only while that instance boots with the same firmware, BIOS or UEFI, as when the backup was taken. After a reinstall with an image that boots with the other firmware, create a new instance from the backup instead.

Disk size

Restore replaces the current root volume only after the size checks pass. The new root disk must be at least as large as the source.
The restored disk keeps its partitions and filesystem at their backed-up size, and the platform never changes them.
Every catalog image runs cloud-init’s growpart and resizefs on every boot, so a system restored from one grows into a larger disk on its next boot while cloud-init is still installed and enabled.
Other systems must grow the partition and filesystem themselves, for example with growpart /dev/vda 1 and then resize2fs or xfs_growfs.

Approve a hosted backup’s restore

ghost account approve REQUEST_ID --yes

Only your account key can decrypt a hosted backup. A hosted backup’s restore from the website, over its instance or into a new instance, opens an approval page (/approvals/REQUEST_ID) with a ghost account approve command.

Inspect the request in your CLI.
Approve it with --yes.
Keep the CLI running until authorization completes. If it is interrupted, repeat the same command to resume the admitted job. Progress remains visible on the website.

The CLI handles the restore-key authorization locally; it does not share your recovery private key. For hosted restore, the client unwraps and rewraps only the small backup data key locally. The account key and private recovery key are never sent to the backend or hypervisor.
Unstarted approvals expire after 15 minutes.
When the approval is refused, the page says why and that nothing was charged; approving again once the cause is gone still works until the request expires. The page keeps checking after a lost connection.
backup restore and instance create --backup of a hosted backup wait at most --authorization-timeout-seconds (300) for the destination host’s key offer and authorize no offer that comes later. The job they started goes on, and their --json error names it.
An instance created from a hosted backup waits up to 15 minutes for its restore to be authorized; see Delete for deleting it meanwhile.

More on ghost account approve is under Provider commands.

Create an instance from a backup

Website
ghost

A backup’s page (/backups/BACKUP_ID) offers Choose an offering, which opens Capacity with only the offerings that can take the backup (/?backup=BACKUP_ID). The rent form on an offering’s page lists only the backups it can take, each with its restore charge. Creating an instance from a local backup is direct; from a hosted one it opens an approval page.

ghost catalog offerings --for-backup <BACKUP_UUID>
ghost instance create \
  --offering '<OFFERING_ID>' \
  --backup <BACKUP_UUID> \
  --wait

Find an offering that can take the backup, then create the instance with --backup in place of --image. --for-backup reads your backup, so unlike the rest of the catalog it needs your account key.

You can create a new instance from a backup instead of installing an OS.

Which offerings can take a backup

The selected root disk must be at least the backup’s disk size.
The size must have the memory the backup’s operating system needs (1 GiB for Ubuntu 26.04).
Hosted backups can restore onto any architecture-compatible offering. A local backup can only use capacity on the physical host that stores it.
--for-backup keeps the offerings with a large enough root and, for a local backup, with that host among their host_ids; the backend still checks the architecture and the memory the backup’s operating system needs (1 GiB for Ubuntu 26.04) when you create.
--host <HOST_UUID> alone keeps the offerings that can place an instance on one host. The server applies both, as its minimum_root_disk_bytes and host_id filters.
An offering whose hosts do not include a local backup’s host is refused with backup_host_mismatch, which names that host and its location.
While that host is full or takes no new instances, creation from the backup is refused with capacity_unavailable, or with offering_unavailable if it was the offering’s only host.

What the new instance gets

It keeps the restored system’s users and SSH keys, so the SSH-key and startup-command options are unavailable with --backup.
Put anything else the new instance needs in a --cloud-init-file, which runs once at its first boot.
Gigahost supplies the new network assignment and hostname and boots only after restore finishes.
At its first boot the new instance also gets new SSH host keys and, on systems with systemd, a new /etc/machine-id.

Unavailable and lost local backups

A local backup is kept on a drive of its host.

When the host is missing the drive (the backup pool) that holds it, the backup shows as Unavailable (unavailable), with what the host found in an unavailable column (in JSON the backup’s unavailable object). It cannot be restored, nor an instance made from it: it is refused with backup_pool_unavailable. Keeping it costs nothing until the host has the drive back.
Once the drive is back, the host checks that the backup’s data is still there before it can be restored again and its storage is charged again.
A backup whose data is gone then shows as Lost (lost): it can never be restored, costs nothing more from when the drive went missing, and you are notified. Delete it with ghost backup delete to remove it from your list.

Delete a backup

ghost backup delete <BACKUP_UUID> --yes --wait

Completed backups remain in their selected storage until you request deletion.
Deletion is a background job and keeps an audit tombstone after storage confirms removal.
A backup deletion runs beside the instance’s other jobs, and several deletions run at once.
Deleting an instance does not delete its backups; see Delete.

Restore after an account key migration

ghost \
  --seed-file "$HOME/.config/ghost/account.next.seed" \
  --recovery-seed-file "$HOME/.config/ghost/account.seed" \
  backup restore <BACKUP_UUID> --yes --wait

After migrating an account to a new account key, authenticate with the new account key and select the older account key only when restoring a backup encrypted to its recovery key. The active --seed-file still authorizes the new restore charge. Here the replacement is account.next.seed, and the older account key is still the default account.seed that ghost key generate created.

A hosted backup whose key does not match the account key is refused before anything is sent, with recovery_key_mismatch and the fingerprint of the key the backup was encrypted for:

without --recovery-seed-file, the message says that a backup made before an account key migration needs the account key it was made with;
with it, that the given account key does not match.

ghost key inspect shows an account key’s recovery_key_fingerprint.