{
    "product": "Cenvero Stratum",
    "generated_at": "2026-11-16T13:19:23+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "compute/virtual-machines",
            "title": "Creating Virtual Machines",
            "category": "Compute",
            "url": "https://stratum.cenvero.com/docs/compute/virtual-machines",
            "headings": [
                {
                    "level": 1,
                    "text": "Creating Virtual Machines"
                },
                {
                    "level": 2,
                    "text": "Create one"
                },
                {
                    "level": 2,
                    "text": "First boot"
                },
                {
                    "level": 3,
                    "text": "Changing the first-boot settings"
                },
                {
                    "level": 2,
                    "text": "Installing from a disc"
                },
                {
                    "level": 3,
                    "text": "Windows"
                },
                {
                    "level": 2,
                    "text": "Tenants"
                },
                {
                    "level": 2,
                    "text": "Looking at machines"
                },
                {
                    "level": 2,
                    "text": "Changing a machine"
                },
                {
                    "level": 2,
                    "text": "Growing the disk"
                },
                {
                    "level": 2,
                    "text": "Deleting"
                },
                {
                    "level": 2,
                    "text": "Over the API"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 2812,
            "markdown": "# Creating Virtual Machines\n\nA virtual machine is made from a [registered image](/docs/compute/images), or\ninstalled from an [installation disc](/docs/compute/images#installation-discs)\nonto a blank disk. The node gives it CPUs, memory, a disk and one to four network\ninterfaces, and starts it. A machine made from an image gets its own disk layered\non the image, and its first boot is configured by the node. A machine installed\nfrom a disc is set up by its installer.\n\n> Part of [Compute](/docs/compute/overview), in early access.\n\n## Create one\n\n```bash\nsudo cenvero-str-ctl vm create --name web-01 --tenant t-acme --image img-3f9a1c2e \\\n  --vcpus 2 --memory 2048 --disk 20 \\\n  --network net-acme --ssh-key-file ~/.ssh/id_ed25519.pub\n```\n\n| Flag | Meaning | Default |\n|---|---|---|\n| `--name` | Lowercase letters, digits and hyphens, 1–63 characters, not starting or ending with a hyphen. Unique within its tenant on this node | required |\n| `--image` | The base image's id. Required, unless `--iso` installs the machine from a disc | — |\n| `--vcpus` | Virtual CPUs: from 1 up to the node's CPU count | 1 |\n| `--memory` | Memory in MiB: at least 128, at most the node's memory (machines together may add up to more) | 1024 |\n| `--disk` | Disk size in GiB: at least the image's own size, at most 65536. For an install from a disc, use `--disk-gib` | the image's size |\n| `--disk-gib` | The disk size for an install from a disc: at least 1 GiB. Required with `--iso`; if `--disk` is also given, the two must name the same size | — |\n| `--iso` | Install from a disc in the disc library ([Installing from a disc](#installing-from-a-disc)). With no `--image`, the disk starts blank. With one, the image's disk is used and the disc is the first CD-ROM drive | — |\n| `--driver-iso` | A disc for the second CD-ROM drive, such as a driver disc | — |\n| `--boot-order` | The devices in the order they are tried, comma-separated: `disk`, `cdrom0` (the first drive) and `cdrom1` (the second). At create it may name only the drives the machine has | the disk, then the discs |\n| `--protected` | Refuses deletion until its protection is cleared ([Options](/docs/compute/machine-settings#options)) | off |\n| `--network NET` or `NET=IP` | Attach to a managed network, at its next free address or the one you name. Repeatable | — |\n| `--public-ip auto` or `IP` | An interface holding a public address your provider routes to this server. Repeatable | — |\n| `--tenant` | The customer the machine belongs to | none (an operator machine) |\n| `--placement auto` | In a cluster, the cluster chooses the member that suits the machine best; a refusal lists each member's reasons. Not combined with `--node` ([Placing machines](/docs/clustering/placement)) | off: this node, or the member `--node` names |\n| `--anti-affinity` | The machine's anti-affinity group: no other machine of its tenant with the same group runs on the same member. Needs `--tenant`, and every member running a version that supports it ([Placing machines](/docs/clustering/placement#anti-affinity)) | none |\n| `--hostname` | The guest's hostname | the name |\n| `--ssh-key-file` | A public key file to authorize (every non-comment line is a key). Repeatable, up to 32 keys. Refused with `--iso` when there is no `--image` | — |\n| `--user-data-file` | Your own cloud-init user-data. Refused with `--iso` when there is no `--image` | — |\n| `--dns` | A DNS server for the guest. Repeatable, up to 3. Refused with `--iso` when there is no `--image` | the node's upstream resolvers |\n| `--bandwidth-mbps` | A bandwidth limit on each of the machine's interfaces | none |\n| `--no-start` | Create it stopped | starts it |\n\nThe firmware (`--firmware uefi`, `--secure-boot`, `--tpm`) and the room a\nmachine has to grow while it runs (`--max-vcpus`, `--max-memory`) are chosen at\ncreate too: see [Firmware, resizing, interfaces and the guest\nagent](/docs/compute/machine-settings).\n\nA machine needs at least one `--network` or `--public-ip`, and has at most four\ninterfaces in all. Public interfaces come first, so the guest's first interface\nis the one it is reachable on. How each kind is wired is on\n[Networks and public addresses](/docs/compute/networking).\n\nThe node also needs at least 1 GiB free in its disk pool.\n\n**A create completes, or leaves nothing behind.** A request that cannot be met —\nan image that is not ready, a network of another tenant, an address in use, a\nquota reached — is refused before anything is made, and a failure half-way is\nundone. If the machine is created but will not start, it is kept, stopped, with\nthe reason in `state_reason`; fix the cause and run `vm start`.\n\n## First boot\n\nThe machine's first boot is configured through cloud-init: the node attaches a\nsmall read-only disk labelled `cidata` with three files, rebuilt from its\nrecords every time the machine starts. A machine installed from a disc with no\nimage has none of this: its installer sets the addresses, users and hostname\n([Installing from a disc](#installing-from-a-disc)).\n\n- **meta-data:** the machine's instance id, its hostname and the SSH keys you\n  gave.\n- **network-config:** one entry per interface, matched by its MAC address, with\n  the interface's static address. The default route goes through the first\n  public interface when there is one (see\n  [public addresses](/docs/compute/networking#public-addresses)); otherwise\n  through the first interface's network gateway, if that network has one. The\n  first interface also carries the DNS servers.\n- **user-data:** your file, passed on exactly as you wrote it. It must start with\n  `#cloud-config` or `#!` and be at most 64 KiB. Without one, the node sends only\n  what sets the hostname.\n\ncloud-init applies these once, on the machine's first boot; what the guest\nchanges afterwards is its own. SSH keys and user-data are kept on the node only,\nreadable by root; `vm show` reports how many keys and how many bytes of\nuser-data a machine has, never their content.\n\n```yaml\n#cloud-config\npackages: [nginx]\nruncmd:\n  - systemctl enable --now nginx\n```\n\n```bash\nsudo cenvero-str-ctl vm create --name www --tenant t-acme --image img-3f9a1c2e \\\n  --vcpus 2 --memory 2048 --network net-acme --user-data-file ./www.yaml\n```\n\n### Changing the first-boot settings\n\n`vm cloud-init set` changes a machine's hostname, DNS servers, SSH keys and\nuser-data. It applies to a machine made from an image:\n\n```bash\nsudo cenvero-str-ctl vm cloud-init set vm-3f9a1c2e --hostname web-02 --dns 192.0.2.53,192.0.2.54\nsudo cenvero-str-ctl vm cloud-init set vm-3f9a1c2e --ssh-key-file ~/.ssh/id_ed25519.pub\nsudo cenvero-str-ctl vm cloud-init set vm-3f9a1c2e --user-data-file ./www.yaml --apply-again\nsudo cenvero-str-ctl vm cloud-init show vm-3f9a1c2e\n```\n\n- The change reaches the machine at its **next start**. The guest reads the new\n  settings when it boots.\n- A list you give replaces the one on the machine: `--dns` replaces the servers\n  (an empty value clears them), and `--ssh-key-file` replaces the keys.\n- `--apply-again` makes the next start a new first boot for the guest, so its\n  first-boot steps run again. Without it, a configured guest does not run them\n  again. Use it only when the guest should configure itself again.\n- The same limits as a create apply: a hostname of 1 to 63 lowercase letters,\n  digits and hyphens; at most 3 DNS servers, given as IP addresses; at most 32 SSH\n  keys; and user-data of at most 64 KiB that starts with `#cloud-config` or `#!`.\n- `show` gives the hostname, the DNS servers, each key's type and fingerprint, the\n  user-data's size, and the settings' revision, an id that changes at every edit. It\n  never shows a key or the user-data text, nor anything derived from the text.\n- A machine installed from a disc with no image refuses the change: \"this machine was\n  installed from a disc, so it has no cloud-init settings to change\".\n\n## Installing from a disc\n\nA machine installed from a disc with no `--image` starts with a **blank disk**, at\nleast 1 GiB, and boots the installation disc in its first drive to run the installer.\nIt has no image, so the node sends it no first-boot configuration: the installer sets\nits addresses, users and hostname. Create therefore refuses `--ssh-key-file`,\n`--user-data-file` and `--dns` for such a machine, with the message \"a machine\ninstalled from a disc takes no SSH keys, DNS servers or user-data: those apply only to\na machine made from an image\". Give `--image` as well to keep those settings. The disc\ncomes from the [disc library](/docs/compute/images#installation-discs).\n\n```bash\nsudo cenvero-str-ctl vm create --name db-1 --tenant t-acme --vcpus 2 --memory 4096 \\\n  --disk-gib 40 --iso iso-7d4e2f10 --network net-acme\n```\n\n1. **Create it.** The machine is created and started. With `--no-start` it is\n   created stopped, and it boots the disc at its next start.\n2. **Open its graphical console** in the [web console](/docs/compute/web-console),\n   on the Console tab, and run the installer. The [consoles](/docs/compute/consoles)\n   page covers the consoles on the node.\n3. **Set its addresses in the installer.** Use the address the node gave the\n   machine's interface: `vm show` lists it with the interface's MAC address. A\n   tenant's machine can send traffic only from that address. Also set the network's\n   gateway, if it has one, and the DNS servers you want.\n4. **Eject the disc when the install is done.** Use the id `vm create` printed:\n   `sudo cenvero-str-ctl vm cdrom set vm-3f9a1c2e --slot 0 --iso \"\"`. With the\n   default boot order the disk is tried first, so the disc is used only when the\n   disk cannot boot.\n\nThe console's create wizard starts the disk at 20 GiB. The command line needs\n`--disk-gib`, as above.\n\n### Windows\n\nThe wizard's **Windows preset** sets UEFI firmware and, where the node has one, a\nTPM 2.0 device. It asks for the driver disc in the second drive, and it does not\npick that disc for you. The preset does not turn on secure boot. Nothing is\ninjected into the media: Windows setup reads its storage driver from the driver\ndisc. On the command line:\n\n```bash\nsudo cenvero-str-ctl vm create --name win-02 --tenant t-acme --vcpus 4 --memory 8192 \\\n  --disk-gib 60 --firmware uefi --tpm --iso iso-1a2b3c4d --driver-iso iso-2b3c4d5e \\\n  --network net-acme\n```\n\n`--tpm` needs a node that can give a TPM (`compute status` shows whether it can).\n\n**Windows installs are not verified on hosts without hardware virtualization.**\nThose hosts run machines in software emulation, which is too slow to verify a\nWindows setup. No Windows install has been verified on a host with hardware\nvirtualization yet either. Until this page says otherwise, treat Windows as\nuntested.\n\n## Tenants\n\nA machine with `--tenant` belongs to that customer:\n\n- it can attach only to that tenant's networks (and an operator machine, with no\n  tenant, only to networks without one);\n- it is kept apart from every other tenant's machines and containers, on its own\n  port, before it first runs (see [Tenants](/docs/tenants));\n- it cannot be created or started while the tenant is suspended, and a\n  suspension stops it (the resume starts it again if it was running — see\n  [Lifecycle](/docs/compute/lifecycle));\n- the tenant cannot be deleted while it has machines.\n\nTo cap how many machines a tenant may have **on this node** (across the cluster\nonce every member runs a version that supports it):\n\n```bash\nsudo cenvero-str-ctl tenant quota-set t-acme --max-vms 10\ncenvero-str-ctl tenant quota t-acme        # max_vms and used_vms\n```\n\n`0` means no cap. Lowering the cap never touches machines that already exist; it\nonly refuses the next create.\n\n**Bandwidth.** `--bandwidth-mbps` limits each of the machine's interfaces. It is\nrefused for a tenant that already has a bandwidth cap: the tenant's cap applies\nto its machines (see [Tenants & Bandwidth](/docs/tenants)).\n\n## Looking at machines\n\n```bash\ncenvero-str-ctl vm list\ncenvero-str-ctl vm list --tenant t-acme\ncenvero-str-ctl vm show vm-3f9a1c2e\n```\n\n```json\n{\n  \"vm\": {\n    \"id\": \"vm-3f9a1c2e\",\n    \"name\": \"web-01\",\n    \"tenant_id\": \"t-acme\",\n    \"state\": \"running\",\n    \"desired_state\": \"running\",\n    \"state_reason\": \"\",\n    \"flags\": [],\n    \"vcpus\": 2,\n    \"memory_mib\": 2048,\n    \"disk_gib\": 20,\n    \"image_id\": \"img-3f9a1c2e\",\n    \"hostname\": \"web-01\",\n    \"hypervisor\": \"kvm\",\n    \"nics\": [\n      { \"index\": 0, \"network_id\": \"net-acme\", \"ip\": \"10.30.0.20\", \"mac\": \"02:ce:0a:1e:00:14\",\n        \"interface\": \"cnv-v-3f9a1c2e0\", \"bandwidth_mbps\": 0 }\n    ],\n    \"user_data_bytes\": 0,\n    \"ssh_key_count\": 1,\n    \"console_sessions\": [],\n    \"created_at\": \"2026-09-28T09:20:11Z\",\n    \"updated_at\": \"2026-09-28T09:21:02Z\"\n  }\n}\n```\n\n`state` is what the machine is doing, `desired_state` what you last asked for;\n[Lifecycle and restarts](/docs/compute/lifecycle) explains the states and the\n`flags`. `hypervisor` is `kvm`, or `emulated` on a node without hardware\nvirtualization.\n\n## Changing a machine\n\nCPUs and memory are changed with `vm update`, live on a running machine within\nits maximums; interfaces are added and removed with `vm nic add` and\n`vm nic remove`, also while it runs. Both are on [Firmware, resizing, interfaces\nand the guest agent](/docs/compute/machine-settings), with the guest agent\n(setting a password, the guest's own addresses).\n\n## Growing the disk\n\n```bash\nsudo cenvero-str-ctl vm stop vm-3f9a1c2e\nsudo cenvero-str-ctl vm resize vm-3f9a1c2e --disk 40\nsudo cenvero-str-ctl vm start vm-3f9a1c2e\n```\n\nThe machine must be stopped, and a disk can only grow. The guest sees the new\nsize on its next boot; most cloud images then grow their root file system to fit\nby themselves.\n\n## Deleting\n\n```bash\nsudo cenvero-str-ctl vm delete vm-3f9a1c2e --yes\n```\n\nA **protected** machine is not deleted. The delete is refused with \"this machine is\nprotected; clear its protection before you delete it\", and nothing changes. Clear\nthe protection first: `sudo cenvero-str-ctl vm options set vm-3f9a1c2e --protected=false`\n([Options](/docs/compute/machine-settings#options)). Starting, stopping, restarting\nand the consoles stay allowed on a protected machine.\n\nA running machine is powered off at once (not shut down gracefully — stop it\nfirst if the guest should shut down cleanly), and its disk, its first-boot disk\nand its interfaces are removed. Its network addresses and public address are free\nagain straight away. The disk's current data is gone, and its space is released\nwithout being overwritten first. **Its backups are kept**, as restore points you\ncan restore into a new volume, and they stay until you delete them. A machine that\nhas no backups leaves nothing behind ([Snapshots, backups and schedules](/docs/compute/backups#what-a-delete-keeps)).\nA delete that is interrupted can be run again; it carries on where it stopped.\n\n## Over the API\n\n```bash\ncurl -k -X POST \"$NODE/api/v1/vms\" -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" -d '{\n    \"name\": \"web-01\", \"tenant_id\": \"t-acme\", \"image_id\": \"img-3f9a1c2e\",\n    \"vcpus\": 2, \"memory_mib\": 2048, \"disk_gib\": 20,\n    \"networks\": [ { \"network_id\": \"net-acme\", \"ip\": \"10.30.0.20\" } ],\n    \"ssh_authorized_keys\": [ \"ssh-ed25519 AAAA… ops@example.com\" ],\n    \"user_data\": \"#cloud-config\\npackages: [nginx]\\n\",\n    \"dns\": [ \"192.0.2.53\" ],\n    \"start\": true\n  }'\n```\n\n| Method | Path | Notes |\n|---|---|---|\n| `GET` | `/api/v1/vms` | `?tenant_id=` for one tenant's |\n| `POST` | `/api/v1/vms` | **201** with the machine when the create finishes within 20 seconds. A longer create answers **202** with the machine's `id` and its `task`: follow the task (`GET /api/v1/tasks/{id}`), which ends succeeded or failed with the reason. Do not send the create again while it runs. A create still being prepared after 25 seconds answers **202** with no task and a `message`: list the machines to see whether it was created. Each `networks` entry has `network_id` (optionally `ip`) or `public_ip`, and optionally `bandwidth_mbps`. For an install from a disc, leave out `image_id` and give `iso_id` and `disk_gib`; `driver_iso_id`, `boot_order` and `protected` are optional |\n| `GET` | `/api/v1/vms/{id}` | One machine |\n| `DELETE` | `/api/v1/vms/{id}` | Delete it and its disk. **409** for a protected machine |\n| `POST` | `/api/v1/vms/{id}/resize` | `{\"disk_gib\": 40}`, stopped machines only |\n| `GET` | `/api/v1/vms/{id}/cloud-init` | The first-boot settings, without their secrets |\n| `PUT` | `/api/v1/vms/{id}/cloud-init` | `{\"hostname\", \"dns\", \"ssh_keys\", \"user_data\", \"apply_again\"}`, each optional. **200**; **409** for a machine installed from a disc |\n\nChanging CPUs, memory, interfaces, drives and options, and the guest agent, have\ntheir calls on [Firmware, resizing, interfaces and the guest\nagent](/docs/compute/machine-settings#the-same-over-the-api).\n\nEvery change answers as described here and also names the **task** that\nrecords it (`\"task\"`, and a `Location` header): who asked, what was done and how\nit ended — including a create that failed and was rolled back. A machine's\nhistory is `GET /api/v1/tasks?object=vm-3f9a1c2e`; see [Tasks](/docs/api#tasks).\n`GET /api/v1/resources` lists every machine with its state in one answer.\n\nStarting, stopping and restarting are on [Lifecycle and\nrestarts](/docs/compute/lifecycle). Errors come back as `{\"error\": \"…\"}` in plain\nwords: **400** for a request that is not valid, **404** for an unknown machine or\nimage, **409** for a conflict (a name in use, a state that does not allow it, a\nquota reached), **503** while Compute is not ready, **403** when the licence does\nnot allow it. Unknown fields in the body are refused, not ignored.\n\nTenant-scoped API keys cannot create or delete machines. Use the node's API\ntoken, an operator key, or an account or [API token](/docs/access-control#api-tokens)\nwhose role allows it: creating a machine needs `VM.Allocate` on `/vms` or on its\ntenant, and the right to see the image and networks it names.\n\n## See also\n\n- [Images](/docs/compute/images)\n- [Installation discs](/docs/compute/images#installation-discs)\n- [Firmware, resizing, interfaces and the guest agent](/docs/compute/machine-settings)\n- [Networks and public addresses](/docs/compute/networking)\n- [Lifecycle and restarts](/docs/compute/lifecycle)\n"
        }
    ]
}