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
idstringrequiredThe VPS ID (
vps_…).Body
modestringrequiredincus for UEFI with Secure Boot and TPM 2.0. legacy for BIOS without TPM. One of incus, legacy.storagestringWhere to create the EFI and TPM disks when switching to
incus. Leave it out to use the default.Example
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" }'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": "legacy" }'Responses
200 Firmware mode changed.
{ "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
modestringThe firmware mode now set. One of
incus, legacy.summarystringOne sentence that describes the change.
firmwareobject | nullThe firmware state read after the change. Null when it could not be read.
statusstring or nullThe power state of the VPS when the firmware was read, for example
stopped.biosstring or nullovmf for UEFI or seabios for legacy BIOS.machinestring or nullThe emulated chipset, for example
q35.modestring or nullAlways null in this response. Read the top-level
mode.efiobject | nullThe EFI disk. Its fields are null when the VPS has none.
volumestring or nullStorage volume of the EFI disk.
typestring or nullEFI disk type, for example
4m.sizestring or nullEFI disk size, for example
4M.preEnrolledKeysstring or nullWhether Secure Boot keys are pre-enrolled on the EFI disk, as
"1" or "0".tpmobject | nullThe TPM state disk. Its fields are null when the VPS has none.
volumestring or nullStorage volume of the TPM state disk.
sizestring or nullTPM state disk size, for example
4M.versionstring or nullTPM version,
v2.0 for TPM 2.0.secureBootReadybooleanTrue when the VPS boots with UEFI and has an EFI disk set up for Secure Boot.
tpmReadybooleanTrue when the VPS has a TPM 2.0 device.
actionsobjectWhat the caller can do with the firmware now.
canChangeModeobjectWhether the firmware mode can be changed. False while the VPS runs.
allowedbooleanTrue when a change is allowed now.
reasonstring or nullWhy 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.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 409 | The 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). |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |