A snapshot is a point-in-time copy of a server's disks, kept on the same node and storage as the disks. Taking one is instant, reverting takes seconds, and it is meant for "before I change something risky". It is not a backup: it does not survive the loss of the node or its storage. For copies off the node, use backups.
Snapshots are off by default. Nothing changes for existing plans or servers when you upgrade the panel.
How snapshots work#
- Disks, at one instant. A snapshot holds every disk of the server (disk 0 and extra disks), taken in one atomic step. Optionally it holds the server's memory too (see Snapshots with memory).
- Independent. Each snapshot stands on its own. Deleting one never touches another; reverting to one keeps all the others, newer ones included.
- Cheap at first. A new snapshot shares every block with the disk and takes almost no space. It grows as the server overwrites data.
- Consistent when it can be. For a running server the node freezes the guest's file systems through the QEMU guest agent for well under a second. Without a guest agent the snapshot is crash-consistent: like a power cut at that moment. The guest is never paused (except for a memory snapshot).
- Not in backups. A backup copies the disks only, never the snapshots.
Where snapshots work#
The node takes snapshots with the native mechanism of each storage kind. The agent on the node needs version 0.19.0 or later.
| Storage | Snapshots | Notes |
|---|---|---|
File storage on XFS made with reflink=1 (what vmstack-agent storage setup makes), or btrfs |
Yes | Reflink copies. Sizes are measured. |
| NFS 4.2 export on XFS or btrfs that can clone files | Yes | Reflink copies, as above. |
| LVM-thin | Yes | Thin snapshots. What each snapshot holds alone is not measured. Refused while the pool's data or metadata is above 100 − snapshot_min_free_percent %. |
| ZFS | Yes | ZFS snapshots and clones. |
| Ceph RBD (beta) | Yes | RBD snapshots. |
| ext4, or NFS without reflink | No | There is no full-copy fallback. |
A server whose disks are on both LVM-thin and file storages cannot take snapshots. See Storage for the storage kinds.
When the node cannot take snapshots, the server's Snapshots tab says why: an agent that needs an update, or a storage without a snapshot driver (for example "the storage's file system does not support reflink copies (ext4)").
Turn snapshots on for a plan#
- Open Customers › Hosting plans and edit the plan.
- In the section Backups and snapshots, under Snapshots, set:
| Field | Meaning |
|---|---|
| Snapshots kept | 1–20 snapshots per server at a time. 0 means no snapshots (the default). |
| Total size (GB) | The most the server's snapshots may hold together. Empty: no limit. |
| Delete after at most (days) | 1–365. Every new snapshot gets an expiry of at most this age. Empty: kept until deleted. |
| Include memory | Customers may save a running server's memory with a snapshot. Off by default. |
- Save. A plan's policy is read live: the change reaches every server on the plan at once.
Lowering a limit deletes nothing. A server above the new limit cannot take a new snapshot until it is under it.
A server's own policy#
Administrators can override the plan for one server:
- Open the server and go to the Manage tab.
- On the Snapshot policy row, click Snapshot policy.
- Choose As its plan, No snapshots or Its own limits (the same fields as the plan), then Save policy.
Reseller limit#
A reseller's page has a Snapshots limit: the number of snapshots across all of its customers' servers (empty: no limit). A reseller's own plans cannot keep more per server than that limit. Customers whose reseller has one see "Snapshots: 7 of 20" on their dashboard's limits card.
Customer abilities also have a Snapshots switch: switched off, the customer cannot use snapshots even when the plan allows them. See Customer permissions.
Take a snapshot#
Whoever manages the server (an administrator, its reseller or its owner) can take snapshots.
- Open the server and go to the Snapshots tab (between Storage and Backups). The tab is shown when the policy allows snapshots or the server already has some.
- Click Take snapshot.
- Optionally type a Name (up to 60 characters; empty becomes "Snapshot 15 Nov 14:05 UTC").
- Choose Delete automatically: Never, or after 1, 3, 7 or 30 days. Choices longer than the policy's maximum age are left out, and then so is Never.
- Optionally tick Include memory (see below).
- Click Take snapshot.
The top line of the tab shows the count and size against the limits, for example "2 of 3 snapshots · 6.4 GB of 50 GB", with an amber mark above 80 % of the size limit. Each row shows the name, when it was taken, Consistent or Crash-consistent (or With memory), the space it alone holds and the disk size it reverts to, and when it is deleted.
Take snapshot is disabled, with the reason, while the limit is reached, the server is busy with another task (a backup's copy phase included), another snapshot task runs, the server is in rescue, or its node does not answer. The oldest snapshot is never deleted to make room.
Note: For consistent snapshots, install
qemu-guest-agentinside the server. Servers made from VMStack's cloud images usually have it; servers installed from an ISO usually do not.
Snapshots with memory#
A memory snapshot also saves the running server's memory, so a revert brings it back running, exactly where it was: open programs, unsaved work, its clock and network state of that moment.
- Needs: Include memory on in the plan's (or server's) policy, a node whose agent can save memory, and a running server. The tick is disabled with the reason otherwise ("Memory can only be saved while the server is running.").
- Pause: the guest is paused for a few seconds per GB of memory while it is written. It is never quiesced.
- Size: each memory snapshot holds a file up to the size of the server's memory. It counts in the snapshot's size and against the plan's size limit, and the node refuses it when the memory does not fit beside the free space it keeps.
- Revert offers two ways:
- Resume where it was: the server is running afterwards, even if it is stopped now. With the guest agent its clock is set right at once; without one it is behind until NTP corrects it. It keeps its old network settings: run Reconfigure network afterwards if its addresses changed.
- Start from the disk: as after a power cut at that moment, with today's addresses and host name written in.
- Cannot resume when the server's memory, vCPUs or extra disks changed since, or the node's QEMU refuses the saved machine. The server then starts from the disk and the row says why. Changing the size back makes resuming possible again.
Revert to a snapshot#
- On the Snapshots tab, click Revert on the snapshot's row.
- Read the dialog. It lists what changed since (host name, addresses), whether the root password goes back, whether the disk is larger now, and which extra disks go back too.
- Optionally tick Take a snapshot of the current state first. The revert is then sent only after that snapshot succeeded.
- Type the server's name and click Revert.
What happens:
- The server is powered off at once (no graceful shutdown) and its disks go back to the snapshot. Everything written since is lost. The snapshot itself is kept.
- A disk that grew since the snapshot is grown back to the current size, never shrunk. A server from a cloud image grows its partition at the next boot; a server installed from an ISO must grow its partitions by hand.
- For a server installed from an image, a fresh network seed writes today's addresses and host name into it. Its SSH host keys stay.
- The panel puts back the root password, the image and the "installed from" source the server had then. Overview shows the password that works.
- The server is started if it was running before. A stopped server stays stopped.
- Host name, addresses, plan, sizes, firewall, reverse DNS, ISO drives, boot settings, limits and owner stay as they are now.
The owner and whoever started the revert get the essential mail snapshot.reverted (or snapshot.revert_failed).
If the server does not start after the revert, the row says so and the server shows stopped: start it from the server page.
Rename, expiry and delete#
- Rename changes the name and the expiry. "Delete automatically" counts from now, capped by the policy's maximum age counted from when the snapshot was taken.
- Delete removes the snapshot. It cannot be undone; the server is not affected.
- Dismiss removes the row of a snapshot that failed.
- Revert, rename and delete keep working when the plan no longer includes snapshots, so a customer can always clean up or go back.
Expired snapshots are deleted by the scheduler every hour (vmstack:prune-snapshots, at :35). It skips servers that are busy or whose node does not answer and tries again the next hour. A snapshot with "Couldn't be deleted; will retry" is tried again the same way.
Space on the node#
- Snapshots are not part of a server's disk size, a reseller pool's disk or a node's "Disk that may be sold". They use the headroom of the real storage.
- The agent refuses a new snapshot when the storage has less free than
snapshot_min_free_percentof its size (default 10) or less than the server's disk size, whichever is larger. Set it per node in/etc/vmstack/agent.yaml:
snapshot_min_free_percent: 15
- The agent warns when the storage is 90 % used or more. The node page's storage card shows "Snapshots: 84.0 GB on 12 servers" and the warning; the administrators' dashboard lists the node.
- Nothing is ever deleted automatically to free space. Deleting snapshots is a person's decision.
- A snapshot file on the node that the panel does not know is counted on the node page as "Unknown snapshot files" and never deleted.
What happens to snapshots when the server changes#
| Event | Snapshots |
|---|---|
| Reinstall | Kept. The reinstall page offers Take a snapshot first. Reverting to an older snapshot brings the old system back. |
| Backup restore | Kept. |
| Upgrade | Kept. A revert grows the disk to the current size. Memory snapshots resume only at the same memory and vCPUs. |
| Rescue | Kept. Taking and reverting are refused until Exit rescue; rename and delete work. |
| Suspension | Kept. Administrators may take snapshots of a suspended server (crash-consistent, without memory). Nobody can revert one. Expiry continues. |
| Owner change | Kept. They count in the new owner's reseller pool; the change is refused if they do not fit. |
| Move to another node | Deleted by the move, after you tick to confirm. See Moves. |
| Server deleted | Deleted with the server. |
Who may do what#
| Action | Administrator | Reseller | Owner |
|---|---|---|---|
| Take, rename, revert, delete | Yes | Yes (its customers' servers) | Yes |
| On a suspended server | Take, rename, delete | No | No |
| Server's own snapshot policy | Yes | No | No |
| Plan policy | Panel plans | Its own plans | No |
API and webhooks#
The API has GET/POST /servers/{id}/snapshots, GET/PATCH/DELETE /snapshots/{id}, POST /snapshots/{id}/revert (with snapshot_first and memory) and GET/PUT /servers/{id}/snapshot-policy, under the scopes snapshots:read and snapshots:write. Webhooks: snapshot.completed, snapshot.failed, snapshot.reverted, snapshot.revert_failed, snapshot.deleted. See the API reference and Webhooks.