Restoring a guest

Something has gone wrong inside a guest and you want it back the way it was. There are three answers depending on how bad it is, and they use different machinery:

This page covers the first two.

Finding the point to go back to

hoster vm snapshot list web-01
hoster vm snapshot list web-01 --json
hoster microvm snapshot list registry

Snapshots are named by type and timestamp — hourly_20260801_150001.610985 — and the list is the menu for everything below. If the guest is being snapshotted on a schedule you already have restore points; see Snapshots, replication and the scheduler.

Take one by hand before doing anything risky:

hoster vm snapshot create web-01 --type custom
hoster microvm snapshot create registry --type custom

The retention defaults disagree. --keep defaults to 10 on hoster vm snapshot create and to 3 on hoster microvm snapshot create. The same flag, the same meaning, different numbers — so a microVM quietly keeps fewer restore points than a VM unless you say otherwise.

Rolling back

This is the in-place restore: the dataset returns to exactly what it was at the snapshot, and everything written since is gone.

hoster microvm snapshot rollback rpool/hoster/ct-encrypted/registry@custom_20260801_120000
hoster microvm snapshot delete   rpool/hoster/ct-encrypted/registry@custom_20260801_120000

delete also answers to destroy, remove and rm.

Rollback has no safety rails. It runs zfs rollback -r with no check that the guest is stopped and no confirmation prompt. Two consequences worth internalising before you type it:

• -r destroys every snapshot newer than the target. There is no undo, and the restore points you were relying on for a second attempt go with it.
• Rolling back a running guest changes the storage underneath a live kernel. Stop the guest first. Nothing will stop it for you.

Take a fresh snapshot immediately before rolling back, and you at least have a way back to the broken state if you rolled back too far.

There is no hoster vm snapshot rollback. The VM snapshot tree has only create, create-by-tag and list — no rollback, no delete. This is not a missing feature underneath: RollbackZfsSnapshotByName and DestroyZfsSnapshotByName live in HosterLib’s VM snapshot file, the agent API exposes both at /api/v1/snapshot/rollback and /api/v1/snapshot/destroy, and the microVM CLI calls them. Only the VM CLI has no subcommand for it.

Until it does, rolling a VM back means Control Center, the API, or cloning the snapshot into a new guest as below.

Cloning a snapshot instead

The non-destructive alternative, and the one available for VMs today. Rather than moving the guest backwards, build a second guest from the snapshot:

hoster vm clone rpool/hoster/vm-encrypted/web-01@custom_20260801_120000 web-01-restored \
  --rotate-ip --rotate-uuid --rotate-cloud-init

Often better than a rollback even where rollback exists: the original stays untouched while you confirm the restored copy is what you wanted, and you can pull one file out of it rather than losing a day’s writes to get that file back.

Always rotate. A clone that keeps the source’s MAC, UUID and cloud-init identity is a second machine claiming to be the first — see Cloning for the flag’s naming trap.

Bringing a replica to life

A replicated guest sits on the target host already, and the platform treats it as a copy rather than as the machine:

• it is skipped by DNS record generation, so it never answers to the original’s name;
• ci-reset refuses to touch it;
• its disks cannot be resized;
• the scheduler will not run DR backups for it.

All of that follows from one rule: a guest is primary only on the host named as its parent. Every other copy — including one whose parent host is blank — is a backup.

hoster vm get-config web-01 | grep parent_host

The supported way

Restoring a replica is a real operation with its own library function (RestoreBackupByName): it renames the dataset, gives the guest a new name, and can rotate IP, MAC, UUID and cloud-init on the way — the same identity questions as a clone, because a promoted replica has exactly the same collision risk.

There is no CLI command for it. The agent API exposes it at /api/v1/backup/restore (and /api/v1/backup/destroy for discarding one), and Control Center drives it, but no hoster command reaches it. On a host with only a terminal, restoring a replica is an API call or a manual procedure.

Doing it by hand

If you are on the console of the surviving host with no Control Center available:

# 1. Clone the newest replicated snapshot into a new, independent guest
hoster vm snapshot list web-01
hoster vm clone rpool/hoster/vm-encrypted/web-01@replication_20260801_150001 web-01-live \
  --rotate-ip --rotate-uuid --rotate-cloud-init

# 2. Claim it for this host so it counts as primary
hoster vm set-config update-parent web-01-live

# 3. Check it before starting it
hoster vm get-config web-01-live
hoster vm start web-01-live

Cloning rather than renaming leaves the replica intact, so a failed promotion costs you nothing. See Moving a guest’s parent host for what update-parent does and does not do — it is bookkeeping, and it moves nothing.

Do not do this while the original host is still running the guest. Two hosts each believing they are primary for the same workload is the failure this rule exists to prevent. If the original is merely unreachable rather than dead, mark it offline first — hoster cluster mark-offline — so the cluster agrees with you.

Which to reach for

• A bad change inside one guest, host healthy → clone the snapshot, verify, cut over. Rollback if you are certain and the guest is stopped.
• A guest that will not boot → clone the last known-good snapshot rather than rolling back, so you can compare the two.
• A host that is gone → promote the replica on the surviving host.
• The site is gone → disaster recovery.

Next

• Disaster recovery — the restore path that survives losing the hosts and the replicas together.
• Snapshots, replication and the scheduler — making sure the restore points this page needs actually exist.
• Getting into a guest — the console, for checking a restored guest before you trust it with traffic.
• The scheduler — confirming the snapshots you are about to rely on are actually being taken.