Exclusive Access · Invitation Only

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 is almalinux. 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"
  }
}
stateMeaning
downloadingBeing fetched or copied, checked and converted
readyMachines can be created from it
failedSee 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.
stateMeaning
stagingBeing brought in: downloaded or copied, then checked
readyMachines can be installed from it
failedSee 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

MethodPathBodyAnswer
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

↓ This page as JSON ↓ All documentation as JSON