Backup and restore

A backup is a copy that leaves the host. Virtainer Free produces two of them, and you need both to rebuild a host from nothing.

Three things that look similar

Artifact	Where it lives	What it is for
Snapshot	The same storage pool as the machine	Undoing a change you are about to make
Transfer package	Your computer, briefly	Moving one machine to another host by hand
Backup	Off-host media you manage	Surviving the loss of the host

Only the last one is a backup. A snapshot dies with the pool that holds it, and a transfer package is deleted from the host as soon as it is downloaded.

An online snapshot is not an online backup

Being able to snapshot a machine while it runs has not moved that line. An online snapshot is still written into the same pool as the disks it copies, so it is gone if the pool or the host is gone. What it buys you is a rollback point you can take without stopping the workload. It does not buy you a copy that survives this host.

The conditions run the opposite way too. Snapshotting a running machine needs it up. Backing a machine up needs it stopped, with the host’s own services stopped alongside it.

What you need

Backups are produced on the host itself rather than from the console, so reach the host the way an administrator does. You also need somewhere off-host to write to: a mounted removable disk, a network share, or anything else that is not the pool you are protecting.

Every command on this page is the host’s own virtainer binary with a subcommand. Each one takes an absolute directory: the bundle it writes or reads, or the output directory for a report. The export, verify and restore commands are offline, so they work against the paths configured for this host and the bundle directory is the only thing you give them.

The two backups

A machine

A self-contained directory holding the machine’s record, its root disk, every data volume attached at the time, registered volume metadata, the machine’s snapshots, and any AppVM credentials it carries. Its cached images, metrics, and logs are not in it.

The host’s state

The control plane itself: the host’s database, its encryption key where one exists, and a self-verifying manifest. It holds no machine disks at all. It is what the host knew, not what the machines contained.

Neither one is sufficient alone

State without machine backups gives you a control plane pointing at disks you no longer have. Machine backups without state give you disks and records, but you rebuild the admin account, networks, and host configuration by hand.

Taking both

Stopping Virtainer Free does not stop machines that are already running. Their processes are deliberately independent of the agent, so stopping the agent never stops a machine for you: stop the machines you are exporting first. What you lose during the window below is the console and the API, not uptime for everything else. The machine you are backing up does have to be stopped, because its disks cannot be copied consistently while they are open. A snapshot is the tool for a machine you cannot stop, and it stays inside the pool.

1. Stop the machine you are backing up from the console, and confirm it reads Stopped.

2. Stop the agent, and take both exports in the same window. Each export writes a self-verifying bundle into a target directory you name, and each verifies what it wrote before it reports success. Each target must be an absolute path that does not already exist. The exports contend for the same process lock the agent holds, so they refuse to run while it is up rather than producing a torn copy.

   virtainer state export /mnt/backup/host-state-2026-09-22
   virtainer vm export web01 /mnt/backup/web01-2026-09-22

   state export takes the host’s control plane. vm export takes one machine, named by its id, so run it once for each machine you are backing up.

3. Start the agent again, boot the machine, and record which version produced the bundles. The agent is virtainer serve, and that is also what a bare virtainer runs, because serve is the default subcommand.

Bundles contain secrets

A machine bundle carries its cloud-init configuration and any AppVM credentials. File permissions inside the bundle are not encryption. Choose protected media, and encrypt it yourself if it leaves your control.

Restoring a machine

Restore into a host that has no colliding identity: no machine of that id, and no clash on MAC address, tap device, socket, disk, registered volume id, or an occupied volume attachment. Restore never overwrites, never merges, and never renames to get around a collision; a clash is reported as a conflict.

Verify the bundle before you restore from it. Verification reads the bundle and checks every digest recorded in its manifest against the files in it, without touching the host, so it is how you find out that your media is intact before anything is written:

virtainer vm verify /mnt/backup/web01-2026-09-22

With the agent stopped, restore from the bundle, then start the agent again:

virtainer vm restore /mnt/backup/web01-2026-09-22

The machine comes back Stopped so you can check its network and disk mapping before booting it. If a restore is interrupted, do not delete the target files. Stop the agent and restore the same bundle again.

Restoring host state

State restore writes only into an empty target, and the database’s three files are a single indivisible set. Moving just state.db aside leaves a stale state.db-wal or state.db-shm that would corrupt the restored database, so the restore refuses with state database target is not empty: move all three files aside together, or remove them, before restoring. A conflicting secret.key is refused with secret key '{}' already exists and does not match the export, and you move that file aside in the same way.

Verify before you restore, the same way as for a machine:

virtainer state verify /mnt/backup/host-state-2026-09-22

With the agent stopped, restore the state, then start the agent again:

virtainer state restore /mnt/backup/host-state-2026-09-22

Afterwards, check the admin login, the network topology, the operations list, and the machine records, and confirm each machine’s real state on the host.

Restoring state onto a new host or a new disk does not bring the machines with it. Restore each machine’s own backup first, then start the agent.

A rebuilt host has no console until the agent is up, and if the agent will not start it has no way to show you anything. virtainer diagnostic-report /mnt/backup/report-2026-09-22 writes a diagnostic report offline into the directory you name, from the host’s own configured paths. It is read-only, so it works whether or not the agent is running. With the agent down, the diagnosis findings are the one section it cannot collect, and the command names every section that came out incomplete.

Planning around it

• Every backup is cold and complete. There is no online backup and no incremental. The online capture in Virtainer Free is a snapshot, and it stops at the pool edge. Your exposure is the time since the last finished export, and a restore takes as long as copying and verifying every disk from your media.
• Nothing runs on a timer. Virtainer Free does not schedule backups or expire old ones. Decide your own retention, and take the exports as often as your exposure window allows.
• Keep the version. A machine bundle verifies and restores only on the exact build that produced it; a state bundle is gated on its format version and schema instead. You upgrade forward afterwards. Store the version alongside every bundle.
• Rehearse once. Do a real restore onto a spare host before you rely on any of this, and before you start deleting older bundles.

For a service you cannot afford to stop, snapshot the classic VM while it runs so you keep a rollback point, and run a conventional in-guest backup alongside these. Virtainer Free has no online backup, and the guest does.