Firmware, Resizing, Interfaces and the Guest Agent

This page covers what you can change on a virtual machine after you create it — its vCPUs and memory, 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.

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). compute status lists what the node supports:

"hypervisor": { "virt": "kvm", "firmware": ["bios", "uefi"], "secure_boot": true, "tpm": true }

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 an operator token). A password travels only in the request body.

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`	—

POST /vms takes the create options as max_vcpus, max_memory_mib, firmware, secure_boot and tpm.