OS images & guest templates

Every guest is built from a template you manage in NexoVirt:

• QEMU templates (Provisioning > QEMU Templates): cloud-init OS templates for virtual machines. Each template points to a cloud image that is stored once per node in the image cache.
• LXC templates (Provisioning > LXC Templates): container templates.

Both are organized into groups. A group has a name and an image (a logo), and the groups are the cards of the OS picker in the create wizard and on the reinstall page. A fresh install arrives with a ready-made catalog of groups and templates, and updates add new catalog entries without touching your own.

QEMU templates

The QEMU Templates page has four tabs: Templates, Groups, Images on nodes and Base cloud-init.

Templates

New template creates a template. The Template tab of the form holds:

Field	Meaning
Name, Group, Description	How the template appears in the pickers. Every template needs a group.
Base image URL	The cloud image (.img or .qcow2). It must start with https://, or with http:// when a SHA-256 checksum is set.
Image filename (on node)	Must end in .img or .qcow2.
OS type	Linux, or Windows 10/11. Windows templates ask for an Administrator password at create and use a graphical console.
Download to nodes	Automatic (by hand for Windows), On demand, when a server needs it or Only by hand. See download modes.
SHA-256 checksum	Optional. Every download is verified against it.
Cloud-init user, IP mode, Nameserver, Static IP config, SSH authorized keys	Native cloud-init settings.
Upgrade packages on first boot, Image permits root SSH on :22	Cloud-init options.

The Cloud-init tab of the form takes your own cloud-init YAML as an Override. It is deep-merged over the base cloud-init at provisioning time: lists append, maps merge and scalar values from the override win. Preview merged shows the result.

Groups

The Groups tab adds, edits and deletes groups. Upload a JPG, PNG, SVG or WEBP image of up to 512 KB per group. A group that still holds templates cannot be deleted: move or delete its templates first.

Base cloud-init

The Base cloud-init tab shows the cloud-init configuration that applies to every QEMU guest. It is managed centrally and read-only; adjust a template’s behaviour with its override instead.

Images on nodes

QEMU images are kept in a per-node cache on the managed nexovirt-images storage. Each template has one file per node, and every create and reinstall on that node imports from it, so an image is downloaded once instead of for every new VM. If you change a template’s image URL or checksum, the template gets a new file and the old one is listed as outdated.

The Images on nodes tab shows the cache of one node at a time (pick it in the node selector) and the free space in its image storage. For each template it lists the download mode, the status, the size and the actions:

Status	Meaning	Actions
Not on this node	No copy yet.	Download
Queued	The agent is about to start the download.
Downloading	With percentage and bytes received.	Cancel
Verifying checksum	The download is checked against the SHA-256 checksum.
Ready	The image is stored and used for creates and reinstalls.	Re-download, Delete
Failed	With the reason, for example an unreachable URL, a checksum mismatch or not enough disk space.	Retry, Delete

Other files on this node lists files in the image storage that do not belong to a current template: outdated images of a template, images of deleted templates and files not managed by a template. You can delete them there.

Downloads run on the node in the background, independent of the panel and of the agent’s job loop:

• They are resumable: an interrupted download continues where it stopped.
• They are verified against the template’s SHA-256 checksum when one is set.
• They have no overall time limit, so large images are fine. Before starting and while running, the node checks that there is enough free space for the rest of the image plus a 1 GiB reserve.

Note

Deleting an image does not affect servers already created from it. A delete is refused while a create or reinstall is queued or running on that node. Downloads and deletes are recorded in the audit log.

Download modes

Mode	Behaviour
On demand, when a server needs it	If the image is not on the node, a create or reinstall starts the download and waits for it. The job is checked again every 20 seconds and gives up after 6 hours.
Only by hand	The image must be downloaded on Images on nodes first. Until then the template shows “(download to the node first)” in the wizard, and creates and reinstalls with it are refused. The REST API answers 409 Conflict.
Automatic (by hand for Windows)	On demand for Linux templates, only by hand for Windows templates.

Windows images are large, so they are downloaded only by hand by default. Download them to the nodes you plan to use before customers order Windows servers.

Requirements and clusters

The image cache is handled by the node agent and needs agent version 0.24.1 or newer on the node. With an older agent, NexoVirt falls back to downloading the image for each new VM and removing it afterwards.

A host connection has one agent, and only the node the agent runs on holds images. On a cluster connection, the other members show “(no images)” in the node selector and their templates show “(no images on this node)” in the wizard. Creates of QEMU guests on those members are refused with a clear message. To create VMs on another member, add it as its own connection with its own agent.

LXC templates

The LXC Templates page has two tabs: Templates and Groups (groups work as for QEMU templates). New template asks for:

• Name, Group and Description.
• Source:
  • Proxmox appliance index: Browse PVE templates searches the Proxmox template index and picks an entry.
  • Direct URL: a root filesystem tarball (.tar.zst, .tar.gz or .tar.xz) and its Filename (on node).
• Architecture and OS type.
• Unprivileged container: whether the image is meant to run unprivileged. The create wizard has its own Unprivileged container switch, and that switch decides.
• Applies static IPs: turn this on only for images that apply a Proxmox static IP at boot (images with ifupdown or another reader of /etc/network/interfaces). Minimal or netplan-only images (for example Ubuntu cloud/minimal) must stay off: they use DHCP and cannot be placed on project networks without DHCP.

The template’s tarball is downloaded to the node when a container is created and removed again afterwards; container templates are not kept in the image cache.

Next steps

• Guests to create and reinstall guests from these templates.
• The node agent to install or update the agent on a node.
• REST API for the os-templates and ct-templates discovery endpoints.