Images
A virtual machine starts from a base image: a Linux cloud image registered once on the node, or added once to a cluster's image library and copied to the members that use it. Each machine gets its own disk layered on top of the image, so many machines can share one image and the image itself never changes.
A machine can also be installed from an installation disc: an ISO image kept in the node's disc library, which a machine boots from to run its installer. Discs are covered at the end of this page.
Part of Compute, in early access.
Which images work
- Linux cloud images that configure themselves on first boot with cloud-init from a "NoCloud" data source — the official cloud images of Debian ("genericcloud"), Ubuntu, and most other distributions. The first-boot configuration arrives on a small read-only disk labelled
cidata(what it contains). - Formats: qcow2 or raw. A raw image is converted to qcow2 on the way in.
- Self-contained files only. An image that refers to a backing file or keeps its data in a separate file is refused, as is an encrypted one.
- Up to 50 GiB per image file.
- x86_64 guests (see Current limits).
Images that do not run cloud-init still boot, but nothing inside them is set up for you: give them their address yourself, or turn on DHCP for their network.
Registering an image
From an http:// or https:// URL — the SHA-256 is required, and the image
cannot be used unless the download matches it:
sudo cenvero-str-ctl image register --name debian-13 \
--url https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2 \
--sha256 <sha256 of that file> --wait
Most distributions publish checksums next to their images. Debian publishes
SHA-512 sums: download the image once, check it against them, and use
sha256sum on the same file for the value above.
Or copy a file that is already on the node, from any directory (the SHA-256 is then optional, and checked when given):
sudo cenvero-str-ctl image register --name cirros --path /root/cirros-0.6.3-x86_64-disk.img --wait
The command opens the file itself and hands the open file to the agent, which copies and checks it exactly like a download — so a file in your home directory or a temporary directory works too. The path must name a regular file — not a link, directory, device or pipe. Copying from a path is only possible on the node's own command line, never over the API.
Registration runs in the background. --wait waits until the image is ready
(or failed, with the reason); without it the command returns at once and the
image shows as downloading. At most two images are fetched at a time.
The image name may use letters, digits, ., _ and - (up to 64 characters,
starting with a letter or digit) and must be unique on the node. An image added to
a cluster's library must also have a name that no other image in the cluster has
(The cluster image library).
The image catalogue
The node carries a catalogue of cloud images, each one published by its own distribution. An entry holds the image's name, the publisher's address for it, its SHA-256, and a few facts about it. The catalogue holds addresses and checksums only. The node downloads each image from its publisher, and nothing is redistributed.
The catalogue has one entry in this release:
- AlmaLinux 9 GenericCloud x86_64 (
almalinux-9-genericcloud): release 9, BIOS firmware, cloud-init, about 546 MiB. Its default user isalmalinux. The entry was checked on 2026-10-21.
Each entry's SHA-256 is copied from the publisher's own checksum file, the one
published beside the image. The publisher signs that file. The maintainers check the
signature when they add an entry or refresh one, so no entry carries a checksum the
node's team chose. A download that does not match the checksum is refused, as it is
for any image. For this entry the checksum file is
https://repo.almalinux.org/almalinux/9/cloud/x86_64/images/CHECKSUM, and the
SHA-256 is 25942b554efaac077e2f60d6bb27bd3332c171454cc21bbd33e5f79244d7570f, the
value on the line for the image in that file.
To see the catalogue, and to install an entry:
sudo cenvero-str-ctl image catalogue
sudo cenvero-str-ctl image register --name almalinux-9 --catalogue almalinux-9-genericcloud --wait
image register --catalogue is the install. It takes the entry's name, and no URL
or checksum, because the entry supplies both. Over the API, POST /api/v1/images
takes {"name", "catalogue"}: the same install, answered 202 with the image and
its task. Give exactly one source, either a catalogue id or a URL with its SHA-256.
An id the catalogue does not have is refused with "the catalogue has no image with
that id".
Listing, showing and deleting
cenvero-str-ctl image list
cenvero-str-ctl image show img-3f9a1c2e
sudo cenvero-str-ctl image delete img-3f9a1c2e
{
"image": {
"id": "img-3f9a1c2e",
"name": "debian-13",
"state": "ready",
"sha256": "5754395abffb1d384d50f6d0945d46d1beb7be42a7e786e4fc4a6f27270ab16f",
"format": "qcow2",
"source_format": "qcow2",
"virtual_size": 3221225472,
"file_size": 340983808,
"source_url": "https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2",
"created_at": "2026-09-28T09:14:02Z"
}
}
state | Meaning |
|---|---|
downloading | Being fetched or copied, checked and converted |
ready | Machines can be created from it |
failed | See error (a checksum mismatch, a refused format, a download error, …). The partial file is gone; delete the entry and register again |
An image cannot be deleted while any machine's disk is made from it (the error
names those machines), nor while it is still downloading. An image that was
still downloading when the node restarted is marked failed — register it again.
virtual_size is the size of the disk inside the image, in bytes: a machine's
disk can never be smaller than that.
source_url shows the address without a user name, a password or a query string,
because a query string may carry a secret such as a signed download token. When the
view leaves something out, it adds a source_url_note that says so. The node keeps the
whole address for the download.
Over the API
# register from a URL (202: it downloads in the background)
curl -k -X POST "$NODE/api/v1/images" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"debian-13","url":"https://…/debian-13-genericcloud-amd64.qcow2","sha256":"<hex>"}'
curl -k "$NODE/api/v1/images" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/images/img-3f9a1c2e" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/images/img-3f9a1c2e" -H "Authorization: Bearer $TOKEN"
Registering from a path on the node is refused over the API.
The registration answers with the task that brings the image in ("task").
Its progress is in bytes — of the size the server announces, when it does — and
it can be stopped while it runs; the image is then marked failed, and you delete
it or register it again:
curl -k "$NODE/api/v1/tasks/{task}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/tasks/{task}/cancel" -H "Authorization: Bearer $TOKEN"
sudo cenvero-str-ctl task log {task} --follow # the same on the node
At most two images or discs come in at a time. Up to sixteen more wait for a turn, and
their tasks read queued; a registration made while sixteen already wait is refused
until one of them finishes. A download the agent was in the middle of when it restarted
is marked failed ("interrupted; register it again"), and so is its task.
A note on download addresses. Image downloads may not connect to a loopback, link-local, multicast or unspecified address, a reserved or broadcast address, or a cloud provider's instance-metadata address. An address that leads to one of these, such as an IPv6 address that carries one of them, is refused as well. Private addresses are allowed, so you can keep images on a mirror inside your network — which also means anyone holding an operator API token can make the node fetch from your internal network.
Installation discs
An installation disc is an ISO 9660 image, the usual format an operating system's installer is published in. The node keeps the discs it can install from in its disc library. Every machine on the node can use them. A machine installed from a disc starts with a blank disk (Installing from a disc).
Registering a disc
From an address, with its SHA-256. The checksum is required, and the download is refused unless it matches:
sudo cenvero-str-ctl iso register --name debian-13-netinst \
--url https://downloads.example.net/debian-13-netinst.iso \
--sha256 <sha256 of that file> --wait
Use https:// where the publisher offers it. The node also accepts http://
addresses. The download follows the same rules as an image's: it may not connect
to a loopback, link-local, multicast or unspecified address, a reserved or broadcast
address, or a cloud provider's instance-metadata address; an address that leads to one
of these is refused too (see the note on download addresses under
Over the API).
Or from a file on the node, from any directory:
sudo cenvero-str-ctl iso register --name rescue --path /root/rescue.iso --wait
The command opens the file itself and hands it to the node. The path must name a
regular file: not a link, a directory, a device or a pipe. Only the node's own
command line takes a file. --node refuses it, and the API refuses a path.
Registration runs in the background, and its task reports its progress in bytes.
With --wait, the command returns once the disc is ready or has failed. A
registration whose task is still running can be cancelled, which marks the disc
failed.
The name uses the same rules as an image's name: letters, digits, ., _ and
-, up to 64 characters, starting with a letter or digit, and unique on the node.
What is checked
- The file must be an ISO 9660 image. A file that is not fails with "the disc image is not an ISO 9660 image".
- At most 16 GiB. A larger disc is refused with "the disc image is larger than 16 GiB".
- The SHA-256 must match. A download whose checksum differs fails with "the disc image's checksum does not match the one given".
- Stratum never runs a program on a disc. It checks the disc's structure and its hash, and nothing more: it does not check that the disc boots.
state | Meaning |
|---|---|
staging | Being brought in: downloaded or copied, then checked |
ready | Machines can be installed from it |
failed | See reason: a checksum that does not match, a file that is not an ISO 9660 image, a download that failed, a registration that was cancelled, or one the node restarted in the middle of. Delete it, or register it again |
Listing and deleting
cenvero-str-ctl iso list
cenvero-str-ctl iso show iso-7d4e2f10
sudo cenvero-str-ctl iso delete iso-7d4e2f10 --yes
{
"iso": {
"id": "iso-7d4e2f10",
"name": "debian-13-netinst",
"sha256": "b3a1f7c9d2e4068f1a5c3b7d9e2f4a6c8b0d1e3f5a7c9b2d4e6f8a0c1b3d5e7f",
"size_bytes": 701988864,
"state": "ready",
"origin": "url",
"attached_to": ["vm-3f9a1c2e"],
"created_at": "2026-10-20T09:14:02Z"
}
}
origin is url for a disc registered from an address and local file for one
registered from a file. attached_to lists the machines whose CD-ROM drives hold
the disc, among the machines you may see.
A disc that a machine holds cannot be deleted. The answer is 409 and names the machines you may see:
{ "error": "this disc image is in use by machines; eject it first", "machines": ["vm-3f9a1c2e"] }
Eject the disc from those machines (CD-ROM drives), then delete it. A disc still being brought in cannot be deleted: wait for it to finish, or cancel its registration first. Deleting a disc does not change the machines that were installed from it.
Over the API
| Method | Path | Body | Answer |
|---|---|---|---|
GET | /api/v1/isos | — | 200: the discs the caller may see |
POST | /api/v1/isos | {"name", "url", "sha256"} | 202 with the disc and its task. A path is refused: a file is registered from the node's own command line |
GET | /api/v1/isos/{id} | — | 200 with the disc and the machines that hold it; 404 when there is none |
DELETE | /api/v1/isos/{id} | — | 200; 409 with the machines that hold it, and the sentence above |
Reading a disc needs Image.Audit. Registering and deleting need Image.Allocate,
and a licence that includes Compute and is not frozen. No tenant-scoped key
reaches the library: discs belong to the operator.
See also
- Creating virtual machines
- The cluster image library — sharing an image across the members of a cluster
- Firmware, resizing, interfaces and the guest agent
- Current limits