Commands · reference
vmlab snapshot
vmlab snapshot takes, restores, lists and deletes snapshots of one machine or of the whole lab. A VM and a container snapshot identically. A snapshot records the machine's power state at capture: an online snapshot of a running machine carries disk, RAM and device state, and restoring it resumes the machine where it was; an offline snapshot carries disk state only and restoring it leaves the machine powered off.
| Subcommand | Meaning |
|---|---|
| create | Take a snapshot of one VM/container, or lab-wide with no --vm. |
| restore | Restore a snapshot (resumes running iff it was taken online). |
| list | List a VM's/container's snapshots. |
| delete | Delete a VM/container snapshot. |
| -h, --help | Print help. |
Machine references take the form [lab/]name. A bare name, or no machine at all, is resolved against the lab in the current directory, and the lab daemon is started if none is running. The qualified form addresses a lab that is already running from any directory.
Snapshots are not a workspace backup
A dev machine's source lives on the host, which is what survives destroy and what a restore re-converges the guest from. Both create and restore print this sentence in their help and after a success that touched a dev machine with a workspace, and their refusals are built on it.
vmlab snapshot create
| Option | Meaning |
|---|---|
| <NAME> | Snapshot name. |
| --vm <VM> | Machine ([lab/]name); omitted = every VM and container in the lab. |
| -h, --help | Print help. |
Takes a snapshot named NAME of one machine, or, with no --vm, of every VM and container in the lab under the one name. A lab-wide snapshot is taken machine by machine; consistency across machines is best effort, not coordinated. Each snapshot is recorded in the lab's state with whether it was online and when it was taken, and for a container with the image digest it was taken against. Prints `snapshot "<name>" created`, followed by the workspace-backup warning when a snapshotted machine has a workspace.
For a dev machine with a workspace, capture is bracketed by the workspace syncer. A sync pass is flushed first, so the snapshot is coherent with the canonical copy. If the guest holds work the host has never seen, because the syncer is halted, has not completed a pass, or could not finish the flush, the capture refuses, naming the machine and the outstanding paths. There is no escape flag: a snapshot of a tree that exists nowhere else is not a thing to take against a warning. vmlab dev sync flush waits for a pending pass; a halt has to be resolved first with vmlab dev sync resolve. See vmlab dev. Every other machine passes straight through.
vmlab snapshot restore
| Option | Meaning |
|---|---|
| <NAME> | Snapshot name. |
| --vm <VM> | Machine ([lab/]name); omitted = every VM and container in the lab. |
| --discard-guest-changes | Restore a machine whose workspace is halted, throwing the guest copy of every conflicting path away. |
| -h, --help | Print help. |
Rolls one machine, or every machine in the lab, back to the snapshot NAME. A machine with no snapshot by that name fails with `"<machine>" has no snapshot "<name>"`; in the lab-wide form the first such machine stops the whole restore. An online snapshot resumes running; an offline one leaves the machine stopped. A container's snapshot is pinned to the image digest it was taken against, and restoring it against a different pinned image is refused, naming both digests, with the remedies of destroying the machine or restoring the original pin. Prints `snapshot "<name>" restored`, followed by the workspace-backup warning when a restored machine has a workspace.
For a dev machine with a workspace, restore is bracketed too. A restore rewinds the guest by hundreds of files at once, which a bidirectional syncer cannot tell from the developer having edited them and would carry onto the canonical copy. So the syncer is taken off the workspace before the rewind, a note that a re-seed is owed is written to the sync ledger, and after the rewind the syncer goes back on and runs the re-seed: a host-only reconcile that carries the canonical tree back into the guest and emits no guest-to-host action at all, completing before the watch reopens. The note rides the ledger, so a daemon that dies mid-restore still owes it, and a restore that fails after the note is written still runs it, with the reason on the event feed.
A workspace that is halted at restore time is refused by default, because restoring would silently destroy the guest copy of every conflicting path. The refusal names the affected paths and this verb's one escape flag, --discard-guest-changes, which restores anyway and throws those guest copies away. vmlab dev sync diff shows the guest copy host-side before you decide.
vmlab snapshot list
| Option | Meaning |
|---|---|
| <VM> | The machine, as [lab/]name. |
| -h, --help | Print help. |
Prints one row per snapshot of the machine: NAME, KIND (online or offline) and TAKEN, the capture time in UTC. A machine with none, including a name the lab does not declare, prints `no snapshots for <name>`.
vmlab snapshot delete
| Option | Meaning |
|---|---|
| <VM> | The machine, as [lab/]name. |
| <NAME> | Snapshot name. |
| -h, --help | Print help. |
Removes the snapshot from the machine's disk and from the lab's record. Prints snapshot "<name>" deleted.
Examples
Checkpoint a domain controller before a risky change:
Roll the whole lab back to a known state:
Restore a dev machine whose workspace is halted, giving up the guest's copies:
Exit status
Exit status is 0 on success, and 0 for list on a machine with no snapshots. Every refusal and failure exits 1 (failed): an unknown machine, a missing snapshot, a capture refused because the workspace is not in step, a restore refused on a halted workspace or a changed image pin, and a snapshot the machine cannot take or restore. Exit 5 (conflict) means the supervisor tracks a lab with this name from another directory. A usage error exits 2.