{
    "product": "Cenvero Stratum",
    "generated_at": "2026-11-16T13:19:22+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "compute/machine-settings",
            "title": "Firmware, Resizing, Interfaces and the Guest Agent",
            "category": "Compute",
            "url": "https://stratum.cenvero.com/docs/compute/machine-settings",
            "headings": [
                {
                    "level": 1,
                    "text": "Firmware, Resizing, Interfaces and the Guest Agent"
                },
                {
                    "level": 2,
                    "text": "Firmware: BIOS or UEFI, secure boot and a TPM"
                },
                {
                    "level": 2,
                    "text": "CD-ROM drives and boot order"
                },
                {
                    "level": 3,
                    "text": "Boot order"
                },
                {
                    "level": 2,
                    "text": "Options"
                },
                {
                    "level": 2,
                    "text": "Changing a machine's size"
                },
                {
                    "level": 2,
                    "text": "Adding and removing network interfaces"
                },
                {
                    "level": 2,
                    "text": "If an interface is removed behind Stratum's back"
                },
                {
                    "level": 2,
                    "text": "The guest agent"
                },
                {
                    "level": 3,
                    "text": "Setting a password"
                },
                {
                    "level": 2,
                    "text": "The same over the API"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 2611,
            "markdown": "# Firmware, Resizing, Interfaces and the Guest Agent\n\nThis page covers what you can change on a virtual machine after you create it —\nits name and other options, its CD-ROM drives and boot order, its vCPUs and\nmemory, and its network interfaces — the firmware options you choose when you\ncreate it (UEFI, secure boot, a TPM), and what the guest agent inside a machine\nlets you do: set a password, see the guest's own addresses.\n\n> Part of [Compute](/docs/compute/overview), in early access. The commands\n> below run on the node, as root; every change needs a licence that includes\n> Compute and is not frozen. Looking at a machine never does. Creating a machine\n> is on [Creating virtual machines](/docs/compute/virtual-machines).\n\n## Firmware: BIOS or UEFI, secure boot and a TPM\n\nA machine starts with BIOS firmware unless you ask for UEFI. Windows 11 needs\nUEFI with secure boot and a TPM 2.0:\n\n```bash\nsudo cenvero-str-ctl vm create --name win11 --image img-5d2c90a1 --vcpus 4 --memory 8192 --disk 64 \\\n  --network net-8b1f03 --firmware uefi --secure-boot --tpm\n```\n\n| Option | What the machine gets |\n|---|---|\n| `--firmware bios` | BIOS firmware. The default, and what every machine had before this option existed. |\n| `--firmware uefi` | UEFI firmware, with its own settings store (boot order, secure boot keys) kept on the node. |\n| `--secure-boot` | UEFI with secure boot on and the usual Microsoft keys enrolled, so signed boot loaders (Windows, and Linux distributions with a signed shim) boot. Needs `--firmware uefi`. |\n| `--tpm` | A TPM 2.0 device, emulated per machine, its contents kept on the node. Works with either firmware. |\n\nThe firmware and the TPM are chosen at create and cannot be changed later: a\nguest installed under one firmware does not boot under the other, and a guest\nmay seal keys (a disk encryption key, for example) to its TPM. Deleting the\nmachine deletes its firmware settings and its TPM contents with it. The\n[options](#options) show the firmware read-only, and a request to change it is\nrefused with \"firmware is chosen when a machine is created; it cannot be changed\nafterwards\".\n\nIf the node cannot provide an option you ask for, the create is refused with a\nplain message, for example *this host cannot give a virtual machine a TPM: the\nTPM emulator is not installed*. The installer's `compute` and `suite` profiles\ninstall UEFI and TPM support; re-run the installer with one of them to add it.\nOn a server that already runs another panel's virtual machines, the installer\nlists what is missing instead of installing it (see [Compute](/docs/compute/overview#installing-with-compute)).\n\nUEFI, secure boot and a TPM are offered once the node has confirmed what it can\ngive a machine. Until then a request for one of them is refused with a message to\ntry again, and the node checks again on its own.\n\n`compute status` lists what the node supports:\n\n```json\n\"hypervisor\": { \"virt\": \"kvm\", \"firmware\": [\"bios\", \"uefi\"], \"secure_boot\": true, \"tpm\": true }\n```\n\n## CD-ROM drives and boot order\n\nA machine has up to two CD-ROM drives, and both are read-only. The first holds the\ninstallation disc and the second a driver disc, for Windows. A drive appears once its\nslot has been set, with a disc or with an empty value, and it stays until it is\nremoved, even when its disc is ejected. A disc comes from the\n[disc library](/docs/compute/images#installation-discs). Put one in a drive, change\nit or eject it:\n\n```bash\nsudo cenvero-str-ctl vm cdrom set vm-3f9a1c2e --slot 0 --iso iso-7d4e2f10\nsudo cenvero-str-ctl vm cdrom set vm-3f9a1c2e --slot 0 --iso \"\"\nsudo cenvero-str-ctl vm cdrom list vm-3f9a1c2e\nsudo cenvero-str-ctl vm cdrom remove vm-3f9a1c2e --slot 1\n```\n\nAn empty `--iso` ejects the disc. The answer's `live` field says whether the\nchange took effect at once.\n\n| The machine is | When the disc changes |\n|---|---|\n| Running | At once, if the running machine takes the change: `live` is `true`. If it does not, the change applies at its next start, `live` is `false`, and the machine is flagged `pending_restart` |\n| Stopped | At its next start (`live` is `false`) |\n| Starting, stopping or paused | Once it is running or stopped. Until then the change is refused |\n\nRemoving a drive from a running machine ejects the disc in it first, when there is\none, and then detaches the drive. If the running machine will not release the drive,\nthe removal is refused, and the drive stays on the record. The disc may already have\nleft the tray, so put it back with `set`, or try the removal again. On a stopped\nmachine the removal takes effect at its next start.\n\n### Boot order\n\nThe boot order is the sequence in which the machine tries its devices at each\nstart: `disk` (its disk), `cdrom0` (the first drive) and `cdrom1` (the second).\nBy default the disk comes first, then the discs in their drives. `vm options show`\ngives the order you set as `boot_order` (empty for the default), and the order the\nmachine actually tries the devices in as `effective_boot_order`.\n\n```bash\nsudo cenvero-str-ctl vm options set vm-3f9a1c2e --boot-order cdrom0,disk\nsudo cenvero-str-ctl vm options set vm-3f9a1c2e --boot-order \"\"\n```\n\nThe order takes effect at the next boot; it does not change a running machine.\nDevices the list leaves out are tried after the listed ones, in the default order.\nA name for a drive the machine does not have yet is skipped until the drive is\nadded. To install again from a disc, put the disc first with `--boot-order\ncdrom0,disk`, and restore the default with an empty value.\n\n## Options\n\n`vm options show` gives a machine's options, and `vm options set` changes them.\nEach flag you give changes its option, and the others stay as they are:\n\n```bash\ncenvero-str-ctl vm options show vm-3f9a1c2e\nsudo cenvero-str-ctl vm options set vm-3f9a1c2e --name db-primary\nsudo cenvero-str-ctl vm options set vm-3f9a1c2e --protected=true\nsudo cenvero-str-ctl vm options set vm-3f9a1c2e --start-at-boot=false\n```\n\n```json\n{\n  \"options\": {\n    \"id\": \"vm-3f9a1c2e\",\n    \"name\": \"db-primary\",\n    \"protected\": true,\n    \"boot_order\": [],\n    \"effective_boot_order\": [\"disk\", \"cdrom0\"],\n    \"start_at_boot\": true,\n    \"firmware\": { \"mode\": \"uefi\", \"secure_boot\": false, \"tpm\": true },\n    \"firmware_editable\": false\n  }\n}\n```\n\n`boot_order` is empty when the default order is set. `firmware_editable` is always\n`false`.\n\n**Name.** A name must be unique among the machines of its tenant on this node,\nand follow the rule for a create: 1 to 63 lowercase letters, digits and hyphens,\nnot starting or ending with a hyphen. A name another machine of the tenant has is\nrefused: \"another machine of this tenant has that name; choose another name\". The\nnode lists the machine under its new name at once; the name the machine itself\ncarries takes effect at its next start. The hostname the guest has, its network\ninterfaces, its disks and its addresses do not change.\n\n**Protection.** `--protected=true` refuses the deletion of the machine until the\nprotection is cleared with `--protected=false`. Starting, stopping, restarting and\nthe consoles stay allowed. A machine can also be created protected, with\n`--protected`. Changing protection needs the `VM.Config.Options` privilege, as every\noption does.\n\n**Start at boot.** On by default: a machine that was running when its host\nrestarted starts again, as before. With `--start-at-boot=false`, a machine that\nwas running when its host restarts stays stopped. The node sets it stopped at that\nrestart and writes a line to the machine's task log, and the machine waits until\nyou start it. Changing the setting neither starts nor stops the machine now. The\nrule applies at each restart of the host, not when only the agent restarts.\n\n**Firmware** is shown but cannot be changed. It is chosen when the machine is\ncreated, and a request to change it is refused with \"firmware is chosen when a\nmachine is created; it cannot be changed afterwards\".\n\n## Changing a machine's size\n\n```bash\nsudo cenvero-str-ctl vm update vm-3f9a1c2e --vcpus 4 --memory 8192\n```\n\nA stopped machine takes the new size when it next starts. A running machine\nchanges at once where it can, within the **maximums** it runs with:\n\n| Change on a running machine | When it applies |\n|---|---|\n| More vCPUs, up to the maximum | At once: the vCPUs are plugged in. Bringing them online is the guest's job; most Linux cloud images do it on their own. |\n| More or less memory, up to the maximum | At once, through the memory balloon (the guest needs its balloon driver, which Linux has built in). |\n| Fewer vCPUs | At the next restart. |\n| More vCPUs on a machine with secure boot | At the next restart. |\n| Anything above a maximum | At the next restart, which raises the maximum with it. |\n\nThe maximums are what a machine can grow to without a restart. They are the\nsize you create it with, unless you give room to grow at create:\n\n```bash\nsudo cenvero-str-ctl vm create --name web-01 --image img-5d2c90a1 --vcpus 2 --memory 2048 \\\n  --max-vcpus 8 --max-memory 16384 --network net-8b1f03\n```\n\n`vm update` answers with what changed at once and what waits:\n\n```json\n{\n  \"status\": \"updated\",\n  \"applied\": [\"vcpus 2→4\", \"memory 2048→4096 MiB\"],\n  \"pending_restart\": [],\n  \"vm\": { \"id\": \"vm-3f9a1c2e\", \"vcpus\": 4, \"max_vcpus\": 8, \"memory_mib\": 4096, \"max_memory_mib\": 16384, \"flags\": [] }\n}\n```\n\nA machine with changes waiting carries the flag `pending_restart` until it is\nrestarted with `vm restart` (a restart from inside the guest keeps the machine\nrunning and does not apply them). The new size is recorded at once, so it\nsurvives an agent restart and a host reboot.\n\n## Adding and removing network interfaces\n\nA machine can have up to four interfaces. Add one to a running or stopped\nmachine, on a managed network (at the next free address, or `NET=IP` for a\ngiven one) or with a [routed public address](/docs/networking/public-addresses):\n\n```bash\nsudo cenvero-str-ctl vm nic add vm-3f9a1c2e --network net-8b1f03=10.20.0.25\nsudo cenvero-str-ctl vm nic add vm-3f9a1c2e --public-ip auto --bandwidth-mbps 200\n```\n\nEverything that protects an interface is in place before the machine sees it:\nthe address is bound to the interface, the port is locked to it, and a tenant's\ninterface is isolated from every other tenant — exactly as for the interfaces\nthe machine was created with. A running machine sees the new interface at once;\na stopped one at its next start.\n\n**Configure the new interface in the guest.** The network configuration a\nmachine receives at its first boot covers only the interfaces it had then. A\nLinux guest shows the new interface (look it up by its MAC address, which\n`vm show` lists), but gives it no address by itself. Either configure it in the\nguest — for example with netplan, matching the MAC address:\n\n```yaml\nnetwork:\n  version: 2\n  ethernets:\n    extra0:\n      match: { macaddress: \"02:ce:0a:14:00:19\" }\n      addresses: [10.20.0.25/24]\n```\n\n— or let the guest ask for an address by DHCP, on a network that offers it\n(`network create … --host-gateway --dhcp`). Match interfaces by MAC address\nrather than by name: the name a guest gives an interface added while it runs\ncan differ from the one it gives it after a restart.\n\nRemove an interface by its index, its interface name or its address:\n\n```bash\nsudo cenvero-str-ctl vm nic remove vm-3f9a1c2e 1\n```\n\nA running machine is asked to release the interface first, and nothing is\nremoved until it has: if the guest does not let go (it may still be booting),\nthe command says so and changes nothing — try again, or remove the interface\nwhile the machine is stopped. A machine keeps at least one interface.\n\n**Machines created before this version** have no free slot for an interface\nadded while they run. `vm nic add` then says so and asks for one restart\n(`vm restart`); after it, adding works while the machine runs. Adding to a\nstopped machine always works.\n\n## If an interface is removed behind Stratum's back\n\nEvery machine's interface on the node is watched. If one is deleted outside\nStratum, it is recreated and secured again (address binding, port lock, tenant\nisolation) within about half a minute, and a running machine is reconnected to it\nwithout a restart: the guest keeps its interface, its address and its connections. To do\nit at once rather than wait:\n\n```bash\nsudo cenvero-str-ctl vm nic replug vm-3f9a1c2e 0\n```\n\nIf several interfaces of one machine are removed at once and they cannot be\ntold apart, the machine is flagged `network_degraded` instead; restart it to\nreconnect them.\n\n## The guest agent\n\nThe guest agent is a small service inside the machine that the node talks to\ndirectly, without the network. Many cloud images include it; otherwise install\nyour distribution's guest agent package in the guest (Windows guests get it with\nthe guest tools). Nothing depends on it for the machine to run; without it, the\ncommands below say that it does not answer.\n\nSee whether it answers, and the addresses the guest itself reports:\n\n```bash\ncenvero-str-ctl vm guest-agent vm-3f9a1c2e\n```\n\n```json\n{\n  \"vm\": \"vm-3f9a1c2e\",\n  \"guest_agent\": {\n    \"state\": \"responding\",\n    \"interfaces\": [\n      { \"name\": \"lo\", \"mac\": \"00:00:00:00:00:00\", \"addresses\": [\"127.0.0.1/8\", \"::1/128\"] },\n      { \"name\": \"enp1s0\", \"mac\": \"02:ce:0a:14:00:32\", \"addresses\": [\"10.20.0.50/24\"] }\n    ]\n  }\n}\n```\n\n`vm show` includes the same `guest_agent` section. Its `state` is `responding`,\n`not_connected` (no agent runs in the guest), `not_responding`, or\n`vm_not_running`.\n\n### Setting a password\n\nSet the password of an account in a running machine — for example to log in on\nits console after losing an SSH key:\n\n```bash\nsudo cenvero-str-ctl vm password vm-3f9a1c2e --user debian\nNew password:\nRetype it:\n```\n\nThe password is asked for twice, or read from the first line of standard input\nwhen that is not a terminal (`printf '%s\\n' \"$PW\" | sudo cenvero-str-ctl vm password …`).\nIt is never taken from the command line, so it never appears in a process list,\nand Stratum neither logs nor stores it; the change itself is recorded as a\nsecurity event (who, which machine, which account). The account must exist in\nthe guest.\n\n## The same over the API\n\nEvery command above has an API call (`/api/v1`, with a token whose role allows\nthe change — `VM.Config.CPU`, `VM.Config.Memory`, `VM.Config.Disk` (for the drives\ntoo), `VM.Config.Network`, `VM.Config.Options` or `VM.GuestAgent` on the machine).\nA password travels only in the request body. The API is operator-only for\nthese calls: a tenant-scoped key cannot reach the drives, options or first-boot\nsettings.\n\n| Method | Path | Body |\n|---|---|---|\n| POST | `/vms/{id}/update` | `{\"vcpus\": 4, \"memory_mib\": 8192}` (either may be left out) |\n| POST | `/vms/{id}/nics` | `{\"network_id\": \"net-8b1f03\", \"ip\": \"10.20.0.25\"}` or `{\"public_ip\": \"auto\"}`, optionally `\"bandwidth_mbps\"` |\n| DELETE | `/vms/{id}/nics/{nic}` | — (`{nic}`: index, interface name or address) |\n| POST | `/vms/{id}/nics/{nic}/replug` | — |\n| POST | `/vms/{id}/password` | `{\"user\": \"debian\", \"password\": \"…\"}` |\n| GET | `/vms/{id}/guest-agent` | — |\n| GET | `/vms/{id}/cdroms` | — the machine's drives, and the disc in each |\n| PUT | `/vms/{id}/cdroms/{slot}` | `{\"iso_id\": \"iso-7d4e2f10\"}`; an empty `iso_id` ejects. `{slot}` is `0` or `1`. **200** with `\"live\": true` when the running machine took the change; **202** when it applies at the next start |\n| DELETE | `/vms/{id}/cdroms/{slot}` | — ejects the disc, then removes the drive (**200**) |\n| GET | `/vms/{id}/options` | — |\n| PUT | `/vms/{id}/options` | `{\"name\", \"protected\", \"boot_order\", \"start_at_boot\"}`, each may be left out. **200**; **409** for a name another machine of the tenant has |\n\n`POST /vms` takes the create options as `max_vcpus`, `max_memory_mib`,\n`firmware`, `secure_boot` and `tpm`, and the disc options as `iso_id`,\n`driver_iso_id`, `boot_order` and `protected`.\n\n## See also\n\n- [Creating virtual machines](/docs/compute/virtual-machines)\n- [Lifecycle and restarts](/docs/compute/lifecycle)\n- [Current limits](/docs/compute/limits)\n"
        }
    ]
}