Images

The image library servers are made from: adding images, downloads to every node, checksums, images made from servers, clones, container images and FreeBSD.

An image is the operating system a server is installed from: a cloud image that sets itself up at its first boot (host name, root password, SSH keys, network, disk growth). Images live in a library the panel keeps, and every node downloads each enabled image ahead of time, so a new server is copied from the node's own copy instead of waiting for a download.

The library is under Images and ISOs › Images, for administrators. Its tabs are Images, ISOs, Applications, Recipes and Windows templates.

The standard images#

A new panel gets the standard set at install. To add the standard images a newer panel version brings, or to put back one you deleted, run on the panel server:

cd /opt/vmstack/current
runuser -u vmstack -- php artisan vmstack:seed-images

Artisan commands run as the vmstack user, never as root. The command adds what is missing, reads the checksums of the images that have a checksum source, and never changes an image you have.

Distribution Versions
Debian 13, 12
Ubuntu 26.04, 24.04, 22.04
AlmaLinux 10, 9, 8
Rocky Linux 9, 8
FreeBSD 15.1, 14.5

It also adds the VirtIO drivers for Windows ISO to the ISO library. Each standard image that follows a moving "latest" build has its publisher's checksum file as its checksum source (see Checksums).

AlmaLinux 10 (and every RHEL 10 family image) needs an x86-64-v3 CPU, Haswell or later. Such images have Minimum CPU level set, and nodes whose servers get an older CPU model are not offered for them.

Add an image#

  1. Go to Images and ISOs › Images and press Add image.
  2. In General: Kind Virtual machine, a Name, a Slug (the name nodes store the image under: lower-case letters, digits, dots and hyphens; it cannot be changed later), Distribution (for the logo), Version and OS family (Linux or FreeBSD; it follows the distribution).
  3. In Source: the URL and, optionally, a Checksum or a Checksum source.
  4. In Requirements: Minimum disk (GB), Minimum memory (GB), Architecture and Minimum CPU level. Smaller plans and unsuitable nodes are not offered for the image.
  5. In Firmware: BIOS, UEFI or UEFI with Secure Boot, and TPM 2.0 (UEFI only). Servers made or reinstalled from the image get these; a node without the firmware or a TPM is not offered for it.
  6. In Hardware and first boot: Disk bus, Network card and Cloud-init data source (NoCloud for most Linux images, Config drive for OpenStack-style images). Leave the defaults (VirtIO, NoCloud) unless the image needs otherwise.
  7. For a Windows image, the Windows section: Windows optimisations and a Licence note (Windows templates).
  8. Press Add image. Every online node starts downloading it.

