Images and templates

A classic VM boots from a cloud image: a prepared Linux disk image with cloud-init inside. Virtainer Free keeps a local cache of those images and copies from the cache every time you create a VM.

VM images

The Images page under Virtual machines (/vm/images) is a catalogue of what this host can boot, shaped like a registry: one card per operating system. A card is a directory rather than a single release. The Debian card states Debian 13 and Debian 12 as separate rows, because choosing between them means choosing an operating system, not choosing an older copy of one.

Each row leads with the newest build upstream has published for that major version and carries a Download button for it, or a check when this host already holds that exact build. Leading with the newest build, rather than the one already on disk, means a newer upstream release still shows while an older copy is cached. Beside the row the card states how many builds of that version exist and how many this host holds, for example 2 builds · 1 on disk, and the card header totals the same facts for the whole operating system.

When a version holds more than one build, All N builds appears on the card and opens that operating system’s own page (/vm/images/:distro): one page per distro, a section per major version, and every build listed newest first with its file name, size, date, and a short checksum. Each build carries a Download button, or an On disk check if the host holds it, and the newest build of each version is marked Newest. That page reads and downloads. Deletion never happens there, so a destructive click cannot sit one mis-select away from a Download button.

Search matches distro, version, release, or file name. The tags beside it narrow to one operating system, or to On disk for what this host holds. Tags carry no counts: the only number an operator acts on is how much the host is holding, and the footprint card states it once.

Managing images is its own page

The footprint card at the top shows how much of the host’s storage the image cache takes and how many builds it holds. Manage images opens /vm/images/manage, a flat list of what is on disk, for the housekeeping: multi-select, Remove from disk, and notes you can leave on an image. Because that page lists only what the host holds, notes and deletion apply to images already downloaded.

There are three ways to add an image:

• From the catalogue. Use the Download button on a version row to fetch that build. The host downloads it once and verifies its checksum.
• From a URL or an upload. Add Image takes a qcow2 image you already have, as an uploaded file or a URL the host pulls.
• From a machine you already built. Turn a stopped VM’s root disk into a reusable image. See below.

Once an image is cached, creating a VM from it does not touch the network.

Watching a download

Downloads happen on the host, not in your browser, so the page reports on them directly. Start one and the button on that row turns into a progress bar, with the current rate and an estimate of the time remaining. When it finishes, the downloaded release takes its place.

The rate is the number worth watching. It is what tells a slow mirror apart from a stalled one. If the server does not report a total size, you get bytes downloaded and the rate without an invented percentage.

Making an image from a VM

A VM you have configured by hand can become the starting point for the next ones. Stop it completely, then choose More → Create image on its page and give the image a name. While the machine is running the menu item is still listed, greyed out, with the reason appended: “Create image — stop the VM completely first”. The export runs on the host; follow it in Operations, and use Recheck if Virtainer Free restarts while it is running. The result appears on the Custom card of the VM images page and creates new VMs like any other image.

Prepare the guest before you stop it

The export copies every file on the root disk exactly as it is. It does not modify the source VM and it does not sysprep anything for you.

Before stopping the machine, remove anything specific to that one machine, for example /etc/fstab entries pointing at its data volumes or devices. If the image uses cloud-init, clean its state inside the guest, logs and machine id included, so the next VM gets a fresh seed, MAC address, and machine id.

Only the root disk travels. The machine’s CPU and memory, its NICs, its data volumes, and its snapshots stay behind, though any files those features left on the root disk are copied along with everything else. To reproduce a whole machine rather than a starting point, use a transfer package or a backup.

Images are copied, never shared

Creating a VM copies the cached image into the machine’s own disk file. There is no chain back to the original, so the cached image is never modified, and deleting a cached image cannot damage a VM that was built from it.

Each VM’s disk is booked against the pool at the size the disk was created with, which is the larger of the size you asked for and the image’s own capacity, and it shares the image’s blocks on a copy-on-write pool, so the capacity card counts those shared blocks once, under Base images, rather than once per machine. Plan pool capacity by the disks you hand out and what the machines write, not by the number of distinct images.

Templates

A template is a saved set of create-form settings: the first-boot configuration, the shape of the machine, and the options you would otherwise retype. One Templates page holds the classic VM templates and another holds the AppVM ones: Templates under Virtual machines (/vm/templates) and Templates under AppVMs (/appvm/templates), each listing only its own kind.

1. Open Templates under Virtual machines or under AppVMs and create one.
2. Fill in the settings you want to reuse.
3. Pick that template when you create a machine, or leave the picker on No template, and adjust anything per machine.

A template is applied at creation time. It fills the form in, and editing the template later does not reach back into machines that were already created from it.

Creating several machines at once

Count is a block of its own on the create form, with or without a template. How many sets the count. Number from sets where the numbering starts, so running the same settings again later appends to an existing group instead of colliding with the names you already used; with static addressing, IP step controls the spacing between them. Neither is shown while the count is one.

Two rules are checked before anything is created: the hostname must contain an {n} sequence token, and a static starting address must be given as CIDR.

AppVMs can be created several at a time too. They do not step static addresses, and a blank hostname is fine there because each machine derives a distinct name of its own.

Moving a template between hosts

A template is a small JSON document, and the console treats it as one. Each template row can be exported, which downloads a file named after the template with a .template.json suffix, and the Templates page has an Import button that takes such a file back in. The empty state offers the same thing as Import a file.

That is the practical way to keep a set of machine shapes you have already tuned: export them from the host where you built them, and import them on the next one. A template carries create-form settings and nothing else, so importing one creates no disks, copies no image, and starts no machine. It fills the form on a host that has the images it names.

Raw cloud-config

If the form does not cover what you need, a VM template can carry your own #cloud-config document, which is appended to the configuration Virtainer Free generates. Use it for the parts that are genuinely yours; let the form handle hostname, users, and networking so the console and the guest agree on what was set.