Firmware, Resizing, Interfaces and the Guest Agent
This page covers what you can change on a virtual machine after you create it — its name and other options, its CD-ROM drives and boot order, its vCPUs and memory, and its network interfaces — the firmware options you choose when you create it (UEFI, secure boot, a TPM), and what the guest agent inside a machine lets you do: set a password, see the guest's own addresses.
Part of Compute, in early access. The commands below run on the node, as root; every change needs a licence that includes Compute and is not frozen. Looking at a machine never does. Creating a machine is on Creating virtual machines.
Firmware: BIOS or UEFI, secure boot and a TPM
A machine starts with BIOS firmware unless you ask for UEFI. Windows 11 needs UEFI with secure boot and a TPM 2.0:
sudo cenvero-str-ctl vm create --name win11 --image img-5d2c90a1 --vcpus 4 --memory 8192 --disk 64 \
--network net-8b1f03 --firmware uefi --secure-boot --tpm
| Option | What the machine gets |
|---|---|
--firmware bios | BIOS firmware. The default, and what every machine had before this option existed. |
--firmware uefi | UEFI firmware, with its own settings store (boot order, secure boot keys) kept on the node. |
--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. |
--tpm | A TPM 2.0 device, emulated per machine, its contents kept on the node. Works with either firmware. |
The firmware and the TPM are chosen at create and cannot be changed later: a guest installed under one firmware does not boot under the other, and a guest may seal keys (a disk encryption key, for example) to its TPM. Deleting the machine deletes its firmware settings and its TPM contents with it. The options show the firmware read-only, and a request to change it is refused with "firmware is chosen when a machine is created; it cannot be changed afterwards".
If the node cannot provide an option you ask for, the create is refused with a
plain message, for example *this host cannot give a virtual machine a TPM: the
TPM emulator is not installed*. The installer's compute and suite profiles
install UEFI and TPM support; re-run the installer with one of them to add it.
On a server that already runs another panel's virtual machines, the installer
lists what is missing instead of installing it (see Compute).
UEFI, secure boot and a TPM are offered once the node has confirmed what it can give a machine. Until then a request for one of them is refused with a message to try again, and the node checks again on its own.
compute status lists what the node supports:
"hypervisor": { "virt": "kvm", "firmware": ["bios", "uefi"], "secure_boot": true, "tpm": true }
CD-ROM drives and boot order
A machine has up to two CD-ROM drives, and both are read-only. The first holds the installation disc and the second a driver disc, for Windows. A drive appears once its slot has been set, with a disc or with an empty value, and it stays until it is removed, even when its disc is ejected. A disc comes from the disc library. Put one in a drive, change it or eject it:
sudo cenvero-str-ctl vm cdrom set vm-3f9a1c2e --slot 0 --iso iso-7d4e2f10
sudo cenvero-str-ctl vm cdrom set vm-3f9a1c2e --slot 0 --iso ""
sudo cenvero-str-ctl vm cdrom list vm-3f9a1c2e
sudo cenvero-str-ctl vm cdrom remove vm-3f9a1c2e --slot 1
An empty --iso ejects the disc. The answer's live field says whether the
change took effect at once.
| The machine is | When the disc changes |
|---|---|
| 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 |
| Stopped | At its next start (live is false) |
| Starting, stopping or paused | Once it is running or stopped. Until then the change is refused |
Removing a drive from a running machine ejects the disc in it first, when there is
one, and then detaches the drive. If the running machine will not release the drive,
the removal is refused, and the drive stays on the record. The disc may already have
left the tray, so put it back with set, or try the removal again. On a stopped
machine the removal takes effect at its next start.
Boot order
The boot order is the sequence in which the machine tries its devices at each
start: disk (its disk), cdrom0 (the first drive) and cdrom1 (the second).
By default the disk comes first, then the discs in their drives. vm options show
gives the order you set as boot_order (empty for the default), and the order the
machine actually tries the devices in as effective_boot_order.
sudo cenvero-str-ctl vm options set vm-3f9a1c2e --boot-order cdrom0,disk
sudo cenvero-str-ctl vm options set vm-3f9a1c2e --boot-order ""
The order takes effect at the next boot; it does not change a running machine.
Devices the list leaves out are tried after the listed ones, in the default order.
A name for a drive the machine does not have yet is skipped until the drive is
added. To install again from a disc, put the disc first with --boot-order
cdrom0,disk, and restore the default with an empty value.
Options
vm options show gives a machine's options, and vm options set changes them.
Each flag you give changes its option, and the others stay as they are:
cenvero-str-ctl vm options show vm-3f9a1c2e
sudo cenvero-str-ctl vm options set vm-3f9a1c2e --name db-primary
sudo cenvero-str-ctl vm options set vm-3f9a1c2e --protected=true
sudo cenvero-str-ctl vm options set vm-3f9a1c2e --start-at-boot=false
{
"options": {
"id": "vm-3f9a1c2e",
"name": "db-primary",
"protected": true,
"boot_order": [],
"effective_boot_order": ["disk", "cdrom0"],
"start_at_boot": true,
"firmware": { "mode": "uefi", "secure_boot": false, "tpm": true },
"firmware_editable": false
}
}
boot_order is empty when the default order is set. firmware_editable is always
false.
Name. A name must be unique among the machines of its tenant on this node, and follow the rule for a create: 1 to 63 lowercase letters, digits and hyphens, not starting or ending with a hyphen. A name another machine of the tenant has is refused: "another machine of this tenant has that name; choose another name". The node lists the machine under its new name at once; the name the machine itself carries takes effect at its next start. The hostname the guest has, its network interfaces, its disks and its addresses do not change.
Protection. --protected=true refuses the deletion of the machine until the
protection is cleared with --protected=false. Starting, stopping, restarting and
the consoles stay allowed. A machine can also be created protected, with
--protected. Changing protection needs the VM.Config.Options privilege, as every
option does.
Start at boot. On by default: a machine that was running when its host
restarted starts again, as before. With --start-at-boot=false, a machine that
was running when its host restarts stays stopped. The node sets it stopped at that
restart and writes a line to the machine's task log, and the machine waits until
you start it. Changing the setting neither starts nor stops the machine now. The
rule applies at each restart of the host, not when only the agent restarts.
Firmware is shown but cannot be changed. It is chosen when the machine is created, and a request to change it is refused with "firmware is chosen when a machine is created; it cannot be changed afterwards".
Changing a machine's size
sudo cenvero-str-ctl vm update vm-3f9a1c2e --vcpus 4 --memory 8192
A stopped machine takes the new size when it next starts. A running machine changes at once where it can, within the maximums it runs with:
| Change on a running machine | When it applies |
|---|---|
| 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. |
| 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). |
| Fewer vCPUs | At the next restart. |
| More vCPUs on a machine with secure boot | At the next restart. |
| Anything above a maximum | At the next restart, which raises the maximum with it. |
The maximums are what a machine can grow to without a restart. They are the size you create it with, unless you give room to grow at create:
sudo cenvero-str-ctl vm create --name web-01 --image img-5d2c90a1 --vcpus 2 --memory 2048 \
--max-vcpus 8 --max-memory 16384 --network net-8b1f03
vm update answers with what changed at once and what waits:
{
"status": "updated",
"applied": ["vcpus 2→4", "memory 2048→4096 MiB"],
"pending_restart": [],
"vm": { "id": "vm-3f9a1c2e", "vcpus": 4, "max_vcpus": 8, "memory_mib": 4096, "max_memory_mib": 16384, "flags": [] }
}
A machine with changes waiting carries the flag pending_restart until it is
restarted with vm restart (a restart from inside the guest keeps the machine
running and does not apply them). The new size is recorded at once, so it
survives an agent restart and a host reboot.
Adding and removing network interfaces
A machine can have up to four interfaces. Add one to a running or stopped
machine, on a managed network (at the next free address, or NET=IP for a
given one) or with a routed public address:
sudo cenvero-str-ctl vm nic add vm-3f9a1c2e --network net-8b1f03=10.20.0.25
sudo cenvero-str-ctl vm nic add vm-3f9a1c2e --public-ip auto --bandwidth-mbps 200
Everything that protects an interface is in place before the machine sees it: the address is bound to the interface, the port is locked to it, and a tenant's interface is isolated from every other tenant — exactly as for the interfaces the machine was created with. A running machine sees the new interface at once; a stopped one at its next start.
Configure the new interface in the guest. The network configuration a
machine receives at its first boot covers only the interfaces it had then. A
Linux guest shows the new interface (look it up by its MAC address, which
vm show lists), but gives it no address by itself. Either configure it in the
guest — for example with netplan, matching the MAC address:
network:
version: 2
ethernets:
extra0:
match: { macaddress: "02:ce:0a:14:00:19" }
addresses: [10.20.0.25/24]
— or let the guest ask for an address by DHCP, on a network that offers it
(network create … --host-gateway --dhcp). Match interfaces by MAC address
rather than by name: the name a guest gives an interface added while it runs
can differ from the one it gives it after a restart.
Remove an interface by its index, its interface name or its address:
sudo cenvero-str-ctl vm nic remove vm-3f9a1c2e 1
A running machine is asked to release the interface first, and nothing is removed until it has: if the guest does not let go (it may still be booting), the command says so and changes nothing — try again, or remove the interface while the machine is stopped. A machine keeps at least one interface.
Machines created before this version have no free slot for an interface
added while they run. vm nic add then says so and asks for one restart
(vm restart); after it, adding works while the machine runs. Adding to a
stopped machine always works.
If an interface is removed behind Stratum's back
Every machine's interface on the node is watched. If one is deleted outside Stratum, it is recreated and secured again (address binding, port lock, tenant isolation) within about half a minute, and a running machine is reconnected to it without a restart: the guest keeps its interface, its address and its connections. To do it at once rather than wait:
sudo cenvero-str-ctl vm nic replug vm-3f9a1c2e 0
If several interfaces of one machine are removed at once and they cannot be
told apart, the machine is flagged network_degraded instead; restart it to
reconnect them.
The guest agent
The guest agent is a small service inside the machine that the node talks to directly, without the network. Many cloud images include it; otherwise install your distribution's guest agent package in the guest (Windows guests get it with the guest tools). Nothing depends on it for the machine to run; without it, the commands below say that it does not answer.
See whether it answers, and the addresses the guest itself reports:
cenvero-str-ctl vm guest-agent vm-3f9a1c2e
{
"vm": "vm-3f9a1c2e",
"guest_agent": {
"state": "responding",
"interfaces": [
{ "name": "lo", "mac": "00:00:00:00:00:00", "addresses": ["127.0.0.1/8", "::1/128"] },
{ "name": "enp1s0", "mac": "02:ce:0a:14:00:32", "addresses": ["10.20.0.50/24"] }
]
}
}
vm show includes the same guest_agent section. Its state is responding,
not_connected (no agent runs in the guest), not_responding, or
vm_not_running.
Setting a password
Set the password of an account in a running machine — for example to log in on its console after losing an SSH key:
sudo cenvero-str-ctl vm password vm-3f9a1c2e --user debian
New password:
Retype it:
The password is asked for twice, or read from the first line of standard input
when that is not a terminal (printf '%s\n' "$PW" | sudo cenvero-str-ctl vm password …).
It is never taken from the command line, so it never appears in a process list,
and Stratum neither logs nor stores it; the change itself is recorded as a
security event (who, which machine, which account). The account must exist in
the guest.
The same over the API
Every command above has an API call (/api/v1, with a token whose role allows
the change — VM.Config.CPU, VM.Config.Memory, VM.Config.Disk (for the drives
too), VM.Config.Network, VM.Config.Options or VM.GuestAgent on the machine).
A password travels only in the request body. The API is operator-only for
these calls: a tenant-scoped key cannot reach the drives, options or first-boot
settings.
| Method | Path | Body |
|---|---|---|
| POST | /vms/{id}/update | {"vcpus": 4, "memory_mib": 8192} (either may be left out) |
| POST | /vms/{id}/nics | {"network_id": "net-8b1f03", "ip": "10.20.0.25"} or {"public_ip": "auto"}, optionally "bandwidth_mbps" |
| DELETE | /vms/{id}/nics/{nic} | — ({nic}: index, interface name or address) |
| POST | /vms/{id}/nics/{nic}/replug | — |
| POST | /vms/{id}/password | {"user": "debian", "password": "…"} |
| GET | /vms/{id}/guest-agent | — |
| GET | /vms/{id}/cdroms | — the machine's drives, and the disc in each |
| 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 |
| DELETE | /vms/{id}/cdroms/{slot} | — ejects the disc, then removes the drive (200) |
| GET | /vms/{id}/options | — |
| 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 |
POST /vms takes the create options as max_vcpus, max_memory_mib,
firmware, secure_boot and tpm, and the disc options as iso_id,
driver_iso_id, boot_order and protected.