What the URL must point at:

  • An https:// link to a qcow2 cloud image with cloud-init (FreeBSD: nuageinit, as in FreeBSD's BASIC-CLOUDINIT images).
  • It may be compressed with xz, gzip, bzip2 or zstd (FreeBSD's .qcow2.xz): the node tells the compression by the file's first bytes and unpacks it while it downloads. A compressed raw image (.raw.xz) is refused.
  • After unpacking, the file must be qcow2 without a backing file, at most 64 GB.

Disabling an image stops it being offered and removes it from the nodes; servers made from it keep their own disks. A plan can limit the images its customers may reinstall to (Images for reinstalls and setup on the plan form).

Images on every node#

Every enabled image and library ISO is downloaded to every online node before a server needs it. A node is checked when it is first seen after enrolment, when an image or ISO is added, enabled, disabled, deleted or given another link or checksum, after each download it finishes, and every day at 03:40.

  • One at a time. A node downloads one item at a time, images before ISOs, so a new node does not saturate its uplink.
  • Checked. A download is kept only when its checksum matches (when one is set) and it is the right kind of file. A node keeps 5% of its volume free; a download that does not fit fails with "no space".
  • Retried. A failed download is tried again after 5 minutes, 30 minutes, then once a day. The failure is shown with its reason.
  • Removed. A disabled or deleted image is removed from every node.

The Images list shows each image's spread: "Ready on 2 of 3 nodes", "Downloading on node1 (45%)", or "Failed on node1: …". An image is verified once it is ready on at least one node.

On a node's page (Infrastructure › Nodes, the node, Overview), Images and ISOs on this node lists every item with its size, state and time, the node's free space, Download again per item and Download all again.

To turn the downloads ahead of time off, go to System › Settings and switch off Download images and ISOs to nodes ahead of time in Images and ISOs on nodes. Nodes then download an image the first time a server needs it; nothing already on a node is removed.

Checksums#

An image's Checksum is sha256: followed by 64 hex digits, or sha512: followed by 128. The node checks every download against it.

Distributions replace the file behind a "latest" or "current" link with each new build, so a fixed checksum stops matching. For such links, give a Checksum source instead: the https:// address of the publisher's SHA256SUMS, SHA512SUMS or CHECKSUM file. The panel reads the line for the image's file name:

  • when the source is set or changed, then every 6 hours;
  • at once when a node's download fails with a checksum mismatch (at most once every 10 minutes);
  • when you press Refresh checksum now on the image's row (at most once a minute).

A new checksum replaces the old one (the last 10 are kept as "Previous") and the nodes fetch the new build, spread over 10 minutes. A create that failed on the old checksum is sent again once with the new one. After 3 failed reads in a row, administrators get the alert "Image checksum cannot be refreshed".

A checksum typed by hand removes the checksum source, so the panel never replaces your choice. An image with no checksum shows the SHA-256 a node computed, with Pin this checksum.

Note: The checksum file is trusted because it comes over HTTPS from the address you gave; it is not signature-checked. Use the publisher's own server.

Make an image from a server#

An administrator can save a server's first disk as a new library image (a "golden image"):

  1. Prepare the server and shut it down.

  2. Make sure its node has virt-sysprep, which cleans the copy:

    apt install libguestfs-tools
    
  3. On the server's Manage tab, under Make an image, press Make image….

  4. Give the image a Name and Slug, check Distribution, Version, Minimum disk (GB) (at least the server's disk) and Minimum memory (MB), and leave Enable it when it is ready on if it should be offered at once.

  5. Press Make image.

The node copies disk 1 compressed, cleans the copy offline with virt-sysprep, checks it and computes its checksum, which is pinned on the image. The server's own disk is only read. Other nodes then copy the image from that node over the migration port; until a node has it, placement passes that node over ("without the image yet") and a reinstall there is refused.

The copy is cleaned of: SSH host keys, the machine-id, cloud-init's state, shell histories, logs, temporary files, package caches, every account's password (locked; cloud-init sets the new root password), the host name and the network card's remembered address. It is not cleaned of: data in home directories, application data, databases, swap files, and free space on the disk. Make an image only of a server you prepared for it.

A server installed from an ISO can only be made an image of when you tick that it is a prepared template (cloud-init installed and cleaned; for Windows see Windows templates). A Windows template is copied without virt-sysprep.

A captured image has no link: it cannot be downloaded again, and the last node that has it never removes it. A failed capture shows Make again on its row.

Clone a server#

A server can be copied into a new server on the same node:

  1. Shut the server down.
  2. On its Manage tab, under Clone this server, press Clone….
  3. Set the new server's Hostname, plan or size (never smaller than the source's disk), owner (administrators), root password and SSH keys, and Clone server.

The clone gets a new id, MAC and addresses, new SSH host keys, a new machine-id and its own root password at its first start. Snapshots, backups, firewall rules and port forwards are not copied. A copy of an ISO install is an exact copy: change its network and identity inside it.

Customers may clone only when the Clone the server switch is on for them (off by default) and the clone fits their limits. A clone for another owner needs virt-sysprep on the node and is refused for an ISO install and for FreeBSD. Containers cannot be cloned.

Container images#

Container images are root file systems from images.linuxcontainers.org, used only by LXC containers (KVM and containers).

Add from the catalogue#

  1. Go to Images and ISOs › Images and press Browse images.linuxcontainers.org.
  2. The page lists every product a container can be made from, grouped by distribution, with its latest build and size. By default only cloud variants are shown: they carry cloud-init, which sets up the network, root password and SSH keys. Show variants without cloud-init shows the rest; the panel cannot set those up.
  3. Press Add on a row, or tick several and press Add selected.

The image is added enabled, with a name such as "Debian 13 (trixie)", a slug such as ct-debian-13, a minimum disk derived from the build's size, and the signature check on. The catalogue is read every 6 hours by the panel's queue; Refresh now reads it again.

Add by hand#

Press Add image, set Kind to Container, and choose the Product (os:release:arch:variant, for example debian:trixie:amd64:cloud). Optionally set a Pinned build (the SHA-256 of a build's root.tar.xz) and Check the image server's signature (on by default).

On the nodes#

Container images are not downloaded ahead of time. The first container made from a product on a node downloads its newest build (or the pinned one), checks its SHA-256 against the index and its GPG signature, and keeps it for the next containers. Deleting the last image of a product removes its downloads from the nodes.

FreeBSD#

FreeBSD 14.5 and 15.1 are in the standard set, from FreeBSD's BASIC-CLOUDINIT images. Servers made from them get the same first boot as Linux: host name, root password and SSH keys, static IPv4 and IPv6, DNS, the root file system grown to the disk, and the QEMU guest agent. A later password, network or clone setting is applied at boot by a small rc.d script (vmstack_seed).

  • A running FreeBSD server's root password is reset through the guest agent, without a restart, when the agent answers.
  • FreeBSD servers cannot run one-click applications or recipes, and cannot be cloned for another owner.
  • The rescue system is Linux: it reads a FreeBSD UFS disk, but writing to it is experimental.
  • The node's agent must support FreeBSD guests (0.36.0 or later); otherwise the create says "Node … agent cannot set up FreeBSD servers yet: update its agent", and placement passes the node over.

Note: FreeBSD's growfs can add a swap partition after the root partition at the first boot on a disk over 15 GB. A later disk resize then cannot grow the root partition: the new space stays free.

Windows images are made by the panel or by hand: see Windows templates.