{
    "product": "Cenvero Stratum",
    "generated_at": "2026-11-16T13:19:23+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "compute/images",
            "title": "Images",
            "category": "Compute",
            "url": "https://stratum.cenvero.com/docs/compute/images",
            "headings": [
                {
                    "level": 1,
                    "text": "Images"
                },
                {
                    "level": 2,
                    "text": "Which images work"
                },
                {
                    "level": 2,
                    "text": "Registering an image"
                },
                {
                    "level": 2,
                    "text": "The image catalogue"
                },
                {
                    "level": 2,
                    "text": "Listing, showing and deleting"
                },
                {
                    "level": 2,
                    "text": "Over the API"
                },
                {
                    "level": 2,
                    "text": "Installation discs"
                },
                {
                    "level": 3,
                    "text": "Registering a disc"
                },
                {
                    "level": 3,
                    "text": "What is checked"
                },
                {
                    "level": 3,
                    "text": "Listing and deleting"
                },
                {
                    "level": 3,
                    "text": "Over the API"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 2189,
            "markdown": "# Images\n\nA virtual machine starts from a **base image**: a Linux cloud image registered\nonce 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\nmany machines can share one image and the image itself never changes.\n\nA machine can also be installed from an **installation disc**: an ISO image kept\nin the node's disc library, which a machine boots from to run its installer.\nDiscs are covered at the end of this page.\n\n> Part of [Compute](/docs/compute/overview), in early access.\n\n## Which images work\n\n- **Linux cloud images** that configure themselves on first boot with\n  cloud-init from a \"NoCloud\" data source — the official cloud images of Debian\n  (\"genericcloud\"), Ubuntu, and most other distributions. The first-boot\n  configuration arrives on a small read-only disk labelled `cidata`\n  ([what it contains](/docs/compute/virtual-machines#first-boot)).\n- **Formats:** qcow2 or raw. A raw image is converted to qcow2 on the way in.\n- **Self-contained files only.** An image that refers to a backing file or keeps\n  its data in a separate file is refused, as is an encrypted one.\n- **Up to 50 GiB** per image file.\n- **x86_64** guests (see [Current limits](/docs/compute/limits)).\n\nImages that do not run cloud-init still boot, but nothing inside them is set up\nfor you: give them their address yourself, or turn on DHCP for their network.\n\n## Registering an image\n\nFrom an `http://` or `https://` URL — the SHA-256 is required, and the image\ncannot be used unless the download matches it:\n\n```bash\nsudo cenvero-str-ctl image register --name debian-13 \\\n  --url https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2 \\\n  --sha256 <sha256 of that file> --wait\n```\n\nMost distributions publish checksums next to their images. Debian publishes\nSHA-512 sums: download the image once, check it against them, and use\n`sha256sum` on the same file for the value above.\n\nOr copy a file that is already on the node, from any directory (the SHA-256 is\nthen optional, and checked when given):\n\n```bash\nsudo cenvero-str-ctl image register --name cirros --path /root/cirros-0.6.3-x86_64-disk.img --wait\n```\n\nThe command opens the file itself and hands the open file to the agent, which\ncopies and checks it exactly like a download — so a file in your home directory\nor a temporary directory works too. The path must name a regular file — not a\nlink, directory, device or pipe. Copying from a path is only possible on the\nnode's own command line, never over the API.\n\nRegistration runs in the background. `--wait` waits until the image is `ready`\n(or `failed`, with the reason); without it the command returns at once and the\nimage shows as `downloading`. At most two images are fetched at a time.\n\nThe image name may use letters, digits, `.`, `_` and `-` (up to 64 characters,\nstarting with a letter or digit) and must be unique on the node. An image added to\na cluster's library must also have a name that no other image in the cluster has\n([The cluster image library](/docs/clustering/images)).\n\n## The image catalogue\n\nThe node carries a **catalogue** of cloud images, each one published by its own\ndistribution. An entry holds the image's name, the publisher's address for it, its\nSHA-256, and a few facts about it. The catalogue holds addresses and checksums only.\nThe node downloads each image from its publisher, and nothing is redistributed.\n\nThe catalogue has one entry in this release:\n\n- **AlmaLinux 9 GenericCloud x86_64** (`almalinux-9-genericcloud`): release 9,\n  BIOS firmware, cloud-init, about 546 MiB. Its default user is `almalinux`. The\n  entry was checked on 2026-10-21.\n\nEach entry's SHA-256 is copied from the publisher's own checksum file, the one\npublished beside the image. The publisher signs that file. The maintainers check the\nsignature when they add an entry or refresh one, so no entry carries a checksum the\nnode's team chose. A download that does not match the checksum is refused, as it is\nfor any image. For this entry the checksum file is\n`https://repo.almalinux.org/almalinux/9/cloud/x86_64/images/CHECKSUM`, and the\nSHA-256 is `25942b554efaac077e2f60d6bb27bd3332c171454cc21bbd33e5f79244d7570f`, the\nvalue on the line for the image in that file.\n\nTo see the catalogue, and to install an entry:\n\n```bash\nsudo cenvero-str-ctl image catalogue\nsudo cenvero-str-ctl image register --name almalinux-9 --catalogue almalinux-9-genericcloud --wait\n```\n\n`image register --catalogue` is the install. It takes the entry's name, and no URL\nor checksum, because the entry supplies both. Over the API, `POST /api/v1/images`\ntakes `{\"name\", \"catalogue\"}`: the same install, answered **202** with the image and\nits task. Give exactly one source, either a catalogue id or a URL with its SHA-256.\nAn id the catalogue does not have is refused with \"the catalogue has no image with\nthat id\".\n\n## Listing, showing and deleting\n\n```bash\ncenvero-str-ctl image list\ncenvero-str-ctl image show img-3f9a1c2e\nsudo cenvero-str-ctl image delete img-3f9a1c2e\n```\n\n```json\n{\n  \"image\": {\n    \"id\": \"img-3f9a1c2e\",\n    \"name\": \"debian-13\",\n    \"state\": \"ready\",\n    \"sha256\": \"5754395abffb1d384d50f6d0945d46d1beb7be42a7e786e4fc4a6f27270ab16f\",\n    \"format\": \"qcow2\",\n    \"source_format\": \"qcow2\",\n    \"virtual_size\": 3221225472,\n    \"file_size\": 340983808,\n    \"source_url\": \"https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2\",\n    \"created_at\": \"2026-09-28T09:14:02Z\"\n  }\n}\n```\n\n| `state` | Meaning |\n|---|---|\n| `downloading` | Being fetched or copied, checked and converted |\n| `ready` | Machines can be created from it |\n| `failed` | See `error` (a checksum mismatch, a refused format, a download error, …). The partial file is gone; delete the entry and register again |\n\nAn image cannot be deleted while any machine's disk is made from it (the error\nnames those machines), nor while it is still downloading. An image that was\nstill downloading when the node restarted is marked `failed` — register it again.\n\n`virtual_size` is the size of the disk inside the image, in bytes: a machine's\ndisk can never be smaller than that.\n\n`source_url` shows the address without a user name, a password or a query string,\nbecause a query string may carry a secret such as a signed download token. When the\nview leaves something out, it adds a `source_url_note` that says so. The node keeps the\nwhole address for the download.\n\n## Over the API\n\n```bash\n# register from a URL (202: it downloads in the background)\ncurl -k -X POST \"$NODE/api/v1/images\" -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"debian-13\",\"url\":\"https://…/debian-13-genericcloud-amd64.qcow2\",\"sha256\":\"<hex>\"}'\n\ncurl -k \"$NODE/api/v1/images\" -H \"Authorization: Bearer $TOKEN\"\ncurl -k \"$NODE/api/v1/images/img-3f9a1c2e\" -H \"Authorization: Bearer $TOKEN\"\ncurl -k -X DELETE \"$NODE/api/v1/images/img-3f9a1c2e\" -H \"Authorization: Bearer $TOKEN\"\n```\n\nRegistering from a path on the node is refused over the API.\n\nThe registration answers with the **task** that brings the image in (`\"task\"`).\nIts progress is in bytes — of the size the server announces, when it does — and\nit can be stopped while it runs; the image is then marked failed, and you delete\nit or register it again:\n\n```bash\ncurl -k \"$NODE/api/v1/tasks/{task}\" -H \"Authorization: Bearer $TOKEN\"\ncurl -k -X POST \"$NODE/api/v1/tasks/{task}/cancel\" -H \"Authorization: Bearer $TOKEN\"\nsudo cenvero-str-ctl task log {task} --follow     # the same on the node\n```\n\nAt most two images or discs come in at a time. Up to sixteen more wait for a turn, and\ntheir tasks read `queued`; a registration made while sixteen already wait is refused\nuntil one of them finishes. A download the agent was in the middle of when it restarted\nis marked failed (\"interrupted; register it again\"), and so is its task.\n\n**A note on download addresses.** Image downloads may not connect to a loopback,\nlink-local, multicast or unspecified address, a reserved or broadcast address, or a\ncloud provider's instance-metadata address. An address that leads to one of these,\nsuch as an IPv6 address that carries one of them, is refused as well. Private\naddresses are allowed, so you can keep images on a mirror inside your network — which\nalso means anyone holding an operator API token can make the node fetch from your\ninternal network.\n\n## Installation discs\n\nAn **installation disc** is an ISO 9660 image, the usual format an operating\nsystem's installer is published in. The node keeps the discs it can install from in its\n**disc library**. Every machine on the node can use them. A machine installed\nfrom a disc starts with a blank disk ([Installing from a disc](/docs/compute/virtual-machines#installing-from-a-disc)).\n\n### Registering a disc\n\nFrom an address, with its SHA-256. The checksum is required, and the download is\nrefused unless it matches:\n\n```bash\nsudo cenvero-str-ctl iso register --name debian-13-netinst \\\n  --url https://downloads.example.net/debian-13-netinst.iso \\\n  --sha256 <sha256 of that file> --wait\n```\n\nUse `https://` where the publisher offers it. The node also accepts `http://`\naddresses. The download follows the same rules as an image's: it may not connect\nto a loopback, link-local, multicast or unspecified address, a reserved or broadcast\naddress, or a cloud provider's instance-metadata address; an address that leads to one\nof these is refused too (see the note on download addresses under\n[Over the API](#over-the-api)).\n\nOr from a file on the node, from any directory:\n\n```bash\nsudo cenvero-str-ctl iso register --name rescue --path /root/rescue.iso --wait\n```\n\nThe command opens the file itself and hands it to the node. The path must name a\nregular file: not a link, a directory, a device or a pipe. Only the node's own\ncommand line takes a file. `--node` refuses it, and the API refuses a path.\n\nRegistration runs in the background, and its task reports its progress in bytes.\nWith `--wait`, the command returns once the disc is `ready` or has `failed`. A\nregistration whose task is still running can be cancelled, which marks the disc\nfailed.\n\nThe name uses the same rules as an image's name: letters, digits, `.`, `_` and\n`-`, up to 64 characters, starting with a letter or digit, and unique on the node.\n\n### What is checked\n\n- **The file must be an ISO 9660 image.** A file that is not fails with \"the disc\n  image is not an ISO 9660 image\".\n- **At most 16 GiB.** A larger disc is refused with \"the disc image is larger than\n  16 GiB\".\n- **The SHA-256 must match.** A download whose checksum differs fails with \"the\n  disc image's checksum does not match the one given\".\n- Stratum never runs a program on a disc. It checks the disc's structure and its\n  hash, and nothing more: it does not check that the disc boots.\n\n| `state` | Meaning |\n|---|---|\n| `staging` | Being brought in: downloaded or copied, then checked |\n| `ready` | Machines can be installed from it |\n| `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 |\n\n### Listing and deleting\n\n```bash\ncenvero-str-ctl iso list\ncenvero-str-ctl iso show iso-7d4e2f10\nsudo cenvero-str-ctl iso delete iso-7d4e2f10 --yes\n```\n\n```json\n{\n  \"iso\": {\n    \"id\": \"iso-7d4e2f10\",\n    \"name\": \"debian-13-netinst\",\n    \"sha256\": \"b3a1f7c9d2e4068f1a5c3b7d9e2f4a6c8b0d1e3f5a7c9b2d4e6f8a0c1b3d5e7f\",\n    \"size_bytes\": 701988864,\n    \"state\": \"ready\",\n    \"origin\": \"url\",\n    \"attached_to\": [\"vm-3f9a1c2e\"],\n    \"created_at\": \"2026-10-20T09:14:02Z\"\n  }\n}\n```\n\n`origin` is `url` for a disc registered from an address and `local file` for one\nregistered from a file. `attached_to` lists the machines whose CD-ROM drives hold\nthe disc, among the machines you may see.\n\nA disc that a machine holds cannot be deleted. The answer is **409** and names\nthe machines you may see:\n\n```json\n{ \"error\": \"this disc image is in use by machines; eject it first\", \"machines\": [\"vm-3f9a1c2e\"] }\n```\n\nEject the disc from those machines ([CD-ROM drives](/docs/compute/machine-settings#cd-rom-drives-and-boot-order)),\nthen delete it. A disc still being brought in cannot be deleted: wait for it to\nfinish, or cancel its registration first. Deleting a disc does not change the\nmachines that were installed from it.\n\n### Over the API\n\n| Method | Path | Body | Answer |\n|---|---|---|---|\n| `GET` | `/api/v1/isos` | — | **200**: the discs the caller may see |\n| `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 |\n| `GET` | `/api/v1/isos/{id}` | — | **200** with the disc and the machines that hold it; **404** when there is none |\n| `DELETE` | `/api/v1/isos/{id}` | — | **200**; **409** with the machines that hold it, and the sentence above |\n\nReading a disc needs `Image.Audit`. Registering and deleting need `Image.Allocate`,\nand a licence that includes Compute and is not frozen. No tenant-scoped key\nreaches the library: discs belong to the operator.\n\n## See also\n\n- [Creating virtual machines](/docs/compute/virtual-machines)\n- [The cluster image library](/docs/clustering/images) — sharing an image across the members of a cluster\n- [Firmware, resizing, interfaces and the guest agent](/docs/compute/machine-settings)\n- [Current limits](/docs/compute/limits)\n"
        }
    ]
}