Skip to content

Change the firmware mode of a VPS

PUT /api/v2/vps/{id}/firmware

Switches a VPS between UEFI with Secure Boot and TPM 2.0 (incus) and legacy BIOS without TPM (legacy). Stop the VPS first. actions.canChangeMode on GET /api/v2/vps/{id}/firmware is false while it runs. A running VPS returns 409 firmware_update_failed. The change is made at once, without a job. The VPS boots with the new firmware the next time it starts. Switching to legacy deletes the EFI and TPM disks. Anything stored in the TPM is lost. Returns the new mode and the firmware state read after the change.

Authentication: An API key with the scopes write:vm and write:storage. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

modestringrequired
incus for UEFI with Secure Boot and TPM 2.0. legacy for BIOS without TPM. One of incus, legacy.
storagestring
Where to create the EFI and TPM disks when switching to incus. Leave it out to use the default.

Example

PUT /api/v2/vps/{id}/firmware
curl -X PUT "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/firmware" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "incus"
}'

Responses

200 Firmware mode changed.

Response 200
{
"mode": "incus",
"summary": "Firmware mode was changed to UEFI with Secure Boot and TPM 2.0.",
"firmware": {
"status": "stopped",
"bios": "ovmf",
"machine": "q35",
"mode": null,
"efi": {
"volume": "local-lvm:vm-100-disk-0",
"type": "4m",
"size": "4M",
"preEnrolledKeys": "0"
},
"tpm": {
"volume": "local-lvm:vm-100-disk-1",
"size": "4M",
"version": "v2.0"
},
"secureBootReady": true,
"tpmReady": true,
"actions": {
"canChangeMode": {
"allowed": true,
"reason": null
}
}
}
}
Response fields
modestring
The firmware mode now set. One of incus, legacy.
summarystring
One sentence that describes the change.
firmwareobject | null
The firmware state read after the change. Null when it could not be read.
statusstring or null
The power state of the VPS when the firmware was read, for example stopped.
biosstring or null
ovmf for UEFI or seabios for legacy BIOS.
machinestring or null
The emulated chipset, for example q35.
modestring or null
Always null in this response. Read the top-level mode.
efiobject | null
The EFI disk. Its fields are null when the VPS has none.
volumestring or null
Storage volume of the EFI disk.
typestring or null
EFI disk type, for example 4m.
sizestring or null
EFI disk size, for example 4M.
preEnrolledKeysstring or null
Whether Secure Boot keys are pre-enrolled on the EFI disk, as "1" or "0".
tpmobject | null
The TPM state disk. Its fields are null when the VPS has none.
volumestring or null
Storage volume of the TPM state disk.
sizestring or null
TPM state disk size, for example 4M.
versionstring or null
TPM version, v2.0 for TPM 2.0.
secureBootReadyboolean
True when the VPS boots with UEFI and has an EFI disk set up for Secure Boot.
tpmReadyboolean
True when the VPS has a TPM 2.0 device.
actionsobject
What the caller can do with the firmware now.
canChangeModeobject
Whether the firmware mode can be changed. False while the VPS runs.
allowedboolean
True when a change is allowed now.
reasonstring or null
Why a change is not allowed. Null when it is.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
409The VPS cannot change firmware now. code is firmware_update_failed (the VPS is running), vps_not_ready (still being set up) or service_not_active (the VPS service has ended).
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.