QEMU-QMP-REF(7)

🎀 `qemu-qmp-ref` — QEMU QMP Reference Manual 🎀

Okay bestie, welcome to qemu-qmp-ref(7) — the full QEMU QMP Reference Manual, but make it readable 💅.

Introduction
QMP errors
Common data types
Socket data types
VM run state
Cryptography
Background jobs
Accelerators
Block devices
- Block core (VM unrelated)
- Additional block stuff (VM related)
- Block device exports
Character devices
Dump guest memory
Net devices
eBPF Objects
Rocker switch device
TPM (trusted platform module) devices
Remote desktop
- Spice
- VNC
Input
User authorization
Migration
Transactions
Tracing
Compatibility policy
QMP monitor control
QMP introspection
QEMU Object Model (QOM)
Device infrastructure (qdev)
Common machine types
Machines
Record/replay
Yank feature
Miscellanea
Audio
ACPI
PCI
Statistics
Virtio devices
VFIO devices
Cryptography devices
CXL devices
UEFI Variable Store

✨ INTRODUCTION ✨

Okay so, this manual describes the commands and events supported by the QEMU Monitor Protocol (QMP). That's the whole vibe.

Need to find one specific item? Peek at the QMP Index <>. iykyk 🔍

The following notation is used in examples:

Example:

-> ... text sent by client (commands) ...
<- ... text sent by server (command responses and events) ...

Example text is formatted for readability. However, in real protocol usage, it's commonly emitted as a single line.

Please refer to the QEMU Machine Protocol Specification <> for the general format of commands, responses, and events. Fr fr, that's where the formal receipt lives. 🧾

🫶 QMP ERRORS 🫶

🌸 Enum `QapiErrorClass` (Since: 1.2)

QEMU error classes. Yup, the whole error-class family.

Values

GenericError — this is used for errors that don't require a specific error class. This should be the default case for most errors.
CommandNotFound — the requested command has not been found.
DeviceNotActive — a device has failed to be become active.
DeviceNotFound — the requested device has not been found.
KVMMissingCap — the requested operation can't be fulfilled because a required KVM capability is missing.

🌟 COMMON DATA TYPES 🌟

🦋 Enum `IoOperationType` (Since: 2.1)

An enumeration of the I/O operation types. Read or write, those are the options.

Values

read — read operation
write — write operation

🎀 Enum `OnOffAuto` (Since: 2.2)

An enumeration of three options: on, off, and auto. Three little choices, one big decision.

Values

auto — QEMU selects the value between on and off
on — Enabled
off — Disabled

🌼 Enum `OnOffSplit` (Since: 2.6)

An enumeration of three values: on, off, and split. Not just on/off — there's a third plot twist.

Values

on — Enabled
off — Disabled
split — Mixed

🧚 Alternate `StrOrNull` (Since: 2.10)

This is a string value or the explicit lack of a string (null pointer in C). Intended for cases when 'optional absent' already has a different meaning. So yes, "no string" is its own whole mood.

Alternatives

s (string) — the string value
n (null) — no string value

💜 Enum `OffAutoPCIBAR` (Since: 2.12)

An enumeration of options for specifying a PCI BAR. BAR here means PCI BAR, not the cute kind. 💅

Values

off — The specified feature is disabled
auto — The PCI BAR for the feature is automatically selected
bar0 — PCI BAR0 is used for the feature
bar1 — PCI BAR1 is used for the feature
bar2 — PCI BAR2 is used for the feature
bar3 — PCI BAR3 is used for the feature
bar4 — PCI BAR4 is used for the feature
bar5 — PCI BAR5 is used for the feature

🌈 Enum `PCIELinkSpeed` (Since: 4.0)

An enumeration of PCIe link speeds in units of GT/s. Speed check activated. ⚡

Values

2_5 — 2.5GT/s
5 — 5.0GT/s
8 — 8.0GT/s
16 — 16.0GT/s
32 — 32.0GT/s (since 9.0)
64 — 64.0GT/s (since 9.0)

🍓 Enum `PCIELinkWidth` (Since: 4.0)

An enumeration of PCIe link width. Width, not speed — different slay.

Values

1 — x1
2 — x2
4 — x4
8 — x8
12 — x12
16 — x16
32 — x32

🔥 Enum `HostMemPolicy` (Since: 2.1)

Host memory policy types. Where should the memory go? These are the rules.

Values

default — restore default policy, remove any nondefault policy
preferred — set the preferred host nodes for allocation
bind — a strict policy that restricts memory allocation to the host nodes specified
interleave — memory allocations are interleaved across the set of host nodes specified

🌸 Enum `NetFilterDirection` (Since: 2.5)

Indicates whether a netfilter is attached to a netdev's transmit queue or receive queue or both. Direction check, bestie.

Values

all — the filter is attached both to the receive and the transmit queue of the netdev (default).
rx — the filter is attached to the receive queue of the netdev, where it will receive packets sent to the netdev.
tx — the filter is attached to the transmit queue of the netdev, where it will receive packets sent by the netdev.

🦋 Enum `GrabToggleKeys` (Since: 4.0)

Key combinations to toggle input-linux between host and guest. Hotkey combo lore.

Values

ctrl-ctrl — left and right control key
alt-alt — left and right alt key
shift-shift — left and right shift key
meta-meta — left and right meta key
scrolllock — scroll lock key
ctrl-scrolllock — either control key and scroll lock key

💖 Object `HumanReadableText` (Since: 6.2)

Members

human-readable-text (string) — Formatted output intended for humans.

🌈 Enum `EndianMode` (Since: 10.0)

Values

unspecified — Endianness not specified
little — Little endianness
big — Big endianness

🎀 SOCKET DATA TYPES 🎀

Enum NetworkAddressFamily (Since: 2.1)

okay so this one is literally just telling you which family your network address is in. the vibe check for addresses, if you will 💅

Values

ipv4 — the IPV4 family, classic, iconic
ipv6 — the IPV6 family, futuristic queen 👑
unix — unix socket, local legend
vsock — vsock family (since 2.8)
unknown — otherwise, i.e. we don't know her 🙈

Object InetSocketAddressBase

Members

host (string) — the host part of the address 🏠
port (string) — the port part of the address

Object InetSocketAddress (Since: 1.3)

"Captures a socket address or address range in the Internet namespace." bestie it's giving main character address energy ✨

Members

numeric (boolean, optional) — true means the host/port are guaranteed to be numeric, false means name resolution should be attempted. defaults to false. (Since 2.9) 🔢
to (int, optional) — if present, this is a range of possible addresses, with port between port and to. so like a little address buffet 🍓
ipv4 (boolean, optional) — whether to accept IPv4 addresses, default try both IPv4 and IPv6
ipv6 (boolean, optional) — whether to accept IPv6 addresses, default try both IPv4 and IPv6
keep-alive (boolean, optional) — enable keep-alive when connecting to/listening on this socket. (Since 4.2, not supported for listening sockets until 10.1) 💀 yes you read that right, listening sockets didn't get the keep-alive glow-up until 10.1
keep-alive-count (int, optional) — number of keep-alive packets sent before the connection is closed. only supported for TCP sockets on systems where TCP_KEEPCNT socket option is defined (this includes Linux, Windows, macOS, FreeBSD, but not OpenBSD 😭). when set to 0, system setting is used. (Since 10.1)
keep-alive-idle (int, optional) — time in seconds the connection needs to be idle before sending a keepalive packet. only supported for TCP sockets on systems where TCP_KEEPIDLE socket option is defined (this includes Linux, Windows, macOS, FreeBSD, but not OpenBSD 😭). when set to 0, system setting is used. (Since 10.1)
keep-alive-interval (int, optional) — time in seconds between keep-alive packets. only supported for TCP sockets on systems where TCP_KEEPINTVL is defined (this includes Linux, Windows, macOS, FreeBSD, but not OpenBSD 😭). when set to 0, system setting is used. (Since 10.1)
mptcp (boolean, optional) — enable multi-path TCP. (Since 6.1) multi-path, multi-vibes 🦋
plus all the members of InetSocketAddressBase (host and port, they're inherited, nepo babies but make it networking)

Object UnixSocketAddress (Since: 1.3)

"Captures a socket address in the local ("Unix socket") namespace." keeping it local, keeping it cute 💖

Members

path (string) — filesystem path to use
abstract (boolean, optional) — if true, this is a Linux abstract socket address. path will be prefixed by a null byte, and optionally padded with null bytes. defaults to false. (Since 5.1) 🫧
tight (boolean, optional) — if false, pad an abstract socket address with enough null bytes to make it fill struct sockaddr_un member sun_path. defaults to true. (Since 5.1) not tight = padded, yes it's confusing, i don't make the rules

Object VsockSocketAddress (Since: 2.8)

"Captures a socket address in the vsock namespace." 🧚

Members

cid (string) — unique host identifier
port (string) — port

Note: String types are used to allow for possible future hostname or service resolution support. so they're strings on purpose, don't come for them 💅

Object FdSocketAddress (Since: 1.2)

"A file descriptor name or number." short and sweet, we love an efficient queen ✨

Members

str (string) — decimal is for file descriptor number, otherwise it's a file descriptor name. named file descriptors are permitted in monitor commands, in combination with the getfd command. decimal file descriptors are permitted at startup or other contexts where no monitor context is active. 🎀

Object InetSocketAddressWrapper (Since: 1.3)

Members

data (InetSocketAddress) — internet domain socket address 🌈

Object UnixSocketAddressWrapper (Since: 1.3)

Members

data (UnixSocketAddress) — UNIX domain socket address

Object VsockSocketAddressWrapper (Since: 2.8)

Members

data (VsockSocketAddress) — VSOCK domain socket address

Object FdSocketAddressWrapper (Since: 1.3)

Members

data (FdSocketAddress) — file descriptor name or number

Object SocketAddressLegacy (Since: 1.3)

"Captures the address of a socket, which could also be a named file descriptor" — it's giving versatile, it's giving range 💅

Members

type (SocketAddressType) — Transport type
when type is inet: The members of InetSocketAddressWrapper.
when type is unix: The members of UnixSocketAddressWrapper.
when type is vsock: The members of VsockSocketAddressWrapper.
when type is fd: The members of FdSocketAddressWrapper.

Enum SocketAddressType (Since: 2.9)

"Available SocketAddress types" — pick your fighter 👑

Values

inet — Internet address
unix — Unix domain socket
vsock — VMCI address
fd — Socket file descriptor

Object SocketAddress (Since: 2.9)

"Captures the address of a socket, which could also be a socket file descriptor" — the glow-up version of the legacy one, no cap 🔥

Members

type (SocketAddressType) — Transport type
when type is inet: The members of InetSocketAddress.
when type is unix: The members of UnixSocketAddress.
when type is vsock: The members of VsockSocketAddress.
when type is fd: The members of FdSocketAddress.

🦋 VM RUN STATE 🦋

Enum RunState

"An enumeration of VM run states." basically every mood your VM can be in, and bestie there are many 😭

Values

debug — QEMU is running on a debugger 🐛
finish-migrate — guest is paused to finish the migration process
inmigrate — guest is paused waiting for an incoming migration. Note that this state does not tell whether the machine will start at the end of the migration. This depends on the command-line -S option and any invocation of stop or cont that has happened since QEMU was started. iykyk 🫶
internal-error — An internal error that prevents further guest execution has occurred 💀
io-error — the last IOP has failed and the device is configured to pause on I/O errors
paused — guest has been paused via the 'stop' command
postmigrate — guest is paused following a successful 'migrate'
prelaunch — QEMU was started with -S and guest has not started
restore-vm — guest is paused to restore VM state
running — guest is actively running, she's thriving ✨
save-vm — guest is paused to save the VM state
shutdown — guest is shut down (and -no-shutdown is in use)
suspended — guest is suspended (ACPI S3) 😴
watchdog — the watchdog action is configured to pause and has been triggered
guest-panicked — guest has been panicked as a result of guest OS panic 🙈
colo — guest is paused to save/restore VM state under colo checkpoint, VM can not get into this state unless colo capability is enabled for migration. (since 2.8)

Enum ShutdownCause

"An enumeration of reasons for a shutdown." the why behind the bye-bye 👋

Values

none — No shutdown request pending
host-error — An error prevents further use of guest
host-qmp-quit — Reaction to the QMP command quit
host-qmp-system-reset — Reaction to the QMP command system_reset
host-signal — Reaction to a signal, such as SIGINT
host-ui — Reaction to a UI event, like window close
guest-shutdown — Guest shutdown/suspend request, via ACPI or other hardware-specific means
guest-reset — Guest reset request, and command line turns that into a shutdown
guest-panic — Guest panicked, and command line turns that into a shutdown
subsystem-reset — Partial guest reset that does not trigger QMP events and ignores --no-reboot. This is useful for sanitizing hypercalls on s390 that are used during kexec/kdump/boot
snapshot-load — A snapshot is being loaded by the record & replay subsystem. This value is used only within QEMU. It doesn't occur in QMP. (since 7.2) so don't go looking for it in QMP, it's not there bestie 💀

Object StatusInfo (Since: 0.14)

"Information about VM run state" — the tea on how your VM is doing ☕

Members

running (boolean) — true if all VCPUs are runnable, false if not runnable
status (RunState) — the virtual machine RunState

Command query-status (Since: 0.14)

"Query the run status of the VM" — literally just ask her how she's doing 💖

Return StatusInfo

Example:

-> { "execute": "query-status" }
<- { "return": { "running": true,
                 "status": "running" } }

Event SHUTDOWN (Since: 0.12)

"Emitted when the virtual machine has shut down, indicating that QEMU is about to exit." it's the goodbye text, the final post 🔔

Members

guest (boolean) — If true, the shutdown was triggered by a guest request (such as a guest-initiated ACPI shutdown request or other hardware-specific action) rather than a host request (such as sending QEMU a SIGINT). (since 2.10)
reason (ShutdownCause) — The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)

💡 Note: if the command-line option -no-shutdown has been specified, QEMU will not exit, and a STOP event will eventually follow the SHUTDOWN event. no cap.

Example:

<- { "event": "SHUTDOWN",
     "data": { "guest": true, "reason": "guest-shutdown" },
     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }

Event POWERDOWN (Since: 0.12) ⚡

Emitted when the virtual machine is powered down through the power control system, such as via ACPI. like, the polite little shutdown route 💅

Example:

<- { "event": "POWERDOWN",
     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }

Event RESET (Since: 0.12) 🔄

Emitted when the virtual machine is reset. iconic behavior honestly.

Members

guest (boolean) — If true, the reset was triggered by a guest request (such as a guest-initiated ACPI reboot request or other hardware-specific action) rather than a host request (such as the QMP command system_reset). (since 2.10)
reason (ShutdownCause) — The ShutdownCause of the RESET. (since 4.0)

Example:

<- { "event": "RESET",
     "data": { "guest": false, "reason": "guest-reset" },
     "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }

Event STOP (Since: 0.12) 🛑

Emitted when the virtual machine is stopped. it's giving paused-and-proud.

Example:

<- { "event": "STOP",
     "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }

Event RESUME (Since: 0.12) ▶️

Emitted when the virtual machine resumes execution. we're so back 🫶

Example:

<- { "event": "RESUME",
     "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }

Event SUSPEND (Since: 1.1) 😴

Emitted when guest enters a hardware suspension state, for example, S3 state, which is sometimes called standby state. cozy era.

Example:

<- { "event": "SUSPEND",
     "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }

Event SUSPEND_DISK (Since: 1.2) 💾

Emitted when guest enters a hardware suspension state with data saved on disk, for example, S4 state, which is sometimes called hibernate state.

💡 Note: QEMU shuts down (similar to event SHUTDOWN) when entering this state.

Example:

<- { "event": "SUSPEND_DISK",
     "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }

Event WAKEUP (Since: 1.1) 🌞

Emitted when the guest has woken up from suspend state and is running. rise and shine bestie ✨

Example:

<- { "event": "WAKEUP",
     "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }

Event WATCHDOG (Since: 0.13) 🐕

Emitted when the watchdog device's timer is expired. the timer said "girl, wrap it up."

Members

action (WatchdogAction) — action that has been taken

💡 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is followed respectively by the RESET, SHUTDOWN, or STOP events.

💡 Note: This event is rate-limited.

Example:

<- { "event": "WATCHDOG",
     "data": { "action": "reset" },
     "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }

Enum WatchdogAction (Since: 2.1) 🐾

An enumeration of the actions taken when the watchdog device's timer is expired. pick your fighter.

Values

reset — system resets
shutdown — system shutdown, note that it is similar to powerdown, which tries to set to system status and notify guest
poweroff — system poweroff, the emulator program exits
pause — system pauses, similar to stop
debug — system enters debug state
none — nothing is done
inject-nmi — a non-maskable interrupt is injected into the first VCPU (all VCPUS on x86) (since 2.4)

Enum RebootAction (Since: 6.0) 🔁

Possible QEMU actions upon guest reboot. choose your reboot destiny.

Values

reset — Reset the VM
shutdown — Shutdown the VM and exit, according to the shutdown action

Enum ShutdownAction (Since: 6.0) 🚪

Possible QEMU actions upon guest shutdown. bye-bye options.

Values

poweroff — Shutdown the VM and exit
pause — pause the VM

Enum PanicAction (Since: 6.0) 😱

Values

none — Continue VM execution
pause — Pause the VM
shutdown — Shutdown the VM and exit, according to the shutdown action
exit-failure — Shutdown the VM and exit with nonzero status (since 7.1)

Command watchdog-set-action (Since: 2.11) 🐕‍🦺

Set watchdog action. tell the watchdog what to do when it gets dramatic.

Arguments

action (WatchdogAction) — WatchdogAction action taken when watchdog timer expires.

Example:

-> { "execute": "watchdog-set-action",
     "arguments": { "action": "inject-nmi" } }
<- { "return": {} }

Command set-action (Since: 6.0) 🎛️

Set the actions that will be taken by the emulator in response to guest events. one command, all the vibes.

Arguments

reboot (RebootAction, optional) — RebootAction action taken on guest reboot.
shutdown (ShutdownAction, optional) — ShutdownAction action taken on guest shutdown.
panic (PanicAction, optional) — PanicAction action taken on guest panic.
watchdog (WatchdogAction, optional) — WatchdogAction action taken when watchdog timer expires.

Example:

-> { "execute": "set-action",
     "arguments": { "reboot": "shutdown",
                    "shutdown" : "pause",
                    "panic": "pause",
                    "watchdog": "inject-nmi" } }
<- { "return": {} }

Event GUEST_PANICKED (Since: 1.5) 😵‍💫

Emitted when guest OS panic is detected. not the chillest moment ngl.

Members

action (GuestPanicAction) — action that has been taken, currently always "pause"
info (GuestPanicInformation, optional) — information about a panic (since 2.9)

Example:

<- { "event": "GUEST_PANICKED",
     "data": { "action": "pause" },
     "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }

Event GUEST_CRASHLOADED (Since: 5.0) 💥

Emitted when guest OS crash loaded is detected. crash but make it loaded.

Members

action (GuestPanicAction) — action that has been taken, currently always "run"
info (GuestPanicInformation, optional) — information about a panic

Example:

<- { "event": "GUEST_CRASHLOADED",
     "data": { "action": "run" },
     "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }

Event GUEST_PVSHUTDOWN (Since: 9.1) 🧚

Emitted when guest submits a shutdown request via pvpanic interface. pvpanic said "we're done here."

Example:

<- { "event": "GUEST_PVSHUTDOWN",
     "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }

Enum GuestPanicAction (Since: 2.1) 🫠

An enumeration of the actions taken when guest OS panic is detected. panic-mode menu.

Values

pause — system pauses
poweroff — system powers off (since 2.8)
run — system continues to run (since 5.0)

Enum GuestPanicInformationType (Since: 2.9) 🧾

An enumeration of the guest panic information types. panic lore, categorized.

Values

hyper-v — hyper-v guest panic information type
s390 — s390 guest panic information type (Since: 2.12)
tdx — tdx guest panic information type (Since: 10.1)
sev — AMD SEV-ES guest termination information type (Since: 11.0)

Object GuestPanicInformation (Since: 2.9) 📦

Information about a guest panic. the receipts.

Members

type (GuestPanicInformationType) — Crash type that defines the hypervisor specific information
When type is hyper-v: The members of GuestPanicInformationHyperV.
When type is s390: The members of GuestPanicInformationS390.
When type is tdx: The members of GuestPanicInformationTdx.
When type is sev: The members of GuestPanicInformationSev.

Object GuestPanicInformationHyperV (Since: 2.9) 🪟

Hyper-V specific guest panic information (HV crash MSRs). windows lore incoming.

Members

arg1 (int) — for Windows, STOP code for the guest crash. For Linux, an error code.
arg2 (int) — for Windows, first argument of the STOP. For Linux, the guest OS ID, which has the kernel version in bits 16-47 and 0x8100 in bits 48-63.
arg3 (int) — for Windows, second argument of the STOP. For Linux, the program counter of the guest.
arg4 (int) — for Windows, third argument of the STOP. For Linux, the RAX register (x86) or the stack pointer (aarch64) of the guest.
arg5 (int) — for Windows, fourth argument of the STOP. For x86 Linux, the stack pointer of the guest.

Enum S390CrashReason (Since: 2.12) 🧊

Reason why the CPU is in a crashed state. the s390 crash explainer.

Values

unknown — no crash reason was set
disabled-wait — the CPU has entered a disabled wait state
extint-loop — clock comparator or cpu timer interrupt with new PSW enabled for external interrupts
pgmint-loop — program interrupt with BAD new PSW
opint-loop — operation exception interrupt with invalid code at the program interrupt new PSW

Object `GuestPanicInformationS390` (Since: 2.12) 💥

S390-specific guest panic tea — it's the PSW info, bestie.

Members

core (int) — the core id of the CPU that crashed, iykyk
psw-mask (int) — control fields of the guest PSW
psw-addr (int) — the guest instruction address
reason (S390CrashReason) — the guest crash reason

Object `GuestPanicInformationTdx` (Since: 10.1) 🛡️

TDX guest panic info, specifically for TDX, exactly as spelled out in the "Guest-Hypervisor Communication Interface (GHCI) Specification", section TDG.VP.VMCALL<ReportFatalError>. Very official, very iconic.

Members

error-code (int) — TD-specific error code
message (string) — human-readable error message provided by the guest. Not to be trusted. 🚩 (yes, fr fr)
gpa (int, optional) — guest-physical address of a page that holds more verbose error info as a zero-terminated string. It's present when the "GPA valid" bit (bit 63) is set in error-code.

Object `GuestPanicInformationSev` (Since: 11.0) 🌸

Info for an AMD SEV-specific termination request (the GHCB MSR contents).

Members

set (int) — the reason code set provided by the guest
code (int) — the reason code provided by the guest

Event `MEMORY_FAILURE` (Since: 5.2) 💀

Emitted when a memory failure happens on the host side. Like, the host is going through it.

Members

recipient (MemoryFailureRecipient) — recipient is defined as MemoryFailureRecipient.
action (MemoryFailureAction) — the action that has been taken.
flags (MemoryFailureFlags) — flags for MemoryFailureAction.

Example:

<- { "event": "MEMORY_FAILURE",
     "data": { "recipient": "hypervisor",
               "action": "fatal",
               "flags": { "action-required": false,
                          "recursive": false } },
     "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }

Enum `MemoryFailureRecipient` (Since: 5.2) 🫶

A hardware memory failure occurs, and it's handled by the recipient.

Values

hypervisor — memory failure at QEMU process address space. (none guest memory, but used by QEMU itself).
guest — memory failure at guest memory,

Enum `MemoryFailureAction` (Since: 5.2) 🔥

The actions QEMU takes in response to a hardware memory failure.

Values

ignore — the memory failure could be ignored. This will only be the case for action-optional failures.
inject — memory failure occurred in guest memory, the guest enabled the MCE handling mechanism, and QEMU could inject the MCE into the guest successfully.
fatal — the failure is unrecoverable. This happens for action-required failures if the recipient is the hypervisor; QEMU will exit. 😭
reset — the failure is unrecoverable but confined to the guest. This happens if the recipient is a guest that isn't ready to handle memory failures.

Object `MemoryFailureFlags` (Since: 5.2) 🎀

Extra deets about memory failures.

Members

action-required (boolean) — whether a memory failure event is action-required or action-optional (e.g. a failure during memory scrub).
recursive (boolean) — whether the failure occurred while the previous failure was still in progress.

Enum `NotifyVmexitOption` (Since: 7.2) 👑

An enumeration of the options you specify when enabling notify VM exit.

Values

run — enable the feature, do nothing and continue if the notify VM exit happens.
internal-error — enable the feature, raise an internal error if the notify VM exit happens.
disable — disable the feature.

✨ CRYPTOGRAPHY ✨ 🔐

Enum `QCryptoTLSCredsEndpoint` (Since: 2.5) 🦋

The type of network endpoint that's gonna be using the credentials. Most types of credential need different setup / structures depending on whether they're used in a server versus a client — so, know your lane.

Values

client — the network endpoint is acting as the client
server — the network endpoint is acting as the server

Enum `QCryptoSecretFormat` (Since: 2.6) 🍓

The data format that the secret is provided in.

Values

raw — raw bytes. When encoded in JSON only valid UTF-8 sequences can be used
base64 — arbitrary base64 encoded binary data

Enum `QCryptoHashAlgo` (Since: 2.6) 🌈

The supported algorithms for computing content digests.

Values

md5 — MD5. Should not be used in any new code, legacy compat only
sha1 — SHA-1. Should not be used in any new code, legacy compat only
sha224 — SHA-224. (since 2.7)
sha256 — SHA-256. Current recommended strong hash. 💅
sha384 — SHA-384. (since 2.7)
sha512 — SHA-512. (since 2.7)
ripemd160 — RIPEMD-160. (since 2.7)
sm3 — SM3. (since 9.2.0)

Enum `QCryptoCipherAlgo` (Since: 2.6) 🧚

The supported algorithms for content encryption ciphers.

Values

aes-128 — AES with 128 bit / 16 byte keys
aes-192 — AES with 192 bit / 24 byte keys
aes-256 — AES with 256 bit / 32 byte keys
des — DES with 56 bit / 8 byte keys. Do not use except in VNC. (since 6.1)
3des — 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
cast5-128 — Cast5 with 128 bit / 16 byte keys
serpent-128 — Serpent with 128 bit / 16 byte keys
serpent-192 — Serpent with 192 bit / 24 byte keys
serpent-256 — Serpent with 256 bit / 32 byte keys
twofish-128 — Twofish with 128 bit / 16 byte keys
twofish-192 — Twofish with 192 bit / 24 byte keys
twofish-256 — Twofish with 256 bit / 32 byte keys
sm4 — SM4 with 128 bit / 16 byte keys (since 9.0)

Enum `QCryptoCipherMode` (Since: 2.6) 🌀

The supported modes for content encryption ciphers.

Values

ecb — Electronic Code Book
cbc — Cipher Block Chaining
xts — XEX with tweaked code book and ciphertext stealing
ctr — Counter (Since 2.8)

Enum `QCryptoIVGenAlgo` (Since: 2.6) 🌟

The supported algorithms for generating initialization vectors for full disk encryption. Heads up: the 'plain' generator should not be used for disks with sector numbers larger than 2^32, except where compatibility with pre-existing Linux dm-crypt volumes is required. Like, that's the one exception, bestie.

Values

plain — 64-bit sector number truncated to 32-bits
plain64 — 64-bit sector number
essiv — 64-bit sector number encrypted with a hash of the encryption key

Enum `QCryptoBlockFormat` (Since: 2.6) 💖

The supported full disk encryption formats.

Values

qcow — QCow/QCow2 built-in AES-CBC encryption. Use only for liberating data from old images.
luks — LUKS encryption format. Recommended for new images 👑

Object `QCryptoBlockOptionsBase` (Since: 2.6) 🎀

The common options that apply to all full disk encryption formats.

Members

format (QCryptoBlockFormat) — the encryption format

Object `QCryptoBlockOptionsQCow` (Since: 2.6) 🦋

The options that apply to the QCow/QCow2 AES-CBC encryption format.

Members

key-secret (string, optional) — the ID of a QCryptoSecret object providing the decryption key. Mandatory except when probing the image for metadata only.

Object `QCryptoBlockOptionsLUKS` (Since: 2.6) 🌸

The options that apply to the LUKS encryption format.

Members

key-secret (string, optional) — the ID of a QCryptoSecret object providing the decryption key. Mandatory except when probing the image for metadata only.

Object `QCryptoBlockCreateOptionsLUKS` (Since: 2.6) 🔥

The options that apply to LUKS encryption format initialization. Setting up a fresh volume, let's gooo.

Members

cipher-alg (QCryptoCipherAlgo, optional) — the cipher algorithm for data encryption. Currently defaults to 'aes-256'.
cipher-mode (QCryptoCipherMode, optional) — the cipher mode for data encryption. Currently defaults to 'xts'
ivgen-alg (QCryptoIVGenAlgo, optional) — the initialization vector generator. Currently defaults to 'plain64'
ivgen-hash-alg (QCryptoHashAlgo, optional) — the initialization vector generator hash. Currently defaults to 'sha256'
hash-alg (QCryptoHashAlgo, optional) — the master key hash algorithm. Currently defaults to 'sha256'
iter-time (int, optional) — number of milliseconds to spend in PBKDF passphrase processing. Currently defaults to 2000. (since 2.8)
The members of QCryptoBlockOptionsLUKS.

Object `QCryptoBlockOpenOptions` (Since: 2.6) 🫶

The options that are available for all encryption formats when opening an existing volume.

Members

The members of QCryptoBlockOptionsBase.
When format is qcow: the members of QCryptoBlockOptionsQCow.
When format is luks: the members of QCryptoBlockOptionsLUKS.

Object `QCryptoBlockCreateOptions` (Since: 2.6) ⭐

The options that are available for all encryption formats when initializing a new volume.

Members

The members of QCryptoBlockOptionsBase.
format — when it's qcow, you get the members of QCryptoBlockOptionsQCow.
format — when it's luks, you get the members of QCryptoBlockCreateOptionsLUKS.

Object `QCryptoBlockInfoBase` (Since: 2.7)

The shared info that literally every full disk encryption format has, no matter which one you picked 💖

Members

format (QCryptoBlockFormat) — the encryption format, bestie.

Object `QCryptoBlockInfoLUKSSlot` (Since: 2.7)

All the tea about the LUKS block encryption key slot options 🎀

Members

active (boolean) — whether the key slot is currently in use
key-offset (int) — offset to the key material in bytes
iters (int, optional) — number of PBKDF2 iterations for key material
stripes (int, optional) — number of stripes for splitting key material

Object `QCryptoBlockInfoLUKS` (Since: 2.7)

The full rundown on the LUKS block encryption options, we're getting into the details now 🔥

Members

cipher-alg (QCryptoCipherAlgo) — the cipher algorithm for data encryption
cipher-mode (QCryptoCipherMode) — the cipher mode for data encryption
ivgen-alg (QCryptoIVGenAlgo) — the initialization vector generator
ivgen-hash-alg (QCryptoHashAlgo, optional) — the initialization vector generator hash
hash-alg (QCryptoHashAlgo) — the master key hash algorithm
detached-header (boolean) — whether the LUKS header is detached (Since 9.0)
payload-offset (int) — offset to the payload data in bytes
master-key-iters (int) — number of PBKDF2 iterations for key material
uuid (string) — unique identifier for the volume
slots ([QCryptoBlockInfoLUKSSlot]) — information about each key slot

Object `QCryptoBlockInfo` (Since: 2.7)

Info about the block encryption options — it's giving "format-dependent content" ✨

Members

The members of QCryptoBlockInfoBase.
When format is luks: the members of QCryptoBlockInfoLUKS.

Enum `QCryptoBlockLUKSKeyslotState` (Since: 5.1)

Defines the state of the keyslots that get affected by the update 💅

Values

active — the slots contain the given password and are marked as active
inactive — the slots are erased (they contain garbage, gross) and marked as inactive

Object `QCryptoBlockAmendOptionsLUKS` (Since: 5.1)

This struct defines the update parameters that activate/de-activate a set of keyslots. Very "let me just tweak this real quick" energy 🧚

Members

state (QCryptoBlockLUKSKeyslotState) — the desired state of the keyslots
new-secret (string, optional) — the ID of a QCryptoSecret object providing the password to be written into added active keyslots
old-secret (string, optional) — optional (for deactivation only). If given, it will deactivate all keyslots that match the password located in the QCryptoSecret with this ID
iter-time (int, optional) — optional (for activation only). Number of milliseconds to spend in PBKDF passphrase processing for the newly activated keyslot. Currently defaults to 2000.
keyslot (int, optional) — optional. ID of the keyslot to activate/deactivate. For keyslot activation, the keyslot should not be active already (this is unsafe to update an active keyslot, bestie — do not), but it's possible if the force parameter is given. If the keyslot is not given, the first free keyslot will be written. For keyslot deactivation, this parameter specifies the exact keyslot to deactivate.
secret (string, optional) — optional. The ID of a QCryptoSecret object providing the password to use to retrieve the current master key. Defaults to the same secret that was used to open the image.

Object `QCryptoBlockAmendOptions` (Since: 5.1)

The options available for all encryption formats when you're amending encryption settings 🌈

Members

The members of QCryptoBlockOptionsBase.
When format is luks: the members of QCryptoBlockAmendOptionsLUKS.

Object `SecretCommonProperties` (Since: 2.6)

Properties for objects of classes derived from secret-common. Iconic shared base behavior 👑

Members

format (QCryptoSecretFormat, optional) — the data format that the secret is provided in (default: raw)
keyid (string, optional) — the name of another secret that should be used to decrypt the provided data. If not present, the data is assumed to be unencrypted.
iv (string, optional) — the random initialization vector used for encryption of this particular secret. Should be a base64 encrypted string of the 16-byte IV. Mandatory if keyid is given. Ignored if keyid is absent.

Object `SecretProperties` (Since: 2.6)

Properties for secret objects.

Either data or file must be provided, but not both — pick one, bestie, we don't do both 🙈

Members

data (string, optional) — the data associated with the secret, given inline
file (string, optional) — the filename to load the data associated with the secret from
The members of SecretCommonProperties.

Object `SecretKeyringProperties` (Since: 5.1)

Availability: CONFIG_SECRET_KEYRING

Properties for secret_keyring objects — kernel keyring vibes 🔑

Members

serial (int) — serial number that identifies a key to get from the kernel
The members of SecretCommonProperties.

Object `TlsCredsProperties` (Since: 2.5)

Properties for objects of classes derived from tls-creds — secure connection era 💖

Members

verify-peer (boolean, optional) — if true, the peer credentials will be verified once the handshake is completed. This is a no-op for anonymous credentials. (default: true)
dir (string, optional) — the path of the directory that contains the credential files
endpoint (QCryptoTLSCredsEndpoint, optional) — whether the QEMU network backend that uses the credentials will be acting as a client or as a server (default: client)
priority (string, optional) — a gnutls priority string as described at https://gnutls.org/manual/html_node/Priority-Strings.html

Object `TlsCredsAnonProperties` (Since: 2.5)

Properties for tls-creds-anon objects. Anonymous but still secure, we love a mystery 🕵️‍♀️

Members

The members of TlsCredsProperties.

Object `TlsCredsPskProperties` (Since: 3.0)

Properties for tls-creds-psk objects. Pre-shared keys, the classic 🎀

Members

username (string, optional) — the username which will be sent to the server. For clients only. If absent, "qemu" is sent and the property will read back as an empty string.
The members of TlsCredsProperties.

Object `TlsCredsX509Properties` (Since: 2.5)

Properties for tls-creds-x509 objects. Certificates, my beloved 🌸

Members

sanity-check (boolean, optional) — if true, perform some sanity checks before using the credentials (default: true)
passwordid (string, optional) — for the server-key.pem and client-key.pem files which contain sensitive private keys, it is possible to use an encrypted version by providing the passwordid parameter. This provides the ID of a previously created secret object containing the password for decryption.
The members of TlsCredsProperties.

Enum `QCryptoAkCipherAlgo` (Since: 7.1)

The supported algorithms for asymmetric encryption ciphers 🔐

Values

rsa — RSA algorithm

Enum `QCryptoAkCipherKeyType` (Since: 7.1)

The type of asymmetric keys.

Values

public — public key
private — private key

Enum `QCryptoRSAPaddingAlgo` (Since: 7.1)

The padding algorithm for RSA.

Values

raw — no padding used
pkcs1 — pkcs1#v1.5

Object `QCryptoAkCipherOptionsRSA` (Since: 7.1)

Specific parameters for the RSA algorithm. RSA girlies rise 🫶

Members

hash-alg (QCryptoHashAlgo) — QCryptoHashAlgo
padding-alg (QCryptoRSAPaddingAlgo) — QCryptoRSAPaddingAlgo

Object `QCryptoAkCipherOptions` (Since: 7.1)

The options that are available for all asymmetric key algorithms when creating a new QCryptoAkCipher. One options object to rule them all 💫

Members

alg (QCryptoAkCipherAlgo) — encryption cipher algorithm
When alg is rsa: the members of QCryptoAkCipherOptionsRSA.

✨ BACKGROUND JOBS ✨

okay bestie so this is the part where we talk about jobs — you know, the long-running background stuff that keeps chugging along while you do your thing 💅

🎀 Enum JobType (Since: 1.7)

it's giving "what kind of job even IS this" — this enum tells you the type of a background job.

Values

commit — block commit job type, peep block-commit for the deets
stream — block stream job type, check block-stream
mirror — drive mirror job type, aka drive-mirror
backup — drive backup job type, look at drive-backup
create — image creation job type, see blockdev-create (since 3.0)
amend — image options amend job type, see x-blockdev-amend (since 5.1)
snapshot-load — snapshot load job type, see snapshot-load (since 6.0)
snapshot-save — snapshot save job type, see snapshot-save (since 6.0)
snapshot-delete — snapshot delete job type, see snapshot-delete (since 6.0)

🦋 Enum JobStatus (Since: 2.12)

this one's the vibe check for where a job is at in its whole little lifetime. iconique.

Values

undefined — the erroneous, default state. lowkey should never ever be visible, fr fr.
created — the job exists now but hasn't started yet. it's in its "just woke up, hasn't had coffee" era.
running — okay it's actually running now, slay.
paused — running but paused. the pause can be requested by either the QMP user OR by internal processes, so don't come for it.
ready — the job is running, but it's ready for the user to signal completion. this is for those long-running jobs like mirror that are literally designed to run indefinitely.
standby — it's ready but paused. nearly identical to paused. the job can go back to ready or just get canceled.
waiting — the job is waiting for other jobs in the transaction to converge to the waiting state. heads up: this status will probably not be visible for the last job in a transaction.
pending — work is done but there are finalization steps it needs to do before completing. these changes will require manual intervention via job-finalize if auto-finalize was set to false. and bestie, these pending changes may still fail 😭
aborting — the job is in the process of being aborted and will finish with an error. afterwards it'll report that it's concluded. this status may not be visible to the management process.
concluded — all work is finished. if auto-dismiss was set to false, the job just chills in this state until it's dismissed via job-dismiss.
null — the job is being dismantled. this state should not ever be visible externally, periodt.

🌸 Enum JobVerb (Since: 2.12)

the command verbs you can yeet at a job 👑

Values

cancel — see job-cancel
pause — see job-pause
resume — see job-resume
set-speed — see block-job-set-speed
complete — see job-complete
dismiss — see job-dismiss
finalize — see job-finalize
change — see block-job-change (since 8.2)

🎀 Event JOB_STATUS_CHANGE (Since: 3.0)

emitted whenever a job transitions to a different status. it's the job's little "not me changing status" moment ✨

Members

id (string) — the job identifier
status (JobStatus) — the new job status

💖 Command job-pause (Since: 3.0)

pause an active job. 🫶

this command returns immediately after marking the active job for pausing. and pausing an already paused job? that's an error, bestie.

the job will pause as soon as possible, which means transitioning into the PAUSED state if it was RUNNING, or into STANDBY if it was READY. the corresponding JOB_STATUS_CHANGE event will be emitted.

fun fact: cancelling a paused job automatically resumes it 👀

Arguments

id (string) — the job identifier.

🦋 Command job-resume (Since: 3.0)

resume a paused job. let's goooo 🔥

this command returns immediately after resuming a paused job. resuming an already running job is an error.

it also clears the error status for block-jobs (stream, commit, mirror, backup).

Arguments

id (string) — the job identifier.

🌈 Command job-cancel (Since: 3.0)

instruct an active background job to cancel at the next opportunity. this command returns immediately after marking the active job for cancellation.

the job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE event. usually the status will change to ABORTING, but plot twist: it's possible that a job successfully completes instead (like, because it was almost done and there was no opportunity to cancel before it completed) and transitions to PENDING instead. main character energy, honestly.

Arguments

id (string) — the job identifier.

⭐ Command job-complete (Since: 3.0)

manually trigger completion of an active job that's in the READY or STANDBY state. completing the job in any other state is an error, no cap.

this is supported only for drive mirroring, where it also switches the device to write to the target path only. note that drive mirroring includes drive-mirror, blockdev-mirror and block-commit job (only in the case of "active commit", when the node being committed is used by the guest). the ability to complete is signaled with a BLOCK_JOB_READY event.

this command completes an active background block operation synchronously. the ordering of this command's return with the BLOCK_JOB_COMPLETED event is not defined, so don't @ me.

heads up: if an I/O error occurs while this command is being processed: 1) the command itself will fail; 2) the error will be processed according to the rerror/werror arguments that were specified when starting the operation. keep that in mind bestie 💀

Arguments

id (string) — the job identifier.

🧚 Command job-dismiss (Since: 3.0)

deletes a job that's in the CONCLUDED state. you only need to run this explicitly for jobs that don't have automatic dismiss enabled. automatic dismiss, in turn, may only be enabled for jobs that have the auto-dismiss option — which are drive-backup, blockdev-backup, drive-mirror, blockdev-mirror, block-commit and block-stream. and auto-dismiss is enabled by default for those jobs. convenient much? 💅

this command will refuse to operate on any job that hasn't reached its terminal state, CONCLUDED. for jobs that use the JOB_READY event, you'll still need to use job-cancel or job-complete as appropriate first.

Arguments

id (string) — the job identifier.

🍓 Command job-finalize (Since: 3.0)

instructs all jobs in a transaction (or just a single job if it's not part of any transaction) to finalize any graph changes and do whatever cleanup is necessary. this command requires that all involved jobs are in the PENDING state.

for jobs in a transaction, telling one job to finalize will force ALL jobs in the transaction to finalize — so you really only need to instruct a single member job to finalize. efficiency queen 👑

the command is applicable only to jobs which have the auto-finalize option, and only when this option is set to false.

Arguments

id (string) — the identifier of any job in the transaction, or of a job that is not part of any transaction.

💜 Object JobInfo (Since: 3.0)

information about a job. the whole tea ☕

Members

id (string) — the job identifier
type (JobType) — the kind of job that's being performed
status (JobStatus) — current job state/status
current-progress (int) — progress made until now. the unit is arbitrary and the value can only meaningfully be used for the ratio of current-progress to total-progress. the value is monotonically increasing, so it only goes up bestie 📈
total-progress (int) — estimated current-progress value at the completion of the job. this value can arbitrarily change while the job is running, in both directions. messy but valid.
error (string, optional) — if this field is present, the job failed; if it's still missing in the CONCLUDED state, that indicates successful completion, slay. the value is a human-readable error message describing the reason for the job failure. do not parse it in applications, it's not for that.

👑 Command query-jobs (Since: 3.0)

return information about jobs. simple as that 🎀

Return [JobInfo] — a list with info for each active job

✨ ACCELERATORS ✨

🧩 Object `KvmInfo` (Since: 0.14)

Info about whether KVM acceleration is a thing here 💅

Members

enabled (boolean) — true if KVM acceleration is actually active rn
present (boolean) — true if KVM acceleration is compiled into this executable

🛠️ Command `query-kvm` (Since: 0.14)

⚠️ Heads up bestie, this command is deprecated.

Returns the tea on KVM acceleration ☕

Return KvmInfo

Features

deprecated — This command is deprecated. Use query-accelerators instead. (she's old news, move on 💀)

Example:

-> { "execute": "query-kvm" }
<- { "return": { "enabled": true, "present": true } }

🛠️ Command `x-accel-stats` (Since: 10.1)

🧪 This command is unstable/experimental — no cap, handle with care.

Query accelerator statistics 📊

Features

unstable — This command is meant for debugging. (it's giving "devs only" energy ngl)

Return HumanReadableText — accelerator statistics

🔢 Enum `Accelerator` (Since: 10.2.0)

Info about support for MSHV acceleration 👑

Values

hvf — Apple Hypervisor.framework 🍎
kvm — KVM
mshv — Hyper-V
nvmm — NetBSD NVMM
qtest — QTest (dummy accelerator)
tcg — TCG (dynamic translation)
whpx — Windows Hypervisor Platform 🪟
xen — Xen

🧩 Object `AcceleratorInfo` (Since: 10.2.0)

Info about support for all the various accelerators, lowkey a whole roster ✨

Members

enabled (Accelerator) — the accelerator that is in use
present ([Accelerator]) — the list of accelerators that are built into this executable

🛠️ Command `query-accelerators` (Since: 10.2.0)

Returns the info about accelerators, the upgraded glow-up version 💅

Return AcceleratorInfo — AcceleratorInfo

Example:

-> { "execute": "query-accelerators" }
<- { "return": { "enabled": "mshv", "present": ["kvm", "mshv", "qtest", "tcg"] } }

🦋 BLOCK DEVICES 🦋

Block core (VM unrelated) 🎀

🧩 Object `SnapshotInfo` (Since: 1.3)

Members

id (string) — unique snapshot id, one of a kind fr
name (string) — user chosen name
vm-state-size (int) — size of the VM state
date-sec (int) — UTC date of the snapshot in seconds
date-nsec (int) — fractional part in nano seconds to be used with date-sec
vm-clock-sec (int) — VM clock relative to boot in seconds
vm-clock-nsec (int) — fractional part in nano seconds to be used with vm-clock-sec
icount (int, optional) — Current instruction count. Appears when execution record/replay is enabled. Used for "time-traveling" to match the moment in the recorded execution with the snapshots. This counter may be obtained through query-replay command (since 5.2) 🕰️✨

🧩 Object `ImageInfoSpecificQCow2EncryptionBase` (Since: 2.10)

Members

format (BlockdevQcow2EncryptionFormat) — The encryption format

🧩 Object `ImageInfoSpecificQCow2Encryption` (Since: 2.10)

Members

The members of ImageInfoSpecificQCow2EncryptionBase.
When format is luks: The members of QCryptoBlockInfoLUKS.

🧩 Object `ImageInfoSpecificQCow2` (Since: 1.7)

Members

compat (string) — compatibility level
data-file (string, optional) — the filename of the external data file that is stored in the image and used as a default for opening the image (since: 4.0)
data-file-raw (boolean, optional) — True if the external data file must stay valid as a standalone (read-only) raw image without looking at qcow2 metadata (since: 4.0)
extended-l2 (boolean, optional) — true if the image has extended L2 entries; only valid for compat >= 1.1 (since 5.2)
lazy-refcounts (boolean, optional) — on or off; only valid for compat >= 1.1
corrupt (boolean, optional) — true if the image has been marked corrupt; only valid for compat >= 1.1 (since 2.2)
refcount-bits (int) — width of a refcount entry in bits (since 2.3)
encrypt (ImageInfoSpecificQCow2Encryption, optional) — details about encryption parameters; only set if image is encrypted (since 2.10)
bitmaps ([Qcow2BitmapInfo], optional) — A list of qcow2 bitmap details (since 4.0)
compression-type (Qcow2CompressionType) — the image cluster compression method (since 5.1)

🧩 Object `ImageInfoSpecificVmdk` (Since: 1.7)

Members

create-type (string) — The create type of VMDK image
cid (int) — Content id of image
parent-cid (int) — Parent VMDK image's cid
extents ([VmdkExtentInfo]) — List of extent files

🧩 Object `VmdkExtentInfo` (Since: 8.0)

Info about a VMDK extent file, we love a niche lil detail 🫶

Members

filename (string) — Name of the extent file
format (string) — Extent type (e.g. FLAT or SPARSE)
virtual-size (int) — Number of bytes covered by this extent
cluster-size (int, optional) — Cluster size in bytes (for non-flat extents)
compressed (boolean, optional) — Whether this extent contains compressed data

🧩 Object `ImageInfoSpecificRbd` (Since: 6.1)

Members

encryption-format (RbdImageEncryptionFormat, optional) — Image encryption format. If encryption is enabled for the image (see encrypted in BlockNodeInfo), this is the actual format in which the image is accessed. If encryption is not enabled, this is the result of probing when the image was opened, to give a suggestion which encryption format could be enabled. Note that probing results can be changed by the guest by writing a (possibly partial) encryption format header to the image, so don't treat this information as trusted if the guest is not trusted. 👀🔒 (like, guest says jump, you say… maybe don't?)

🧩 Object `ImageInfoSpecificFile` (Since: 8.0)

Members

extent-size-hint (int, optional) — Extent size hint (if available)

🔢 Enum `ImageInfoSpecificKind` (Since: 1.7)

Values

luks — Since 2.7
rbd — Since 6.1
file — Since 8.0
qcow2 — Not documented
vmdk — Not documented

🧩 Object `ImageInfoSpecificQCow2Wrapper` (Since: 1.7)

Members

data (ImageInfoSpecificQCow2) — image information specific to QCOW2

🧩 Object `ImageInfoSpecificVmdkWrapper` (Since: 6.1)

Members

data (ImageInfoSpecificVmdk) — image information specific to VMDK

🧩 Object `ImageInfoSpecificLUKSWrapper` (Since: 2.7)

Members

data (QCryptoBlockInfoLUKS) — image information specific to LUKS

🧩 Object `ImageInfoSpecificRbdWrapper` (Since: 6.1)

Members

data (ImageInfoSpecificRbd) — image information specific to RBD

🧩 Object `ImageInfoSpecificFileWrapper` (Since: 8.0)

Members

data (ImageInfoSpecificFile) — image information specific to files

🧩 Object `ImageInfoSpecific` (Since: 1.7)

A discriminated record of image format specific information structures. (she contains multitudes 🌈)

Members

type (ImageInfoSpecificKind) — block driver name
When type is qcow2: The members of ImageInfoSpecificQCow2Wrapper.
When type is vmdk: The members of ImageInfoSpecificVmdkWrapper.
When type is luks: The members of ImageInfoSpecificLUKSWrapper.
When type is rbd: The members of ImageInfoSpecificRbdWrapper.
When type is file: The members of ImageInfoSpecificFileWrapper.

🧩 Object `BlockLimitsInfo`

Members

request-alignment (int) — Alignment requirement, in bytes, for offset/length of I/O requests.
max-discard (int, optional) — Maximum number of bytes that can be discarded at once. If not present, there is no specific maximum.
discard-alignment (int, optional) — Optimal alignment for discard requests in bytes. Note that this doesn't have to be a power of two. If not present, discards don't have a alignment requirement different from request-alignment.
max-write-zeroes (int, optional) — Maximum number of bytes that can be zeroed out at once. If not present, there is no specific maximum.
write-zeroes-alignment (int, optional) — Optimal alignment for write zeroes requests in bytes. Note that this doesn't have to be a power of two. If not present, write_zeroes doesn't have a alignment requirement different from request-alignment.
opt-transfer (int, optional) — Optimal transfer length in bytes. If not present, there is no preferred size.
max-transfer (int, optional) — Maximal transfer length in bytes. If not present, there is no specific maximum.
max-hw-transfer (int, optional) — Maximal hardware transfer length in bytes. Applies whenever transfers to the device bypass the kernel I/O scheduler, for example with SG_IO. If not present, there is no specific maximum.
max-iov (int) — Maximum number of scatter/gather elements
max-hw-iov (int, optional) — the absolute max number of scatter/gather elements the hardware lets you use. It applies whenever transfers to the device skip the kernel I/O scheduler (think SG_IO ✨). If this field isn't there, the hardware limit is basically a mystery 🙈 and max-iov gets used every time.
min-mem-alignment (int) — the minimum memory alignment, in bytes, that zero-copy I/O needs to actually succeed. If a request is unaligned, QEMU's just gonna use a bounce buffer instead 🎀.
opt-mem-alignment (int) — the optimal memory alignment in bytes. This is the alignment QEMU uses for any buffer allocations it does internally 💅.

🖼️ Object `BlockNodeInfo` (Since: 8.0)

Info about a QEMU image file. Lowkey essential.

Members

filename (string) — name of the image file
format (string) — format of the image file
virtual-size (int) — maximum capacity in bytes of the image
actual-size (int, optional) — actual size on disk in bytes of the image
dirty-flag (boolean, optional) — true if the image is not cleanly closed 😬
cluster-size (int, optional) — size of a cluster in bytes
encrypted (boolean, optional) — true if the image is encrypted 🔐
compressed (boolean, optional) — true if the image is compressed (Since 1.7)
backing-filename (string, optional) — name of the backing file
full-backing-filename (string, optional) — full path of the backing file
backing-filename-format (string, optional) — the format of the backing file
snapshots ([SnapshotInfo], optional) — list of VM snapshots 📸
limits (BlockLimitsInfo, optional) — block limits that are used for I/O on the node (Since 10.2)
format-specific (ImageInfoSpecific, optional) — structure supplying additional format-specific information (since 1.7)

🫶 Object `ImageInfo` (Since: 1.3)

Info about a QEMU image file — and potentially its backing image too, because it's giving "whole friend group" energy.

Members

backing-image (ImageInfo, optional) — info of the backing image
The members of BlockNodeInfo. ← yes, it inherits all of those, slay

🌸 Object `BlockChildInfo` (Since: 8.0)

Info about all the nodes in the block graph starting at some node, annotated with info about that node in relation to its parent. It's a whole family tree fr fr.

Members

name (string) — child name of the root node in the BlockGraphInfo struct, in its role as the child of some undescribed parent node
info (BlockGraphInfo) — block graph information starting at this node

🦋 Object `BlockGraphInfo` (Since: 8.0)

Info about all nodes in a block (sub)graph, delivered in the form of BlockNodeInfo data. The base BlockNodeInfo struct contains the info for the (sub)graph's root node 👑.

Members

children ([BlockChildInfo]) — array of links to this node's child nodes' information
The members of BlockNodeInfo.

🔍 Object `ImageCheck` (Since: 1.4)

Info about a QEMU image file check. The vibe check, literally.

Members

filename (string) — name of the image file checked
format (string) — format of the image file checked
check-errors (int) — number of unexpected errors that occurred during the check 😭
image-end-offset (int, optional) — offset (in bytes) where the image ends; this field is present if the driver for the image format supports it
corruptions (int, optional) — number of corruptions found during the check, if any
leaks (int, optional) — number of leaks found during the check, if any
corruptions-fixed (int, optional) — number of corruptions fixed during the check, if any
leaks-fixed (int, optional) — number of leaks fixed during the check, if any
total-clusters (int, optional) — total number of clusters; this field is present if the driver for the image format supports it
allocated-clusters (int, optional) — total number of allocated clusters; this field is present if the driver for the image format supports it
fragmented-clusters (int, optional) — total number of fragmented clusters; this field is present if the driver for the image format supports it
compressed-clusters (int, optional) — total number of compressed clusters; this field is present if the driver for the image format supports it

🗺️ Object `MapEntry` (Since: 2.6)

Mapping info going from a virtual block range to a host file range. It's giving GPS for your disk coordinates 🧚.

Members

start (int) — virtual (guest) offset of the first byte described by this entry
length (int) — the number of bytes of the mapped virtual range
data (boolean) — reading the image will actually read data from a file (in particular, if offset is present this means the sectors are not simply preallocated, but contain actual data in raw format)
zero (boolean) — whether the virtual blocks read as zeroes
compressed (boolean) — true if the data is stored compressed (since 8.2)
depth (int) — number of layers (0 = top image, 1 = top image's backing file, ..., n - 1 = bottom image, where n is the number of images in the chain) before reaching one for which the range is allocated
present (boolean) — true if this layer provides the data, false if adding a backing layer could impact this region (since 6.1)
offset (int, optional) — if present, the image file stores the data for this range in raw format at the given (host) offset
filename (string, optional) — filename that is referred to by offset

💾 Object `BlockdevCacheInfo` (Since: 2.3)

Cache mode info for a block device.

Members

writeback (boolean) — true if writeback mode is enabled
direct (boolean) — true if the host page cache is bypassed (O_DIRECT)
no-flush (boolean) — true if flush requests are ignored for the device

🎀 Object `BlockdevChild` (Since: 10.1)

Members

child (string) — the name of the child, for example 'file' or 'backing'.
node-name (string) — the name of the child's block driver node.

👑 Object `BlockDeviceInfo` (Since: 0.14)

Info about the backing device for a block device.

Members

file (string) — the filename of the backing device
node-name (string) — the name of the block driver node (Since 2.0)
ro (boolean) — true if the backing device was open read-only
drv (string) — the name of the block format used to open the backing device. As of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg', 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' — then 2.2: 'archipelago' added, 'cow' dropped; 2.3: 'host_floppy' deprecated; 2.5: 'host_floppy' dropped; 2.6: 'luks' added; 2.8: 'replication' added, 'tftp' dropped; 2.9: 'archipelago' dropped
backing_file (string, optional) — the name of the backing file (for copy-on-write)
backing_file_depth (int) — number of files in the backing file chain (since: 1.2)
children ([BlockdevChild]) — information about child block nodes. (since: 10.1)
active (boolean) — true if the backend is active; typical cases for inactive backends are on the migration source instance after migration completes and on the destination before it completes. (since: 10.0)
encrypted (boolean) — true if the backing device is encrypted 🔐
detect_zeroes (BlockdevDetectZeroesOptions) — detect and optimize zero writes (Since 2.1)
bps (int) — total throughput limit in bytes per second is specified
bps_rd (int) — read throughput limit in bytes per second is specified
bps_wr (int) — write throughput limit in bytes per second is specified
iops (int) — total I/O operations per second is specified
iops_rd (int) — read I/O operations per second is specified
iops_wr (int) — write I/O operations per second is specified
image (ImageInfo) — the info of image used (since: 1.6)
bps_max (int, optional) — total throughput limit during bursts, in bytes (Since 1.7)
bps_rd_max (int, optional) — read throughput limit during bursts, in bytes (Since 1.7)
bps_wr_max (int, optional) — write throughput limit during bursts, in bytes (Since 1.7)
iops_max (int, optional) — total I/O operations per second during bursts, in bytes (Since 1.7)
iops_rd_max (int, optional) — read I/O operations per second during bursts, in bytes (Since 1.7) 🙈 yes bestie it literally says "in bytes" for an iops field, I'm not fixing it, that's what the page says, don't come for me 💀
iops_wr_max (int, optional) — write I/O operations per second during bursts, in bytes (Since 1.7)
bps_max_length (int, optional) — maximum length of the bps_max burst period, in seconds. (Since 2.6)
bps_rd_max_length (int, optional) — maximum length of the bps_rd_max burst period, in seconds. (Since 2.6)
bps_wr_max_length (int, optional) — maximum length of the bps_wr_max burst period, in seconds. (Since 2.6)
iops_max_length (int, optional) — maximum length of the iops burst period, in seconds. (Since 2.6)
iops_rd_max_length (int, optional) — maximum length of the iops_rd_max burst period, in seconds. (Since 2.6)
iops_wr_max_length (int, optional) — maximum length of the iops_wr_max burst period, in seconds. (Since 2.6)
iops_size (int, optional) — an I/O size in bytes (Since 1.7)
group (string, optional) — throttle group name (Since 2.4)
cache (BlockdevCacheInfo) — the cache mode used for the block device (since: 2.3)
write_threshold (int) — configured write threshold for the device. 0 if disabled. (Since 2.3)
dirty-bitmaps ([BlockDirtyInfo], optional) — dirty bitmaps information (only present if node has one or more dirty bitmaps) (Since 4.2) ✨

🦋 Enum `BlockDeviceIoStatus` (`Since: 1.0`)

An enumeration of block device I/O status. Basically a vibe check for your last I/O 💅

Values

ok — The last I/O operation has succeeded 👑
failed — The last I/O operation has failed 😭
nospace — The last I/O operation has failed due to a no-space condition 💀 (your disk said "bestie I'm full")

🌸 Object `BlockDirtyInfo` (`Since: 1.3`)

Block dirty bitmap information. The receipts for what's changed on disk 🎀

Members

name (string, optional) — the name of the dirty bitmap (Since 2.4)
count (int) — number of dirty bytes according to the dirty bitmap
granularity (int) — granularity of the dirty bitmap in bytes (since 1.4)
recording (boolean) — true if the bitmap is recording new writes from the guest. (since 4.0)
busy (boolean) — true if the bitmap is in-use by some operation (NBD or jobs) and cannot be modified via QMP or used by another operation. (since 4.0)
persistent (boolean) — true if the bitmap was stored on disk, is scheduled to be stored on disk, or both. (since 4.0)
inconsistent (boolean, optional) — true if this is a persistent bitmap that was improperly stored. Implies persistent to be true; recording and busy to be false. This bitmap cannot be used. To remove it, use block-dirty-bitmap-remove. (Since 4.0)

⚠️ ok so that inconsistent one is giving "corrupted, do not touch". It literally says cannot be used — so don't try to be cute with it, just call block-dirty-bitmap-remove and move on 🙈

🧚 Enum `Qcow2BitmapInfoFlags` (`Since: 4.0`)

An enumeration of flags that a bitmap can report to the user. Little status stickers for your bitmap ✨

Values

in-use — This flag is set by any process actively modifying the qcow2 file, and cleared when the updated bitmap is flushed to the qcow2 image. The presence of this flag in an offline image means that the bitmap was not saved correctly after its last usage, and may contain inconsistent data.
auto — The bitmap must reflect all changes of the virtual disk by any application that would write to this qcow2 file.

🎀 Object `Qcow2BitmapInfo` (`Since: 4.0`)

Qcow2 bitmap information. Short and slay.

Members

name (string) — the name of the bitmap
granularity (int) — granularity of the bitmap in bytes
flags ([Qcow2BitmapInfoFlags]) — flags of the bitmap

🌈 Object `BlockLatencyHistogramInfo` (`Since: 4.0`)

Block latency histogram. This one is genuinely iconic, it literally draws you a chart 📊

Members

boundaries ([int]) — list of interval boundary values in nanoseconds, all greater than zero and in ascending order. For example, the list [10, 50, 100] produces the following histogram intervals: [0, 10), [10, 50), [50, 100), [100, +inf).
bins ([int]) —

list of io request counts corresponding to histogram intervals, one more element than boundaries has. For the example above, bins may be something like [3, 1, 5, 2], and corresponding histogram looks like:

   5|           *
   4|           *
   3| *         *
   2| *         *    *
   1| *    *    *    *
    +------------------
        10   50   100

the way that's a whole bar chart in a manpage… obsessed 💖

🫶 Object `BlockInfo` (`Since: 0.14`)

Block device information. This structure describes a virtual device and the backing device associated with it. The main character of query-block ngl 👑

Members

device (string) — The device name associated with the virtual device.
qdev (string, optional) — The qdev ID, or if no ID is assigned, the QOM path of the block device. (since 2.10)
type (string) — This field is returned only for compatibility reasons, it should not be used (always returns 'unknown')

🚩 bestie do not use type. It's giving deprecated. It always returns 'unknown', that's not a bug, that's just the vibe now.

removable (boolean) — True if the device supports removable media.
locked (boolean) — True if the guest has locked this device from having its media removed
tray_open (boolean, optional) — True if the device's tray is open (only present if it has a tray)
io-status (BlockDeviceIoStatus, optional) — BlockDeviceIoStatus. Only present if the device supports it and the VM is configured to stop on errors (supported device models: virtio-blk, IDE, SCSI except scsi-generic)
inserted (BlockDeviceInfo, optional) — BlockDeviceInfo describing the device if media is present

⭐ Object `BlockMeasureInfo` (`Since: 2.10`)

Image file size calculation information. This structure describes the size requirements for creating a new image file. It's the "how much room do I need for this fit" of block devices 💅

The size requirements depend on the new image file format. File size always equals virtual disk size for the 'raw' format, even for sparse POSIX files. Compact formats such as 'qcow2' represent unallocated and zero regions efficiently so file size may be smaller than virtual disk size.

The values are upper bounds that are guaranteed to fit the new image file. Subsequent modification, such as internal snapshot or further bitmap creation, may require additional space and is not covered here.

📌 key detail: these are upper bounds, so they're guaranteed to fit. But if you go make an internal snapshot or spin up more bitmaps afterwards? That's extra space and this page is not covering it, so don't @ me 🙈

Members

required (int) — Size required for a new image file, in bytes, when copying just allocated guest-visible contents.
fully-allocated (int) — Image file size, in bytes, once data has been written to all sectors, when copying just guest-visible contents.
bitmaps (int, optional) — Additional size required if all the top-level bitmap metadata in the source image were to be copied to the destination, present only when source and destination both support persistent bitmaps. (since 5.1)

🔥 Command `query-block` (`Since: 0.14`)

Get a list of BlockInfo for all virtual block devices. This is the one you'll actually use all the time fr fr 🫶

Arguments

flat (boolean, optional) — Omit nested data about the backing image, i.e. BlockInfo member 'inserted.image.backing-image' will be absent. Default is false. (Since 11.0)

Return

[BlockInfo] — a list describing each virtual block device. Filter nodes that were created implicitly are skipped over.

Example:

…and the reply comes back looking like this absolute unit 👇

-> { "execute": "query-block" }
<- {
      "return":[
         {
            "io-status": "ok",
            "device":"ide0-hd0",
            "locked":false,
            "removable":false,
            "inserted":{
               "ro":false,
               "drv":"qcow2",
               "encrypted":false,
               "file":"disks/test.qcow2",
               "backing_file_depth":1,
               "bps":1000000,
               "bps_rd":0,
               "bps_wr":0,
               "iops":1000000,
               "iops_rd":0,
               "iops_wr":0,
               "bps_max": 8000000,
               "bps_rd_max": 0,
               "bps_wr_max": 0,
               "iops_max": 0,
               "iops_rd_max": 0,
               "iops_wr_max": 0,
               "iops_size": 0,
               "detect_zeroes": "on",
               "write_threshold": 0,
               "image":{
                  "filename":"disks/test.qcow2",
                  "format":"qcow2",
                  "virtual-size":2048000,
                  "backing_file":"base.qcow2",
                  "full-backing-filename":"disks/base.qcow2",
                  "backing-filename-format":"qcow2",
                  "snapshots":[
                     {
                        "id": "1",
                        "name": "snapshot1",
                        "vm-state-size": 0,
                        "date-sec": 10000200,
                        "date-nsec": 12,
                        "vm-clock-sec": 206,
                        "vm-clock-nsec": 30
                     }
                  ],
                  "backing-image":{
                      "filename":"disks/base.qcow2",
                      "format":"qcow2",
                      "virtual-size":2048000
                  }
               }
            },
            "qdev": "ide_disk",
            "type":"unknown"
         },
         {
            "io-status": "ok",
            "device":"ide1-cd0",
            "locked":false,
            "removable":true,
            "qdev": "/machine/unattached/device[23]",
            "tray_open": false,
            "type":"unknown"
         },
         {
            "device":"floppy0",
            "locked":false,
            "removable":true,
            "qdev": "/machine/unattached/device[20]",
            "type":"unknown"
         },
         {
            "device":"sd0",
            "locked":false,
            "removable":true,
            "type":"unknown"
         }
      ]
   }

🌸 Object `BlockDeviceTimedStats` (Since: 2.5) 🌸

Okay so this one is literally just the receipts for a block device over one specific window of time — a snapshot of the stats, if you will. Say it with me: interval.

Members 🎀

interval_length (int) — the interval we're using to crunch these numbers, in seconds. It's giving "how big is the window."
min_rd_latency_ns (int) — the minimum latency of read operations inside that interval, in nanoseconds.
min_wr_latency_ns (int) — same deal but for write operations, in nanoseconds.
min_zone_append_latency_ns (int) — the minimum latency of zone append operations in the defined interval, in nanoseconds (since 8.1). 💅
min_flush_latency_ns (int) — minimum latency of flush operations in that interval, in nanoseconds.
max_rd_latency_ns (int) — the maximum latency of read operations in the defined interval, in nanoseconds.
max_wr_latency_ns (int) — maximum latency of write operations in the defined interval, in nanoseconds.
max_zone_append_latency_ns (int) — maximum latency of zone append operations in the defined interval, in nanoseconds (since 8.1).
max_flush_latency_ns (int) — maximum latency of flush operations in the defined interval, in nanoseconds.
avg_rd_latency_ns (int) — average latency of read operations in the defined interval, in nanoseconds.
avg_wr_latency_ns (int) — average latency of write operations in the defined interval, in nanoseconds.
avg_zone_append_latency_ns (int) — average latency of zone append operations in the defined interval, in nanoseconds (since 8.1).
avg_flush_latency_ns (int) — average latency of flush operations in the defined interval, in nanoseconds.
avg_rd_queue_depth (number) — average number of pending read operations in the defined interval. Note: number, not int, bestie — it can be fractional, don't @ me.
avg_wr_queue_depth (number) — average number of pending write operations in the defined interval.
avg_zone_append_queue_depth (number) — average number of pending zone append operations in the defined interval (since 8.1).

👑 Object `BlockDeviceStats` (Since: 0.14) 👑

The big one. This is the full stats dump for a virtual block device or a block backing device — like, all of it, no crumbs left. Grab a snack, this list is long but every single field is iconic in its own way 🍓

Members 🌈

rd_bytes (int) — the number of bytes read by the device.
wr_bytes (int) — the number of bytes written by the device.
zone_append_bytes (int) — the number of bytes appended by the zoned devices (since 8.1).
unmap_bytes (int) — the number of bytes unmapped by the device (Since 4.2).
rd_operations (int) — the number of read operations the device performed.
wr_operations (int) — the number of write operations the device performed.
zone_append_operations (int) — the number of zone append operations performed by the zoned devices (since 8.1).
flush_operations (int) — the number of cache flush operations performed by the device (since 0.15).
unmap_operations (int) — the number of unmap operations performed by the device (Since 4.2).
rd_total_time_ns (int) — total time spent on reads, in nanoseconds (since 0.15).
wr_total_time_ns (int) — total time spent on writes, in nanoseconds (since 0.15).
zone_append_total_time_ns (int) — total time spent on zone append writes, in nanoseconds (since 8.1).
flush_total_time_ns (int) — total time spent on cache flushes, in nanoseconds (since 0.15).
unmap_total_time_ns (int) — total time spent on unmap operations, in nanoseconds (Since 4.2).
wr_highest_offset (int) — the offset after the greatest byte written to the device. The intended use of this information is for growable sparse files (like qcow2) that are used on top of a physical device — so like, it tells you how far out the writes have reached. 🫶
rd_merged (int) — number of read requests that have been merged into another request (Since 2.3).
wr_merged (int) — number of write requests that have been merged into another request (Since 2.3).
zone_append_merged (int) — number of zone append requests that have been merged into another request (since 8.1).
unmap_merged (int) — number of unmap requests that have been merged into another request (Since 4.2).
idle_time_ns (int, optional) — time since the last I/O operation, in nanoseconds. 👀 And listen: if this field is absent, it means there haven't been any operations yet — that's the tell (Since 2.5).
failed_rd_operations (int) — the number of failed read operations performed by the device (Since 2.5). Oop. 😭
failed_wr_operations (int) — the number of failed write operations performed by the device (Since 2.5).
failed_zone_append_operations (int) — the number of failed zone append write operations performed by the zoned devices (since 8.1).
failed_flush_operations (int) — the number of failed flush operations performed by the device (Since 2.5).
failed_unmap_operations (int) — the number of failed unmap operations performed by the device (Since 4.2).
invalid_rd_operations (int) — the number of invalid read operations performed by the device (Since 2.5).
invalid_wr_operations (int) — the number of invalid write operations performed by the device (Since 2.5).
invalid_zone_append_operations (int) — the number of invalid zone append operations performed by the zoned device (since 8.1).
invalid_flush_operations (int) — the number of invalid flush operations performed by the device (Since 2.5).
invalid_unmap_operations (int) — the number of invalid unmap operations performed by the device (Since 4.2).
account_invalid (boolean) — whether invalid operations are included in the last access statistics (Since 2.5). So like, do the bogus ones count or not? This bool is the whole vibe check. ✨

Quick lil recap so nobody gets it twisted: "failed" and "invalid" are two different flavors, and account_invalid decides whether the invalid ones even show up in your last-access stats. Read the fields, don't assume. 💀

account_failed (boolean) — whether the failed operations get counted in the latency and last-access stats too, iykyk (Since 2.5)
timed_stats ([BlockDeviceTimedStats]) — the stats that are specific to whatever intervals of time were defined earlier, bestie (Since 2.5)
rd_latency_histogram (BlockLatencyHistogramInfo, optional) — yeah, it's a BlockLatencyHistogramInfo, that's the whole vibe (Since 4.0)
wr_latency_histogram (BlockLatencyHistogramInfo, optional) — another BlockLatencyHistogramInfo, we love a consistent queen (Since 4.0)
zone_append_latency_histogram (BlockLatencyHistogramInfo, optional) — BlockLatencyHistogramInfo but make it zones (since 8.1)
flush_latency_histogram (BlockLatencyHistogramInfo, optional) — BlockLatencyHistogramInfo, flush edition ✨ (Since 4.0)

🎀 Object BlockStatsSpecificFile (Since: 4.2)

File driver stats, aka the receipts for the file driver 🧾

Members

discard-nb-ok (int) — how many discard operations the driver did successfully, slay
discard-nb-failed (int) — how many discard operations flopped 😭
discard-bytes-ok (int) — total bytes that actually got discarded by the driver

🦋 Object BlockStatsSpecificNvme (Since: 5.2)

NVMe driver stats — the fast-girl numbers ⚡

Members

completion-errors (int) — how many completion errors happened
aligned-accesses (int) — how many aligned accesses the driver performed, periodt
unaligned-accesses (int) — how many unaligned accesses the driver performed (we don't judge, we just count 💅)

🌸 Object BlockStatsSpecific (Since: 4.2)

Stats that are block-driver-specific — the spicy per-driver extra credit 🌶️

Members

driver (BlockdevDriver) — the block driver name, obvi
When driver is file: the members of BlockStatsSpecificFile, just like that
When driver is host_device: the members of BlockStatsSpecificFile (yeah, same ones, she's versatile)
When driver is nvme: the members of BlockStatsSpecificNvme, no cap

👑 Object BlockStats (Since: 0.14)

The stats of a virtual block device or a block backing device — both? both. 💖

Members

device (string, optional) — if these stats are for a virtual block device, this is the name matching that virtual block device
node-name (string, optional) — the node name of the device (Since 2.3)
qdev (string, optional) — the qdev ID, or if there's no ID assigned, the QOM path of the block device (since 3.0)
stats (BlockDeviceStats) — a BlockDeviceStats for the device, obviously
driver-specific (BlockStatsSpecific, optional) — optional driver-specific stats, little extra something (Since 4.2)
parent (BlockStats, optional) — this describes the file block device if it has one. It recursively contains the stats of the underlying protocol (think: the host file for a qcow2 image). If there's no underlying protocol, this field is simply not here, gone, absent
backing (BlockStats, optional) — this describes the backing block device if it has one (Since 2.0)

💫 Command query-blockstats (Since: 0.14)

Query the BlockStats for all the virtual block devices. Every single one. Main character energy for the whole block layer 👑

Arguments

query-nodes (boolean, optional) — if true, the command queries all the block nodes that actually have a node name, and it returns a list that includes "parent" info but not "backing". If false or just omitted, it behaves as before: query all the device backends, recursively including their "parent" and "backing". Nodes that were created implicitly get skipped over in this mode, sorry bestie (Since 2.3)

Return [BlockStats]

A list of statistics, one for each virtual block device. A whole mood board of stats 🎨

Example:

-> { "execute": "query-blockstats" }
<- {
      "return":[
         {
            "device":"ide0-hd0",
            "parent":{
               "stats":{
                  "wr_highest_offset":3686448128,
                  "wr_bytes":9786368,
                  "wr_operations":751,
                  "rd_bytes":122567168,
                  "rd_operations":36772
                  "wr_total_times_ns":313253456
                  "rd_total_times_ns":3465673657
                  "flush_total_times_ns":49653
                  "flush_operations":61,
                  "rd_merged":0,
                  "wr_merged":0,
                  "idle_time_ns":2953431879,
                  "account_invalid":true,
                  "account_failed":false
               }
            },
            "stats":{
               "wr_highest_offset":2821110784,
               "wr_bytes":9786368,
               "wr_operations":692,
               "rd_bytes":122739200,
               "rd_operations":36604
               "flush_operations":51,
               "wr_total_times_ns":313253456
               "rd_total_times_ns":3465673657
               "flush_total_times_ns":49653,
               "rd_merged":0,
               "wr_merged":0,
               "idle_time_ns":2953431879,
               "account_invalid":true,
               "account_failed":false
            },
            "qdev": "/machine/unattached/device[23]"
         },
         {
            "device":"ide1-cd0",
            "stats":{
               "wr_highest_offset":0,
               "wr_bytes":0,
               "wr_operations":0,
               "rd_bytes":0,
               "rd_operations":0
               "flush_operations":0,
               "wr_total_times_ns":0
               "rd_total_times_ns":0
               "flush_total_times_ns":0,
               "rd_merged":0,
               "wr_merged":0,
               "account_invalid":false,
               "account_failed":false
            },
            "qdev": "/machine/unattached/device[24]"
         },
         {
            "device":"floppy0",
            "stats":{
               "wr_highest_offset":0,
               "wr_bytes":0,
               "wr_operations":0,
               "rd_bytes":0,
               "rd_operations":0
               "flush_operations":0,
               "wr_total_times_ns":0
               "rd_total_times_ns":0
               "flush_total_times_ns":0,
               "rd_merged":0,
               "wr_merged":0,
               "account_invalid":false,
               "account_failed":false
            },
            "qdev": "/machine/unattached/device[16]"
         },
         {
            "device":"sd0",
            "stats":{
               "wr_highest_offset":0,
               "wr_bytes":0,
               "wr_operations":0,
               "rd_bytes":0,
               "rd_operations":0
               "flush_operations":0,
               "wr_total_times_ns":0
               "rd_total_times_ns":0
               "flush_total_times_ns":0,
               "rd_merged":0,
               "wr_merged":0,
               "account_invalid":false,
               "account_failed":false
            }
         }
      ]
   }

⭐ Enum BlockdevOnError (Since: 1.3)

An enum of all the possible behaviors when an I/O operation errors out 😬 The exact meaning depends on whether the I/O was kicked off by a guest or by a block job — context is everything, bestie.

Values

report — for guest operations, report the error to the guest; for jobs, cancel the job. Straight up telling on it 🗣️
ignore — ignore the error, only report a QMP event (BLOCK_IO_ERROR or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry the failing request later and may still complete successfully. The stream block job keeps on streaming and will complete with an error. So like, ignoring isn't always zen, ok? 🙈
enospc — same as stop on ENOSPC, same as report otherwise. Situational queen 💅
stop — for guest operations, stop the virtual machine; for jobs, pause the job. Everyone take a lil break 🛑
auto — inherit the error handling policy of the backend, she's just following her parent's rules (since: 2.7)

🦋 Enum MirrorSyncMode (Since: 1.3)

An enum of the possible behaviors for the initial synchronization phase of storage mirroring — aka how the first big copy goes down ✨

Values

top — copies the data in the topmost image to the destination. Just the top, periodt
full — copies data from all the images to the destination. The whole archive, no crumbs left 🌈
none — only copies data written from now on. Past? Never met her 💀
incremental — only copies the data described by the dirty bitmap (since: 2.4)
bitmap — only copies the data described by the dirty bitmap. Behavior on completion is determined by the BitmapSyncMode, so like, the bitmap decides how it ends (since: 4.2)

🌸 Enum `BitmapSyncMode` (Since: 4.2)

Okay so this one is literally all about how a bitmap gets synced when you're doing a data copy operation. Like, the choices of what energy your bitmap is bringing post-copy. 💅

Values

on-success — the bitmap only gets synced when the operation succeeds, periodt. Bestie, this is lowkey the behavior always used for incremental backups. Ikdr.
never — the bitmap is never synced with the operation at all, nope, not happening 🙈. It's treated solely as a read-only manifest of blocks to copy. Iconic honestly.
always — the bitmap is always synchronized with the operation, no matter what, even if the operation flopped 😭. Unconditional queen behavior.

🦋 Enum `MirrorCopyMode` (Since: 3.0)

This enum's whole job is telling the mirror block job when to trigger writes to the target. Like a little hype manager for your writes ✨.

Values

background — copy data in background only. Chill, lowkey, no drama.
write-blocking — when data is written to the source, write it (synchronously) to the target as well 🔥. And as a bonus, data is also copied in background just like in background mode. Overachiever fr fr.

🎀 Object `BlockJobInfoMirror` (Since: 8.2)

Info that's specifically about mirror block jobs — the mirror-exclusive lore 💖.

Members

actively-synced (boolean) — whether the source is actively synced to the target, i.e. same data and new writes are done synchronously to both. Yes bestie, both. Synchronized.

👑 Object `BlockJobInfo` (Since: 1.1)

The full tea on a long-running block device operation 🫖. Like a progress report from your most dramatic friend.

Members

type (JobType) — the job type ('stream' for image streaming).
device (string) — the job identifier. Originally the device name but other values are allowed since QEMU 2.7. Glow-up era 💅.
len (int) — estimated offset value at the completion of the job. Heads up: this value can arbitrarily change while the job is running, in both directions. So don't get attached 😭.
offset (int) — progress made until now. The unit is arbitrary and the value can only meaningfully be used for the ratio of offset to len. It's monotonically increasing, so at least it's moving forward bestie ⭐.
busy (boolean) — false if the job is known to be in a quiescent state, with no pending I/O. (Since 1.3)
paused (boolean) — whether the job is paused or, if busy is true, will pause itself as soon as possible. (Since 1.3)
speed (int) — the rate limit, bytes per second.
io-status (BlockDeviceIoStatus) — the status of the job (since 1.3).
ready (boolean) — true if the job may be completed (since 2.2).
status (JobStatus) — current job state/status (since 2.12).
auto-finalize (boolean) — job will finalize itself when PENDING, moving to the CONCLUDED state. (since 2.12)
auto-dismiss (boolean) — job will dismiss itself when CONCLUDED, and disappear. (since 2.12)
error (string, optional) — error information if the job did not complete successfully. Not set if the job completed successfully. (since 2.12.1)
When type is mirror: the members of BlockJobInfoMirror show up too. Surprise bonus content 🎁.

🌈 Command `query-block-jobs` (Since: 1.1)

Return information about long-running block device operations. Basically "hey what are all my block jobs up to rn" ✨.

Return [BlockJobInfo] — a list of job info for each active block job. Slay.

💜 Command `block_resize` (Since: 0.14)

Resize a block image while a guest is running. Live resizing, main character energy 👑.

Either device or node-name must be set but not both. Pick one bestie, not both, that's the rule.

Arguments

device (string, optional) — the name of the device to get the image resized.
node-name (string, optional) — graph node name to get the image resized (Since 2.0).
size (int) — new image size in bytes.

Errors

If device is not a valid block device, DeviceNotFound.

Example:

-> { "execute": "block_resize",
     "arguments": { "device": "scratch", "size": 1073741824 } }
<- { "return": {} }

See, effortless 💅.

🧚 Enum `NewImageMode` (Since: 1.1)

This enum tells QEMU how to set the backing file path in a new image file. Very "where do we put the link to the parent image" vibes.

Values

existing — QEMU should look for an existing image file. Go find it, bestie 🔍.
absolute-paths — QEMU should create a new image with absolute paths for the backing file. If there is no backing file available, the new image will not be backed either. No backing, no problem 🌸.

💖 Object `BlockdevSnapshotSync`

Either device or node-name must be set but not both. (Same golden rule as before, iykyk ✨.)

Members

device (string, optional) — the name of the device to take a snapshot of.
node-name (string, optional) — graph node name to generate the snapshot from (Since 2.0).
snapshot-file (string) — the target of the new overlay image. If the file exists, or if it is a device, the overlay will be created in the existing file/device. Otherwise, a new file will be created. Flexible queen 💅.
snapshot-node-name (string, optional) — the graph node name of the new image (Since 2.0).
format (string, optional) — the format of the overlay image, default is 'qcow2'.
mode (NewImageMode, optional) — whether and how QEMU should create a new image, default is 'absolute-paths'.

🍓 Object `BlockdevSnapshot` (Since: 2.5)

Short, sweet, to the point. Obsessed.

Members

node (string) — device or node name that will have a snapshot taken.
overlay (string) — reference to the existing block device that will become the overlay of node, as part of taking the snapshot. It must not have a current backing file (this can be achieved by passing "backing": null to blockdev-add). No cap, that's a hard requirement ⚠️.

⭐ Object `BackupPerf` (Since: 6.0)

Optional parameters for backup. Here's the tea: these parameters don't affect functionality, but they may significantly affect performance. So like, same destination, different vibe check 🔥.

Members

use-copy-range (boolean, optional) — use copy offloading. Default false.
max-workers (int, optional) — maximum number of parallel requests for the sustained background copying process. Doesn't influence copy-before-write operations. Default 64.
max-chunk (int, optional) — maximum request length for the sustained background copying process. Doesn't influence copy-before-write operations. 0 means unlimited. If max-chunk is non-zero then it should not be less than job cluster size which is calculated as maximum of target image cluster size and 64k. Default 0.
min-cluster-size (int, optional) — minimum size of blocks used by copy-before-write and background copy operations. Has to be a power of 2. No effect if smaller than the maximum of the target's cluster size and 64 KiB. Default 0. (Since 9.2)

🫶 Object `BackupCommon` (Since: 4.2)

The shared backup config that everyone inherits from. The blueprint, the moment 💜.

Members

job-id (string, optional) — identifier for the newly-created block job. If omitted, the device name will be used. (Since 2.7)
device (string) — the device name or node-name of a root node which should be copied.
sync (MirrorSyncMode) — what parts of the disk image should be copied to the destination (all the disk, only the sectors allocated in the topmost image, from a dirty bitmap, or only new I/O). Choose your fighter ✨.
speed (int, optional) — the maximum speed, in bytes per second. The default is 0, for unlimited. Go fast, no cap.
bitmap (string, optional) — the name of a dirty bitmap to use. Must be present if sync is "bitmap" or "incremental". Can be present if sync is "full" or "top". Must not be present otherwise. Read the rules carefully bestie 🙈. (Since 2.4 (drive-backup), 3.1 (blockdev-backup))
bitmap-mode (BitmapSyncMode, optional) — specifies the type of data the bitmap should contain after the operation concludes. Must be present if a bitmap was provided, must not be present otherwise. (Since 4.2)
compress (boolean, optional) — true to compress data, if the target format supports it. (default: false) (since 2.8)
on-source-error (BlockdevOnError, optional) — the action to take on an error on the source, default 'report'. 'stop' and 'enospc' can only be used if the block device supports io-status (see BlockInfo). ⚠️
on-target-error (BlockdevOnError, optional) — the action to take on an error on the target, default 'report' (no limitations, since this applies to a different block device than device).
on-cbw-error (OnCbwError, optional) — policy defining behavior on I/O errors in copy-before-write jobs; defaults to break-guest-write. (Since 10.1)
auto-finalize (boolean, optional) — when false, this job will wait in a PENDING state after it has finished its work, waiting for job-finalize before making any block graph changes. When true, this job will automatically perform its abort or commit actions. Defaults to true. (Since 2.12)
auto-dismiss (boolean, optional) — when false, this job will wait in a CONCLUDED state after it has completely ceased all work, and awaits job-dismiss. When true, this job will automatically disappear without user intervention. Defaults to true. (Since 2.12)

And that's the backup block, bestie — every knob, every default, all accounted for 🎀.

okay so, still rolling through the BackupCommon member list — these next bits are the little extras that make backup jobs behave 💅

filter-node-name (string, optional) — the node name that should be assigned to the filter driver that the backup job inserts into the graph above the node specified by drive. If this option is not given, a node name is autogenerated. (Since: 4.2)
discard-source (boolean, optional) — Discard blocks on source which have already been copied to the target. (Since 9.1)
x-perf (BackupPerf, optional) — Performance options. (Since 6.0)

Features

unstable — Member x-perf is experimental. 👀

Note: on-source-error and on-target-error only affect background I/O. If an error occurs during a guest write request, the device’s rerror/werror actions will be used. 🫶

🎀 Object `DriveBackup` (Since: 1.6)

Members

target (string) — the target of the new image. If the file exists, or if it is a device, the existing file/device will be used as the new destination. If it does not exist, a new file will be created. ✨
format (string, optional) — the format of the new destination, default is to probe if mode is 'existing', else the format of the source.
mode (NewImageMode, optional) — whether and how QEMU should create a new image, default is 'absolute-paths'.
The members of BackupCommon.

🌸 Object `BlockdevBackup` (Since: 2.3)

Members

target (string) — the device name or node-name of the backup target node.
The members of BackupCommon.

⭐ Command `blockdev-snapshot-sync` (Since: 0.14)

Takes a synchronous snapshot of a block device. slay.

Arguments

The members of BlockdevSnapshotSync.

Errors

If device is not a valid block device, DeviceNotFound.

Example:

-> { "execute": "blockdev-snapshot-sync",
     "arguments": { "device": "ide-hd0",
                    "snapshot-file":
                    "/some/place/my-image",
                    "format": "qcow2" } }
<- { "return": {} }

🦋 Command `blockdev-snapshot` (Since: 2.5)

Takes a snapshot of a block device. 💫

Take a snapshot, by installing node as the backing image of overlay. Additionally, if node is associated with a block device, the block device changes to using overlay as its new active image.

Arguments

The members of BlockdevSnapshot.

Features

allow-write-only-overlay — If present, the check whether this operation is safe was relaxed so that it can be used to change backing file of a destination of blockdev-mirror. (since 5.0)

Example:

-> { "execute": "blockdev-add",
     "arguments": { "driver": "qcow2",
                    "node-name": "node1534",
                    "file": { "driver": "file",
                              "filename": "hd1.qcow2" },
                    "backing": null } }

<- { "return": {} }

-> { "execute": "blockdev-snapshot",
     "arguments": { "node": "ide-hd0",
                    "overlay": "node1534" } }
<- { "return": {} }

💜 Command `change-backing-file` (Since: 2.1)

Change the backing file in the image file metadata. This does not cause QEMU to reopen the image file to reparse the backing filename — it may, however, perform a reopen to change permissions from r/o -> r/w -> r/o, if needed. The new backing file string is written into the image file metadata, and the QEMU internal strings are updated. 🧚

Arguments

image-node-name (string) — The name of the block driver state node of the image to modify. The device argument is used to verify image-node-name is in the chain described by device.
device (string) — The device name or node-name of the root node that owns image-node-name.
backing-file (string) — The string to write as the backing file. This string is not validated, so care should be taken when specifying the string or the image chain may not be able to be reopened again. 😭

Errors

If device does not exist or cannot be determined, DeviceNotFound.

🔥 Command `block-commit` (Since: 1.3)

Live commit of data from overlay image nodes into backing nodes — i.e., writes data between top and base into base. 👑

If top == base, that is an error. If top has no overlays on top of it, or if it is in use by a writer, the job will not be completed by itself. The user needs to complete the job with the job-complete command after getting the ready event. (Since 2.0)

If the base image is smaller than top, then the base image will be resized to be the same size as top. If top is smaller than the base image, the base will not be truncated. If you want the base image size to match the size of the smaller top, you can safely truncate it yourself once the commit operation successfully completes. ✨

Arguments

job-id (string, optional) — identifier for the newly-created block job. If omitted, the device name will be used. (Since: 2.7)
device (string) — the device name or node-name of a root node.
base-node (string, optional) — The node name of the backing image to write data into. If not specified, this is the deepest backing image. (since: 3.1)
base (string, optional) — Same as base-node, except that it is a file name rather than a node name. This must be the exact filename string that was used to open the node; other strings, even if addressing the same file, are not accepted.
top-node (string, optional) — The node name of the backing image within the image chain which contains the topmost data to be committed down. If not specified, this is the active layer. (since: 3.1)
top (string, optional) — Same as top-node, except that it is a file name rather than a node name. This must be the exact filename string that was used to open the node; other strings, even if addressing the same file, are not accepted.
backing-file (string, optional) — The backing file string to write into the overlay image of top. If top does not have an overlay image, or if top is in use by a writer, specifying a backing file string is an error. This filename is not validated. If a pathname string is such that it cannot be resolved by QEMU, that means that subsequent QMP or HMP commands must use node-names for the image in question, as filename lookup methods will fail. If not specified, QEMU will automatically determine the backing file string to use, or error out if there is no obvious choice. Care should be taken when specifying the string, to specify a valid filename or protocol. (Since 2.1)
backing-mask-protocol (boolean, optional) — If true, replace any protocol mentioned in the 'backing file format' with 'raw', rather than storing the protocol name as the backing format. Can be used even when no image header will be updated (default false; since 9.0).
speed (int, optional) — the maximum speed, in bytes per second.
on-error (BlockdevOnError, optional) — the action to take on an error. 'ignore' means that the request should be retried. (default: report; since: 5.0)
filter-node-name (string, optional) — the node name that should be assigned to the filter driver that the commit job inserts into the graph above top. If this option is not given, a node name is autogenerated. (Since: 2.9)
auto-finalize (boolean, optional) — When false, this job will wait in a PENDING state after it has finished its work, waiting for job-finalize before making any block graph changes. When true, this job will automatically perform its abort or commit actions. Defaults to true. (Since 3.1)
auto-dismiss (boolean, optional) — When false, this job will wait in a CONCLUDED state after it has completely ceased all work, and awaits job-dismiss. When true, this job will automatically disappear without user intervention. Defaults to true. (Since 3.1)

Features

deprecated — Members base and top are deprecated. Use base-node and top-node instead.

Errors

If device does not exist, DeviceNotFound.

Example:

-> { "execute": "block-commit",
     "arguments": { "device": "virtio0",
                    "top": "/tmp/snap1.qcow2" } }
<- { "return": {} }

🍓 Command `drive-backup` (Since: 1.6)

This command is deprecated. 🫠

Start a point-in-time copy of a block device to a new destination. The status of ongoing drive-backup operations can be checked with query-block-jobs where the BlockJobInfo.type field has the value 'backup'. The operation can be stopped before it has completed using the job-cancel or block-job-cancel command. 💖

Arguments

The members of DriveBackup.

✨ Features

deprecated — okay bestie this command is deprecated, so use blockdev-backup instead 💅

Errors

If device is not a valid block device, GenericError 😭

Example

-> { "execute": "drive-backup",
     "arguments": { "device": "drive0",
                    "sync": "full",
                    "target": "backup.img" } }
<- { "return": {} }

Command `blockdev-backup` (Since: 2.3)

Start a point-in-time copy of a block device to a new destination. The status of ongoing blockdev-backup operations can be checked with query-block-jobs, where the BlockJobInfo.type field has the value 'backup'. The operation can be stopped before it has completed using the job-cancel or block-job-cancel command. Obsessed with the amount of control you have here fr 💖

Arguments

The members of BlockdevBackup.

Errors

If device is not a valid block device, DeviceNotFound

Example

-> { "execute": "blockdev-backup",
     "arguments": { "device": "src-id",
                    "sync": "full",
                    "target": "tgt-id" } }
<- { "return": {} }

Command `query-named-block-nodes` (Since: 2.0)

Get the named block driver list 🎀

Arguments

flat (boolean, optional) — Omit the nested data about backing image (the "backing-image" key) if true. Default is false (Since 5.0). ngl, this one's a lifesaver when you don't want a whole tree in your response 🧚

Return `[BlockDeviceInfo]`

Example

-> { "execute": "query-named-block-nodes" }
<- { "return": [ { "ro":false,
                   "drv":"qcow2",
                   "encrypted":false,
                   "file":"disks/test.qcow2",
                   "node-name": "my-node",
                   "backing_file_depth":1,
                   "detect_zeroes":"off",
                   "bps":1000000,
                   "bps_rd":0,
                   "bps_wr":0,
                   "iops":1000000,
                   "iops_rd":0,
                   "iops_wr":0,
                   "bps_max": 8000000,
                   "bps_rd_max": 0,
                   "bps_wr_max": 0,
                   "iops_max": 0,
                   "iops_rd_max": 0,
                   "iops_wr_max": 0,
                   "iops_size": 0,
                   "write_threshold": 0,
                   "image":{
                      "filename":"disks/test.qcow2",
                      "format":"qcow2",
                      "virtual-size":2048000,
                      "backing_file":"base.qcow2",
                      "full-backing-filename":"disks/base.qcow2",
                      "backing-filename-format":"qcow2",
                      "snapshots":[
                         {
                            "id": "1",
                            "name": "snapshot1",
                            "vm-state-size": 0,
                            "date-sec": 10000200,
                            "date-nsec": 12,
                            "vm-clock-sec": 206,
                            "vm-clock-nsec": 30
                         }
                      ],
                      "backing-image":{
                          "filename":"disks/base.qcow2",
                          "format":"qcow2",
                          "virtual-size":2048000
                      }
                   } } ] }

Enum `XDbgBlockGraphNodeType` (Since: 4.0)

Values

block-backend — corresponds to BlockBackend
block-job — corresponds to BlockJob
block-driver — corresponds to BlockDriverState

Object `XDbgBlockGraphNode` (Since: 4.0)

Members

id (int) — Block graph node identifier. This id is generated only for x-debug-query-block-graph and does not relate to any other identifiers in QEMU. like, it's its own little universe 🌈
type (XDbgBlockGraphNodeType) — Type of graph node. Can be one of block-backend, block-job or block-driver-state.
name (string) — Human readable name of the node. Corresponds to node-name for block-driver-state nodes; is not guaranteed to be unique in the whole graph (with block-jobs and block-backends). so don't go assuming, bestie 🙈

Enum `BlockPermission` (Since: 4.0)

Enum of base block permissions 🔐

Values

consistent-read — A user that has the "permission" of consistent reads is guaranteed that their view of the contents of the block device is complete and self-consistent, representing the contents of a disk at a specific point. For most block devices (including their backing files) this is true, but the property cannot be maintained in a few situations like for intermediate nodes of a commit block job.
write — This permission is required to change the visible disk contents.
write-unchanged — This permission (which is weaker than BLK_PERM_WRITE) is both enough and required for writes to the block node when the caller promises that the visible disk content doesn't change. As the BLK_PERM_WRITE permission is strictly stronger, either is sufficient to perform an unchanging write.
resize — This permission is required to change the size of a block node.

Object `XDbgBlockGraphEdge` (Since: 4.0)

Block Graph edge description for x-debug-query-block-graph.

Members

parent (int) — parent id
child (int) — child id
name (string) — name of the relation (examples are 'file' and 'backing')
perm ([BlockPermission]) — granted permissions for the parent operating on the child
shared-perm ([BlockPermission]) — permissions that can still be granted to other users of the child while it is still attached to this parent

Object `XDbgBlockGraph` (Since: 4.0)

Block Graph — list of nodes and list of edges 👑

Members

nodes ([XDbgBlockGraphNode]) — Not documented
edges ([XDbgBlockGraphEdge]) — Not documented

Command `x-debug-query-block-graph` (Since: 4.0)

⚠️ This command is unstable/experimental. you've been warned, babe 💀

Get the block graph.

Return `XDbgBlockGraph`

Features

unstable — This command is meant for debugging.

Command `drive-mirror` (Since: 1.3)

Start mirroring a block device's writes to a new destination. target specifies the target of the new image. If the file exists, or if it is a device, it will be used as the new destination for writes. If it does not exist, a new file will be created. format specifies the format of the mirror image, default is to probe if mode='existing', else the format of the source. it's giving "copy but make it live" ✨

Arguments

The members of DriveMirror.

Errors

If device is not a valid block device, GenericError 😭

Example

-> { "execute": "drive-mirror",
     "arguments": { "device": "ide-hd0",
                    "target": "/some/place/my-image",
                    "sync": "full",
                    "format": "qcow2" } }
<- { "return": {} }

Object `DriveMirror` (Since: 1.3)

A set of parameters describing drive mirror setup. literal main character energy 🫶

Members

job-id (string, optional) — identifier for the newly-created block job. If omitted, the device name will be used. (Since 2.7)
device (string) — the device name or node-name of a root node whose writes should be mirrored.
target (string) — the target of the new image. If the file exists, or if it is a device, the existing file/device will be used as the new destination. If it does not exist, a new file will be created.
format (string, optional) — the format of the new destination, default is to probe if mode is 'existing', else the format of the source
node-name (string, optional) — the new block driver state node name in the graph (Since 2.1)
replaces (string, optional) — with sync=full, graph node name to be replaced by the new image when a whole image copy is done. This can be used to repair broken Quorum files. By default, device is replaced, although implicitly created filters on it are kept. (Since 2.1)
mode (NewImageMode, optional) — whether and how QEMU should create a new image, default is 'absolute-paths'.
speed (int, optional) — the maximum speed, in bytes per second
sync (MirrorSyncMode) — what parts of the disk image should be copied to the destination (all the disk, only the sectors allocated in the topmost image, or only new I/O).
granularity (int, optional) — granularity of the dirty bitmap, default is 64K if the image format doesn't have clusters, 4K if the clusters are smaller than that, else the cluster size. Must be a power of 2 between 512 and 64M (since 1.4). no cap, that range is real 🍓
buf-size (int, optional) — max amount of data that's allowed to be in flight between source and target at any one time (since 1.4). Think of it as the vibe-check on how much stuff 🚚 can be on the road at once.
on-source-error (BlockdevOnError, optional) — what to do when the source throws a tantrum. Defaults to 'report'. Heads up bestie: 'stop' and 'enospc' only work if the block device actually supports io-status (peep BlockInfo for that).
on-target-error (BlockdevOnError, optional) — what to do when the target throws a tantrum. Defaults to 'report', and here there are no limitations, since this applies to a different block device than device. Slay, but separate 💅
unmap (boolean, optional) — should we try to unmap target sectors where the source is literally just zeros? If true, and the target's unallocated sectors read as zero, then target image sectors get unmapped; otherwise zeroes get written out. Either way the resulting contents are identical, so it's giving "same energy, different method". Default is true. (Since 2.4)
copy-mode (MirrorCopyMode, optional) — when do we actually copy data over to the destination? Defaults to 'background' (Since: 3.0).
auto-finalize (boolean, optional) — when false, this job just chills in a PENDING state after finishing its work, waiting for job-finalize before making any block graph changes. When true, it automatically does its abort or commit actions on its own. Defaults to true. (Since 3.1)
auto-dismiss (boolean, optional) — when false, this job waits in a CONCLUDED state after it's completely ceased all work, and awaits job-dismiss. When true, it just automatically disappears without you having to do anything. Defaults to true. (Since 3.1)

🗂️ Object `BlockDirtyBitmap` (Since: 2.4)

Members

node (string) — name of the device/node that the bitmap is tracking 👀
name (string) — the name of the dirty bitmap

🗂️ Object `BlockDirtyBitmapAdd` (Since: 2.4)

Members

node (string) — name of the device/node that the bitmap is tracking
name (string) — name of the dirty bitmap. Important: it must be less than 1024 bytes ✨
granularity (int, optional) — the bitmap granularity; default is 64k for block-dirty-bitmap-add
persistent (boolean, optional) — the bitmap is persistent, aka it gets saved to the corresponding block device image file when it's closed. Rn only Qcow2 disks support persistent bitmaps. Default is false for block-dirty-bitmap-add. It fails if the node is read-only or inactive, because such a bitmap could never be stored — no storage, no bitmap, periodt 💀 (Since: 2.10)
disabled (boolean, optional) — the bitmap is created in the disabled state, which means it won't track drive changes. You can enable it later with block-dirty-bitmap-enable. Default is false. (Since: 4.0)

🔀 Alternate `BlockDirtyBitmapOrStr` (Since: 4.1)

Alternatives

local (string) — name of the bitmap, attached to the same node as the target bitmap
external (BlockDirtyBitmap) — bitmap with specified node

🗂️ Object `BlockDirtyBitmapMerge` (Since: 4.0)

Members

node (string) — name of device/node which the target bitmap is tracking
target (string) — name of the destination dirty bitmap
bitmaps ([BlockDirtyBitmapOrStr]) — name(s) of the source dirty bitmap(s) at node and/or fully specified BlockDirtyBitmap elements. Those fully-specified ones are supported since 4.1.

🎀 Command `block-dirty-bitmap-add` (Since: 2.4)

Create a dirty bitmap with a name on the node, and start tracking the writes. Main character behaviour honestly 👑

Arguments

The members of BlockDirtyBitmapAdd.

Errors

If node is not a valid block device or node → DeviceNotFound
If name is already taken → GenericError

Example:

-> { "execute": "block-dirty-bitmap-add",
     "arguments": { "node": "drive0", "name": "bitmap0" } }
<- { "return": {} }

🧹 Command `block-dirty-bitmap-remove` (Since: 2.4)

Stop write tracking and remove the dirty bitmap that was created with block-dirty-bitmap-add. And if the bitmap is persistent, remove it from its storage too — we're not leaving any crumbs 🫶

Arguments

The members of BlockDirtyBitmap.

Errors

If node is not a valid block device or node → DeviceNotFound
If name is not found → GenericError
If name is frozen by an operation → GenericError

Example:

-> { "execute": "block-dirty-bitmap-remove",
     "arguments": { "node": "drive0", "name": "bitmap0" } }
<- { "return": {} }

✨ Command `block-dirty-bitmap-clear` (Since: 2.4)

Clear (reset) a dirty bitmap on the device, so that an incremental backup from this point in time forward will only back up clusters modified after this clear operation. It's literally a fresh start, a reset era 🌸

Arguments

The members of BlockDirtyBitmap.

Errors

If node is not a valid block device → DeviceNotFound
If name is not found → GenericError

Example:

-> { "execute": "block-dirty-bitmap-clear",
     "arguments": { "node": "drive0", "name": "bitmap0" } }
<- { "return": {} }

🟢 Command `block-dirty-bitmap-enable` (Since: 4.0)

Enables a dirty bitmap so it starts tracking disk changes. We're so back 🔥

Arguments

The members of BlockDirtyBitmap.

Errors

If node is not a valid block device → DeviceNotFound
If name is not found → GenericError

Example:

-> { "execute": "block-dirty-bitmap-enable",
     "arguments": { "node": "drive0", "name": "bitmap0" } }
<- { "return": {} }

🔴 Command `block-dirty-bitmap-disable` (Since: 4.0)

Disables a dirty bitmap so it stops tracking disk changes. It's giving "going offline, don't @ me" 🙈

Arguments

The members of BlockDirtyBitmap.

Errors

If node is not a valid block device → DeviceNotFound
If name is not found → GenericError

Example:

-> { "execute": "block-dirty-bitmap-disable",
     "arguments": { "node": "drive0", "name": "bitmap0" } }
<- { "return": {} }

🫂 Command `block-dirty-bitmap-merge` (Since: 4.0)

Merge the dirty bitmaps listed in bitmaps into the target dirty bitmap. The bitmaps in bitmaps stay unchanged — except if one of them also shows up as the target bitmap. Any bits already set in target will still be set after the merge, i.e. this operation does not clear the target. And on error, target is unchanged. No messy half-merges here, we don't do that 💅

The resulting bitmap will count as dirty any clusters that were dirty in any of the source bitmaps. You can use this to achieve backup checkpoints, or in simpler usages, to copy bitmaps.

Arguments

The members of BlockDirtyBitmapMerge.

Errors

If node is not a valid block device → DeviceNotFound
If any bitmap in bitmaps or target is not found → GenericError
If any of the bitmaps have different sizes or granularities → GenericError

Example:

-> { "execute": "block-dirty-bitmap-merge",
     "arguments": { "node": "drive0", "target": "bitmap0",
                    "bitmaps": ["bitmap1"] } }
<- { "return": {} }

🔐 Object `BlockDirtyBitmapSha256` (Since: 2.10)

SHA256 hash of dirty bitmap data. Cryptographic realness 🧚

Members

sha256 (string) — ASCII representation of SHA256 bitmap hash

🧪 Command `x-debug-block-dirty-bitmap-sha256` (Since: 2.10)

⚠️ Heads up bestie: this command is unstable/experimental.

Get bitmap SHA256.

Arguments

The members of BlockDirtyBitmap.

Features

unstable — This command is meant for debugging.

Return

BlockDirtyBitmapSha256

Errors

If node is not a valid block device → DeviceNotFound
If name is not found or if hashing has failed → GenericError

🪞 Command `blockdev-mirror` (Since: 2.6)

Start mirroring a block device's writes to a new destination. Copy-paste but make it infrastructure ✨

Arguments

job-id (string, optional) — identifier for the newly-created block job. If you omit it, the device name gets used. (Since 2.7)
device (string) — the device name or node-name of a root node whose writes should be mirrored
target (string) — the id or node-name of the block device to mirror to. This mustn't be attached to guest.
replaces (string, optional) — with sync=full, the graph node name to be replaced by the new image when a whole image copy is done. You can use this to repair broken Quorum files. By default device is replaced, although implicitly created filters on it are kept.
speed (int, optional) — the maximum speed, in bytes per second
sync (MirrorSyncMode) — what parts of the disk image should be copied to the destination (all the disk, only the sectors allocated in the topmost image, or only new I/O)
granularity (int, optional) — granularity of the dirty bitmap. Default is 64K if the image format doesn't have clusters, 4K if the clusters are smaller than that, otherwise the cluster size. And it must be a power of 2 between 512 and 64M — no in-between vibes allowed 🔢
buf-size (int, optional) — the max amount of data that can be in flight from source to target at once 🌀 lowkey the "how much can we yeet at a time" knob
on-source-error (BlockdevOnError, optional) — what we do when the source throws a tantrum; defaults to 'report'. Heads up bestie: 'stop' and 'enospc' only work if the block device actually supports io-status (peep BlockInfo for that) ⚠️
on-target-error (BlockdevOnError, optional) — same vibe but for the target; defaults to 'report' — and no limitations here, since this applies to a different block device than device 💅
filter-node-name (string, optional) — the node name given to the filter driver that the mirror job inserts into the graph above device. Don't pass it and a node name gets autogenerated for you ✨ (Since: 2.9)
copy-mode (MirrorCopyMode, optional) — tells it when to copy data over to the destination; defaults to 'background' 🌙 (Since: 3.0)
auto-finalize (boolean, optional) — set it false and the job just chills in a PENDING state after finishing its work, waiting for job-finalize before it makes any block graph changes. Set it true and it automatically does its abort or commit actions. Defaults to true 🫶 (Since 3.1)
auto-dismiss (boolean, optional) — set it false and the job waits in a CONCLUDED state after it has completely ceased all work, awaiting job-dismiss. Set it true and it automatically disappears with zero user intervention, iconique 😌✨ Defaults to true. (Since 3.1)
target-is-zero (boolean, optional) — assume the destination reads as all zeroes before the mirror started. Setting this true can speed up the mirror 🏎️ BUT — setting it true when the destination is not actually all zero can corrupt the destination 😭 so like, be sure. (Since 10.1)

Example:

-> { "execute": "blockdev-mirror",
     "arguments": { "device": "ide-hd0",
                    "target": "target0",
                    "sync": "full" } }
<- { "return": {} }

🌸 Object BlockIOThrottle (Since: 1.1) 🌸

A whole set of parameters describing block throttling — aka how we tell a device to slow its roll 🐢

Members

device (string, optional) — block device name
id (string, optional) — the name or QOM path of the guest device (since: 2.8)
bps (int) — total throughput limit in bytes per second
bps_rd (int) — read throughput limit in bytes per second
bps_wr (int) — write throughput limit in bytes per second
iops (int) — total I/O operations per second
iops_rd (int) — read I/O operations per second
iops_wr (int) — write I/O operations per second
bps_max (int, optional) — total throughput limit during bursts, in bytes (Since 1.7)
bps_rd_max (int, optional) — read throughput limit during bursts, in bytes (Since 1.7)
bps_wr_max (int, optional) — write throughput limit during bursts, in bytes (Since 1.7)
iops_max (int, optional) — total I/O operations per second during bursts, in bytes (Since 1.7)
iops_rd_max (int, optional) — read I/O operations per second during bursts, in bytes (Since 1.7)
iops_wr_max (int, optional) — write I/O operations per second during bursts, in bytes (Since 1.7)
bps_max_length (int, optional) — max length of the bps_max burst period, in seconds. It must only be set if bps_max is set as well. Defaults to 1. ⏱️ (Since 2.6)
bps_rd_max_length (int, optional) — max length of the bps_rd_max burst period, in seconds. It must only be set if bps_rd_max is set as well. Defaults to 1. (Since 2.6)
bps_wr_max_length (int, optional) — max length of the bps_wr_max burst period, in seconds. It must only be set if bps_wr_max is set as well. Defaults to 1. (Since 2.6)
iops_max_length (int, optional) — max length of the iops burst period, in seconds. It must only be set if iops_max is set as well. Defaults to 1. (Since 2.6)
iops_rd_max_length (int, optional) — max length of the iops_rd_max burst period, in seconds. It must only be set if iops_rd_max is set as well. Defaults to 1. (Since 2.6)
iops_wr_max_length (int, optional) — max length of the iops_wr_max burst period, in seconds. It must only be set if iops_wr_max is set as well. Defaults to 1. (Since 2.6)
iops_size (int, optional) — an I/O size in bytes (Since 1.7)
group (string, optional) — throttle group name (Since 2.4)

Features

deprecated — member device is deprecated. Use id instead. 👀 (yes bestie, the old one's on its way out)

🎀 Object ThrottleLimits (Since: 2.11) 🎀

Limit parameters for throttling. Since some limit combos are illegal, limits should always be set in one transaction — no piecemeal nonsense 🚫. All fields are optional, and when you're setting limits, a missing field means the current value just stays put 🫶

Members

iops-total (int, optional) — limit total I/O operations per second
iops-total-max (int, optional) — I/O operations burst
iops-total-max-length (int, optional) — length of the iops-total-max burst period, in seconds. It must only be set if iops-total-max is set as well.
iops-read (int, optional) — limit read operations per second
iops-read-max (int, optional) — I/O operations read burst
iops-read-max-length (int, optional) — length of the iops-read-max burst period, in seconds. It must only be set if iops-read-max is set as well.
iops-write (int, optional) — limit write operations per second
iops-write-max (int, optional) — I/O operations write burst
iops-write-max-length (int, optional) — length of the iops-write-max burst period, in seconds. It must only be set if iops-write-max is set as well.
bps-total (int, optional) — limit total bytes per second
bps-total-max (int, optional) — total bytes burst
bps-total-max-length (int, optional) — length of the bps-total-max burst period, in seconds. It must only be set if bps-total-max is set as well.
bps-read (int, optional) — limit read bytes per second
bps-read-max (int, optional) — total bytes read burst
bps-read-max-length (int, optional) — length of the bps-read-max burst period, in seconds. It must only be set if bps-read-max is set as well.
bps-write (int, optional) — limit write bytes per second
bps-write-max (int, optional) — total bytes write burst
bps-write-max-length (int, optional) — length of the bps-write-max burst period, in seconds. It must only be set if bps-write-max is set as well.
iops-size (int, optional) — when limiting by iops, max size of an I/O in bytes

💜 Object ThrottleGroupProperties (Since: 2.11) 💜

Properties for throttle-group objects 🧚

Members

limits (ThrottleLimits, optional) — limits to apply for this throttle group
x-iops-total (int, optional) — Not documented
x-iops-total-max (int, optional) — Not documented
x-iops-total-max-length (int, optional) — Not documented
x-iops-read (int, optional) — Not documented
x-iops-read-max (int, optional) — Not documented
x-iops-read-max-length (int, optional) — Not documented
x-iops-write (int, optional) — Not documented
x-iops-write-max (int, optional) — Not documented
x-iops-write-max-length (int, optional) — Not documented
x-bps-total (int, optional) — Not documented
x-bps-total-max (int, optional) — Not documented
x-bps-total-max-length (int, optional) — Not documented
x-bps-read (int, optional) — Not documented
x-bps-read-max (int, optional) — Not documented
x-bps-read-max-length (int, optional) — Not documented
x-bps-write (int, optional) — Not documented
x-bps-write-max (int, optional) — Not documented
x-bps-write-max-length (int, optional) — Not documented
x-iops-size (int, optional) — Not documented

Features

unstable — all members starting with x- are aliases for the same key without x- in the limits object. This is not a stable interface and may be removed or changed incompatibly in the future 😬 use limits for a supported stable interface, bestie, fr fr.

⭐ Command block-stream (Since: 1.1) ⭐

Copy data from a backing file into a block device 💾✨ that's the whole assignment, and it ate.

Okay so the block streaming operation just runs in the background until the entire backing file has been copied over. It doesn't wait around — this command returns immediately once streaming has started. ✨ Wanna peek at how your ongoing block streaming operations are doing? query-block-jobs, bestie. Wanna stop it before it's done? Hit it with job-cancel or block-job-cancel. 💅

The node that receives the data is called the top image — it can live anywhere in the chain (but always above the base image; scroll down, it's explained) and you can point at it using its device or node name. 🎀 Earlier QEMU versions only allowed device to name the top level node; the presence of the base-node parameter during introspection can be used as a witness of the enhanced semantics of device.

If you specify a base file, then sectors are not copied from that base file and its backing chain. This is literally how you stream just a subset of the backing file chain instead of flattening the entire image. 🌸 When streaming completes, the image file will have the base file as its backing file — unless that node was changed while the job was running. In that case, base's parent's backing (or filtered, whichever exists) child (i.e., base at the beginning of the job) will be the new backing file.

On successful completion the image file is updated to drop the backing file and the BLOCK_JOB_COMPLETED event is emitted. 🦋

In case device is a filter node, block-stream modifies the first non-filter overlay node below it to point to the new backing node instead of modifying device itself.

🎀 Arguments 🎀

job-id (string, optional) — identifier for the newly-created block job. If you leave it out, the device name gets used instead. (Since 2.7)
device (string) — the device or node name of the top image.
base (string, optional) — the common backing file name. It cannot be set if base-node or bottom is also set. 🙈
base-node (string, optional) — the node name of the backing file. It cannot be set if base or bottom is also set. (Since 2.8)
bottom (string, optional) — the last node in the chain that should be streamed into top. It cannot be set if base or base-node is also set. It cannot be a filter node. (Since 6.0)
backing-file (string, optional) — the backing file string to write into the top image. This filename is not validated. 🫠

If a pathname string is such that it cannot be resolved by QEMU, that means that subsequent QMP or HMP commands must use node-names for the image in question, as filename lookup methods will fail.

If not specified, QEMU will automatically determine the backing file string to use, or error out if there is no obvious choice. Care should be taken when specifying the string, to specify a valid filename or protocol. (Since 2.1)

backing-mask-protocol (boolean, optional) — if true, replace any protocol mentioned in the 'backing file format' with raw, rather than storing the protocol name as the backing format. Can be used even when no image header will be updated (default false; since 9.0).
speed (int, optional) — the maximum speed, in bytes per second.
on-error (BlockdevOnError, optional) — the action to take on an error (default report). stop and enospc can only be used if the block device supports io-status (see BlockInfo). (Since 1.3)
filter-node-name (string, optional) — the node name that should be assigned to the filter driver that the stream job inserts into the graph above device. If this option is not given, a node name is autogenerated. (Since: 6.0)
auto-finalize (boolean, optional) — when false, this job will wait in a PENDING state after it has finished its work, waiting for job-finalize before making any block graph changes. When true, this job will automatically perform its abort or commit actions. Defaults to true. (Since 3.1)
auto-dismiss (boolean, optional) — when false, this job will wait in a CONCLUDED state after it has completely ceased all work, and awaits job-dismiss. When true, this job will automatically disappear without user intervention. Defaults to true. (Since 3.1)

💀 Errors 💀

If device does not exist, DeviceNotFound.

🌈 Example 🌈

     "arguments": { "device": "virtio0",
                    "base": "/tmp/master.qcow2" } }
<- { "return": {} }

Command `block-job-set-speed` (Since: 1.1) 🔥

Set maximum speed for a background block operation. 🏎️

This command can only be issued when there is an active block job.

Throttling can be disabled by setting the speed to 0.

Arguments 🎀

device (string) — The job identifier. This used to be a device name (hence the name of the parameter), but since QEMU 2.7 it can have other values.
speed (int) — the maximum speed, in bytes per second, or 0 for unlimited. Defaults to 0.

Errors 💀

If no background operation is active on this device, DeviceNotActive.

Command `block-job-cancel` (Since: 1.1) 🔥

Stop an active background block operation. ✋

This command returns immediately after marking the active background block operation for cancellation. It is an error to call this command if no operation is in progress. 🙅

The operation will cancel as soon as possible and then emit the BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when enumerated using query-block-jobs.

Note that if you issue block-job-cancel after drive-mirror has indicated (via the event BLOCK_JOB_READY) that the source and destination are synchronized, then the event triggered by this command changes to BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the destination now has a point-in-time copy tied to the time of the cancellation.

For streaming, the image file retains its backing file unless the streaming operation happens to complete just as it is being cancelled. A new streaming operation can be started at a later time to finish copying all data from the backing file.

Arguments 🎀

device (string) — The job identifier. This used to be a device name (hence the name of the parameter), but since QEMU 2.7 it can have other values.
force (boolean, optional) — If true, and the job has already emitted the event BLOCK_JOB_READY, abandon the job immediately (even if it is paused) instead of waiting for the destination to complete its final synchronization (since 1.3).

Errors 💀

If no background operation is active on this device, DeviceNotActive.

Command `block-job-pause` (Since: 1.3) ⏸️

This command is deprecated. 😭

Pause an active background block operation.

This command returns immediately after marking the active job for pausing. Pausing an already paused job is an error.

The job will pause as soon as possible, which means transitioning into the PAUSED state if it was RUNNING, or into STANDBY if it was READY. The corresponding JOB_STATUS_CHANGE event will be emitted. ✨

Cancelling a paused job automatically resumes it.

Arguments 🎀

device (string) — The job identifier. This used to be a device name (hence the name of the parameter), but since QEMU 2.7 it can have other values.

Features 🌸

deprecated — This command is deprecated. Use job-pause instead.

Errors 💀

If no background operation is active on this device, DeviceNotActive.

Command `block-job-resume` (Since: 1.3) ▶️

This command is deprecated. 😭

Resume an active background block operation.

This command returns immediately after resuming a paused job. Resuming an already running job is an error.

This command also clears the error status of the job. 🧚

Arguments 🎀

device (string) — The job identifier. This used to be a device name (hence the name of the parameter), but since QEMU 2.7 it can have other values.

Features 🌸

deprecated — This command is deprecated. Use job-resume instead.

Errors 💀

If no background operation is active on this device, DeviceNotActive.

Command `block-job-complete` (Since: 1.3) ✅

This command is deprecated. 😭

Manually trigger completion of an active job in the READY or STANDBY state. Completing the job in any other state is an error. 🙈

This is supported only for drive mirroring, where it also switches the device to write to the target path only. Note that drive mirroring includes drive-mirror, blockdev-mirror and block-commit job (only in case of "active commit", when the node being committed is used by the guest). The ability to complete is signaled with a BLOCK_JOB_READY event. 👑

This command wraps up an active background block operation synchronously, bestie. The ordering of this command's return with the BLOCK_JOB_COMPLETED event is not defined, so don't come for it about timing. 👀 Also important: if an I/O error happens while this command is processing — 1) the command itself will fail, and 2) that error gets processed according to the rerror/werror arguments you specified when you started the operation. No cap.

Arguments

device (string) — the job identifier. It used to be a device name (that's why the parameter is literally called that), but since QEMU 2.7 it can have other values too. glow-up 💅

Features

deprecated — this command is deprecated, babe. Use job-complete instead. 🫶

Errors

If no background operation is active on this device → DeviceNotActive

Command `block-job-dismiss` (Since: 2.12)

Heads up: this command is deprecated. 💀

It deletes a job that's in the CONCLUDED state. You only need to run this explicitly for jobs that don't have automatic dismiss enabled. And automatic dismiss can only be enabled for jobs that have the auto-dismiss option — which are drive-backup, blockdev-backup, drive-mirror, blockdev-mirror, block-commit and block-stream. auto-dismiss is enabled by default for those, slay.

This command will refuse to operate on any job that hasn't reached its terminal state, CONCLUDED. So for jobs that use the BLOCK_JOB_READY event, you'll still need job-cancel, block-job-cancel or job-complete as appropriate. Do it right or don't do it at all, honestly.

Arguments

id (string) — the job identifier.

Features

deprecated — this command is deprecated. Use job-dismiss instead. ✨

Command `block-job-finalize` (Since: 2.12)

Deprecated alert 🚨 — this one's deprecated too.

It tells all jobs in a transaction (or a single job if it's not part of any transaction) to finalize any graph changes and do whatever cleanup is necessary. This command requires that all involved jobs are in the PENDING state.

For jobs in a transaction, telling one job to finalize forces ALL jobs in the transaction to finalize — so you only need to instruct a single member job. Teamwork, honestly. 👑

The command is applicable only to jobs which have the auto-finalize option, and only when this option is set to false.

Arguments

id (string) — the job identifier.

Features

deprecated — this command is deprecated. Use job-finalize instead.

Object `BlockJobChangeOptionsMirror` (Since: 8.2)

Members

copy-mode (MirrorCopyMode) — switch to this copy mode. Currently, only the switch from 'background' to 'write-blocking' is implemented. Lowkey a limited menu but okay. 🍓

Object `BlockJobChangeOptions` (Since: 8.2)

Block job options that can be changed after job creation. Post-launch glow-up options, iykyk.

Members

id (string) — the job identifier
type (JobType) — the job type
When type is mirror → the members of BlockJobChangeOptionsMirror. 🌈

Command `block-job-change` (Since: 8.2)

Changes the block job's options. That's it, that's the vibe.

Arguments

The members of BlockJobChangeOptions. 💅

Enum `BlockdevDiscardOptions` (Since: 2.9)

Determines how to handle discard requests.

Values

ignore — ignore the request
unmap — forward as an unmap request

Enum `BlockdevDetectZeroesOptions` (Since: 2.1)

Describes the operation mode for automatically converting plain zero writes from the OS into driver-specific optimized zero write commands. ✨ efficient ✨

Values

off — disabled (default)
on — enabled
unmap — enabled and it'll even try to unmap blocks if possible. This also requires that BlockdevDiscardOptions is set to unmap for this device. 👀

Enum `BlockdevAioOptions` (Since: 2.9)

Picks the AIO backend to handle I/O requests.

Values

threads — use QEMU's thread pool
native — use the native AIO backend (only Linux and Windows)
io_uring — use linux io_uring (since 5.0) 🔥

Object `BlockdevCacheOptions` (Since: 2.9)

Includes cache-related options for block devices. The little cache settings that matter.

Members

direct (boolean, optional) — enables use of O_DIRECT (bypass the host page cache; default: false)
no-flush (boolean, optional) — ignore any flush requests for the device (default: false)

Enum `BlockdevDriver` (Since: 2.9)

Drivers that are supported in block device operations. Big list energy, ngl. 📋

Values

throttle — Since 2.11
nvme — Since 2.12
copy-on-read — Since 3.0
blklogwrites — Since 3.0
blkreplay — Since 4.2
compress — Since 5.0
copy-before-write — Since 6.2
snapshot-access — Since 7.0
blkdebug — Not documented
blkverify — Not documented
bochs — Not documented
cloop — Not documented
dmg — Not documented
file — Not documented
ftp — Not documented
ftps — Not documented
host_cdrom — Not documented
host_device — Not documented
http — Not documented
https — Not documented
io_uring — Not documented
iscsi — Not documented
luks — Not documented
nbd — Not documented
nfs — Not documented
null-aio — Not documented
null-co — Not documented
nvme-io_uring — Not documented
parallels — Not documented
preallocate — Not documented
qcow — Not documented
qcow2 — Not documented
qed — Not documented
quorum — Not documented
raw — Not documented
rbd — Not documented
replication — Not documented
ssh — Not documented
vdi — Not documented
vhdx — Not documented
virtio-blk-vfio-pci — Not documented
virtio-blk-vhost-user — Not documented
virtio-blk-vhost-vdpa — Not documented
vmdk — Not documented
vpc — Not documented
vvfat — Not documented

(Yes we're all "Not documented," it's giving mystery. 🙈)

Object `BlockdevOptionsFile` (Since: 2.9)

Driver-specific block device options for the file backend. The classic. 🎀

Members

filename (string) — path to the image file
pr-manager (string, optional) — the id for the object that will handle persistent reservations for this device (default: none, forward the commands via SG_IO; since 2.11)
aio (BlockdevAioOptions, optional) — AIO backend (default: threads) (since: 2.8)
aio-max-batch (int, optional) — maximum number of requests to batch together into a single submission in the AIO backend. The smallest value between this and the aio-max-batch value of the IOThread object is chosen. 0 means that the AIO backend will handle it automatically. (default: 0, since 6.2)
locking (OnOffAuto, optional) — whether to enable file locking. If set to 'auto', only enable when Open File Descriptor (OFD) locking API is available (default: auto, since 2.10)
drop-cache (boolean, optional) — invalidate page cache during live migration. This prevents stale data on the migration destination with cache.direct=off. Currently only supported on Linux hosts. (default: on, since: 4.0)
x-check-cache-dropped (boolean, optional) — whether to check that page cache was dropped on live migration. May cause noticeable delays if the image file is large, do not use in production. (default: off) (since: 3.0)

That x-check-cache-dropped one is legit a debugging thing — the docs literally say don't use it in production. Respect the warning bestie 😭

Features

dynamic-auto-read-only — if present, enabled auto-read-only means the driver will open the image read-only at first, dynamically reopen the image file read-write when the first writer is attached to the node, and reopen read-only when the last writer is detached. This allows giving QEMU write permissions only on demand when an operation actually needs write access. 💖
unstable — member x-check-cache-dropped is meant for debugging.

Object `BlockdevOptionsNull` (Since: 2.9)

Driver-specific block device options for the null backend. The void. The nothing. Iconic. 🕳️

Members

size (int, optional) — size of the device in bytes.
latency-ns (int, optional) — emulated latency (in nanoseconds) in processing requests. Defaults to zero, which completes requests immediately. (Since 2.4)
read-zeroes (boolean, optional) — if true, reads from the device produce zeroes; if false, the buffer is left unchanged. (default: false; since: 4.1)

Object `BlockdevOptionsNVMe` (Since: 2.12)

Driver-specific block device options for the NVMe backend. Fast storage squad. ⚡

Members

device (string) — PCI controller address of the NVMe device in format hhhh:bb:ss.f (host:bus:slot.function)
namespace (int) — namespace number of the device, starting from 1.

FYI: the PCI device must have been unbound from any host kernel driver before telling QEMU to add the blockdev. Do the unbinding first or it's not gonna slay. 💅

Object BlockdevOptionsVVFAT (Since: 2.9) 💾

okay so these are the driver-specific block device options for the vvfat protocol — yes, the fake-FAT one, she's real ✨

Members

dir (string) — the directory that gets exported as a FAT image 🗂️
fat-type (int, optional) — the FAT type bestie, and it's gotta be 12, 16 or 32
floppy (boolean, optional) — do you want to export a floppy image (true) or a partitioned hard disk (false, and that's the default) 🥏
label (string, optional) — sets the volume label, capped at 11 bytes (ikr). FAT16 and FAT32 traditionally have some restrictions on labels, which most operating systems simply ignore 🙈. Defaults to "QEMU VVFAT". (since 2.4)
rw (boolean, optional) — whether write operations are allowed (default: false) 🔒

Object BlockdevOptionsGenericFormat (Since: 2.9) 📦

driver-specific block device options for image formats that literally have no option besides their data source. minimal queen behavior 💅

Members

file (BlockdevRef) — reference to, or definition of, the data source block device 🔗

Object BlockdevOptionsLUKS (Since: 2.9) 🔐

driver-specific block device options for LUKS. cue the encryption vibes 🌸

Members

key-secret (string, optional) — the ID of a QCryptoSecret object that provides the decryption key. Mandatory except when you're doing a metadata-only probe of the image. (since 2.6)
header (BlockdevRef, optional) — block device holding a detached LUKS header. (since 9.0)
plus the members of BlockdevOptionsGenericFormat ✅

Object BlockdevOptionsGenericCOWFormat (Since: 2.9) 🐄

driver-specific block device options for image formats that have nothing besides their data source and an optional backing file. copy-on-write girlies rise 🫶

Members

backing (BlockdevRefOrNull, optional) — reference to or definition of the backing file block device; null disables the backing file entirely. Defaults to the backing file stored in the image file.
plus the members of BlockdevOptionsGenericFormat ✅

Enum Qcow2OverlapCheckMode (Since: 2.9) 🕵️‍♀️

the general overlap check modes, aka how paranoid are we feeling today

Values

none — do not perform any checks at all, we trust the process 😌
constant — only perform checks that can be done in constant time, and without reading anything from disk
cached — only perform checks that can be done without reading anything from disk
all — perform all available overlap checks, maximum vigilance 👑

Object Qcow2OverlapCheckFlags (Since: 2.9) 🚩

this is the structure of flags for each metadata structure. Setting a field to true makes QEMU guard that Qcow2 format structure against unintended overwriting ✋. Peep the Qcow2 format specification for the detailed tea on these structures. The default value gets chosen according to the template you hand it.

Members

template (Qcow2OverlapCheckMode, optional) — specifies a template mode which you can then adjust with the other flags. Defaults to 'cached' ✨
main-header (boolean, optional) — the Qcow2 format header
active-l1 (boolean, optional) — the Qcow2 active L1 table
active-l2 (boolean, optional) — the Qcow2 active L2 table
refcount-table (boolean, optional) — the Qcow2 refcount table
refcount-block (boolean, optional) — the Qcow2 refcount blocks
snapshot-table (boolean, optional) — the Qcow2 snapshot table
inactive-l1 (boolean, optional) — the Qcow2 inactive L1 tables
inactive-l2 (boolean, optional) — the Qcow2 inactive L2 tables
bitmap-directory (boolean, optional) — the Qcow2 bitmap directory (since 3.0) 🎀

Alternate Qcow2OverlapChecks (Since: 2.9) 🎛️

tells you which metadata structures should be guarded against unintended overwriting. it's giving "choose your fighter".

Alternatives

flags (Qcow2OverlapCheckFlags) — a set of flags so you can separately specify each metadata structure type 🧩
mode (Qcow2OverlapCheckMode) — a named mode that picks a specific set of flags for you, lowkey convenient

Enum BlockdevQcowEncryptionFormat (Since: 2.10) 🔑

Values

aes — AES-CBC with plain64 initialization vectors 🔥

Object BlockdevQcowEncryption (Since: 2.10) 🗝️

Members

format (BlockdevQcowEncryptionFormat) — the encryption format
When format is aes: the members of QCryptoBlockOptionsQCow 🧚

Object BlockdevOptionsQcow (Since: 2.10) 🌷

driver-specific block device options for qcow (the old one, not qcow2, respect her legacy)

Members

encrypt (BlockdevQcowEncryption, optional) — image decryption options. Mandatory for encrypted images, except when you're doing a metadata-only probe of the image.
plus the members of BlockdevOptionsGenericCOWFormat ✅

Enum BlockdevQcow2EncryptionFormat (Since: 2.10) 💜

Values

aes — AES-CBC with plain64 initialization vectors
luks — Not documented 🙈 (yes, that's literally all we get, don't come for me)

Object BlockdevQcow2Encryption (Since: 2.10) 🦋

Members

format (BlockdevQcow2EncryptionFormat) — the encryption format
When format is aes: the members of QCryptoBlockOptionsQCow
When format is luks: the members of QCryptoBlockOptionsLUKS

Object BlockdevOptionsPreallocate (Since: 6.0) 🧚‍♀️

a filter driver whose whole personality is being inserted between the format and protocol node so it can do preallocation in the protocol node on write. main character energy, honestly.

Members

prealloc-align (int, optional) — on preallocation, align the file length to this number. default 1048576 (1M) 📏
prealloc-size (int, optional) — how much to preallocate. default 134217728 (128M) 📦
plus the members of BlockdevOptionsGenericFormat ✅

Object BlockdevOptionsQcow2 (Since: 2.9) 👑

the big one bestie, driver-specific block device options for qcow2. buckle up 💖

Members

lazy-refcounts (boolean, optional) — whether to enable the lazy refcounts feature (the default is taken from the image file) 😴
pass-discard-request (boolean, optional) — whether discard requests to the qcow2 device should be forwarded to the data source 🗑️
pass-discard-snapshot (boolean, optional) — whether discard requests for the data source should be issued when a snapshot operation (like deleting a snapshot) frees clusters in the qcow2 file
pass-discard-other (boolean, optional) — whether discard requests for the data source should be issued on other occasions where a cluster gets freed
discard-no-unref (boolean, optional) — when enabled, data clusters stay preallocated when they're no longer used, e.g. because they were discarded or converted to zero clusters. As per usual, whether the old data is discarded or kept at the protocol level (i.e. in the image file) depends on how pass-discard-request is set. Keeping the clusters preallocated prevents qcow2 fragmentation that freeing and re-allocating them later would otherwise cause. Besides potential performance degradation, that kind of fragmentation can lead to increased allocation of clusters past the end of the image file, resulting in image files whose file length can grow much larger than their guest disk size would suggest 😭. If image file length is a concern (e.g. when storing qcow2 images directly on block devices), you should consider enabling this option. (since 8.1)
overlap-check (Qcow2OverlapChecks, optional) — which overlap checks to perform for writes to the image. defaults to 'cached' (since 2.2)
cache-size (int, optional) — the maximum total size of the L2 table and refcount block caches, in bytes (since 2.2)
l2-cache-size (int, optional) — the maximum size of the L2 table cache, in bytes (since 2.2)
l2-cache-entry-size (int, optional) — the size of each entry in the L2 cache, in bytes. It must be a power of two between 512 and the cluster size. The default value is the cluster size. (since 2.12)
refcount-cache-size (int, optional) — the maximum size of the refcount block cache, in bytes (since 2.2)
cache-clean-interval (int, optional) — cleans unused entries in the L2 and refcount caches. The interval is in seconds. The default value is 600 on supporting platforms, and 0 on other platforms. 0 disables this feature. (since 2.5)
encrypt (BlockdevQcow2Encryption, optional) — image decryption options. Mandatory for encrypted images, except when doing a metadata-only probe of the image. (since 2.10)
data-file (BlockdevRef, optional) — reference to, or definition of, the external data file. This may only be specified for images that require an external data file. If it's not specified for such an image, the data file name is loaded from the image file. (since 4.0)
plus the members of BlockdevOptionsGenericCOWFormat ✅

Enum SshHostKeyCheckMode (Since: 2.12) 🔐

Values

none — don't check the host key at all, living dangerously 😎
hash — compare the host key with a given hash
known_hosts — check the host key against the known_hosts file 📁

Enum SshHostKeyCheckHashType (Since: 2.12) #

Values

md5 — the given hash is an md5 hash 🧮
sha1 — the hash you're handing over is an sha1 hash ✨
sha256 — and this one's an sha256 hash, no cap 💅

🦋 Object SshHostKeyHash (Since: 2.12) 🦋

the little pair of fields that describe what hash you're expecting, bestie.

Members

type (SshHostKeyCheckHashType) — which hash algorithm got used for that hash 🌸
hash (string) — the actual expected hash value 🎀

🫶 Object SshHostKeyCheck (Since: 2.12) 🫶

how we're gonna check the host key, periodt.

Members

mode (SshHostKeyCheckMode) — how to check the host key 👀
when mode is hash: you also get all the members of SshHostKeyHash riding along 💖

✨ Object BlockdevOptionsSsh (Since: 2.9) ✨

everything you need to point a block device at an image sitting on an ssh server.

Members

server (InetSocketAddress) — the host address 🖥️
path (string) — path to the image on the host 🗺️
user (string, optional) — the user to connect as; defaults to your current local user name 🙋
host-key-check (SshHostKeyCheck, optional) — says how and what to check the host key against (default: known_hosts) 🔐

💀 Enum BlkdebugEvent (Since: 2.9) 💀

the trigger events that blkdebug supports — like, this is the whole menu of stuff it can trip on.

Values

l1_shrink_write_table — write zeros to the l1 table to shrink the image (since 2.11)
l1_shrink_free_l2_clusters — discard the l2 tables (since 2.11)
cor_write — a write that happens because of copy-on-read (since 2.11)
cluster_alloc_space — allocating file space for a cluster (since 4.1)
none — triggers exactly once, at the creation of the blkdebug node (since 4.1)
l1_update — Not documented 🙈
l1_grow_alloc_table — Not documented 😭
l1_grow_write_table — Not documented 🫠
l1_grow_activate_table — Not documented 💀
l2_load — Not documented 🌸
l2_update — Not documented 🎀
l2_update_compressed — Not documented ✨
l2_alloc_cow_read — Not documented 🦋
l2_alloc_write — Not documented 💅
read_aio — Not documented 📖
read_backing_aio — Not documented 📚
read_compressed — Not documented 🗜️
write_aio — Not documented ✍️
write_compressed — Not documented 🗜️
vmstate_load — Not documented 💾
vmstate_save — Not documented 💾
cow_read — Not documented 🐄
cow_write — Not documented 🐄
reftable_load — Not documented 📋
reftable_grow — Not documented 📋
reftable_update — Not documented 📋
refblock_load — Not documented 🧱
refblock_update — Not documented 🧱
refblock_update_part — Not documented 🧱
refblock_alloc — Not documented 🧱
refblock_alloc_hookup — Not documented 🧱
refblock_alloc_write — Not documented 🧱
refblock_alloc_write_blocks — Not documented 🧱
refblock_alloc_write_table — Not documented 🧱
refblock_alloc_switch_table — Not documented 🧱
cluster_alloc — Not documented 🧩
cluster_alloc_bytes — Not documented 🧩
cluster_free — Not documented 🧩
flush_to_os — Not documented 🚽
flush_to_disk — Not documented 🚽
pwritev_rmw_head — Not documented 🔁
pwritev_rmw_after_head — Not documented 🔁
pwritev_rmw_tail — Not documented 🔁
pwritev_rmw_after_tail — Not documented 🔁
pwritev — Not documented 📝
pwritev_zero — Not documented 0️⃣
pwritev_done — Not documented ✅
empty_image_prepare — Not documented 🫙

ok real talk: that's a lot of "Not documented" and I'm not gonna pretend otherwise 😭 the manpage genuinely just says that for each one — I'm not hiding lore from you, bestie, there just isn't any here.

👑 Enum BlkdebugIOType (Since: 4.1) 👑

the kinds of I/O that blkdebug is allowed to inject errors into. iconic little list honestly.

Values

read — .bdrv_co_preadv()
write — .bdrv_co_pwritev()
write-zeroes — .bdrv_co_pwrite_zeroes()
discard — .bdrv_co_pdiscard()
flush — .bdrv_co_flush_to_disk()
block-status — .bdrv_co_block_status()

🌈 Object BlkdebugInjectErrorOptions (Since: 2.9) 🌈

describes one single error injection for blkdebug. one. singular. 💅

Members

event (BlkdebugEvent) — the trigger event 🔔
state (int, optional) — the state identifier blkdebug needs to be in for the event to actually trigger; defaults to "any" 🎯
iotype (BlkdebugIOType, optional) — which type of I/O operation this error gets injected on; defaults to "all read, write, write-zeroes, discard, and flush operations" (since: 4.1) 🌀
errno (int, optional) — the error identifier (errno) to return; defaults to EIO 😱
delay-ns (int, optional) — request delay before completion, in nanoseconds (default: 0, since: 11.1) ⏳
sector (int, optional) — which sector index has to be affected for the event to actually trigger; defaults to "any sector" 🎯
once (boolean, optional) — kills further events after this one fires; defaults to false 1️⃣
immediately (boolean, optional) — fail immediately; defaults to false ⚡

🍓 Object BlkdebugSetStateOptions (Since: 2.9) 🍓

describes one single state-change event for blkdebug — the glow-up moment where blkdebug switches states ✨

Members

event (BlkdebugEvent) — the trigger event 🔔
state (int, optional) — the current state identifier blkdebug needs to be in; defaults to "any" 🎯
new_state (int) — the state identifier blkdebug is supposed to assume if this event gets triggered 🔄

🧚 Object BlockdevOptionsBlkdebug (Since: 2.9) 🧚

driver-specific block device options for blkdebug. it's giving very detailed, very extra, we love her.

Members

image (BlockdevRef) — the underlying raw block device (or image file) 🖼️
config (string, optional) — filename of the configuration file 📄
align (int, optional) — required alignment for requests in bytes; must be a positive power of 2, or 0 for default 📐
max-transfer (int, optional) — maximum size for I/O transfers in bytes; must be a positive multiple of align and of the underlying file's request alignment (but doesn't need to be a power of 2), or 0 for default (since 2.10) 📦
opt-write-zero (int, optional) — preferred alignment for write-zero requests in bytes; must be a positive multiple of align and of the underlying file's request alignment (but doesn't need to be a power of 2), or 0 for default (since 2.10) 0️⃣
max-write-zero (int, optional) — maximum size for write-zero requests in bytes; must be a positive multiple of align, of opt-write-zero, and of the underlying file's request alignment (but doesn't need to be a power of 2), or 0 for default (since 2.10) 📦
opt-discard (int, optional) — preferred alignment for discard requests in bytes; must be a positive multiple of align and of the underlying file's request alignment (but doesn't need to be a power of 2), or 0 for default (since 2.10) 🗑️
max-discard (int, optional) — maximum size for discard requests in bytes; must be a positive multiple of align, of opt-discard, and of the underlying file's request alignment (but doesn't need to be a power of 2), or 0 for default (since 2.10) 📦
inject-error ([BlkdebugInjectErrorOptions], optional) — array of error injection descriptions 💥
set-state ([BlkdebugSetStateOptions], optional) — array of state-change descriptions 🔄
take-child-perms ([BlockPermission], optional) — permissions to take on image on top of whatever's necessary anyway (which depends on how the blkdebug node gets used); defaults to none (since 5.0) 🔑
unshare-child-perms ([BlockPermission], optional) — permissions not to share on image on top of whatever can't be shared anyway (which depends on how the blkdebug node gets used); defaults to none (since 5.0) 🚫

🎀 Object BlockdevOptionsBlklogwrites (Since: 3.0) 🎀

driver-specific block device options for blklogwrites — logging every write like it's keeping a diary 📔

Members

file (BlockdevRef) — block device 💾
log (BlockdevRef) — block device used to log writes to file 📝
log-sector-size (int, optional) — sector size used when logging writes to file; determines the granularity of offsets and sizes of writes (default: 512) 📏
log-append (boolean, optional) — append to an existing log (default: false) ➕
log-super-update-interval (int, optional) — how many write requests go by before the log super block gets updated to disk (default: 4096) 🔄

💜 Object BlockdevOptionsBlkverify (Since: 2.9) 💜

driver-specific block device options for blkverify — the "but did you double check tho" driver.

Members

test (BlockdevRef) — the block device to be tested 🧪
raw (BlockdevRef) — raw image used for verification ✅

⭐ Object BlockdevOptionsBlkreplay (Since: 4.2) ⭐

driver-specific block device options for blkreplay — replay era, let's go 🎬

Members

image (BlockdevRef) — the disk image that should be controlled with blkreplay 🖼️

🦋 Enum QuorumReadPattern (Since: 2.9) 🦋

a whole enumeration of quorum read patterns, because of course there's more than one way to read 👀

Values

quorum — read all the children and do a quorum vote on the reads 🗳️
fifo — read only from the first child that hasn't failed 🥇

🌸 Object BlockdevOptionsQuorum (Since: 2.9) 🌸

driver-specific block device options for Quorum — yes she has her own options object and yes she's a main character.

Members

and the members list is right up next, bestie — keep scrolling 💖

blkverify (boolean, optional) — true if the driver has to print a content mismatch. Defaults to false, bestie. 🫶
children ([BlockdevRef]) — the child block devices to use. they're like the quorum's little minions ✨
vote-threshold (int) — the vote limit; go under it and a read just fails. democracy but make it storage 💅
rewrite-corrupted (boolean, optional) — rewrite corrupted data when quorum is reached (Since 2.1) 🔥
read-pattern (QuorumReadPattern, optional) — picks the read pattern, defaults to quorum (Since 2.2)

🦋 Object `BlockdevOptionsIoUring` (Since: 7.2)

Availability: CONFIG_BLKIO

Driver-specific block device options for the io_uring backend. fancy modern kernel vibes, no cap.

Members

filename (string) — path to the image file

🦋 Object `BlockdevOptionsNvmeIoUring` (Since: 7.2)

Availability: CONFIG_BLKIO

Driver-specific block device options for the nvme-io_uring backend.

Members

path (string) — path to the NVMe namespace's character device (e.g. /dev/ng0n1).

🦋 Object `BlockdevOptionsVirtioBlkVfioPci` (Since: 7.2)

Availability: CONFIG_BLKIO

Driver-specific block device options for the virtio-blk-vfio-pci backend.

Members

path (string) — path to the PCI device's sysfs directory (e.g. /sys/bus/pci/devices/0000:00:01.0).

🦋 Object `BlockdevOptionsVirtioBlkVhostUser` (Since: 7.2)

Availability: CONFIG_BLKIO

Driver-specific block device options for the virtio-blk-vhost-user backend.

Members

path (string) — path to the vhost-user UNIX domain socket.

🦋 Object `BlockdevOptionsVirtioBlkVhostVdpa` (Since: 7.2)

Availability: CONFIG_BLKIO

Driver-specific block device options for the virtio-blk-vhost-vdpa backend.

Members

path (string) — path to the vhost-vdpa character device.

Features

fdset — the path member supports the special "/dev/fdset/N" path (since 8.1) 👑

🌈 Enum `IscsiTransport` (Since: 2.9)

An enumeration of libiscsi transport types. it's giving options.

Values

tcp — Not documented 🙈
iser — Not documented 🙈

🌈 Enum `IscsiHeaderDigest` (Since: 2.9)

An enumeration of header digests supported by libiscsi.

Values

crc32c — Not documented 🙈
none — Not documented 🙈
crc32c-none — Not documented 🙈
none-crc32c — Not documented 🙈

🎀 Object `BlockdevOptionsIscsi` (Since: 2.9)

Driver-specific block device options for iscsi. iSCSI bestie, the classic.

Members

transport (IscsiTransport) — the iscsi transport type
portal (string) — the address of the iscsi portal
target (string) — the target iqn name
lun (int, optional) — LUN to connect to. Defaults to 0.
user (string, optional) — user name to log in with. If omitted, no CHAP authentication is performed.
password-secret (string, optional) — the ID of a QCryptoSecret object providing the password for the login. This option is required if user is specified. ⚠️ like, actually required, not a suggestion
initiator-name (string, optional) — the iqn name we want to identify to the target as. If this option is not specified, an initiator name is generated automatically. it just spawns one, iconic
header-digest (IscsiHeaderDigest, optional) — the desired header digest. Defaults to none-crc32c.
timeout (int, optional) — timeout in seconds after which a request will timeout. 0 means no timeout and is the default. (so patient, love that for it)

🌈 Enum `RbdAuthMode` (Since: 3.0)

Values

cephx — Not documented 🙈
none — Not documented 🙈

🌈 Enum `RbdImageEncryptionFormat` (Since: 6.1)

Values

luks-any — used for opening either luks or luks2 (Since 8.0)
luks — Not documented 🙈
luks2 — Not documented 🙈

🧚 Object `RbdEncryptionOptionsLUKSBase` (Since: 6.1)

Members

key-secret (string) — ID of a QCryptoSecret object providing a passphrase for unlocking the encryption 🔐

🧚 Object `RbdEncryptionCreateOptionsLUKSBase` (Since: 6.1)

Members

cipher-alg (QCryptoCipherAlgo, optional) — the encryption algorithm
the members of RbdEncryptionOptionsLUKSBase. (inheritance slay ✨)

🧚 Object `RbdEncryptionOptionsLUKS` (Since: 6.1)

Members

the members of RbdEncryptionOptionsLUKSBase.

🧚 Object `RbdEncryptionOptionsLUKS2` (Since: 6.1)

Members

the members of RbdEncryptionOptionsLUKSBase.

🧚 Object `RbdEncryptionOptionsLUKSAny` (Since: 8.0)

Members

the members of RbdEncryptionOptionsLUKSBase.

🧚 Object `RbdEncryptionCreateOptionsLUKS` (Since: 6.1)

Members

the members of RbdEncryptionCreateOptionsLUKSBase.

🧚 Object `RbdEncryptionCreateOptionsLUKS2` (Since: 6.1)

Members

the members of RbdEncryptionCreateOptionsLUKSBase.

🧚 Object `RbdEncryptionOptions` (Since: 6.1)

Members

format (RbdImageEncryptionFormat) — encryption format.
parent (RbdEncryptionOptions, optional) — parent image encryption options (for cloned images). Can be left unspecified if this cloned image is encrypted using the same format and secret as its parent image (i.e. not explicitly formatted) or if its parent image is not encrypted. (Since 8.0) (passing the vibe down the family tree 🫶)
when format is luks: the members of RbdEncryptionOptionsLUKS.
when format is luks2: the members of RbdEncryptionOptionsLUKS2.
when format is luks-any: the members of RbdEncryptionOptionsLUKSAny.

🧚 Object `RbdEncryptionCreateOptions` (Since: 6.1)

Members

format (RbdImageEncryptionFormat) — encryption format.
when format is luks: the members of RbdEncryptionCreateOptionsLUKS.
when format is luks2: the members of RbdEncryptionCreateOptionsLUKS2.

💜 Object `BlockdevOptionsRbd` (Since: 2.9)

Members

pool (string) — Ceph pool name.
namespace (string, optional) — Rados namespace name in the Ceph pool. (Since 5.0)
image (string) — image name in the Ceph pool.
conf (string, optional) — path to Ceph configuration file. Values in the configuration file will be overridden by options specified via QAPI. (QAPI wins, periodt 💅)
snapshot (string, optional) — Ceph snapshot name.
encrypt (RbdEncryptionOptions, optional) — image encryption options. (Since 6.1) 🔐
user (string, optional) — Ceph id name.
auth-client-required ([RbdAuthMode], optional) — acceptable authentication modes. This maps to Ceph configuration option "auth_client_required". (Since 3.0)
key-secret (string, optional) — ID of a QCryptoSecret object providing a key for cephx authentication. This maps to Ceph configuration option "key". (Since 3.0)
server ([InetSocketAddressBase], optional) — monitor host address and port. This maps to the "mon_host" Ceph option.

🌸 Enum `ReplicationMode` (Since: 2.9)

Availability: CONFIG_REPLICATION

An enumeration of replication modes. it's giving "there can only be one primary".

Values

primary — primary mode, the vm's state will be sent to secondary QEMU. you're the main character 👑
secondary — secondary mode, receive the vm's state from primary QEMU. supporting role but make it essential 💖

🌸 Object `BlockdevOptionsReplication` (Since: 2.9)

Availability: CONFIG_REPLICATION

Driver-specific block device options for replication.

Members

mode (ReplicationMode) — the replication mode
top-id (string, optional) — in secondary mode, node name or device ID of the root node who owns the replication node chain. Must not be given in primary mode. 🚫 (like, do NOT, fr fr)
the members of BlockdevOptionsGenericFormat.

🍓 Enum `NFSTransport` (Since: 2.9)

An enumeration of NFS transport types.

Values

inet — TCP transport

🍓 Object `NFSServer` (Since: 2.9)

Captures the address of the socket.

Members

type (NFSTransport) — transport type used for NFS (only TCP supported) (just the one option, and that's valid bestie)
host (string) — host address for NFS server

🍓 Object `BlockdevOptionsNfs` (Since: 2.9)

Driver-specific block device option for NFS. the O.G. network filesystem ✨

Members

server (NFSServer) — host address
path (string) — path of the image on the host
user (int, optional) — UID value to use when talking to the server (defaults to 65534 on Windows and getuid() on unix)
group (int, optional) — GID value to use when talking to the server (defaults to 65534 on Windows and getgid() in unix)
tcp-syn-count (int, optional) — number of SYNs during the session establishment (defaults to libnfs default)
readahead-size (int, optional) — set the readahead size in bytes (defaults to libnfs default)
page-cache-size (int, optional) — set the pagecache size in bytes (defaults to libnfs default)
debug (int, optional) — set the NFS debug level (max 2) (defaults to libnfs default)

⭐ Object `BlockdevOptionsCurlBase` (Since: 2.9)

Driver-specific block device options shared by all protocols supported by the curl backend. one base class to rule them all 🫶

Members

url (string) — the URL of the image file ✨
readahead (int, optional) — size of the read-ahead cache; must be a multiple of 512 (defaults to 256 kB)
timeout (int, optional) — timeout for connections, in seconds (defaults to 5)
username (string, optional) — username for authentication (defaults to none)
password-secret (string, optional) — ID of a QCryptoSecret object providing a password for authentication (defaults to no password)
proxy-username (string, optional) — username for proxy authentication (defaults to none)
proxy-password-secret (string, optional) — ID of a QCryptoSecret object providing a password for proxy authentication (defaults to no password)

🌐 Object `BlockdevOptionsCurlHttp` (Since: 2.9)

Driver-specific block device options for HTTP connections running over the curl backend. URLs have to start with "<http://>".

Members

cookie (string, optional) — list of cookies to set; the format is "name1=content1; name2=content2;" exactly as explained by CURLOPT_COOKIE(3). Defaults to no cookies 🍪
cookie-secret (string, optional) — ID of a QCryptoSecret object that hands over the cookie data in a secure way. Peep cookie for the format. (since 2.10)
force-range (boolean, optional) — don't fire off a HEAD HTTP request to go find out whether the http server supports range requests, just trust GET requests only. This is especially useful for S3 presigned URLs where HEAD requests are unauthorized, iykyk. (default: false; since 11.0)
the members of BlockdevOptionsCurlBase, obviously 💅

🔒 Object `BlockdevOptionsCurlHttps` (Since: 2.9)

Driver-specific block device options for HTTPS connections over the curl backend. URLs have to start with "<https://>".

Members

sslverify (boolean, optional) — whether to verify that the SSL certificate is actually valid (defaults to true)
the members of BlockdevOptionsCurlHttp

📁 Object `BlockdevOptionsCurlFtp` (Since: 2.9)

Driver-specific block device options for FTP connections over the curl backend. URLs have to start with "<ftp://>".

Members

the members of BlockdevOptionsCurlBase

🔐 Object `BlockdevOptionsCurlFtps` (Since: 2.9)

Driver-specific block device options for FTPS connections over the curl backend. URLs have to start with "ftps://".

Members

sslverify (boolean, optional) — whether to verify that the SSL certificate is valid (defaults to true)
the members of BlockdevOptionsCurlBase

🦋 Object `BlockdevOptionsNbd` (Since: 2.9)

Driver-specific block device options for NBD, bestie.

Members

server (SocketAddress) — the NBD server address
export (string, optional) — export name
tls-creds (string, optional) — TLS credentials ID
tls-hostname (string, optional) — TLS hostname override, for certificate validation (Since 7.0)
x-dirty-bitmap (string, optional) — a metadata context name like "qemu:dirty-bitmap:NAME" or "qemu:allocation-depth" to query in place of the traditional "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and yes, naming this option x-context would have made way more sense 🙈) (since 3.0)
reconnect-delay (int, optional) — when the connection drops unexpectedly, the nbd client keeps trying to connect again until it succeeds or hits a serious error. For the first reconnect-delay seconds, all requests are paused and get rerun after a successful reconnect. After that window, any delayed requests — plus all future requests made before a successful reconnect — immediately fail. Default 0 (Since 4.2)
open-timeout (int, optional) — in seconds. If it's zero, the nbd driver tries the connection exactly once and just fails to open if the connection fails. If it's non-zero, the nbd driver keeps repeating connection attempts until it succeeds or until open-timeout seconds have gone by. Default 0 (Since 7.0)

Features

unstable — member x-dirty-bitmap is experimental ⚠️

🪞 Object `BlockdevOptionsRaw` (Since: 2.9)

Driver-specific block device options for the raw driver.

Members

offset (int, optional) — position where the block device starts
size (int, optional) — the assumed size of the device
the members of BlockdevOptionsGenericFormat

🚦 Object `BlockdevOptionsThrottle` (Since: 2.11)

Driver-specific block device options for the throttle driver.

Members

throttle-group (string) — the name of the throttle-group object to use. It has to already exist, no creating it on the fly.
file (BlockdevRef) — reference to, or definition of, the data source block device

📖 Object `BlockdevOptionsCor` (Since: 6.0)

Driver-specific block device options for the copy-on-read driver.

Members

bottom (string, optional) — the name of a non-filter node (allocation-bearing layer) that caps the COR operations in the backing chain (inclusive), so that nothing below this node ever gets copied by this filter. Leave the option out and there's no limit at all, so data from every backing layer can get copied.
the members of BlockdevOptionsGenericFormat

💀 Enum `OnCbwError` (Since: 7.1)

A whole enum of possible behaviors for when copy-before-write operations fail 😭

Values

break-guest-write — report the error to the guest. That way the guest can't overwrite areas that can't be backed up, so the backup process stays valid. Lowkey the safe one.
break-snapshot — carry on with the guest write. Doing this makes the snapshot state you provided invalid, and any backup or export process built on top of it will ultimately fail. Not the vibe.

🎀 Object `BlockdevOptionsCbw` (Since: 6.2)

Driver-specific block device options for the copy-before-write driver, which does the so-called copy-before-write operations: when data gets written to the filter, the filter first reads the corresponding blocks from its file child and copies them over to the target child. Once that copy succeeds, the write request gets propagated to the file child. If the copying fails, the original write request fails too and no data is written to the file child. Periodt.

Members

target (BlockdevRef) — the target for copy-before-write operations.
bitmap (BlockDirtyBitmap, optional) — if you specify it, the copy-before-write filter only does copy-before-write operations for the dirty regions of that bitmap. The bitmap size must equal the length of the file and target children of the filter. Also note: the bitmap is only used to initialize the internal bitmap of the process, so further modifications to (or removal of) the specified bitmap doesn't influence the filter. (Since 7.0)
on-cbw-error (OnCbwError, optional) — behavior when a copy-before-write operation fails. Default is break-guest-write. (Since 7.1)
cbw-timeout (int, optional) — zero means no limit. Non-zero sets the timeout in seconds for the copy-before-write operation. When a timeout hits, that particular copy-before-write operation fails, and the on-cbw-error parameter decides how that failure gets handled. Default 0. (Since 7.1)
min-cluster-size (int, optional) — minimum size of the blocks used by copy-before-write operations. Has to be a power of 2. No effect if it's smaller than the max of the target's cluster size and 64 KiB. Default 0. (Since 9.2)
the members of BlockdevOptionsGenericFormat

👑 Object `BlockdevOptions` (Since: 2.9)

Options for creating a block device. Tons of options are available for all block devices, no matter which block driver you're on:

Members

driver (BlockdevDriver) — block driver name
node-name (string, optional) — the node name of the new node. This option is required on the top level of blockdev-add. Valid node names start with an alphabetic character and may contain only alphanumeric characters, '-', '.' and '_'. Their maximum length is 31 characters. (Since 2.0)
discard (BlockdevDiscardOptions, optional) — discard-related options (default: ignore)
cache (BlockdevCacheOptions, optional) — cache-related options
active (boolean, optional) — whether the block node should be activated (default: true). Having inactive block nodes is useful primarily for migration, because it lets you open an image on the destination while the source is still holding locks on it. (Since 10.0)
read-only (boolean, optional) — whether the block device should be read-only (default: false). Heads up: some block drivers support only read-only access, either generally or in certain configurations. In that case the default value doesn't work and you must specify the option explicitly 🫶
auto-read-only (boolean, optional) — okay so if this is true and read-only is false, QEMU is allowed to be like "hmm, actually bestie, I'm not gonna open this image read-write like you asked" and lowkey fall back to read-only instead (and it can flip between the two modes later). When does it decide? Depends on stuff like whether the image file is even writable, or whether a writing user is attached to the node. Default is false, since 3.1. 🫶
detect-zeroes (BlockdevDetectZeroesOptions, optional) — detects and optimizes zero writes, since 2.1. Default is off. ✨
force-share (boolean, optional) — forces sharing of all permissions on added nodes. Requires read-only=true. Since 2.10. No cap, just read that caveat again. 👑
When driver is blkdebug: the members of BlockdevOptionsBlkdebug.
When driver is blklogwrites: the members of BlockdevOptionsBlklogwrites.
When driver is blkverify: the members of BlockdevOptionsBlkverify.
When driver is blkreplay: the members of BlockdevOptionsBlkreplay.
When driver is bochs: the members of BlockdevOptionsGenericFormat.
When driver is cloop: the members of BlockdevOptionsGenericFormat.
When driver is compress: the members of BlockdevOptionsGenericFormat.
When driver is copy-before-write: the members of BlockdevOptionsCbw.
When driver is copy-on-read: the members of BlockdevOptionsCor.
When driver is dmg: the members of BlockdevOptionsGenericFormat.
When driver is file: the members of BlockdevOptionsFile.
When driver is ftp: the members of BlockdevOptionsCurlFtp.
When driver is ftps: the members of BlockdevOptionsCurlFtps.
When driver is host_cdrom: the members of BlockdevOptionsFile.
When driver is host_device: the members of BlockdevOptionsFile.
When driver is http: the members of BlockdevOptionsCurlHttp.
When driver is https: the members of BlockdevOptionsCurlHttps.
When driver is io_uring: the members of BlockdevOptionsIoUring.
When driver is iscsi: the members of BlockdevOptionsIscsi.
When driver is luks: the members of BlockdevOptionsLUKS.
When driver is nbd: the members of BlockdevOptionsNbd.
When driver is nfs: the members of BlockdevOptionsNfs.
When driver is null-aio: the members of BlockdevOptionsNull.
When driver is null-co: the members of BlockdevOptionsNull.
When driver is nvme: the members of BlockdevOptionsNVMe.
When driver is nvme-io_uring: the members of BlockdevOptionsNvmeIoUring.
When driver is parallels: the members of BlockdevOptionsGenericFormat.
When driver is preallocate: the members of BlockdevOptionsPreallocate.
When driver is qcow2: the members of BlockdevOptionsQcow2.
When driver is qcow: the members of BlockdevOptionsQcow.
When driver is qed: the members of BlockdevOptionsGenericCOWFormat.
When driver is quorum: the members of BlockdevOptionsQuorum.
When driver is raw: the members of BlockdevOptionsRaw.
When driver is rbd: the members of BlockdevOptionsRbd.
When driver is replication: the members of BlockdevOptionsReplication.
When driver is snapshot-access: the members of BlockdevOptionsGenericFormat.
When driver is ssh: the members of BlockdevOptionsSsh.
When driver is throttle: the members of BlockdevOptionsThrottle.
When driver is vdi: the members of BlockdevOptionsGenericFormat.
When driver is vhdx: the members of BlockdevOptionsGenericFormat.
When driver is virtio-blk-vfio-pci: the members of BlockdevOptionsVirtioBlkVfioPci.
When driver is virtio-blk-vhost-user: the members of BlockdevOptionsVirtioBlkVhostUser.
When driver is virtio-blk-vhost-vdpa: the members of BlockdevOptionsVirtioBlkVhostVdpa.
When driver is vmdk: the members of BlockdevOptionsGenericCOWFormat.
When driver is vpc: the members of BlockdevOptionsGenericFormat.
When driver is vvfat: the members of BlockdevOptionsVVFAT.

💅 Alternate `BlockdevRef` (Since: 2.9)

Reference to a block device. It's an either/or situation, bestie.

Alternatives

definition (BlockdevOptions) — defines a new block device inline. ✨
reference (string) — references the ID of an existing block device.

🦋 Alternate `BlockdevRefOrNull` (Since: 2.9)

Reference to a block device — but now with a null option, because glow-ups happen.

Alternatives

definition (BlockdevOptions) — defines a new block device inline.
reference (string) — references the ID of an existing block device. An empty string means that no block device should be referenced. Deprecated; use null instead. 💀
null (null) — no block device should be referenced, since 2.10.

🎀 Command `blockdev-add` (Since: 2.9)

Creates a brand-new block device. Iconic behavior.

Arguments

The members of BlockdevOptions.

Example:

-> { "execute": "blockdev-add",
     "arguments": {
          "driver": "qcow2",
          "node-name": "test1",
          "file": {
              "driver": "file",
              "filename": "test.qcow2"
           }
      }
    }
<- { "return": {} }

Example:

-> { "execute": "blockdev-add",
     "arguments": {
          "driver": "qcow2",
          "node-name": "node0",
          "discard": "unmap",
          "cache": {
             "direct": true
           },
           "file": {
             "driver": "file",
             "filename": "/tmp/test.qcow2"
           },
           "backing": {
              "driver": "raw",
              "file": {
                 "driver": "file",
                 "filename": "/dev/fdset/4"
               }
           }
       }
     }

<- { "return": {} }

🔥 Command `blockdev-reopen` (Since: 6.1)

Reopens one or more block devices using the given set of options. Fr fr, listen closely: any option not specified will be reset to its default value, regardless of what it was before. So if you forget something, it's going back to default, no cap.

If an option can't be changed, or a particular driver doesn't support reopening, the command returns an error. All the devices in the list get reopened in one single transaction, so if one of them fails, the whole transaction is cancelled. It's giving all-or-nothing. 😭

The command receives a list of block devices to reopen. For each one, the top-level node-name option (from BlockdevOptions) must be specified, and it's used to select the block device to be reopened. Other node-name options must be either omitted or set to the current name of the appropriate node. This command won't change any node name, and any attempt to do that will result in an error. Don't try it. 🙈

In the case of options that refer to child nodes, the behavior depends on the value:

A set of options (BlockdevOptions): the child is reopened with the specified set of options.
A reference to the current child: the child is reopened using its existing set of options.
A reference to a different node: the current child is replaced with the specified one.
null: the current child (if any) is detached.

Options (1) and (2) are supported in all cases. Option (3) is supported for file and backing, and option (4) for backing only. ⭐

Unlike with blockdev-add, the backing option must always be present — unless the node being reopened doesn't have a backing file and its image doesn't have a default backing file name as part of its metadata. Read that twice. 💜

Arguments

options ([BlockdevOptions]) — Not documented.

🌸 Command `blockdev-del` (Since: 2.9)

Deletes a block device that's been added using blockdev-add. The command will fail if the node is attached to a device or is otherwise being used. So bestie, clean up your attachments first. 💅

Arguments

node-name (string) — Name of the graph node to delete.

Example:

-> { "execute": "blockdev-add",
     "arguments": {
          "driver": "qcow2",
          "node-name": "node0",
          "file": {
              "driver": "file",
              "filename": "test.qcow2"
          }
     }
   }
<- { "return": {} }

-> { "execute": "blockdev-del",
     "arguments": { "node-name": "node0" }
   }
<- { "return": {} }

👑 Command `blockdev-set-active` (Since: 10.0)

Activate or deactivate a block device. Use this to manage the handover of block devices on migration with qemu-storage-daemon. Main character energy for your migration era. 🌈

...okay so here's the tea: when you activate a node, it auto-activates all of its child nodes first, like it's pulling its whole friend group into the plans 💅. And when you deactivate a node, it auto-deactivates any of its child nodes that aren't still being used by a node that's still active. No orphan vibes left behind, periodt.

Arguments 🌸

node-name (string, optional) — the name of the graph node you wanna activate or deactivate. Leave it out and every single node gets hit by the operation, no cap.
active (boolean) — true means the nodes should be active when the command comes back a success, false means they should be inactive. Simple as that bestie.

Example ✨

-> { "execute": "blockdev-set-active",
     "arguments": {
          "node-name": "node0",
          "active": false
     }
   }
<- { "return": {} }

💾 Object `BlockdevCreateOptionsFile` (Since: 2.12)

Driver-specific image creation options for file. Like, the actual raw file file 🍓

Members

filename (string) — the filename for the new image file.
size (int) — size of the virtual disk, in bytes.
preallocation (PreallocMode, optional) — preallocation mode for the new image (default: off; allowed values: off, falloc (only if CONFIG_POSIX_FALLOCATE), full (only if CONFIG_POSIX)).
nocow (boolean, optional) — turns off copy-on-write (only valid on btrfs; default: off).
extent-size-hint (int, optional) — an extent size hint to add to the image file; 0 means don't add one at all (default: 1 MB, since 5.1).

🔐 Object `BlockdevCreateOptionsLUKS` (Since: 2.12)

Driver-specific image creation options for LUKS. Encrypted, mysterious, main character energy 👑

Members

file (BlockdevRef, optional) — the node to create the image format on. Mandatory except when 'preallocation' is not requested. Yes that's a whole situation, read it twice 🙈
header (BlockdevRef, optional) — a block device holding a detached LUKS header (since 9.0).
size (int) — size of the virtual disk in bytes.
preallocation (PreallocMode, optional) — preallocation mode for the new image (since: 4.2) (default: off; allowed values: off, metadata, falloc, full).
The members of QCryptoBlockCreateOptionsLUKS. (yep, they're just in there too, go look 💖)

🌐 Object `BlockdevCreateOptionsNfs` (Since: 2.12)

Driver-specific image creation options for NFS.

Members

location (BlockdevOptionsNfs) — where to store the new image file.
size (int) — size of the virtual disk in bytes.

🧩 Object `BlockdevCreateOptionsParallels` (Since: 2.12)

Driver-specific image creation options for parallels.

Members

file (BlockdevRef) — node to create the image format on.
size (int) — size of the virtual disk in bytes.
cluster-size (int, optional) — cluster size in bytes (default: 1 MB).

🎀 Object `BlockdevCreateOptionsQcow` (Since: 2.12)

Driver-specific image creation options for qcow. The og format, lowkey iconic.

Members

file (BlockdevRef) — node to create the image format on.
size (int) — size of the virtual disk in bytes.
backing-file (string, optional) — file name of the backing file, if a backing file should be used.
encrypt (QCryptoBlockCreateOptions, optional) — encryption options, if the image should be encrypted.

🦋 Enum `BlockdevQcow2Version` (Since: 2.12)

Values

v2 — the original QCOW2 format as introduced in QEMU 0.10 (version 2).
v3 — the extended QCOW2 format as introduced in QEMU 1.1 (version 3).

🗜️ Enum `Qcow2CompressionType` (Since: 5.1)

The compression type used in a qcow2 image file. Squish responsibly 💅

Values

zlib — zlib compression, see http://zlib.net/.
zstd — zstd compression, see http://github.com/facebook/zstd.

✨ Object `BlockdevCreateOptionsQcow2` (Since: 2.12)

Driver-specific image creation options for qcow2. This one's got a lot going on, bestie — buckle in.

Members

file (BlockdevRef) — node to create the image format on.
data-file (BlockdevRef, optional) — node to use as an external data file, where all guest data gets stored so that only metadata remains in the qcow2 file (since: 4.0).
data-file-raw (boolean, optional) — true if the external data file must stay valid as a standalone (read-only) raw image without looking at qcow2 metadata (default: false; since: 4.0).
extended-l2 (boolean, optional) — true to make the image have extended L2 entries (default: false; since 5.2).
size (int) — size of the virtual disk in bytes.
version (BlockdevQcow2Version, optional) — compatibility level (default: v3).
backing-file (string, optional) — file name of the backing file, if a backing file should be used.
backing-fmt (BlockdevDriver, optional) — name of the block driver to use for the backing file.
encrypt (QCryptoBlockCreateOptions, optional) — encryption options, if the image should be encrypted.
cluster-size (int, optional) — qcow2 cluster size in bytes (default: 65536).
preallocation (PreallocMode, optional) — preallocation mode for the new image (default: off; allowed values: off, falloc, full, metadata).
lazy-refcounts (boolean, optional) — true if refcounts may be updated lazily (default: off).
refcount-bits (int, optional) — width of reference counts in bits (default: 16).
compression-type (Qcow2CompressionType, optional) — the image cluster compression method (default: zlib, since 5.1).

🌸 Object `BlockdevCreateOptionsQed` (Since: 2.12)

Driver-specific image creation options for qed.

Members

file (BlockdevRef) — node to create the image format on.
size (int) — size of the virtual disk in bytes.
backing-file (string, optional) — file name of the backing file, if a backing file should be used.
backing-fmt (BlockdevDriver, optional) — name of the block driver to use for the backing file.
cluster-size (int, optional) — cluster size in bytes (default: 65536).
table-size (int, optional) — L1/L2 table size (in clusters).

🐙 Object `BlockdevCreateOptionsRbd` (Since: 2.12)

Driver-specific image creation options for rbd/Ceph. Aquatic. Glowing. Slightly terrifying 💜

Members

location (BlockdevOptionsRbd) — where to store the new image file. Heads up: this location cannot point to a snapshot 🫶
size (int) — size of the virtual disk in bytes.
cluster-size (int, optional) — RBD object size.
encrypt (RbdEncryptionCreateOptions, optional) — image encryption options (Since 6.1).

📦 Enum `BlockdevVmdkSubformat` (Since: 4.0)

Subformat options for VMDK images.

Values

monolithicSparse — single file image with sparse cluster allocation.
monolithicFlat — single flat data image plus a descriptor file.
twoGbMaxExtentSparse — data gets split into 2GB (per virtual LBA) sparse extent files, plus a descriptor file.
twoGbMaxExtentFlat — data gets split into 2GB (per virtual LBA) flat extent files, plus a descriptor file.
streamOptimized — single file image, sparse cluster allocation, optimized for streaming over the network.

🔌 Enum `BlockdevVmdkAdapterType` (Since: 4.0)

Adapter type info for VMDK images.

Values

ide — not documented. (lol, mysterious 💀)
buslogic — not documented.
lsilogic — not documented.
legacyESX — not documented.

💿 Object `BlockdevCreateOptionsVmdk` (Since: 4.0)

Driver-specific image creation options for VMDK.

Members

file (BlockdevRef) — where to store the new image file. This refers to the image file for monolithcSparse and streamOptimized formats, or the descriptor file for the other formats.
size (int) — size of the virtual disk in bytes.
extents ([BlockdevRef], optional) — where to store the data extents. Required for monolithcFlat, twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For monolithicFlat, only one entry is required; for twoGbMaxExtent* formats, the number of entries required is calculated as extent_number = virtual_size / 2GB. And btw — providing more extents than will be used is an error 🙈
subformat (BlockdevVmdkSubformat, optional) — the subformat of the VMDK image. Default: "monolithicSparse".
backing-file (string, optional) — the path of the backing file. Default: no backing file is used.
adapter-type (BlockdevVmdkAdapterType, optional) — the adapter type used to fill in the descriptor. Default: ide.
hwversion (string, optional) — hardware version. The meaningful options are "4" or "6". Default: "4".
toolsversion (string, optional) — VMware guest tools version. Default: "2147483647" (Since 6.2).
zeroed-grain (boolean, optional) — whether to enable the zeroed-grain feature for sparse subformats. Default: false.

🧚 Object `BlockdevCreateOptionsSsh` (Since: 2.12)

Driver-specific image creation options for SSH.

Members

location (BlockdevOptionsSsh) — where to store the new image file
size (int) — size of the virtual disk in bytes

Object `BlockdevCreateOptionsVdi` (Since: 2.12) 🦋

Driver specific image creation options for VDI.

Members

file (BlockdevRef) — node to create the image format on
size (int) — size of the virtual disk in bytes
preallocation (PreallocMode, optional) — preallocation mode for the new image (default: off; allowed values: off, metadata)

Enum `BlockdevVhdxSubformat` (Since: 2.12) ✨

Values

dynamic — growing image file
fixed — preallocated fixed-size image file

Object `BlockdevCreateOptionsVhdx` (Since: 2.12) 💅

Driver specific image creation options for vhdx.

Members

file (BlockdevRef) — node to create the image format on
size (int) — size of the virtual disk in bytes
log-size (int, optional) — log size in bytes, must be a multiple of 1 MB (default: 1 MB)
block-size (int, optional) — block size in bytes, must be a multiple of 1 MB and not larger than 256 MB (default: automatically choose a block size depending on the image size)
subformat (BlockdevVhdxSubformat, optional) — vhdx subformat (default: dynamic)
block-state-zero (boolean, optional) — force use of payload blocks of type 'ZERO'. Non-standard, but default. Do not set to 'off' when using qemu-img convert with subformat=dynamic. 👀

Enum `BlockdevVpcSubformat` (Since: 2.12) 🎀

Values

dynamic — growing image file
fixed — preallocated fixed-size image file

Object `BlockdevCreateOptionsVpc` (Since: 2.12) 🫶

Driver specific image creation options for vpc (VHD).

Members

file (BlockdevRef) — node to create the image format on
size (int) — size of the virtual disk in bytes
subformat (BlockdevVpcSubformat, optional) — vhdx subformat (default: dynamic)
force-size (boolean, optional) — force use of the exact byte size instead of rounding to the next size that can be represented in CHS geometry (default: false)

Object `BlockdevCreateOptions` (Since: 2.12) 🌈

Options for creating an image format on a given node.

Members

driver (BlockdevDriver) — block driver to create the image format
When driver is file: the members of BlockdevCreateOptionsFile.
When driver is luks: the members of BlockdevCreateOptionsLUKS.
When driver is nfs: the members of BlockdevCreateOptionsNfs.
When driver is parallels: the members of BlockdevCreateOptionsParallels.
When driver is qcow: the members of BlockdevCreateOptionsQcow.
When driver is qcow2: the members of BlockdevCreateOptionsQcow2.
When driver is qed: the members of BlockdevCreateOptionsQed.
When driver is rbd: the members of BlockdevCreateOptionsRbd.
When driver is ssh: the members of BlockdevCreateOptionsSsh.
When driver is vdi: the members of BlockdevCreateOptionsVdi.
When driver is vhdx: the members of BlockdevCreateOptionsVhdx.
When driver is vmdk: the members of BlockdevCreateOptionsVmdk.
When driver is vpc: the members of BlockdevCreateOptionsVpc.

Command `blockdev-create` (Since: 3.0) 🔥

Starts a job to create an image format on a given node. The job is automatically finalized, but a manual job-dismiss is required — so like, don't ghost the dismiss, bestie, it's rude. 💀

Arguments

job-id (string) — identifier for the newly created job
options (BlockdevCreateOptions) — options for the image creation

Object `BlockdevAmendOptionsLUKS` (Since: 5.1) 🔐

Driver specific image amend options for LUKS.

Members

The members of QCryptoBlockAmendOptionsLUKS.

Object `BlockdevAmendOptionsQcow2` (Since: 5.1) 🌸

Driver specific image amend options for qcow2. For now, only encryption options can be amended.

Members

encrypt (QCryptoBlockAmendOptions, optional) — encryption options to be amended

Object `BlockdevAmendOptions` (Since: 5.1) ⭐

Options for amending an image format.

Members

driver (BlockdevDriver) — block driver of the node to amend
When driver is luks: the members of BlockdevAmendOptionsLUKS.
When driver is qcow2: the members of BlockdevAmendOptionsQcow2.

Command `x-blockdev-amend` (Since: 5.1) 🙈

This command is unstable/experimental. The x- prefix is literally the "do not perceive me" of Unix, ok?

Starts a job to amend format specific options of an existing open block device. The job is automatically finalized, but a manual job-dismiss is required.

Arguments

job-id (string) — identifier for the newly created job
node-name (string) — name of the block node to work on
options (BlockdevAmendOptions) — options (driver specific)
force (boolean, optional) — allow unsafe operations, format specific. For luks that allows erase of the last active keyslot (permanent loss of data), and replacement of an active keyslot (possible loss of data if IO error happens). 😭 Like, this flag is not playing around — read it twice.

Features

unstable — this command is experimental.

Enum `BlockErrorAction` (Since: 2.1) 💀

An enumeration of action that has been taken when a DISK I/O occurs.

Values

ignore — error has been ignored
report — error has been reported to the device
stop — error caused VM to be stopped

Event `BLOCK_IMAGE_CORRUPTED` (Since: 1.7) 🚨

Emitted when a disk image is being marked corrupt. The image can be identified by its device or node name. The device field is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated.

Members

device (string) — device name. This is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated.
node-name (string, optional) — node name (Since: 2.4)
msg (string) — informative message for human consumption, such as the kind of corruption being detected. It should not be parsed by machine as it is not guaranteed to be stable
offset (int, optional) — if the corruption resulted from an image access, this is the host's access offset into the image
size (int, optional) — if the corruption resulted from an image access, this is the access size
fatal (boolean) — if set, the image is marked corrupt and therefore unusable after this event and must be repaired (Since 2.2; before, every BLOCK_IMAGE_CORRUPTED event was fatal)

Note: if action is "stop", a STOP event will eventually follow the BLOCK_IO_ERROR event.

Example:

<- { "event": "BLOCK_IMAGE_CORRUPTED",
     "data": { "device": "", "node-name": "drive", "fatal": false,
               "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
     "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }

Event `BLOCK_IO_ERROR` (Since: 0.13) 🍓

Emitted when a disk I/O error occurs.

Members

qom-path (string) — path to the device object in the QOM tree (since 9.2)
device (string) — device name. This is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated.
node-name (string, optional) — node name. Note that errors may be reported for the root node that is directly attached to a guest device rather than for the node where the error occurred. The node name is not present if the drive is empty. (Since: 2.8)
operation (IoOperationType) — I/O operation
action (BlockErrorAction) — action that has been taken
nospace (boolean, optional) — true if I/O error was caused due to a no-space condition. This key is only present if query-block's io-status is present, please see query-block documentation for more information (since: 2.2)
reason (string) — human readable string describing the error cause. (This field is a debugging aid for humans, it should not be parsed by applications) (since: 2.2)

Note: if action is "stop", a STOP event will eventually follow the BLOCK_IO_ERROR event.

Note: this event is rate-limited, except if action is "stop".

Example:

<- { "event": "BLOCK_IO_ERROR",
     "data": { "qom-path": "/machine/unattached/device[0]",
               "device": "ide0-hd1",
               "node-name": "#block212",
               "operation": "write",
               "action": "stop",
               "reason": "No space left on device" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

Event `BLOCK_JOB_COMPLETED` (Since: 1.1) 👑

Emitted when a block job has completed.

Members

…and that's exactly where this part hands the aux cord off — members incoming. 💖

type (JobType) — the job type, obvi 🎀
device (string) — the job identifier. Like, it started as the device name but other values are allowed since QEMU 2.7, so don't come for it 💅
len (int) — the maximum progress value 🏁
offset (int) — the current progress value. On success this equals len. On failure this is less than len 😭
speed (int) — rate limit, in bytes per second ⚡
error (string, optional) — the error message. Only present on failure. This field is a human-readable error message, and that's literally all it is — there are no semantics other than that streaming has failed and clients should not try to interpret the error string 🙈

Example:

<- { "event": "BLOCK_JOB_COMPLETED",
     "data": { "type": "stream", "device": "virtio-disk0",
               "len": 10737418240, "offset": 10737418240,
               "speed": 0 },
     "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }

🌸 Event `BLOCK_JOB_CANCELLED` (Since: 1.1)

Emitted when a block job has been cancelled ✂️ like ok it's over, we're done here.

Members

type (JobType) — job type
device (string) — The job identifier. Originally the device name but other values are allowed since QEMU 2.7
len (int) — maximum progress value
offset (int) — current progress value. On success this is equal to len. On failure this is less than len
speed (int) — rate limit, bytes per second

Example:

<- { "event": "BLOCK_JOB_CANCELLED",
     "data": { "type": "stream", "device": "virtio-disk0",
               "len": 10737418240, "offset": 134217728,
               "speed": 0 },
     "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }

💀 Event `BLOCK_JOB_ERROR` (Since: 1.3)

Emitted when a block job encounters an error 😬 it's giving "something went wrong" energy.

Members

device (string) — The job identifier. Originally the device name but other values are allowed since QEMU 2.7
operation (IoOperationType) — I/O operation
action (BlockErrorAction) — action that has been taken

Example:

<- { "event": "BLOCK_JOB_ERROR",
     "data": { "device": "ide0-hd1",
               "operation": "write",
               "action": "stop" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

👑 Event `BLOCK_JOB_READY` (Since: 1.3)

Emitted when a block job is ready to complete ✨ it's ready bestie, it's ready.

Members

type (JobType) — job type
device (string) — The job identifier. Originally the device name but other values are allowed since QEMU 2.7
len (int) — maximum progress value
offset (int) — current progress value. On success this is equal to len. On failure this is less than len
speed (int) — rate limit, bytes per second

Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR event. So like, the error card just nukes the ready status, no cap 🃏

Example:

<- { "event": "BLOCK_JOB_READY",
     "data": { "device": "drive0", "type": "mirror", "speed": 0,
               "len": 2097152, "offset": 2097152 },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

🦋 Event `BLOCK_JOB_PENDING` (Since: 2.12)

Emitted when a block job is awaiting explicit authorization to finalize graph changes via job-finalize. Lowkey it's just sitting there like "can I finish pls 🥺". If this job is part of a transaction, it will not emit this event until the transaction has converged first — so the transaction has to be done being dramatic before this one gets any attention 💅

Members

type (JobType) — job type
id (string) — The job identifier.

Example:

<- { "event": "BLOCK_JOB_PENDING",
     "data": { "type": "mirror", "id": "backup_1" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

🎀 Enum `PreallocMode` (Since: 2.2)

Preallocation mode of a QEMU image file 🗂️ aka how much space are we claiming upfront, bestie.

Values

off — no preallocation. zero thoughts, zero space, head empty 🫧
metadata — preallocate only for metadata
falloc — like full preallocation but allocate disk space by posix_fallocate() rather than writing data. Very efficient of it honestly 🔥
full — preallocate all data by writing it to the device to ensure disk space is really available. This data may or may not be zero, depending on the image format and storage. full preallocation also sets up metadata correctly. It's giving thorough 🎀

🌈 Event `BLOCK_WRITE_THRESHOLD` (Since: 2.3)

Emitted when writes on a block device reaches or exceeds the configured write threshold 📈. For thin-provisioned devices, this means the device should be extended to avoid pausing for disk exhaustion. The event is one shot — once triggered, it needs to be re-registered with another block-set-write-threshold command. Like yes it told you once, don't make it tell you again 🙄

Members

node-name (string) — graph node name on which the threshold was exceeded.
amount-exceeded (int) — amount of data which exceeded the threshold, in bytes.
write-threshold (int) — last configured threshold, in bytes.

⭐ Command `block-set-write-threshold` (Since: 2.3)

Change the write threshold for a block drive. An event will be delivered if a write to this block drive crosses the configured threshold. The threshold is an offset, thus must be non-negative. Default is no write threshold. Setting the threshold to zero disables it 🚫

This is useful to transparently resize thin-provisioned drives without the guest OS noticing 🤫 sneaky but make it seamless.

Arguments

node-name (string) — graph node name on which the threshold must be set.
write-threshold (int) — configured threshold for the block device, bytes. Use 0 to disable the threshold.

Example:

-> { "execute": "block-set-write-threshold",
     "arguments": { "node-name": "mydev",
                    "write-threshold": 17179869184 } }
<- { "return": {} }

🧚 Command `x-blockdev-change` (Since: 2.7)

This command is unstable/experimental. You've been warned bestie 💀

Dynamically reconfigure the block driver state graph 🔧 graph surgery, but make it hot.

Currently only supports adding and deleting quorum children. A child will be added at the end of the list of children. Its contents must be consistent with the other childrens' contents. Deleting a child that is not last in the list of children is problematic, because it "renumbers" the children following it 😭 like it literally shifts everyone's index, rude.

Arguments

parent (string) — the id or name of the parent node.
child (string, optional) — the name of a child to be deleted. Mutually exclusive with node.
node (string, optional) — the name of the node to be added. Mutually exclusive with child.

Features

unstable — This command is experimental.

Example: Add a new node to a quorum

-> { "execute": "blockdev-add",
     "arguments": {
         "driver": "raw",
         "node-name": "new_node",
         "file": { "driver": "file",
                   "filename": "test.raw" } } }
<- { "return": {} }
-> { "execute": "x-blockdev-change",
     "arguments": { "parent": "disk1",
                    "node": "new_node" } }
<- { "return": {} }

Example: Delete a quorum's node

-> { "execute": "x-blockdev-change",
     "arguments": { "parent": "disk1",
                    "child": "children.1" } }
<- { "return": {} }

🫶 Command `x-blockdev-set-iothread` (Since: 2.12)

This command is unstable/experimental.

Move node and its children into the iothread. If iothread is null then move node and its children into the main loop 🔄 relocation era.

The node must not be attached to a BlockBackend. Like, it's not allowed, that's the rule 🚧

Arguments

node-name (string) — the name of the block driver node
iothread (StrOrNull) — the name of the IOThread object or null for the main loop
force (boolean, optional) — true if the node and its children should be moved when a BlockBackend is already attached

Features

unstable — This command is experimental and intended for test cases that need control over IOThreads only.

Example: Move a node into an IOThread

-> { "execute": "x-blockdev-set-iothread",
     "arguments": { "node-name": "disk1",
                    "iothread": "iothread0" } }
<- { "return": {} }

Example: Move a node into the main loop

-> { "execute": "x-blockdev-set-iothread",
     "arguments": { "node-name": "disk1",
                    "iothread": null } }
<- { "return": {} }

💜 Enum `QuorumOpType` (Since: 2.6)

An enumeration of the quorum operation types 🗳️ the quorum has opinions and these are the kinds.

Values

read — read operation
write — write operation
flush — flush operation

🍓 Event `QUORUM_FAILURE` (Since: 2.0)

Emitted by the Quorum block driver if it fails to establish a quorum 😭 the group chat did not reach consensus, it's giving flop.

Members

reference (string) — device name if defined else node name
sector-num (int) — number of the first sector of the failed read operation
sectors-count (int) — failed read operation sector count

Note: This event is rate-limited. So it won't spam you, it's got restraint 💅

Example:

                     <- { "event": "QUORUM_FAILURE",
                          "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
                          "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }

🌸 Event `QUORUM_REPORT_BAD` (Since: 2.0)

okay so this one exists purely to tell you a Quorum file got corrupted 😭 like it's the snitch event.

Members

type (QuorumOpType) — what kind of quorum operation it was (Since: 2.6)
error (string, optional) — the error message. Only present on failure. It's a human-readable error message and that's literally all it is — there are no semantics beyond "the block layer reported an error," so besties, do not try to interpret this error string. Just... read it and move on 💅
node-name (string) — the graph node name of the block driver state
sector-num (int) — number of the first sector of the failed read operation
sectors-count (int) — failed read operation sector count

Note: this event is rate-limited. So you're not gonna get spammed, bestie 🫶

Example: Read operation

<- { "event": "QUORUM_REPORT_BAD",
     "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
               "type": "read" },
     "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }

Example: Flush operation

<- { "event": "QUORUM_REPORT_BAD",
     "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
               "type": "flush", "error": "Broken pipe" },
     "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }

🎀 Object `BlockdevSnapshotInternal` (Since: 1.7)

Members

device (string) — the device name or node-name of a root node to generate the snapshot from
name (string) — the name of the internal snapshot to be created

✨ Command `blockdev-snapshot-internal-sync` (Since: 1.7)

Takes an internal snapshot of a block device, synchronously — but only when the format of the image used actually supports it. And heads up: if name is an empty string, or a snapshot with that name already exists, the operation will fail. No cap 💀

Arguments

The members of BlockdevSnapshotInternal.

Errors

If device is not a valid block device, GenericError
If any snapshot matching name exists, or name is empty, GenericError
If the format of the image used does not support it, GenericError

Note: only some image formats support internal snapshots, like qcow2 and rbd. Not all of them, bestie 🙈

Example:

-> { "execute": "blockdev-snapshot-internal-sync",
     "arguments": { "device": "ide-hd0",
                    "name": "snapshot0" }
   }
<- { "return": {} }

🦋 Command `blockdev-snapshot-delete-internal-sync` (Since: 1.7)

Synchronously deletes an internal snapshot of a block device, when the format of the image used supports it. The snapshot is identified by name or id or both — one of name or id is required. It returns SnapshotInfo for the snapshot that got successfully deleted, which is lowkey satisfying ngl.

Arguments

device (string) — the device name or node-name of a root node to delete the snapshot from
id (string, optional) — optional the snapshot's ID to be deleted
name (string, optional) — optional the snapshot's name to be deleted

Return SnapshotInfo

Errors

If device is not a valid block device, GenericError
If snapshot not found, GenericError
If the format of the image used does not support it, GenericError
If id and name are both not specified, GenericError

Example:

-> { "execute": "blockdev-snapshot-delete-internal-sync",
     "arguments": { "device": "ide-hd0",
                    "name": "snapshot0" }
   }
<- { "return": {
                   "id": "1",
                   "name": "snapshot0",
                   "vm-state-size": 0,
                   "date-sec": 1000012,
                   "date-nsec": 10,
                   "vm-clock-sec": 100,
                   "vm-clock-nsec": 20,
                   "icount": 220414
     }
   }

💀 Object `DummyBlockCoreForceArrays` (Since: 8.0)

Not used by QMP. It's a hack to let us use BlockGraphInfoList internally. That's the whole personality. It's giving "placeholder friend" energy 🙈

Members

unused-block-graph-info ([BlockGraphInfo]) — Not documented

⭐ Enum `BiosAtaTranslation` (Since: 2.0)

The policy BIOS should use to interpret cylinder/head/sector addresses. Big important caveat bestie: note that Bochs BIOS and SeaBIOS will not actually translate logical CHS to physical — instead, they'll use logical block addressing. So this is more of a vibe than a promise 💅

Values

auto — If cylinder/heads/sizes are passed, choose between none and LBA depending on the size of the disk. If they are not passed, choose none if QEMU can guess that the disk had 16 or fewer heads, large if QEMU can guess that the disk had 131072 or fewer tracks across all heads (i.e. cylinders*heads<131072), otherwise LBA.
none — The physical disk geometry is equal to the logical geometry.
lba — Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 heads (if fewer than 255 are enough to cover the whole disk with 1024 cylinders/head). The number of cylinders/head is then computed based on the number of sectors and heads.
large — The number of cylinders per head is scaled down to 1024 by correspondingly scaling up the number of heads.
rechs — Same as large, but first convert a 16-head geometry to 15-head, by proportionally scaling up the number of cylinders/head.

🍓 Enum `FloppyDriveType` (Since: 2.6)

The type of floppy drive the Floppy Disk Controller should emulate. Retro icon behaviour honestly 👑

Values

144 — 1.44MB 3.5" drive
288 — 2.88MB 3.5" drive
120 — 1.2MB 5.25" drive
none — No drive connected
auto — Automatically determined by inserted media at boot

💜 Object `PRManagerInfo` (Since: 3.0)

Info about a persistent reservation manager.

Members

id (string) — the identifier of the persistent reservation manager
connected (boolean) — true if the persistent reservation manager is connected to the underlying storage or helper

🧚 Command `query-pr-managers` (Since: 3.0)

Returns a list of information about each persistent reservation manager. Like a little roll call 📋

Return [PRManagerInfo] — a list of manager info for each persistent reservation manager

🔥 Command `eject` (Since: 0.14)

Ejects the medium from a removable drive. Bye bye disc 💅

Arguments

device (string, optional) — Block device name
id (string, optional) — The name or QOM path of the guest device (since: 2.8)
force (boolean, optional) — If true, eject regardless of whether the drive is locked. If not specified, the default value is false.

Features

deprecated — Member device is deprecated. Use id instead.

Errors

If device is not a valid block device, DeviceNotFound

Note: ejecting a device with no media results in success. Nothing to eject? Still slayed ✨

Example:

-> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
<- { "return": {} }

🎀 Command `blockdev-open-tray` (Since: 2.5)

Opens a block device's tray. If there's a block driver state tree inserted as a medium, it becomes inaccessible to the guest — but don't panic, it stays associated to the block device, so closing the tray brings it right back 🫶

If the tray was already open before, this is a no-op. iconic, honestly.

Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. But there are cases where no such event gets generated, and those include:

if the guest has locked the tray, force is false and the guest does not respond to the eject request
if the BlockBackend denoted by device does not have a guest device attached to it
if the guest device does not have an actual tray

Arguments

device (string, optional) — Block device name
id (string, optional) — The name or QOM path of the guest device (since: 2.8)
force (boolean, optional) — if false (the default), an eject request will be sent to the guest if it has locked the tray (and the tray will not be opened immediately); if true, the tray will be opened regardless of whether it is locked

Features

deprecated — Member device is deprecated. Use id instead.

Example:

-> { "execute": "blockdev-open-tray",
     "arguments": { "id": "ide0-1-0" } }

<- { "timestamp": { "seconds": 1418751016,
                    "microseconds": 716996 },
     "event": "DEVICE_TRAY_MOVED",
     "data": { "device": "ide1-cd0",
               "id": "ide0-1-0",
               "tray-open": true } }

<- { "return": {} }

🎀 Command `blockdev-close-tray` (Since: 2.5)

Bestie, this one shuts the tray on a block device. That's it, that's the vibe. But here's the cute part: if there's a block driver state tree hanging out with that block device (like, one that's currently ejected), that whole tree gets loaded as the medium. Free real estate 💅

And if the tray was already closed? No-op. Nothing happens. Move on. ✨

Arguments

device (string, optional) — Block device name
id (string, optional) — The name or QOM path of the guest device (since: 2.8)

Features

deprecated — Member device is deprecated. Use id instead. (Yeah she's old, we're moving on 🫶)

Example:

-> { "execute": "blockdev-close-tray",
     "arguments": { "id": "ide0-1-0" } }

<- { "timestamp": { "seconds": 1418751345,
                    "microseconds": 272147 },
     "event": "DEVICE_TRAY_MOVED",
     "data": { "device": "ide1-cd0",
               "id": "ide0-1-0",
               "tray-open": false } }

<- { "return": {} }

🦋 Command `blockdev-remove-medium` (Since: 2.12)

Removes a medium (a block driver state tree, iykyk) from a block device. The rule tho: that block device's tray must currently be open — unless there's no attached guest device, in which case we're chill about it.

And if the tray is open and there's literally no medium inserted? No-op again. Nothing to remove, nothing to do, iconic behaviour honestly. ⭐

Arguments

id (string) — The name or QOM path of the guest device

Example:

-> { "execute": "blockdev-remove-medium",
     "arguments": { "id": "ide0-1-0" } }

<- { "error": { "class": "GenericError",
                "desc": "Tray of device 'ide0-1-0' is not open" } }

-> { "execute": "blockdev-open-tray",
     "arguments": { "id": "ide0-1-0" } }

<- { "timestamp": { "seconds": 1418751627,
                    "microseconds": 549958 },
     "event": "DEVICE_TRAY_MOVED",
     "data": { "device": "ide1-cd0",
               "id": "ide0-1-0",
               "tray-open": true } }

<- { "return": {} }

-> { "execute": "blockdev-remove-medium",
     "arguments": { "id": "ide0-1-0" } }

<- { "return": {} }

🌸 Command `blockdev-insert-medium` (Since: 2.12)

The opposite vibe of the last one — this inserts a medium (yep, a block driver state tree) into a block device. Two conditions, no exceptions bestie: that block device's tray must currently be open (again, unless there's no attached guest device), and there must be no medium inserted already. 🎀

Arguments

id (string) — The name or QOM path of the guest device
node-name (string) — name of a node in the block driver state graph

Example:

-> { "execute": "blockdev-add",
     "arguments": {
         "node-name": "node0",
         "driver": "raw",
         "file": { "driver": "file",
                   "filename": "fedora.iso" } } }
<- { "return": {} }

-> { "execute": "blockdev-insert-medium",
     "arguments": { "id": "ide0-1-0",
                    "node-name": "node0" } }

<- { "return": {} }

💜 Enum `BlockdevChangeReadOnlyMode` (Since: 2.3)

This tells you the new read-only mode of a block device that's subject to the blockdev-change-medium command. Three flavours, all valid, pick ur fighter:

Values

retain — Retains the current read-only mode
read-only — Makes the device read-only
read-write — Makes the device writable

🔥 Command `blockdev-change-medium` (Since: 2.5)

Okay so this is the big one — it changes the medium inserted into a block device. It does that by ejecting the current medium and loading a brand new image file which then gets inserted as the new medium. Basically it's a combo: blockdev-open-tray + blockdev-remove-medium + blockdev-insert-medium + blockdev-close-tray, all in one slay little call. She ate. 👑

Arguments

device (string, optional) — Block device name
id (string, optional) — The name or QOM path of the guest device (since: 2.8)
filename (string) — filename of the new image to be loaded
format (string, optional) — format to open the new image with (defaults to the probed format)
read-only-mode (BlockdevChangeReadOnlyMode, optional) — change the read-only mode of the device; defaults to 'retain'
force (boolean, optional) — if false (the default), an eject request through blockdev-open-tray will be sent to the guest if it has locked the tray (and the tray will not be opened immediately); if true, the tray will be opened regardless of whether it is locked. (since 7.1)

Features

deprecated — Member device is deprecated. Use id instead.

Example: Change a removable medium

-> { "execute": "blockdev-change-medium",
     "arguments": { "id": "ide0-1-0",
                    "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
                    "format": "raw" } }
<- { "return": {} }

Example: Load a read-only medium into a writable drive

-> { "execute": "blockdev-change-medium",
     "arguments": { "id": "floppyA",
                    "filename": "/srv/images/ro.img",
                    "format": "raw",
                    "read-only-mode": "retain" } }

<- { "error":
     { "class": "GenericError",
       "desc": "Could not open '/srv/images/ro.img': Permission denied" } }

-> { "execute": "blockdev-change-medium",
     "arguments": { "id": "floppyA",
                    "filename": "/srv/images/ro.img",
                    "format": "raw",
                    "read-only-mode": "read-only" } }

<- { "return": {} }

🌈 Event `DEVICE_TRAY_MOVED` (Since: 1.1)

Emitted whenever the tray of a removable device gets moved — by the guest, or by HMP/QMP commands. Either way, you get the notification, bestie. Notifications on. 🔔

Members

device (string) — Block device name. This is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated. (so like, don't assume it's got content 💀)
id (string) — The name or QOM path of the guest device (since 2.8)
tray-open (boolean) — true if the tray has been opened or false if it has been closed

Example:

<- { "event": "DEVICE_TRAY_MOVED",
     "data": { "device": "ide1-cd0",
               "id": "/machine/unattached/device[22]",
               "tray-open": true
     },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

🧚 Event `PR_MANAGER_STATUS_CHANGED` (Since: 3.0)

Fires whenever the connected status of a persistent reservation manager changes. Status change! 📣

Members

id (string) — The id of the PR manager object
connected (boolean) — true if the PR manager is connected to a backend

Example:

<- { "event": "PR_MANAGER_STATUS_CHANGED",
     "data": { "id": "pr-helper0",
               "connected": true
     },
     "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }

⭐ Command `block_set_io_throttle` (Since: 1.1)

Change I/O throttle limits for a block drive. Yes bestie, we're doing rate limiting, hold on to ur wig. 🎀

Since QEMU 2.4, each device with I/O limits is member of a throttle group. Group project but make it I/O.

If two or more devices are members of the same group, the limits apply to the combined I/O of the whole group, in a round-robin fashion. So setting new I/O limits on a device affects the whole group. Sharing is caring, unfortunately. 🫶

The name of the group can be specified using the 'group' parameter. If the parameter is unset, it's assumed to be the current group of that device. And if it's not in any group yet, the name of the device gets used as the name for its group. Automatic. ✨

The 'group' parameter can also be used to move a device to a different group. In that case the limits specified in the parameters get applied to the new group only. Fresh start energy.

I/O limits can be disabled by setting all of them to 0. In that case the device gets removed from its group and the rest of its members are not affected — and heads up, the 'group' parameter is ignored in that situation. 🙈

Arguments

The members of BlockIOThrottle.

Errors

If device is not a valid block device, DeviceNotFound

Example:

-> { "execute": "block_set_io_throttle",
     "arguments": { "id": "virtio-blk-pci0/virtio-backend",
                    "bps": 0,
                    "bps_rd": 0,
                    "bps_wr": 0,
                    "iops": 512,
                    "iops_rd": 0,
                    "iops_wr": 0,
                    "bps_max": 0,
                    "bps_rd_max": 0,
                    "bps_wr_max": 0,
                    "iops_max": 0,
                    "iops_rd_max": 0,
                    "iops_wr_max": 0,
                    "bps_max_length": 0,
                    "iops_size": 0 } }
<- { "return": {} }

Example:

...and here's the rest of that block_set_io_throttle example from before, bestie — all those throttle numbers landing at once ✨

-> { "execute": "block_set_io_throttle",
     "arguments": { "id": "ide0-1-0",
                    "bps": 1000000,
                    "bps_rd": 0,
                    "bps_wr": 0,
                    "iops": 0,
                    "iops_rd": 0,
                    "iops_wr": 0,
                    "bps_max": 8000000,
                    "bps_rd_max": 0,
                    "bps_wr_max": 0,
                    "iops_max": 0,
                    "iops_rd_max": 0,
                    "iops_wr_max": 0,
                    "bps_max_length": 60,
                    "iops_size": 0 } }
<- { "return": {} }

💅 Command `block-latency-histogram-set` (Since: 4.0) 💅

Okay so this one is literally the vibe-check manager for your device's latency histograms — read, write and flush. 🌸

If you only hand it the id parameter, it removes all the present latency histograms for that device. Otherwise, it adds/resets some of them (or all of them). Periodt.

Arguments

id (string) — The name or QOM path of the guest device. 🎀
boundaries ([int], optional) — a list of interval boundary values (the description lives over in the BlockLatencyHistogramInfo definition). If you specify it, all latency histograms get removed and empty ones get created for all io types, with intervals matching boundaries — except for the io types where you've set specific boundaries through the following parameters. 🔥
boundaries-read ([int], optional) — a list of interval boundary values for the read latency histogram. If you specify it, the old read latency histogram gets removed and an empty one gets created with intervals matching boundaries-read. Heads up: this parameter has higher priority than boundaries. 👑
boundaries-write ([int], optional) — a list of interval boundary values for the write latency histogram.
boundaries-zap ([int], optional) — a list of interval boundary values for the zone append write latency histogram. 💀
boundaries-flush ([int], optional) — a list of interval boundary values for the flush latency histogram.

Errors

if the device isn't found, or any of the boundary arrays are invalid. 😭

Example: set new histograms for all io types with intervals [0, 10), [10, 50), [50, 100), [100, +inf):

-> { "execute": "block-latency-histogram-set",
     "arguments": { "id": "drive0",
                    "boundaries": [10, 50, 100] } }
<- { "return": {} }

Example: set a new histogram only for write — every other histogram just stays exactly as it was (or never gets created at all):

-> { "execute": "block-latency-histogram-set",
     "arguments": { "id": "drive0",
                    "boundaries-write": [10, 50, 100] } }
<- { "return": {} }

Example: set new histograms with these intervals: - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) - write: [0, 1000), [1000, 5000), [5000, +inf)

-> { "execute": "block-latency-histogram-set",
     "arguments": { "id": "drive0",
                    "boundaries": [10, 50, 100],
                    "boundaries-write": [1000, 5000] } }
<- { "return": {} }

Example: remove all the latency histograms:

-> { "execute": "block-latency-histogram-set",
     "arguments": { "id": "drive0" } }
<- { "return": {} }

🦋 Block device exports 🦋

Object `NbdServerOptionsBase`

Members

handshake-max-seconds (int, optional) — Time limit, in seconds, at which a client that hasn't completed the negotiation handshake will be disconnected, or 0 for no limit (since 10.0; default: 10). ⏰
tls-creds (string, optional) — ID of the TLS credentials object (since 2.6). 🔐
tls-authz (string, optional) — ID of the QAuthZ authorization object used to validate the client's x509 distinguished name. This object is only resolved at time of use, so it can be deleted and recreated on the fly while the NBD server is active — iconic, honestly. If it's missing, it defaults to denying access (since 4.0). 🚫
max-connections (int, optional) — The maximum number of connections to allow at the same time, 0 for unlimited. Setting this to 1 also stops the server from advertising multiple client support (since 5.2; default: 100). 👯

Object `NbdServerOptions`

Keep this type consistent with the NbdServerOptionsLegacy type — the only intended difference is using SocketAddress instead of SocketAddressLegacy. fr fr, that's the whole tea. 🍵

Members

addr (SocketAddress) — Address on which to listen (since 4.2). 🎧
The members of NbdServerOptionsBase.

Object `NbdServerOptionsLegacy`

Keep this type consistent with the NbdServerOptions type — the only intended difference is using SocketAddressLegacy instead of SocketAddress. Same energy, different socket type. 💅

Members

addr (SocketAddressLegacy) — Address on which to listen (since 1.3). 🎧
The members of NbdServerOptionsBase.

Command `nbd-server-start` (Since: 1.3)

Start an NBD server listening on the given host and port. Block devices can then be exported using nbd-server-add. The NBD server will present them as named exports — so, for example, another QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME". 🫶

Arguments

The members of NbdServerOptionsLegacy.

Errors

if the server is already running 😬

Object `BlockExportOptionsNbdBase` (Since: 5.0)

An NBD block export — these are the common options shared between nbd-server-add and the NBD branch of block-export-add. 🌈

Members

name (string, optional) — Export name. If it's unspecified, the device parameter gets used as the export name. (Since 2.12)
description (string, optional) — Free-form description of the export, up to 4096 bytes. (Since 5.0) 📝

Object `BlockExportOptionsNbd` (Since: 5.2)

An NBD block export — these are the distinct options used in the NBD branch of block-export-add. ✨

Members

bitmaps ([BlockDirtyBitmapOrStr], optional) — Also export each of the named dirty bitmaps reachable from device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect each bitmap. Since 7.1 the bitmap may be specified by a node/name pair. 🗺️
allocation-depth (boolean, optional) — Also export the allocation depth map for device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata context name "qemu:allocation-depth" to inspect allocation details. (since 5.2) 🔍
The members of BlockExportOptionsNbdBase.

Object `BlockExportOptionsVhostUserBlk` (Since: 5.2)

A vhost-user-blk block export. Slay. 🖤

Members

addr (SocketAddress) — The vhost-user socket on which to listen. Both 'unix' and 'fd' SocketAddress types are supported. Passed fds must be UNIX domain sockets. 🔌
logical-block-size (int, optional) — Logical block size in bytes. Defaults to 512 bytes.
num-queues (int, optional) — Number of request virtqueues. Must be greater than 0. Defaults to 1.

Enum `FuseExportAllowOther` (Since: 6.1)

Possible allow_other modes for FUSE exports. 🌸

Values

off — Do not pass allow_other as a mount option.
on — Pass allow_other as a mount option.
auto — Try mounting with allow_other first, and if that fails, retry without allow_other. 🔁

Object `BlockExportOptionsFuse` (Since: 6.0)

Availability: CONFIG_FUSE 🧚

Options for exporting a block graph node on some (file) mountpoint as a raw image.

Multi-threading note: the FUSE export supports multi-threading. Currently, requests are distributed across those threads in a round-robin fashion, i.e. independently of the CPU core from which a request originates. Not me being round-robin pilled 💀

Members

mountpoint (string) — Path on which to export the block device via FUSE. This must point to an existing regular file. 📁
growable (boolean, optional) — Whether writes beyond the EOF should grow the block node accordingly. (default: false)
allow-other (FuseExportAllowOther, optional) — If this is off, only QEMU's user is allowed access to this export. That cannot be changed, even with chmod or chown. Enabling this option will allow other users access to the export with the FUSE mount option "allow_other". Note that using allow_other as a non-root user requires user_allow_other to be enabled in the global fuse.conf configuration file. In auto mode (the default), the FUSE export driver will first attempt to mount the export with allow_other, and if that fails, try again without. (since 6.1; default: auto) 🫶

Object `BlockExportOptionsVduseBlk` (Since: 7.1)

A vduse-blk block export. 💜

Members

name (string) — the name of the VDUSE device (must be unique across the host). 👑
num-queues (int, optional) — the number of virtqueues. Defaults to 1.
queue-size (int, optional) — how big the virtqueue is. Defaults to 256.
logical-block-size (int, optional) — the logical block size, in bytes. Range is [512, PAGE_SIZE] and it must be a power of 2, no cap. Defaults to 512 bytes.
serial (string, optional) — the serial number of the virtio block device. Defaults to the empty string.

🧚 Object `NbdServerAddOptions` (Since: 5.0)

An NBD block export — like, the per-legacy-nbd-server-add-command situation 💅

Members

device (string) — the device name or node name of the node that's getting exported
writable (boolean, optional) — whether clients should be able to write to the device over the NBD connection (default false).
bitmap (string, optional) — also export a single dirty bitmap reachable from device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap (since 4.0).
The members of BlockExportOptionsNbdBase.

🫶 Command `nbd-server-add` (Since: 1.3)

⚠️ bestie this command is deprecated. Like, it still works, but… 👀

Export a block node to QEMU's embedded NBD server.

The export name gets used as the id for the resulting block export, cute right.

Arguments

The members of NbdServerAddOptions.

Features

deprecated — This command is deprecated. Use block-export-add instead.

Errors

if the server is not running
if an export with the same name already exists

🌈 Enum `BlockExportRemoveMode` (Since: 2.12)

Mode for removing a block export. Pick your vibe:

Values

safe — Remove export if there are no existing connections, fail otherwise. Polite queen behavior 🎀
hard — Drop all connections immediately and remove export. no thoughts head empty 💀

⭐ Command `nbd-server-remove` (Since: 2.12)

⚠️ also deprecated, yeah. Use block-export-del instead.

Remove NBD export by name.

Arguments

name (string) — Block export id.
mode (BlockExportRemoveMode, optional) — Mode of command operation. See BlockExportRemoveMode description. Default is 'safe'.

Features

deprecated — This command is deprecated. Use block-export-del instead.

Errors

if the server is not running
if export is not found
if mode is 'safe' and there are existing connections

💜 Command `nbd-server-stop` (Since: 1.3)

Stop QEMU's embedded NBD server, and unregister all devices previously added via nbd-server-add. it's giving cleanup era 🧹

🔥 Enum `BlockExportType` (Since: 4.2)

An enumeration of block export types, aka the menu of export flavors ✨

Values

nbd — NBD export
vhost-user-blk — vhost-user-blk export (since 5.2)
fuse — FUSE export (since: 6.0)
vduse-blk — vduse-blk export (since 7.1)

👑 Object `BlockExportOptions` (Since: 4.2)

Describes a block export, i.e. how a single node should be exported on an external interface. main character object fr fr 💅

Members

type (BlockExportType) — Block export type
id (string) — A unique identifier for the block export (across all export types)
node-name (string) — The node name of the block node to be exported (since: 5.2)
writable (boolean, optional) — True if clients should be able to write to the export (default false)
writethrough (boolean, optional) — If true, caches are flushed after every write request to the export before completion is signalled. (since: 5.2; default: false)
iothread (BlockExportIothreads, optional) — The name(s) of one or more iothread object(s) where the export will run. The default is to use the thread currently associated with the block node. (since: 5.2; multi-threading since 10.1)
fixed-iothread (boolean, optional) — True prevents the block node from being moved to another thread while the export is active. If true and iothread is given, export creation fails if the block node cannot be moved to the iothread. Must not be true when giving multiple iothreads for iothread. The default is false. (since: 5.2)
allow-inactive (boolean, optional) — If true, the export allows the exported node to be inactive. If it is created for an inactive block node, the node remains inactive. If the export type doesn't support running on an inactive node, an error is returned. If false, inactive block nodes are automatically activated before creating the export and trying to inactivate them later fails. (since: 10.0; default: false)
When type is nbd: The members of BlockExportOptionsNbd.
When type is vhost-user-blk: The members of BlockExportOptionsVhostUserBlk.
When type is fuse: The members of BlockExportOptionsFuse.
When type is vduse-blk: The members of BlockExportOptionsVduseBlk.

🦋 Alternate `BlockExportIothreads` (Since: 10.1)

Specify a single or multiple I/O threads in which to run a block export's I/O. pick your fighter 🥊

Alternatives

single (string) — Run the export's I/O in the given single I/O thread.
multi ([string]) — Use multi-threading across the given set of I/O threads, which must not be empty. Note: Passing a single I/O thread via this variant is still treated as multi-threading, which is different from using the single variant. In particular, even if there only is a single I/O thread in the set, export types that do not support multi-threading will generally reject this variant, and BlockExportOptions.fixed-iothread is always incompatible with it.

🎀 Command `block-export-add` (Since: 5.2)

Creates a new block export.

Arguments

The members of BlockExportOptions.

🌸 Command `block-export-del` (Since: 5.2)

Request to remove a block export. This drops the user's reference to the export, but the export may still stay around after this command returns until the shutdown of the export has completed. so like… it's not gone-gone yet, iykyk 🫠

Arguments

id (string) — Block export id.
mode (BlockExportRemoveMode, optional) — Mode of command operation. See BlockExportRemoveMode description. Default is 'safe'.

Errors

if the export is not found
if mode is 'safe' and the export is still in use (e.g. by existing client connections)

💖 Event `BLOCK_EXPORT_DELETED` (Since: 5.2)

Emitted when a block export is removed and its id can be reused. recycling era ♻️

Members

id (string) — Block export id.

🍓 Object `BlockExportInfo` (Since: 5.2)

Information about a single block export.

Members

id (string) — The unique identifier for the block export
type (BlockExportType) — The block export type
node-name (string) — The node name of the block node that is exported
shutting-down (boolean) — True if the export is shutting down (e.g. after a block-export-del command, but before the shutdown has completed)

💫 Command `query-block-exports` (Since: 5.2)

Return [BlockExportInfo] — A list describing all block exports ✨

🌸 CHARACTER DEVICES 🌸

🎀 Object `ChardevInfo` (Since: 0.14)

Information about a character device.

Members

label (string) — the label of the character device
filename (string) — the filename of the character device
frontend-open (boolean) — shows whether the frontend device attached to this backend (e.g. with the chardev=... option) is in open or closed state (since 2.1)

💡 Note: filename is encoded using the QEMU command line character device encoding. See the QEMU man page for details.

🧚 Command `query-chardev` (Since: 0.14)

Return information about current character devices. go off bestie 🫶

Return [ChardevInfo]

Example:

-> { "execute": "query-chardev" }
<- {
      "return": [
         {
            "label": "charchannel0",
            "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
            "frontend-open": false
         },
         {
            "label": "charmonitor",
            "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
            "frontend-open": true
         },
         {
            "label": "charserial0",
            "filename": "pty:/dev/pts/2",
            "frontend-open": true
         }
      ]
   }

🔥 Object `ChardevBackendInfo` (Since: 2.0)

Information about a character device backend 💅

Members

name (string) — The backend name

🌈 Command `query-chardev-backends` (Since: 2.0)

Return information about character device backends.

Return [ChardevBackendInfo]

Example:

-> { "execute": "query-chardev-backends" }
<- {
      "return":[
         {
            "name":"udp"
         },
         {
            "name":"tcp"
         },
         {
            "name":"unix"
         },
         {
            "name":"spiceport"
         }
      ]
   }

That's the whole roster of backends your QEMU knows about, bestie — ask and it dumps the list 💅

💖 Enum `DataFormat` (Since: 1.4)

It's literally just "which format is this data in," and there are exactly two answers 🎀

Values

utf8 — the data is a UTF-8 string (RFC 3629)
base64 — the data is Base64-encoded binary (RFC 3548)

🦋 Command `ringbuf-write` (Since: 1.4)

Write stuff into a ring buffer character device. That's the whole job, she's simple, she's iconic ✨

Arguments

device (string) — the ring buffer character device name
data (string) — data to write
format (DataFormat, optional) — data encoding, default 'utf8'.
- base64: data must be base64-encoded text. Its binary decoding gets written.
- utf8: data's UTF-8 encoding is written.
- data itself is always Unicode regardless of format, like any other string.

Example:

-> { "execute": "ringbuf-write",
     "arguments": { "device": "foo",
                    "data": "abcdefgh",
                    "format": "utf8" } }
<- { "return": {} }

🌸 Command `ringbuf-read` (Since: 1.4)

Read back out of a ring buffer character device. Grab your snack, this one has lore 🍓

Arguments

device (string) — the ring buffer character device name
size (int) — how many bytes to read at most
format (DataFormat, optional) — data encoding, default 'utf8'.
- base64: the data read is returned in base64 encoding.
- utf8: the data read is interpreted as UTF-8. Bug: can screw up when the buffer contains invalid UTF-8 sequences, NUL characters, after the ring buffer lost data, and when reading stops because the size limit is reached.
- The return value is always Unicode regardless of format, like any other string.

Return string — data read from the device

Example:

-> { "execute": "ringbuf-read",
     "arguments": { "device": "foo",
                    "size": 1000,
                    "format": "utf8" } }
<- { "return": "abcdefgh" }

⚠️ Not me warning you twice: that utf8 bug list is real. Invalid UTF-8, NULs, post-data-loss reads, and size-limited reads can all come out cursed 😭

👑 Object `ChardevCommon` (Since: 2.6)

The configuration every single chardev backend shares. Think of it as the group chat everyone's in 🫶

Members

logfile (string, optional) — the name of a logfile to save output
logappend (boolean, optional) — true to append instead of truncate (defaults to false to truncate)
logtimestamp (boolean, optional) — true to insert timestamps into the logfile (default false) (since 11.0)

💜 Object `ChardevFile` (Since: 1.4)

Config info for file chardevs. Very "just write it to a file" of her 💅

Members

in (string, optional) — the name of the input file
out (string) — the name of the output file
append (boolean, optional) — open the file in append mode (default false to truncate) (Since 2.6)
The members of ChardevCommon.

⭐ Object `ChardevHostdev` (Since: 1.4)

Config info for device and pipe chardevs. Host device era ✨

Members

device (string) — the name of the special file for the device, i.e. /dev/ttyS0 on Unix or COM1: on Windows
The members of ChardevCommon.

🔥 Object `ChardevSocket` (Since: 1.4)

Config info for (stream) socket chardevs. Big one, lots of knobs, stay with me 🌈

Members

addr (SocketAddressLegacy) — socket address to listen on (server=true) or connect to (server=false)
tls-creds (string, optional) — the ID of the TLS credentials object (since 2.6)
tls-authz (string, optional) — the ID of the QAuthZ authorization object against which the client's x509 distinguished name will be validated. This object is only resolved at time of use, so it can be deleted and recreated on the fly while the chardev server is active. If missing, it will default to denying access (since 4.0)
server (boolean, optional) — create server socket (default: true)
wait (boolean, optional) — wait for incoming connection on server sockets (default: false). Silently ignored with server: false. This use is deprecated.
nodelay (boolean, optional) — set TCP_NODELAY socket option (default: false)
telnet (boolean, optional) — enable telnet protocol on server sockets (default: false)
tn3270 (boolean, optional) — enable tn3270 protocol on server sockets (default: false) (Since: 2.10)
websocket (boolean, optional) — enable websocket protocol on server sockets (default: false) (Since: 3.1)
reconnect-ms (int, optional) — for a client socket, if a socket is disconnected, then attempt a reconnect after the given number of milliseconds. Setting this to zero disables this function. (default: 0) (Since: 9.2)
The members of ChardevCommon.

🚨 wait is deprecated, bestie. She still works but she's on notice.

🧚 Object `ChardevUdp` (Since: 1.5)

Config info for datagram socket chardevs. Fire and forget, no cap 🎀

Members

remote (SocketAddressLegacy) — remote address
local (SocketAddressLegacy, optional) — local address
The members of ChardevCommon.

💀 Object `ChardevMux` (Since: 1.5)

Config info for mux chardevs. One chardev to rule them all 👑

Members

chardev (string) — name of the base chardev
The members of ChardevCommon.

🦋 Object `ChardevHub` (Since: 10.0)

Config info for hub chardevs. Mux's extroverted cousin 🌸

Members

chardevs ([string]) — IDs to be added to this hub (maximum 4 devices)
The members of ChardevCommon.

💡 Four. Max. That's the limit, don't push her.

🍓 Object `ChardevStdio` (Since: 1.5)

Config info for stdio chardevs. Classic, timeless, still serving 🫶

Members

signal (boolean, optional) — allow signals (such as SIGINT triggered by ^C) be delivered to QEMU. Default: true.
The members of ChardevCommon.

💅 Object `ChardevSpiceChannel` (Since: 1.5)

Availability: CONFIG_SPICE

Config info for spice vm channel chardevs. Spice girl behavior 🌶️

Members

type (string) — kind of channel (for example vdagent)
The members of ChardevCommon.

✨ Object `ChardevSpicePort` (Since: 1.5)

Availability: CONFIG_SPICE

Config info for spice port chardevs.

Members

fqdn (string) — name of the channel (see docs/spice-port-fqdn.txt)
The members of ChardevCommon.

🎀 Enum `ChardevVCEncoding` (Since: 11.1)

The character encoding the guest is expected to use on a virtual console. Yes, guest encoding is a whole personality trait now 💖

Values

cp437 — CP437 (8-bit Extended ASCII / VGA). Every byte maps directly to a glyph; suitable for DOS or other guests that output raw CP437.
utf8 — UTF-8. Multi-byte sequences are decoded and then mapped back to CP437 glyphs for display; unmappable codepoints are shown as '?'. Suitable for modern Linux guests.

🔥 Object `ChardevDBus` (Since: 7.0)

Availability: CONFIG_DBUS_DISPLAY

Config info for DBus chardevs. Bus girlie 💜

Members

name (string) — name of the channel (following docs/spice-port-fqdn.txt)
encoding (ChardevVCEncoding, optional) — character encoding the guest is expected to use (since 11.1)
The members of ChardevCommon.

👑 Object `ChardevVC` (Since: 1.5)

Config info for virtual console chardevs. The graphics-adjacent one ⭐

Members

width (int, optional) — console width, in pixels
height (int, optional) — console height, in pixels
cols (int, optional) — console width, in chars
rows (int, optional) — console height, in chars
encoding (ChardevVCEncoding, optional) — character encoding the guest is expected to use (since 11.1)
The members of ChardevCommon.

Note: the options are only effective when the VNC or SDL graphical display backend is active. They are ignored with the GTK, Spice, VNC and D-Bus display backends.

🙈 And yes — VNC is straight up in both lists. That's what the page says, I'm not fighting it, I'm just the messenger. Read it twice if you need to, iykyk.

🌈 Object `ChardevRingbuf` (Since: 1.5)

Config info for ring buffer chardevs. The one behind ringbuf-write and ringbuf-read up there 🔁

Members

size (int, optional) — ring buffer size, must be power of two, default is 65536
The members of ChardevCommon.

⚠️ Must be a power of two. 65536 is, 1000 is not. Do the math, bestie 😭

🫶 Object `ChardevQemuVDAgent` (Since: 6.1)

Availability: CONFIG_SPICE_PROTOCOL

Config info for QEMU vdagent implementation. Clipboard and mouse duties 🖱️

Members

mouse (boolean, optional) — enable/disable mouse, default is enabled.
clipboard (boolean, optional) — enable/disable clipboard, default is disabled.
The members of ChardevCommon.

💡 Mouse on by default, clipboard off by default. Two very different defaults, two very different vibes.

🧚 Object `ChardevPty` (Since: 9.2)

Config info for pty implementation. Pseudo-terminal realness 🎀

Members

path (string, optional) — optional path to create a symbolic link that points to the allocated PTY
The members of ChardevCommon.

💀 Enum `ChardevBackendKind` (Since: 1.4)

The list of backend kinds, and she's still going 🦋

Values

file — regular files
serial — serial host device
parallel — parallel host device
pipe — pipes (since 1.5)
socket — stream socket
udp — datagram socket (since 1.5)
pty — pseudo-terminal
null — provides no input, throws away output (it's giving black hole, honestly iconic)
mux — (since 1.5)
hub — (since 10.0)
msmouse — emulated Microsoft serial mouse (since 1.5)
wctablet — emulated Wacom Penpartner serial tablet (since 2.9)
braille — Baum Braille device (since 1.5)
testdev — device for test-suite control (since 2.2)
stdio — standard I/O (since 1.5)
console — Windows console (since 1.5)
spicevmc — spice vm channel (since 1.5)
spiceport — Spice port channel (since 1.5)
qemu-vdagent — Spice vdagent (since 6.1)
dbus — D-Bus channel (since 7.0)
vc — virtual console (since 1.5)
ringbuf — memory ring buffer (since 1.6)
memory — synonym for ringbuf (since 1.5)

🎀 Features

deprecated — member memory is deprecated. Use ringbuf instead. Like bestie, it still works, but it's on its way out, so switch already 💅

🌸 Object `ChardevFileWrapper` (Since: 1.4)

Members

data (ChardevFile) — configuration info for file chardevs

🌸 Object `ChardevHostdevWrapper` (Since: 1.4)

Members

data (ChardevHostdev) — configuration info for device and pipe chardevs

🌸 Object `ChardevSocketWrapper` (Since: 1.4)

Members

data (ChardevSocket) — configuration info for (stream) socket chardevs

🌸 Object `ChardevUdpWrapper` (Since: 1.5)

Members

data (ChardevUdp) — configuration info for datagram socket chardevs

🌸 Object `ChardevCommonWrapper` (Since: 2.6)

Members

data (ChardevCommon) — configuration shared across all chardev backends

🌸 Object `ChardevMuxWrapper` (Since: 1.5)

Members

data (ChardevMux) — configuration info for mux chardevs

🌸 Object `ChardevHubWrapper` (Since: 10.0)

Members

data (ChardevHub) — configuration info for hub chardevs

🌸 Object `ChardevStdioWrapper` (Since: 1.5)

Members

data (ChardevStdio) — configuration info for stdio chardevs

🌸 Object `ChardevSpiceChannelWrapper` (Since: 1.5)

Availability: CONFIG_SPICE (and yeah, the doc generator coughed up .INDENT 7.0 right after that — that's a formatting artifact, not a config flag, bestie, ignore the noise 🙈)

Members

data (ChardevSpiceChannel) — configuration info for spice vm channel chardevs

🌸 Object `ChardevSpicePortWrapper` (Since: 1.5)

Availability: CONFIG_SPICE (same .INDENT 7.0 laboring under a formatting mishap, don't @ me)

Members

data (ChardevSpicePort) — configuration info for spice port chardevs

🌸 Object `ChardevQemuVDAgentWrapper` (Since: 6.1)

Availability: CONFIG_SPICE_PROTOCOL (yep, with that same .INDENT 7.0 artifact trailing it)

Members

data (ChardevQemuVDAgent) — configuration info for QEMU vdagent implementation

🌸 Object `ChardevDBusWrapper` (Since: 7.0)

Availability: CONFIG_DBUS_DISPLAY (.INDENT 7.0 again — it's a whole thing 🙈)

Members

data (ChardevDBus) — configuration info for DBus chardevs

🌸 Object `ChardevVCWrapper` (Since: 1.5)

Members

data (ChardevVC) — configuration info for virtual console chardevs

🌸 Object `ChardevRingbufWrapper` (Since: 1.5)

Members

data (ChardevRingbuf) — configuration info for ring buffer chardevs

🌸 Object `ChardevPtyWrapper` (Since: 9.2)

Members

data (ChardevPty) — configuration info for pty chardevs

👑 Object `ChardevBackend` (Since: 1.4)

Configuration info for the new chardev backend. Okay this is the big one, the main character of the whole section ✨

Members

type (ChardevBackendKind) — backend type
When type is file: the members of ChardevFileWrapper.
When type is serial: the members of ChardevHostdevWrapper.
When type is parallel: the members of ChardevHostdevWrapper.
When type is pipe: the members of ChardevHostdevWrapper.
When type is socket: the members of ChardevSocketWrapper.
When type is udp: the members of ChardevUdpWrapper.
When type is pty: the members of ChardevPtyWrapper.
When type is null: the members of ChardevCommonWrapper.
When type is mux: the members of ChardevMuxWrapper.
When type is hub: the members of ChardevHubWrapper.
When type is msmouse: the members of ChardevCommonWrapper.
When type is wctablet: the members of ChardevCommonWrapper.
When type is braille: the members of ChardevCommonWrapper.
When type is testdev: the members of ChardevCommonWrapper.
When type is stdio: the members of ChardevStdioWrapper.
When type is console: the members of ChardevCommonWrapper.
When type is spicevmc: the members of ChardevSpiceChannelWrapper.
When type is spiceport: the members of ChardevSpicePortWrapper.
When type is qemu-vdagent: the members of ChardevQemuVDAgentWrapper.
When type is dbus: the members of ChardevDBusWrapper.
When type is vc: the members of ChardevVCWrapper.
When type is ringbuf: the members of ChardevRingbufWrapper.
When type is memory: the members of ChardevRingbufWrapper.

✅ Object `ChardevReturn` (Since: 1.4)

Return info about the chardev backend just created. Receipts, basically 🧾

Members

pty (string, optional) — name of the slave pseudoterminal device, present if and only if a chardev of type 'pty' was created. No pty, no pty field, periodt.

💖 Command `chardev-add` (Since: 1.4)

Add a character device backend. Fresh chardev, just dropped 🎀

Arguments

id (string) — the chardev's ID, must be unique
backend (ChardevBackend) — backend type and parameters

Return ChardevReturn

Example:

-> { "execute" : "chardev-add",
     "arguments" : { "id" : "foo",
                     "backend" : { "type" : "null", "data" : {} } } }
<- { "return": {} }

Example:

-> { "execute" : "chardev-add",
     "arguments" : { "id" : "bar",
                     "backend" : { "type" : "file",
                                   "data" : { "out" : "/tmp/bar.log" } } } }
<- { "return": {} }

Example:

-> { "execute" : "chardev-add",
     "arguments" : { "id" : "baz",
                     "backend" : { "type" : "pty", "data" : {} } } }
<- { "return": { "pty" : "/dev/pty/42" } }

🔥 Command `chardev-change` (Since: 2.10)

Change a character device backend. Same chardev, new fit — glow-up command fr fr 💅

Arguments

id (string) — the chardev's ID
backend (ChardevBackend) — new backend type and parameters

Return ChardevReturn

Example:

-> { "execute" : "chardev-change",
     "arguments" : { "id" : "baz",
                     "backend" : { "type" : "pty", "data" : {} } } }
<- { "return": { "pty" : "/dev/pty/42" } }

Example:

-> {"execute" : "chardev-change",
    "arguments" : {
        "id" : "charchannel2",
        "backend" : {
            "type" : "socket",
            "data" : {
                "addr" : {
                    "type" : "unix" ,
                    "data" : {
                        "path" : "/tmp/charchannel2.socket"
                    }
                 },
                 "server" : true,
                 "wait" : false }}}}
<- {"return": {}}

🦋 Command `chardev-remove` (Since: 1.4)

Remove a character device backend. It's gone, it's deleted, we don't know her 😭

Arguments

id (string) — the chardev's ID, must not be in use

Example:

-> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
<- { "return": {} }

⭐ Command `chardev-send-break` (Since: 2.10)

Send a break to a character device. Not a heartbreak, a serial break — very different vibe 💀

Arguments

id (string) — the chardev's ID

Example:

-> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
<- { "return": {} }

🌈 Event `VSERPORT_CHANGE` (Since: 2.1)

Emitted when the guest opens or closes a virtio-serial port. Little notification, big feelings 🫶

Members

id (string) — device identifier of the virtio-serial port
open (boolean) — true if the guest has opened the virtio-serial port

Note: this event is rate-limited. So no, it's not gonna spam you, bestie — it's on its best behavior ✨

Example:

<- { "event": "VSERPORT_CHANGE",
     "data": { "id": "channel0", "open": true },
     "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }

✨ DUMP GUEST MEMORY ✨

Enum DumpGuestMemoryFormat (Since: 2.0)

okay so this is literally the list of formats that dump-guest-memory can spit out. bestie, it's giving ✨menu✨.

Values

elf — elf format, the classic, the icon 💅
kdump-zlib — makedumpfile flattened, kdump-compressed format with zlib compression
kdump-lzo — makedumpfile flattened, kdump-compressed format with lzo compression
kdump-snappy — makedumpfile flattened, kdump-compressed format with snappy compression
kdump-raw-zlib — raw assembled kdump-compressed format with zlib compression (since 8.2)
kdump-raw-lzo — raw assembled kdump-compressed format with lzo compression (since 8.2)
kdump-raw-snappy — raw assembled kdump-compressed format with snappy compression (since 8.2)
win-dmp — Windows full crashdump format, can be used instead of ELF converting (since 2.13)

Features

allowed-by-guest — If present, win-dmp is listed by query-dump-guest-memory-capability, and accepted by dump-guest-memory, only when the guest has published a Windows dump header through the vmcoreinfo device (since 11.1)

Command dump-guest-memory (Since: 1.2)

Dump guest's memory to vmcore. Heads up though: it is a synchronous operation that can take very long depending on the amount of guest memory. like, go make a snack, fr fr. 😭

Arguments

paging (boolean) —

if true, do paging to get guest's memory mapping. This allows using gdb to process the core file.

Important: this option can make QEMU allocate several gigabytes of RAM. This can happen for a large guest, or a malicious guest pretending to be large. 💀

Also, paging=true has the following limitations:

The guest may be in a catastrophic state or can have corrupted memory, which cannot be trusted
The guest can be in real-mode even if paging is enabled. For example, the guest uses ACPI to sleep, and ACPI sleep state goes in real-mode
Currently only supported on i386 and x86_64.

protocol (string) —

the filename or file descriptor of the vmcore. The supported protocols are:

file: the protocol starts with "file:", and the following string is the file's path.
fd: the protocol starts with "fd:", and the following string is the fd's name.

detach (boolean, optional) — if true, QMP will return immediately rather than waiting for the dump to finish. The user can track progress using query-dump. (since 2.6). no more staring at the terminal bestie 🫶
begin (int, optional) — if specified, the starting physical address.
length (int, optional) — if specified, the memory size, in bytes. If you don't want to dump all guest's memory, please specify the start begin and length
format (DumpGuestMemoryFormat, optional) — if specified, the format of guest memory dump. But non-elf format is conflict with paging and filter, ie. paging, begin and length is not allowed to be specified with non-elf format at the same time (since 2.0)

Note: All boolean arguments default to false.

Example:

-> { "execute": "dump-guest-memory",
     "arguments": { "paging": false, "protocol": "fd:dump" } }
<- { "return": {} }

Enum DumpStatus (Since: 2.6)

Describe the status of a long-running background guest memory dump. the vibe check for your dump 🔍

Values

none — no dump-guest-memory has started yet.
active — there is one dump running in background.
completed — the last dump has finished successfully. slay 🎉
failed — the last dump has failed. 🙈

Object DumpQueryResult (Since: 2.6)

The result format for query-dump.

Members

status (DumpStatus) — enum of DumpStatus, which shows current dump status
completed (int) — bytes written in latest dump (uncompressed)
total (int) — total bytes to be written in latest dump (uncompressed)

Command query-dump (Since: 2.6)

Query latest dump status.

Return DumpQueryResult — An object showing the dump status.

Example:

-> { "execute": "query-dump" }
<- { "return": { "status": "active", "completed": 1024000,
                 "total": 2048000 } }

Event DUMP_COMPLETED (Since: 2.6)

Emitted when background dump has completed. it's giving "we are so back" energy ✨

Members

result (DumpQueryResult) — final dump status
error (string, optional) — human-readable error string that provides hint on why dump failed. Only presents on failure. The user should not try to interpret the error string. just... don't look at it directly, bestie 😭

Example:

<- { "event": "DUMP_COMPLETED",
     "data": { "result": { "total": 1090650112, "status": "completed",
                           "completed": 1090650112 } },
     "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }

Object DumpGuestMemoryCapability (Since: 2.0)

Members

formats ([DumpGuestMemoryFormat]) — the available formats for dump-guest-memory

Command query-dump-guest-memory-capability (Since: 2.0)

Return the available formats for dump-guest-memory

Return DumpGuestMemoryCapability — An object listing available formats for dump-guest-memory

Example:

-> { "execute": "query-dump-guest-memory-capability" }
<- { "return": { "formats":
                 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }

🌐 NET DEVICES 🌐

Command set_link (Since: 0.14)

Sets the link status of a virtual network adapter. like unplugging the cable but make it software 💅

Arguments

name (string) — the device name of the virtual network adapter
up (boolean) — true to set the link status to be up

Errors

If name is not a valid network device, DeviceNotFound

Note: Not all network adapters support setting link status. This command will succeed even if the network adapter does not support link status notification. (iconic "no thoughts, head empty" behaviour ngl)

Example:

-> { "execute": "set_link",
     "arguments": { "name": "e1000.0", "up": false } }
<- { "return": {} }

Command netdev_add (Since: 0.14)

Add a network backend.

Additional arguments depend on the type.

Arguments

The members of Netdev.

Errors

If type is not a valid network backend, DeviceNotFound

Example:

-> { "execute": "netdev_add",
     "arguments": { "type": "user", "id": "netdev1",
                    "dnssearch": [ { "str": "example.org" } ] } }
<- { "return": {} }

Command netdev_del (Since: 0.14)

Remove a network backend. bye bestie 👋

Arguments

id (string) — the name of the network backend to remove

Errors

If id is not a valid network backend, DeviceNotFound

Example:

-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
<- { "return": {} }

Object NetLegacyNicOptions (Since: 1.2)

Create a new Network Interface Card.

Members

netdev (string, optional) — id of -netdev to connect to
macaddr (string, optional) — MAC address
model (string, optional) — device model (e1000, rtl8139, virtio etc.)
addr (string, optional) — PCI device address
vectors (int, optional) — number of MSI-x vectors, 0 to disable MSI-X

Object PasstSearch (Since: 10.1)

Members

str (string) — DNS domain name suffix for host name lookup, or "none". See passt(1) option --search.

Object PasstPortForward (Since: 10.1)

Members

str (string) — passt port forwarding specification, see passt(1) option --tcp-ports and --udp-ports.

Object PasstParameter (Since: 10.1)

Members

str (string) — Additional arguments for the passt executable, see passt(1)

Object NetdevPasstOptions (Since: 10.1)

Availability: CONFIG_PASST

Unprivileged user-mode network connectivity using passt 🍓 (no root, no drama)

Members

path (string, optional) — Filename of the passt program to run (by default 'passt', and use PATH)
quiet (boolean, optional) — don't print informational messages (default, passed as '--quiet')
vhost-user (boolean, optional) — enable vhost-user
mtu (int, optional) — assign MTU via DHCP/NDP
address (string, optional) — IPv4 or IPv6 address
netmask (string, optional) — IPv4 mask
mac (string, optional) — source MAC address
gateway (string, optional) — IPv4 or IPv6 address as gateway
interface (string, optional) — interface for addresses and routes
outbound (string, optional) — bind to address as outbound source
outbound-if4 (string, optional) — bind to outbound interface for IPv4
outbound-if6 (string, optional) — bind to outbound interface for IPv6
dns (string, optional) — IPv4 or IPv6 address as DNS
search ([PasstSearch], optional) — search domains
fqdn (string, optional) — FQDN to configure client with
dhcp-dns (boolean, optional) — the enable/disable switch for the DNS list in DHCP/DHCPv6/NDP.
dhcp-search (boolean, optional) — the enable/disable switch for the list in DHCP/DHCPv6/NDP.
map-host-loopback (string, optional) — the addresse to refer to the host (yes, that spelling is straight from the source, bestie 💅).
map-guest-addr (string, optional) — the addr to translate to the guest’s address.
dns-forward (string, optional) — where DNS queries sent out get forwarded to.
dns-host (string, optional) — the host nameserver to direct queries to.
tcp (boolean, optional) — enable/disable TCP.
udp (boolean, optional) — enable/disable UDP.
icmp (boolean, optional) — enable/disable ICMP.
dhcp (boolean, optional) — enable/disable DHCP.
ndp (boolean, optional) — enable/disable NDP.
dhcpv6 (boolean, optional) — enable/disable DHCPv6.
ra (boolean, optional) — enable/disable route advertisements.
freebind (boolean, optional) — bind to any address for forwarding.
ipv4 (boolean, optional) — enable/disable IPv4.
ipv6 (boolean, optional) — enable/disable IPv6.
tcp-ports ([PasstPortForward], optional) — TCP ports to forward.
udp-ports ([PasstPortForward], optional) — UDP ports to forward.
param ([PasstParameter], optional) — parameter to pass to the passt command.

🦋 Object `NetdevUserDomainSuffix` (Since: 1.2)

Members

str (string) — DNS domain name suffix for host name lookup, similar to resolv.conf(5).

🎀 Object `NetdevUserHostForward` (Since: 1.2)

Members

str (string) — Host port forwarding rule.

🫶 Object `NetdevUserGuestForward` (Since: 1.2)

Members

str (string) — Guest port forwarding rule.

✨ Object `NetdevUserOptions` (Since: 1.2)

This is the user-mode network stack — the one that requires no administrator privilege to run.

Members

hostname (string, optional) — client hostname reported by the builtin DHCP server.
restrict (boolean, optional) — isolate the guest from the host.
ipv4 (boolean, optional) — whether to support IPv4; default true for enabled (since 2.6).
ipv6 (boolean, optional) — whether to support IPv6; default true for enabled (since 2.6).
ip (string, optional) — legacy parameter, use net= instead.
net (string, optional) — IP network address that the guest will see, in the form addr[/netmask]. The netmask is optional, and can be either in the form a.b.c.d or as a number of valid top-most bits. Default is 10.0.2.0/24.
host (string, optional) — guest-visible address of the host.
tftp (string, optional) — root directory of the built-in TFTP server.
bootfile (string, optional) — BOOTP filename, for use with tftp=.
dhcpstart (string, optional) — the first of the 16 IPs the built-in DHCP server can assign.
dns (string, optional) — guest-visible address of the virtual nameserver.
dnssearch ([NetdevUserDomainSuffix], optional) — list of DNS suffixes to search, passed as a DHCP option to the guest.
domainname (string, optional) — guest-visible domain name of the virtual nameserver (since 3.0).
ipv6-prefix (string, optional) — IPv6 network prefix (default is fec0::). The network prefix is given in the usual hexadecimal IPv6 address notation. (since 2.6)
ipv6-prefixlen (int, optional) — IPv6 network prefix length (default is 64) (since 2.6).
ipv6-host (string, optional) — guest-visible IPv6 address of the host (since 2.6).
ipv6-dns (string, optional) — guest-visible IPv6 address of the virtual nameserver (since 2.6).
smb (string, optional) — root directory of the built-in SMB server.
smbserver (string, optional) — IP address of the built-in SMB server.
hostfwd ([NetdevUserHostForward], optional) — redirect incoming TCP, UDP or UNIX host connections to guest endpoints.
guestfwd ([NetdevUserGuestForward], optional) — forward guest TCP connections.
tftp-server-name (string, optional) — RFC2132 "TFTP server name" string (Since 3.1).

🐚 Object `NetdevTapOptions` (Since: 1.2)

This one configures a host TAP network interface backend.

Members

ifname (string, optional) — interface name.
fd (string, optional) — file descriptor of an already opened tap.
fds (string, optional) — multiple file descriptors of already opened multiqueue capable tap.
script (string, optional) — script to initialize the interface.
downscript (string, optional) — script to shut down the interface.
br (string, optional) — bridge name (since 2.8).
helper (string, optional) — command to execute to configure bridge.
sndbuf (int, optional) — send buffer limit. Understands [TGMKkb] suffixes.
vnet_hdr (boolean, optional) — enable the IFF_VNET_HDR flag on the tap interface.
vhost (boolean, optional) — enable vhost-net network accelerator.
vhostfd (string, optional) — file descriptor of an already opened vhost net device.
vhostfds (string, optional) — file descriptors of multiple already opened vhost net devices.
vhostforce (boolean, optional) — vhost on for non-MSIX virtio guests.
queues (int, optional) — number of queues to be created for multiqueue capable tap.
poll-us (int, optional) — maximum number of microseconds that could be spent on busy polling for tap (since 2.7).

🔌 Object `NetdevSocketOptions` (Since: 1.2)

Socket netdevs establish a network connection to another QEMU virtual machine via a TCP socket.

Members

fd (string, optional) — file descriptor of an already opened socket.
listen (string, optional) — port number, and optional hostname, to listen on.
connect (string, optional) — port number, and optional hostname, to connect to.
mcast (string, optional) — UDP multicast address and port number.
localaddr (string, optional) — source address and port for multicast and udp packets.
udp (string, optional) — UDP unicast address and port number.

🧚 Object `NetdevL2TPv3Options` (Since: 2.1)

This configures an Ethernet over L2TPv3 tunnel.

Members

src (string) — source address.
dst (string) — destination address.
srcport (string, optional) — source port — mandatory for udp, optional for ip.
dstport (string, optional) — destination port — mandatory for udp, optional for ip.
ipv6 (boolean, optional) — force the use of ipv6.
udp (boolean, optional) — use the udp version of l2tpv3 encapsulation.
cookie64 (boolean, optional) — use 64 bit cookies.
counter (boolean, optional) — have sequence counter.
pincounter (boolean, optional) — pin sequence counter to zero — workaround for buggy implementations or networks with packet reorder.
txcookie (int, optional) — 32 or 64 bit transmit cookie.
rxcookie (int, optional) — 32 or 64 bit receive cookie.
txsession (int) — 32 bit transmit session.
rxsession (int, optional) — 32 bit receive session — if not specified set to the same value as transmit.
offset (int, optional) — additional offset — allows the insertion of additional application-specific data before the packet payload.

🌸 Object `NetdevVdeOptions` (Since: 1.2)

Connect to a vde switch running on the host.

Members

sock (string, optional) — socket path.
port (int, optional) — port number.
group (string, optional) — group owner of socket.
mode (int, optional) — permissions for socket.

🎀 Object `NetdevBridgeOptions` (Since: 1.2)

Connect a host TAP network interface to a host bridge device.

Members

br (string, optional) — bridge name.
helper (string, optional) — command to execute to configure bridge.

💫 Object `NetdevHubPortOptions` (Since: 1.2)

Connect two or more net clients through a software hub.

Members

hubid (int) — hub identifier number.
netdev (string, optional) — used to connect hub to a netdev instead of a device (since 2.12).

🌈 Object `NetdevNetmapOptions` (Since: 2.0)

Connect a client to a netmap-enabled NIC or to a VALE switch port.

Members

ifname (string) — either the name of a network interface that already exists and netmap supports, or the name of a VALE port (which gets created on the fly, periodt). A VALE port name looks like 'valeXXX:YYY', where XXX and YYY are non-negative integers. XXX IDs a switch and YYY IDs a port on that switch — so VALE ports sharing the same XXX are literally connected to the same switch 💅
devname (string, optional) — path of the netmap device (default: '/dev/netmap').

✨ Enum `AFXDPMode` (Since: 8.2)

Availability: CONFIG_AF_XDP

Attach mode for a default XDP program 🎀

Values

skb — generic mode, no driver support necessary
native — DRV mode, program is attached to a driver, packets are passed to the socket without allocation of skb.

🦋 Object `NetdevAFXDPOptions` (Since: 8.2)

Availability: CONFIG_AF_XDP

AF_XDP network backend 🌸

Members

ifname (string) — the name of an existing network interface.
mode (AFXDPMode, optional) — attach mode for a default XDP program. If it's not specified, then 'native' gets tried first, then 'skb'.
force-copy (boolean, optional) — force XDP copy mode even if the device supports zero-copy. (default: false)
queues (int, optional) — number of queues to be used for multiqueue interfaces (default: 1).
start-queue (int, optional) — use queues starting from this queue number (default: 0).
inhibit (boolean, optional) — don't load a default XDP program, use one that's already loaded to the interface (default: false). Requires sock-fds or map-path.
sock-fds (string, optional) — a colon (:) separated list of file descriptors for AF_XDP sockets that are already open but not bound, in queue order. One fd per queue. These descriptors should already be added into the XDP socket map for the corresponding queues. sock-fds and map-path are mutually exclusive. Requires inhibit.
map-path (string, optional) — the path to a pinned xsk map to push file descriptors for bound AF_XDP sockets into. map-path and sock-fds are mutually exclusive. Requires inhibit. (Since 10.1)
map-start-index (int, optional) — use map-path to insert xsk sockets starting from this index number (default: 0). Requires map-path. (Since 10.1)

💜 Object `NetdevVhostUserOptions` (Since: 2.1)

Vhost-user network backend 💖

Members

chardev (string) — name of a unix socket chardev
vhostforce (boolean, optional) — vhost on for non-MSIX virtio guests (default: false).
queues (int, optional) — number of queues to be created for multiqueue vhost-user (default: 1) (Since 2.5)

💀 Object `NetdevVhostVDPAOptions` (Since: 5.1)

Vhost-vdpa network backend

A vDPA device is a device that uses a datapath which complies with the virtio specifications with a vendor specific control path. iykyk 🫶

Members

vhostdev (string, optional) — path of vhost-vdpa device (default: '/dev/vhost-vdpa-0')
vhostfd (string, optional) — file descriptor of an already opened vhost vdpa device
queues (int, optional) — number of queues to be created for multiqueue vhost-vdpa (default: 1)
x-svq (boolean, optional) — start device with (experimental) shadow virtqueue. (Since 7.1) (default: false)

Features

unstable — Member x-svq is experimental.

🚨 heads up bestie: that x-svq member is flagged experimental. It's giving "handle with care".

🌈 Object `NetdevVmnetHostOptions` (Since: 7.1)

Availability: CONFIG_VMNET

vmnet (host mode) network backend.

Lets the vmnet interface talk to other vmnet interfaces that are in host mode, and also to the host itself ✨

Members

start-address (string, optional) — the starting IPv4 address to use for the interface. Must be in the private IP range (RFC 1918). Must be specified along with end-address and subnet-mask. This address is used as the gateway address. The subsequent address up to and including end-address are placed in the DHCP pool.
end-address (string, optional) — the DHCP IPv4 range end address to use for the interface. Must be in the private IP range (RFC 1918). Must be specified along with start-address and subnet-mask.
subnet-mask (string, optional) — the IPv4 subnet mask to use on the interface. Must be specified along with start-address and subnet-mask.
isolated (boolean, optional) — enable isolation for this interface. Interface isolation ensures that the vmnet interface is not able to communicate with any other vmnet interfaces. Only communication with host is allowed. Requires at least macOS Big Sur 11.0.
net-uuid (string, optional) — the identifier (UUID) to uniquely identify the isolated network this vmnet interface should be added to. If set, no DHCP service is provided for this interface and network communication is allowed only with other interfaces added to this network identified by the UUID. Requires at least macOS Big Sur 11.0.

⭐ Object `NetdevVmnetSharedOptions` (Since: 7.1)

Availability: CONFIG_VMNET

vmnet (shared mode) network backend.

Lets traffic coming from the vmnet interface reach the Internet through a network address translator (NAT) 🦋. The vmnet interface can communicate with the host and with other shared mode interfaces on the same subnet. If no DHCP settings, subnet mask and IPv6 prefix are specified, the interface can communicate with any of the other interfaces in shared mode.

Members

start-address (string, optional) — the starting IPv4 address to use for the interface. Must be in the private IP range (RFC 1918). Must be specified along with end-address and subnet-mask. This address is used as the gateway address. The subsequent address up to and including end-address are placed in the DHCP pool.
end-address (string, optional) — the DHCP IPv4 range end address to use for the interface. Must be in the private IP range (RFC 1918). Must be specified along with start-address and subnet-mask.
subnet-mask (string, optional) — the IPv4 subnet mask to use on the interface. Must be specified along with start-address and subnet-mask.
isolated (boolean, optional) — enable isolation for this interface. Interface isolation ensures that the vmnet interface is not able to communicate with any other vmnet interfaces. Only communication with host is allowed. Requires at least macOS Big Sur 11.0.
nat66-prefix (string, optional) — the IPv6 prefix to use into guest network. Must be a unique local address i.e. start with fd00::/8 and have length of 64.

🎀 Object `NetdevVmnetBridgedOptions` (Since: 7.1)

Availability: CONFIG_VMNET

vmnet (bridged mode) network backend.

Bridges the vmnet interface with a physical network interface 🔥

Members

ifname (string) — the name of the physical interface to be bridged.
isolated (boolean, optional) — enable isolation for this interface. Interface isolation ensures that the vmnet interface is not able to communicate with any other vmnet interfaces. Only communication with host is allowed. Requires at least macOS Big Sur 11.0.

🍓 Object `NetdevStreamOptions` (Since: 7.2)

Configuration info for stream socket netdev 🌸

Members

addr (SocketAddress) — socket address to listen on (server=true) or connect to (server=false)
server (boolean, optional) — create server socket (default: false)
reconnect-ms (int, optional) — for a client socket, if a socket is disconnected, then attempt a reconnect after the given number of milliseconds. Setting this to zero disables this function. (default: 0) (Since: 9.2)

Only SocketAddress types 'unix', 'inet' and 'fd' are supported. Don't come at me with anything else 🙈

🧚 Object `NetdevDgramOptions` (Since: 7.2)

Configuration info for datagram socket netdev.

Members

remote (SocketAddress, optional) — remote address
local (SocketAddress, optional) — local address

Only SocketAddress types 'unix', 'inet' and 'fd' are supported.

If the remote address is present and it's a multicast address, the local address is optional. Otherwise the local address is required and the remote address is optional. periodt 💅

💫 the valid-combinations cheat sheet

okay so before we get into the enum, here's the little vibe-check table for which remote/local combos are actually legal — memorize it, bestie:

remote absent + local absent → no 🙈
remote absent + local not fd → no 🙈
remote absent + local fd → yes ✨
remote multicast + local absent → yes ✨
remote multicast + local present → yes ✨
remote not multicast + local absent → no 🙈
remote not multicast + local present → yes ✨

that's it, that's the whole grid 🫶

🌐 Enum `NetClientDriver` (Since: 2.7)

the roster of netdev drivers you can pick from. iconic lineup, honestly.

Values

l2tpv3 — since 2.1
vhost-vdpa — since 5.1
vmnet-host — since 7.1
vmnet-shared — since 7.1
vmnet-bridged — since 7.1
stream — since 7.2
dgram — since 7.2
af-xdp — since 8.2
passt — since 10.1
none — Not documented
nic — Not documented
user — Not documented
tap — Not documented
socket — Not documented
vde — Not documented
bridge — Not documented
hubport — Not documented
netmap — Not documented
vhost-user — Not documented

(the "Not documented" girlies are just out here living their truth, no lore provided 😌)

📦 Object `Netdev` (Since: 1.2)

this one captures the configuration of a network device. like a lil snapshot of how your netdev is set up 💅

Members

id (string) — identifier for monitor commands.
type (NetClientDriver) — Specify the driver used for interpreting remaining arguments.
When type is nic: The members of NetLegacyNicOptions.
When type is passt: The members of NetdevPasstOptions.
When type is user: The members of NetdevUserOptions.
When type is tap: The members of NetdevTapOptions.
When type is l2tpv3: The members of NetdevL2TPv3Options.
When type is socket: The members of NetdevSocketOptions.
When type is stream: The members of NetdevStreamOptions.
When type is dgram: The members of NetdevDgramOptions.
When type is vde: The members of NetdevVdeOptions.
When type is bridge: The members of NetdevBridgeOptions.
When type is hubport: The members of NetdevHubPortOptions.
When type is netmap: The members of NetdevNetmapOptions.
When type is af-xdp: The members of NetdevAFXDPOptions.
When type is vhost-user: The members of NetdevVhostUserOptions.
When type is vhost-vdpa: The members of NetdevVhostVDPAOptions.
When type is vmnet-host: The members of NetdevVmnetHostOptions.
When type is vmnet-shared: The members of NetdevVmnetSharedOptions.
When type is vmnet-bridged: The members of NetdevVmnetBridgedOptions.

so basically type is the main character and every other field is just the entourage that shows up with it 😭

🦋 Enum `RxState` (Since: 1.6)

packets receiving state — i.e. what the NIC is willing to accept, vibe-wise.

Values

normal — filter assigned packets according to the mac-table
none — don't receive any assigned packet
all — receive all assigned packets

three moods, pick one 💫

🎀 Object `RxFilterInfo` (Since: 1.6)

rx-filter info for a NIC. receipts, basically 💅

Members

name (string) — net client name
promiscuous (boolean) — whether promiscuous mode is enabled
multicast (RxState) — multicast receive state
unicast (RxState) — unicast receive state
vlan (RxState) — vlan receive state (Since 2.0)
broadcast-allowed (boolean) — whether to receive broadcast
multicast-overflow (boolean) — multicast table is overflowed or not
unicast-overflow (boolean) — unicast table is overflowed or not
main-mac (string) — the main macaddr string
vlan-table ([int]) — a list of active vlan id
unicast-table ([string]) — a list of unicast macaddr string
multicast-table ([string]) — a list of multicast macaddr string

okay the *-overflow booleans are lowkey the drama of this object — if those flip true, bestie, your table is full 😭

🔍 Command `query-rx-filter` (Since: 1.6)

Return rx-filter information for all NICs (or for the given NIC).

Arguments

name (string, optional) — net client name

Return [RxFilterInfo] — list of info for all NICs (or for the given NIC).

Errors

if the given name doesn't exist
if the given NIC doesn't support rx-filter querying
if the given net client isn't a NIC

like, three whole ways to fail, we love a command with boundaries 🙈

Example:

-> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
<- { "return": [
        {
            "promiscuous": true,
            "name": "vnet0",
            "main-mac": "52:54:00:12:34:56",
            "unicast": "normal",
            "vlan": "normal",
            "vlan-table": [
                4,
                0
            ],
            "unicast-table": [
            ],
            "multicast": "normal",
            "multicast-overflow": false,
            "unicast-overflow": false,
            "multicast-table": [
                "01:00:5e:00:00:01",
                "33:33:00:00:00:01",
                "33:33:ff:12:34:56"
            ],
            "broadcast-allowed": false
        }
      ]
   }

not the empty unicast-table just vibing there 🫶

🔔 Event `NIC_RX_FILTER_CHANGED` (Since: 1.6)

Emitted once until the query-rx-filter command is executed, the first event will always be emitted

(read that again: once until you run query-rx-filter, and the very first event is always fired off no matter what — it's giving "i WILL get your attention" 💀)

Members

name (string, optional) — net client name
path (string) — device path

Example:

<- { "event": "NIC_RX_FILTER_CHANGED",
     "data": { "name": "vnet0",
               "path": "/machine/peripheral/vnet0/virtio-backend" },
     "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }

📣 Object `AnnounceParameters` (Since: 4.0)

Parameters for self-announce timers. yes, your VM is announcing itself, it's an influencer now ✨

Members

initial (int) — Initial delay (in ms) before sending the first GARP/RARP announcement
max (int) — Maximum delay (in ms) between GARP/RARP announcement packets
rounds (int) — Number of self-announcement attempts
step (int) — Delay increase (in ms) after each self-announcement attempt
interfaces ([string], optional) — An optional list of interface names, which restricts the announcement to the listed interfaces. (Since 4.1)
id (string, optional) — A name to be used to identify an instance of announce-timers and to allow it modified later. Not for use as part of the migration parameters. (Since 4.1)

⚠️ heads up: that id is not for use as part of the migration parameters — don't try it, it's not that kind of field 🙅‍♀️

📢 Command `announce-self` (Since: 4.0)

Trigger generation of broadcast RARP frames to update network switches. This can be useful when network bonds fail-over the active slave.

basically: your bond's active slave dipped, so you yell "I'M STILL HERE" in RARP at the switch, and the switch updates its notes. communication, queen 👑

Arguments

The members of AnnounceParameters.

Example:

-> { "execute": "announce-self",
     "arguments": {
         "initial": 50, "max": 550, "rounds": 10, "step": 50,
         "interfaces": ["vn2", "vn3"], "id": "bob" } }
<- { "return": {} }

her name is bob and she's booked for 10 rounds 💅

🤝 Event `FAILOVER_NEGOTIATED` (Since: 4.2)

Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation. Failover primary devices which were hidden (not hotplugged when requested) before will now be hotplugged by the virtio-net standby device.

translation: the primary was being shy and hiding, and now the standby device is like "bestie come OUT" and hotplugs it 🔥

Members

device-id (string) — QEMU device id of the unplugged device

Example:

<- { "event": "FAILOVER_NEGOTIATED",
     "data": { "device-id": "net1" },
     "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }

🌊 Event `NETDEV_STREAM_CONNECTED` (Since: 7.2)

Emitted when the netdev stream backend is connected. connection established, we're so back 🦋

Members

netdev-id (string) — QEMU netdev id that is connected
addr (SocketAddress) — The destination address

Example:

<- { "event": "NETDEV_STREAM_CONNECTED",
     "data": { "netdev-id": "netdev0",
               "addr": { "port": "47666", "ipv6": true,
                         "host": "::1", "type": "inet" } },
     "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }

note that "port": "47666" is a string, okay? don't come for me, that's just how SocketAddress rolls 😌

Example:

🌸 (the payload for this one slides in right after — hold please)

<- { "event": "NETDEV_STREAM_CONNECTED",
     "data": { "netdev-id": "netdev0",
               "addr": { "path": "/tmp/qemu0", "type": "unix" } },
     "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }

💔 Event `NETDEV_STREAM_DISCONNECTED` (Since: 7.2)

Fires the moment the netdev stream backend dips out — connection's gone, she left the chat 😭

Members

netdev-id (string) — the QEMU netdev id that is disconnected

Example:

<- { "event": "NETDEV_STREAM_DISCONNECTED",
     "data": {"netdev-id": "netdev0"},
     "timestamp": {"seconds": 1663330937, "microseconds": 526695} }

👑 Event `NETDEV_VHOST_USER_CONNECTED` (Since: 10.0)

Bestie the vhost-user chardev literally just connected, we're so back ✨

Members

netdev-id (string) — the QEMU netdev id that is connected
chardev-id (string) — the character device id used by the QEMU netdev

Example:

<- { "timestamp": {"seconds": 1739538638, "microseconds": 354181 },
     "event": "NETDEV_VHOST_USER_CONNECTED",
     "data": { "netdev-id": "netdev0", "chardev-id": "chr0" } }

💀 Event `NETDEV_VHOST_USER_DISCONNECTED` (Since: 10.0)

And here's the sad one — the vhost-user chardev disconnected. not the vibe 🥀

Members

netdev-id (string) — the QEMU netdev id that is disconnected

Example:

<- { "timestamp": { "seconds": 1739538634, "microseconds": 920450 },
     "event": "NETDEV_VHOST_USER_DISCONNECTED",
     "data": { "netdev-id": "netdev0" } }

🧚 EBPF OBJECTS 🧚

Okay so picture this: an eBPF object is an ELF binary, right? And inside it you've got the eBPF program plus the eBPF map description (that's the BTF). So overall the eBPF object has to contain the program and enough metadata to create/load eBPF with libbpf. Since the eBPF maps/programs have to correspond to QEMU, you can't reuse an eBPF from a different QEMU build — no cap, it just won't work 💅

Right now the one possible eBPF that exists is for receive-side scaling (RSS). 🦋

🌸 Object `EbpfObject` (Since: 9.0)

Availability: CONFIG_EBPF

An eBPF ELF object. That's it, that's the object.

Members

object (string) — the eBPF object encoded in base64

🌈 Enum `EbpfProgramID` (Since: 9.0)

Availability: CONFIG_EBPF

The eBPF programs you can actually get your hands on with request-ebpf. Iconic little list, ngl.

Values

rss — Receive side scaling! It's the technology that lets traffic get steered between queues by calculating a hash. Users may set up an indirection table and hash/packet types configurations. It's used with virtio-net. 🫶

⭐ Command `request-ebpf` (Since: 9.0)

Availability: CONFIG_EBPF

This one retrieves an eBPF object that can be loaded with libbpf. Management applications (think libvirt) may load it and pass file descriptors over to QEMU, so they can run running QEMU without BPF capabilities. Slay — the app does the privileged bit, QEMU just gets handed the goods 💖

Arguments

id (EbpfProgramID) — the ID of the program to return.

Return EbpfObject — eBPF object encoded in base64.

🎀 ROCKER SWITCH DEVICE 🎀

Okay so buckle up bestie, because we're about to get into the rocker switch device, and it is lowkey a whole vibe. Everything here is "Since: 2.4", so it's been iconic for a minute. Let's go 💅

🌸 Object `RockerSwitch` (Since: 2.4)

Rocker switch information. That's the tea.

Members

name (string) — the switch name
id (int) — the switch ID
ports (int) — how many front-panel ports it's serving

✨ Command `query-rocker` (Since: 2.4)

Return rocker switch information. Like, literally just hand it over.

Arguments

name (string) — the switch name

Return RockerSwitch

Example:

-> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
<- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}

🦋 Enum `RockerPortDuplex` (Since: 2.4)

An enumeration of port duplex states. It's giving very binary, ngl.

Values

half — half duplex
full — full duplex

🌈 Enum `RockerPortAutoneg` (Since: 2.4)

An enumeration of port autoneg states. The easiest on/off ever, periodt.

Values

off — autoneg is off
on — autoneg is on

💖 Object `RockerPort` (Since: 2.4)

Rocker switch port information. Every port deserves its own glow-up era.

Members

name (string) — the port name
enabled (boolean) — is the port enabled for I/O?
link-up (boolean) — is the physical link UP on the port?
speed (int) — port link speed in Mbps
duplex (RockerPortDuplex) — the port link duplex
autoneg (RockerPortAutoneg) — the port link autoneg

🎀 Command `query-rocker-ports` (Since: 2.4)

Return rocker switch port information. All the port lore you could ever want.

Arguments

name (string) — the port name

Return [RockerPort]

Example:

-> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
<- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
                  "autoneg": "off", "link-up": true, "speed": 10000},
                 {"duplex": "full", "enabled": true, "name": "sw1.2",
                  "autoneg": "off", "link-up": true, "speed": 10000}
   ]}

💜 Object `RockerOfDpaFlowKey` (Since: 2.4)

Rocker switch OF-DPA flow key. This is the main character of flow matching, fr fr.

Members

priority (int) — key priority, where 0 is the lowest priority
tbl-id (int) — flow table ID
in-pport (int, optional) — physical input port
tunnel-id (int, optional) — tunnel ID
vlan-id (int, optional) — VLAN ID
eth-type (int, optional) — Ethernet header type
eth-src (string, optional) — Ethernet header source MAC address
eth-dst (string, optional) — Ethernet header destination MAC address
ip-proto (int, optional) — IP Header protocol field
ip-tos (int, optional) — IP header TOS field
ip-dst (string, optional) — IP header destination address

🫶 Note: Optional members may or may not appear in the flow key depending on if they're relevant to the flow key. So don't come for them if some are missing — they're just living their truth.

🍓 Object `RockerOfDpaFlowMask` (Since: 2.4)

Rocker switch OF-DPA flow mask. The vibe check for your flow, basically.

Members

in-pport (int, optional) — physical input port
tunnel-id (int, optional) — tunnel ID
vlan-id (int, optional) — VLAN ID
eth-src (string, optional) — Ethernet header source MAC address
eth-dst (string, optional) — Ethernet header destination MAC address
ip-proto (int, optional) — IP Header protocol field
ip-tos (int, optional) — IP header TOS field

🫶 Note: Optional members may or may not appear in the flow mask depending on if they're relevant to the flow mask. Same energy as above, bestie.

🌸 Object `RockerOfDpaFlowAction` (Since: 2.4)

Rocker switch OF-DPA flow action. This is where the flow actually does something — we love a decisive moment.

Members

goto-tbl (int, optional) — next table ID
group-id (int, optional) — group ID
tunnel-lport (int, optional) — tunnel logical port ID
vlan-id (int, optional) — VLAN ID
new-vlan-id (int, optional) — new VLAN ID
out-pport (int, optional) — physical output port

🫶 Note: Optional members may or may not appear in the flow action depending on if they're relevant to the flow action. See the pattern? Optional = only shows up when it matters 💅

🔥 Object `RockerOfDpaFlow` (Since: 2.4)

Rocker switch OF-DPA flow. The whole package deal, assembled and gorgeous.

Members

cookie (int) — flow unique cookie ID
hits (int) — count of matches (hits) on the flow
key (RockerOfDpaFlowKey) — the flow key
mask (RockerOfDpaFlowMask) — the flow mask
action (RockerOfDpaFlowAction) — the flow action

⭐ Command `query-rocker-of-dpa-flows` (Since: 2.4)

Return rocker OF-DPA flow information. Ask and you shall receive the flows.

Arguments

name (string) — the switch name
tbl-id (int, optional) — flow table ID. If tbl-id is not specified, it returns flow information for all tables. No tbl-id, no filter, no problem ✨

Return [RockerOfDpaFlow] — rocker OF-DPA flow information

Example:

-> { "execute": "query-rocker-of-dpa-flows",
     "arguments": { "name": "sw1" } }
<- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
                  "hits": 138,
                  "cookie": 0,
                  "action": {"goto-tbl": 10},
                  "mask": {"in-pport": 4294901760}
                 },
                 ...
   ]}

🧚 Object `RockerOfDpaGroup` (Since: 2.4)

Rocker switch OF-DPA group. Group chat energy, but for ports, and honestly it ate.

Members

id (int) — group unique ID
type (int) — group type
vlan-id (int, optional) — VLAN ID
pport (int, optional) — physical port number
index (int, optional) — group index, unique with group type
out-pport (int, optional) — output physical port number
group-id (int, optional) — next group ID
set-vlan-id (int, optional) — VLAN ID to set
pop-vlan (int, optional) — pop the VLAN header from the packet
group-ids ([int], optional) — list of next group IDs
set-eth-src (string, optional) — set source MAC address in Ethernet header
set-eth-dst (string, optional) — set destination MAC address in Ethernet header
ttl-check (int, optional) — perform TTL check

🫶 Note: Optional members may or may not appear in the group depending on if they're relevant to the group type. Okay we've said this like four times but it's still true, bestie.

💀 Command `query-rocker-of-dpa-groups` (Since: 2.4)

Return rocker OF-DPA group information. Your groups, served fresh.

Arguments

name (string) — the switch name
type (int, optional) — group type. If type is not specified, it returns group information for all group types. This is the "no filter, give me everything" setting 💅

Return [RockerOfDpaGroup] — rocker OF-DPA group information

Example:

-> { "execute": "query-rocker-of-dpa-groups",
     "arguments": { "name": "sw1" } }
<- { "return": [ {"type": 0, "out-pport": 2,
                  "pport": 2, "vlan-id": 3841,
                  "pop-vlan": 1, "id": 251723778},
                 {"type": 0, "out-pport": 0,
                  "pport": 0, "vlan-id": 3841,
                  "pop-vlan": 1, "id": 251723776},
                 {"type": 0, "out-pport": 1,
                  "pport": 1, "vlan-id": 3840,
                  "pop-vlan": 1, "id": 251658241},
                 {"type": 0, "out-pport": 0,
                  "pport": 0, "vlan-id": 3840,
                  "pop-vlan": 1, "id": 251658240}
   ]}

✨ TPM (TRUSTED PLATFORM MODULE) DEVICES ✨

Okay so TPM stuff, let's go, this is genuinely so cool 🎀

Enum `TpmModel` (Since: 1.5)

Availability: CONFIG_TPM

A whole lil enumeration of TPM models, bestie.

Values

tpm-tis — the TPM TIS model
tpm-crb — the TPM CRB model (since 2.12)
tpm-spapr — the TPM SPAPR model (since 5.0)

Command `query-tpm-models` (Since: 1.5)

Availability: CONFIG_TPM

Bestie, this one returns a list of all the TPM models your build supports 💅

Return [TpmModel]

Example:

-> { "execute": "query-tpm-models" }
<- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }

Enum `TpmType` (Since: 1.5)

Availability: CONFIG_TPM

An enumeration of TPM types. Icons only, fr fr.

Values

passthrough — TPM passthrough type
emulator — Software Emulator TPM type (since 2.11)

Command `query-tpm-types` (Since: 1.5)

Availability: CONFIG_TPM

Returns the list of supported TPM types ✨

Return [TpmType]

Example:

-> { "execute": "query-tpm-types" }
<- { "return": [ "passthrough", "emulator" ] }

Object `TPMPassthroughOptions` (Since: 1.5)

Availability: CONFIG_TPM

The tea on the TPM passthrough type ☕

Members

path (string, optional) — a string describing the path used for accessing the TPM device
cancel-path (string, optional) — a string showing the TPM's sysfs cancel file, used for cancellation of TPM commands while they are executing

Object `TPMEmulatorOptions` (Since: 2.11)

Availability: CONFIG_TPM

The tea on the TPM emulator type 🧚

Members

chardev (string) — name of a unix socket chardev

Object `TPMPassthroughOptionsWrapper` (Since: 1.5)

Availability: CONFIG_TPM.INDENT 7.0

Members

data (TPMPassthroughOptions) — information about the TPM passthrough type

Object `TPMEmulatorOptionsWrapper` (Since: 2.11)

Availability: CONFIG_TPM.INDENT 7.0

Members

data (TPMEmulatorOptions) — information about the TPM emulator type

Object `TpmTypeOptions` (Since: 1.5)

Availability: CONFIG_TPM

A union referencing different TPM backend types' configuration options. Iconic union behaviour 👑

Members

type (TpmType) — .INDENT 2.0
'passthrough' The configuration options for the TPM passthrough type
'emulator' The configuration options for TPM emulator backend type
When type is passthrough: The members of TPMPassthroughOptionsWrapper.
When type is emulator: The members of TPMEmulatorOptionsWrapper.

Object `TPMInfo` (Since: 1.5)

Availability: CONFIG_TPM

All the info about the TPM 💖

Members

id (string) — the Id of the TPM
model (TpmModel) — the TPM frontend model
options (TpmTypeOptions) — the TPM (backend) type configuration options

Command `query-tpm` (Since: 1.5)

Availability: CONFIG_TPM

Returns information about the TPM device. Look at this adorable nested example 😭

Return [TPMInfo]

Example:

-> { "execute": "query-tpm" }
<- { "return":
     [
       { "model": "tpm-tis",
         "options":
           { "type": "passthrough",
             "data":
               { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
                 "path": "/dev/tpm0"
               }
           },
         "id": "tpm0"
       }
     ]
   }

🖥️ REMOTE DESKTOP 🖥️

Enum `DisplayProtocol` (Since: 7.0)

Display protocols which support changing password options. Slay 💅

Values

vnc — Not documented
spice — Not documented

Enum `SetPasswordAction` (Since: 7.0)

An action to take on changing a password on a connection with active clients. Choose your fighter 🔥

Values

keep — maintain existing clients
fail — fail the command if clients are connected
disconnect — disconnect existing clients

Object `SetPasswordOptions` (Since: 7.0)

Options for set_password. Obsessed with a good options object ngl.

Members

protocol (DisplayProtocol) — .INDENT 2.0
'vnc' to modify the VNC server password
'spice' to modify the Spice server password
password (string) — the new password
connected (SetPasswordAction, optional) — how to handle existing clients when changing the password. If nothing is specified, defaults to 'keep'. For VNC, only 'keep' is currently implemented.
When protocol is vnc: The members of SetPasswordOptionsVnc.

Object `SetPasswordOptionsVnc` (Since: 7.0)

Options for set_password specific to the VNC protocol 🦋

Members

display (string, optional) — the id of the display where the password should be changed. Defaults to the first.

Command `set_password` (Since: 0.14)

Sets the password of a remote display server. Secure the vibe ✨

Arguments

The members of SetPasswordOptions.

Errors

If Spice is not enabled, DeviceNotFound

Example:

-> { "execute": "set_password", "arguments": { "protocol": "vnc",
                                               "password": "secret" } }
<- { "return": {} }

Object `ExpirePasswordOptions` (Since: 7.0)

General options for expire_password. The clock is ticking bestie ⏰

Members

protocol (DisplayProtocol) — .INDENT 2.0
'vnc' to modify the VNC server expiration
'spice' to modify the Spice server expiration
time (string) — when to expire the password.
- 'now' to expire the password immediately
- 'never' to cancel password expiration
- '+INT' where INT is the number of seconds from now (integer)
- 'INT' where INT is the absolute time in seconds
When protocol is vnc: The members of ExpirePasswordOptionsVnc.

Note: Time is relative to the server and currently there is no way to coordinate server time with client time. It is not recommended to use the absolute time version of the time parameter unless you're sure you are on the same machine as the QEMU instance. Like, please don't, I'm begging 🙈

Object `ExpirePasswordOptionsVnc` (Since: 7.0)

Options for expire_password specific to the VNC protocol 🌸

Members

display (string, optional) — the id of the display where the expiration should be changed. Defaults to the first.

Command `expire_password` (Since: 0.14)

Expires the password of a remote display server. Bye bye credential 👋

Arguments

The members of ExpirePasswordOptions.

Errors

If protocol is 'spice' and Spice is not active, DeviceNotFound

Example:

-> { "execute": "expire_password", "arguments": { "protocol": "vnc",
                                                  "time": "+60" } }
<- { "return": {} }

Enum `ImageFormat` (Since: 7.1)

Supported image format types, for all your screenshot needs 📸

Values

png — PNG format
ppm — PPM format

Command `screendump` (Since: 0.14)

Availability: CONFIG_PIXMAN

Captures the contents of a screen and writes it to a file. Literally a screenshot, main character energy 💖

Arguments

filename (string) — the path of a new file to store the image
device (string, optional) — ID of the display device that should be dumped. If this parameter is missing, the primary display will be used. (Since 2.12)
head (int, optional) — head to use in case the device supports multiple heads. If this parameter is missing, head #0 will be used. Also note that the head can only be specified in conjunction with the device ID. (Since 2.12)
format (ImageFormat, optional) — image format for screendump. (default: ppm) (Since 7.1)

Example:

-> { "execute": "screendump",
     "arguments": { "filename": "/tmp/image" } }
<- { "return": {} }

Example:

-> { "execute": "query-spice" }
<- { "return": {
         "enabled": true,
         "auth": "spice",
         "port": 5920,
         "migrated":false,
         "tls-port": 5921,
         "host": "0.0.0.0",
         "mouse-mode":"client",
         "channels": [
            {
               "port": "54924",
               "family": "ipv4",
               "channel-type": 1,
               "connection-id": 1804289383,
               "host": "127.0.0.1",
               "channel-id": 0,
               "tls": true
            },
            {
               "port": "36710",
               "family": "ipv4",
               "channel-type": 4,
               "connection-id": 1804289383,
               "host": "127.0.0.1",
               "channel-id": 0,
               "tls": false
            },
            ...
         ]
      }
   }

✨ Event `SPICE_CONNECTED` (Since: 0.14)

Availability: CONFIG_SPICE

Emitted when a SPICE client establishes a connection 🎉

Members

server (SpiceBasicInfo) — server information
client (SpiceBasicInfo) — client information

Example:

<- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
     "event": "SPICE_CONNECTED",
     "data": {
       "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
       "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
   }}

✨ Event `SPICE_INITIALIZED` (Since: 0.14)

Availability: CONFIG_SPICE

Emitted after the initial handshake and authentication take place (if any) and the SPICE channel is up and running 🦋

Members

server (SpiceServerInfo) — server information
client (SpiceChannel) — client information

Example:

<- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
     "event": "SPICE_INITIALIZED",
     "data": {"server": {"auth": "spice", "port": "5921",
                         "family": "ipv4", "host": "127.0.0.1"},
              "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
                         "connection-id": 1804289383, "host": "127.0.0.1",
                         "channel-id": 0, "tls": true}
   }}

✨ Event `SPICE_DISCONNECTED` (Since: 0.14)

Availability: CONFIG_SPICE

Emitted when the SPICE connection is closed 😭 (the vibes have departed)

Members

server (SpiceBasicInfo) — server information
client (SpiceBasicInfo) — client information

Example:

<- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
     "event": "SPICE_DISCONNECTED",
     "data": {
       "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
       "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
   }}

✨ Event `SPICE_MIGRATE_COMPLETED` (Since: 1.3)

Availability: CONFIG_SPICE

Emitted when SPICE migration has completed 👑

Example:

<- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
     "event": "SPICE_MIGRATE_COMPLETED" }

none — Not documented
vnc — Not documented
ra2 — Not documented
ra2ne — Not documented
tight — Not documented
ultra — Not documented
tls — Not documented
vencrypt — Not documented
sasl — Not documented

yeah bestie the docs literally just say "Not documented" for every single one, I'm not making stuff up 💀

✨ Enum `VncVencryptSubAuth` (Since: 2.3)

Availability: CONFIG_VNC

vnc sub authentication method with vencrypt 🔐

Values

plain — Not documented
tls-none — Not documented
x509-none — Not documented
tls-vnc — Not documented
x509-vnc — Not documented
tls-plain — Not documented
x509-plain — Not documented
tls-sasl — Not documented
x509-sasl — Not documented

✨ Object `VncServerInfo2` (Since: 2.9)

Availability: CONFIG_VNC

The network connection information for server 🌸

Members

🖱️ INPUT 🖱️

🐭 Object `MouseInfo` (Since: 0.14)

Okay so this object is literally the little info card for a mouse device. It tells you what’s up with one mouse input thingy.

Members

name (string) — the name of the mouse device 💖
index (int) — the index of the mouse device
current (boolean) — true if this device is currently receiving mouse events
absolute (boolean) — true if this device supports absolute coordinates as input

🖱️ Command `query-mice` (Since: 0.14)

This one returns info about every active mouse device. Like a little roll call for mice. 🐭✨

It returns [MouseInfo] — a list of info for each device.

Example

-> { "execute": "query-mice" }
<- { "return": [
         {
            "name":"QEMU Microsoft Mouse",
            "index":0,
            "current":false,
            "absolute":false
         },
         {
            "name":"QEMU PS/2 Mouse",
            "index":1,
            "current":true,
            "absolute":true
         }
      ]
   }

⌨️ Enum `QKeyCode` (Since: 1.3)

This is an enumeration of key names. It’s used by the send-key command, so if you’re trying to tell QEMU “bestie, press this key,” this is the list it understands. 💅

Values

unmapped — since 2.0
pause — since 2.0
ro — since 2.4
kp_comma — since 2.4
kp_equals — since 2.6
power — since 2.6
hiragana — since 2.9
henkan — since 2.9
yen — since 2.9
sleep — since 2.10
wake — since 2.10
audionext — since 2.10
audioprev — since 2.10
audiostop — since 2.10
audioplay — since 2.10
audiomute — since 2.10
volumeup — since 2.10
volumedown — since 2.10
mediaselect — since 2.10
mail — since 2.10
calculator — since 2.10
computer — since 2.10
ac_home — since 2.10
ac_back — since 2.10
ac_forward — since 2.10
ac_refresh — since 2.10
ac_bookmarks — since 2.10
muhenkan — since 2.12
katakanahiragana — since 2.12
lang1 — since 6.1
lang2 — since 6.1
f13 — since 8.0
f14 — since 8.0
f15 — since 8.0
f16 — since 8.0
f17 — since 8.0
f18 — since 8.0
f19 — since 8.0
f20 — since 8.0
f21 — since 8.0
f22 — since 8.0
f23 — since 8.0
f24 — since 8.0
shift — Not documented
shift_r — Not documented
alt — Not documented
alt_r — Not documented
ctrl — Not documented
ctrl_r — Not documented
menu — Not documented
esc — Not documented
1 — Not documented
2 — Not documented
3 — Not documented
4 — Not documented
5 — Not documented
6 — Not documented
7 — Not documented
8 — Not documented
9 — Not documented
0 — Not documented
minus — Not documented
equal — Not documented
backspace — Not documented
tab — Not documented
q — Not documented
w — Not documented
e — Not documented
r — Not documented
t — Not documented
y — Not documented
u — Not documented
i — Not documented
o — Not documented
p — Not documented
bracket_left — Not documented
bracket_right — Not documented
ret — Not documented
a — Not documented
s — Not documented
d — Not documented
f — Not documented
g — Not documented
h — Not documented
j — Not documented
k — Not documented
l — Not documented
semicolon — Not documented
apostrophe — Not documented
grave_accent — Not documented
backslash — the docs are literally giving Not documented 🙈
z — Not documented 💀
x — Not documented 💀
c — Not documented 💀
v — Not documented 💀
b — Not documented 💀
n — Not documented 💀
m — Not documented 💀
comma — Not documented 🙈
dot — Not documented 🙈
slash — Not documented 🙈
asterisk — Not documented 🙈
spc — Not documented 🙈
caps_lock — Not documented 🙈
f1 — Not documented
f2 — Not documented
f3 — Not documented
f4 — Not documented
f5 — Not documented
f6 — Not documented
f7 — Not documented
f8 — Not documented
f9 — Not documented
f10 — Not documented
num_lock — Not documented
scroll_lock — Not documented
kp_divide — Not documented
kp_multiply — Not documented
kp_subtract — Not documented
kp_add — Not documented
kp_enter — Not documented
kp_decimal — Not documented
sysrq — Not documented (but pls read the lore below 👇)
kp_0 — Not documented
kp_1 — Not documented
kp_2 — Not documented
kp_3 — Not documented
kp_4 — Not documented
kp_5 — Not documented
kp_6 — Not documented
kp_7 — Not documented
kp_8 — Not documented
kp_9 — Not documented
less — Not documented
f11 — Not documented
f12 — Not documented
print — Not documented
home — Not documented
pgup — Not documented
pgdn — Not documented
end — Not documented
left — Not documented
up — Not documented
down — Not documented
right — Not documented
insert — Not documented
delete — Not documented
stop — Not documented
again — Not documented
props — Not documented
undo — Not documented
front — Not documented
copy — Not documented
open — Not documented
paste — Not documented
find — Not documented
cut — Not documented
lf — Not documented
help — Not documented
meta_l — Not documented
meta_r — Not documented
compose — Not documented

🫶 okay so storytime on sysrq: it was mistakenly added to hack around the fact that the ps2 driver was not generating correct scancodes sequences when alt+print was pressed. That flaw is now fixed and the sysrq key serves no further purpose. Any further use of sysrq will be transparently changed to print, so they are effectively synonyms. so like... they're the same key now, bestie 💅

🎀 Enum KeyValueKind (Since: 1.3)

Values

number — Not documented 🙈
qcode — Not documented 🙈

🌸 Object IntWrapper (Since: 1.3)

Members

data (int) — a numeric key code

🌸 Object QKeyCodeWrapper (Since: 1.3)

Members

data (QKeyCode) — An enumeration of key name

✨ Object KeyValue (Since: 1.3)

Represents a keyboard key. that's it, that's the whole vibe 🔥

Members

type (KeyValueKind) — key encoding
When type is number: The members of IntWrapper.
When type is qcode: The members of QKeyCodeWrapper.

💅 Command send-key (Since: 1.3)

Send keys to guest. like you're literally typing for the VM, iconic 👑

Arguments

keys ([KeyValue]) — An array of KeyValue elements. All KeyValues in this array are simultaneously sent to the guest. A KeyValue.number value is sent directly to the guest, while KeyValue.qcode must be a valid QKeyCode value
hold-time (int, optional) — time to delay key up events, milliseconds. Defaults to 100

Errors

If key is unknown or redundant, GenericError

Example:

-> { "execute": "send-key",
     "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
                              { "type": "qcode", "data": "alt" },
                              { "type": "qcode", "data": "delete" } ] } }
<- { "return": {} }

that's the classic ctrl+alt+delete moment, no cap 🫶

🦋 Enum InputButton (Since: 2.0)

Button of a pointer input device (mouse, tablet). pointer stuff, very main character energy ✨

Values

side — front side button of a 5-button mouse (since 2.9)
extra — rear side button of a 5-button mouse (since 2.9)
touch — screen contact on a multi-touch device (since 8.1)
left — Not documented 🙈
middle — Not documented 🙈
right — Not documented 🙈
wheel-up — Not documented 🙈
wheel-down — Not documented 🙈
wheel-left — Not documented 🙈
wheel-right — Not documented 🙈

🦋 Enum InputAxis (Since: 2.0)

Position axis of a pointer input device (mouse, tablet).

Values

x — Not documented 🙈
y — Not documented 🙈

🧚 Enum InputMultiTouchType (Since: 8.1)

Type of a multi-touch event. touchy-feely era 💖

Values

begin — A new touch event sequence has just started.
update — A touch event sequence has been updated.
end — A touch event sequence has finished.
cancel — A touch event sequence has been canceled.
data — Absolute position data.

⭐ Object InputKeyEvent (Since: 2.0)

Keyboard input event. keys! keys! keys! ⌨️

Members

key (KeyValue) — Which key this event is for.
down (boolean) — True for key-down and false for key-up events.

⭐ Object InputBtnEvent (Since: 2.0)

Pointer button input event.

Members

button (InputButton) — Which button this event is for.
down (boolean) — True for key-down and false for key-up events.

⭐ Object InputMoveEvent (Since: 2.0)

Pointer motion input event.

Members

axis (InputAxis) — Which axis is referenced by value.
value (int) — Pointer position. For absolute coordinates the valid range is 0 to 0x7fff. don't go outside that range, bestie 😭

⭐ Object InputMultiTouchEvent (Since: 8.1)

MultiTouch input event.

Members

type (InputMultiTouchType) — The type of multi-touch event.
slot (int) — Which slot has generated the event.
tracking-id (int) — ID to correlate this event with previously generated events.
axis (InputAxis) — Which axis is referenced by value.
value (int) — Contact position.

🍓 Enum InputEventKind (Since: 2.0)

Values

key — a keyboard input event
btn — a pointer button input event
rel — a relative pointer motion input event
abs — an absolute pointer motion input event
mtt — a multi-touch input event

🍓 Object InputKeyEventWrapper (Since: 2.0)

Members

data (InputKeyEvent) — Keyboard input event

🍓 Object InputBtnEventWrapper (Since: 2.0)

Members

data (InputBtnEvent) — Pointer button input event

🍓 Object InputMoveEventWrapper (Since: 2.0)

Members

data (InputMoveEvent) — Pointer motion input event

🍓 Object InputMultiTouchEventWrapper (Since: 8.1)

Members

data (InputMultiTouchEvent) — MultiTouch input event

👑 Object InputEvent (Since: 2.0)

Input event union. it's giving "choose your fighter" but for input 🎀

Members

type (InputEventKind) — the type of input event
When type is key: The members of InputKeyEventWrapper.
When type is btn: The members of InputBtnEventWrapper.
When type is rel: The members of InputMoveEventWrapper.
When type is abs: The members of InputMoveEventWrapper.
When type is mtt: The members of InputMultiTouchEventWrapper.

🌈 Command input-send-event (Since: 2.6)

Send input event(s) to guest. plural, because why send one when you can send many 💅

The device and head parameters can be used to send the input event to specific input devices in case (a) multiple input devices of the same kind are added to the virtual machine and (b) you have configured input routing (see docs/multiseat.txt) for those input devices. The parameters work exactly like the device and head properties of input devices. If device is missing, only devices that have no input routing config are admissible. If device is specified, both input devices with and without input routing config are admissible, but devices with input routing config take precedence.

Arguments

device (string, optional) — display device to send event(s) to.
head (int, optional) — head to send event(s) to, in case the display device supports multiple scanouts.
events ([InputEvent]) — List of InputEvent union.

👀 Note: The consoles are visible in the qom tree, under /backend/console[$index]. They have a device link and head property, so it is possible to map which console belongs to which device and display. iykyk 🧚

Example: Press left mouse button

and for the release half of that click, same energy:

-> { "execute": "input-send-event",
    "arguments": { "device": "video0",
                   "events": [ { "type": "btn",
                   "data" : { "down": false, "button": "left" } } ] } }
<- { "return": {} }

Example: Press ctrl-alt-del — the classic, the icon, the "have u tried turning it off and on again" of keyboard shortcuts 💅

-> { "execute": "input-send-event",
     "arguments": { "events": [
        { "type": "key", "data" : { "down": true,
          "key": {"type": "qcode", "data": "ctrl" } } },
        { "type": "key", "data" : { "down": true,
          "key": {"type": "qcode", "data": "alt" } } },
        { "type": "key", "data" : { "down": true,
          "key": {"type": "qcode", "data": "delete" } } } ] } }
<- { "return": {} }

Example: Move mouse pointer to absolute coordinates — yes bestie, abs means absolute, that cursor is going exactly where u tell it 🎯

-> { "execute": "input-send-event" ,
  "arguments": { "events": [
               { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
               { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
<- { "return": {} }

✨ Object `DisplayGTK` (Since: 2.12) ✨

GTK display options. the whole vibe of ur little window, basically 🪟

Members

clipboard (boolean, optional) — Enable host-guest clipboard sharing. Defaults to "off". (Since 11.1)
grab-on-hover (boolean, optional) — Grab keyboard input on mouse hover.
zoom-to-fit (boolean, optional) — Zoom the guest display so it fits inside the host window. When u turn this off, the host window gets resized instead. And if the display device can tell the guest about window resizes (looking at u, virtio-gpu), this defaults to "on" — the assumption being the guest will then resize its display to match the window size. Otherwise it defaults to "off". (Since 3.1)
show-tabs (boolean, optional) — Display the tab bar for switching between the various graphical interfaces (like VGA and virtual console character devices) by default. (Since 7.1)
show-menubar (boolean, optional) — Display the main window menubar. Defaults to "on". (Since 8.0)
keep-aspect-ratio (boolean, optional) — Keep the width/height aspect ratio of the guest content when resizing the host window. Defaults to "on". (Since 10.1)
scale (number, optional) — Set the preferred scale of the display. Defaults to 1.0. (Since 10.1)

🦋 Object `DisplayEGLHeadless` (Since: 3.1) 🦋

EGL headless display options. no window, just vibes ✨

Members

rendernode (string, optional) — Which DRM render node should be used. Default is the first available node on the host.

🌸 Object `DisplayDBus` (Since: 7.0) 🌸

DBus display options.

Members

addr (string, optional) — The D-Bus bus address (defaults to the session bus).
rendernode (string, optional) — Which DRM render node should be used. Default is the first available node on the host.
p2p (boolean, optional) — Whether to use peer-to-peer connections (accepted through add_client).
audiodev (string, optional) — Use the specified DBus audiodev to export audio.

🎀 Enum `DisplayGLMode` (Since: 3.0) 🎀

Display OpenGL mode. pick ur fighter:

Values

off — Disable OpenGL (default).
on — Use OpenGL, pick the context type automatically. ngl it would better be named 'auto', but it's called 'on' for backward compatibility with the bool type. periodt.
core — Use OpenGL with Core (desktop) Context.
es — Use OpenGL with ES (embedded systems) Context.

🌈 Object `DisplayCurses` (Since: 4.0) 🌈

Curses display options. retro terminal realness 🖥️

Members

charset (string, optional) — Font charset used by the guest (default: CP437).

🍓 Object `DisplayCocoa` (Since: 7.0) 🍓

Cocoa display options. macOS besties, this one's for u 💖

Members

left-command-key (boolean, optional) — Enable/disable forwarding of the left command key to the guest. Handy because it allows command-tab window switching on the host without sending that key to the guest when it's "off". Defaults to "on".
full-grab (boolean, optional) — Capture all key presses, including system combos. Heads up: this requires accessibility permissions, since it performs a global grab on key events. (default: off) See https://support.apple.com/en-in/guide/mac-help/mh32356/mac
swap-opt-cmd (boolean, optional) — Swap the Option and Command keys so their key codes match their position on non-Mac keyboards, and u can use Meta/Super and Alt exactly where u expect them. (default: off)
zoom-to-fit (boolean, optional) — Zoom the guest display so it fits into the host window. When turned off, the host window will be resized instead. Defaults to "off". (Since 8.2)
zoom-interpolation (boolean, optional) — Apply interpolation to smooth the output when zoom-to-fit is enabled. Defaults to "off". (Since 9.0)

💜 Enum `HotKeyMod` (Since: 7.1) 💜

The set of modifier keys that need to be held for shortcut key actions.

Values

lctrl-lalt — Not documented
lshift-lctrl-lalt — Not documented
rctrl — Not documented

ok so the manpage literally just says Not documented for all three 😭 that's not me being lazy bestie, that's canon. iykyk.

💅 Object `DisplaySDL` (Since: 7.1) 💅

SDL2 display options.

Members

grab-mod (HotKeyMod, optional) — Modifier keys that should be pressed together with the "G" key to release the mouse grab.

⭐ Enum `DisplayType` (Since: 2.12) ⭐

Display (user interface) type. choose ur aesthetic:

Values

default — The default user interface, selecting from the first available of gtk, sdl, cocoa, and vnc.
none — No user interface or video output display. The guest still sees an emulated graphics card, but its output just... isn't shown to the QEMU user. ghosted 👻
gtk — The GTK user interface.
sdl — The SDL user interface.
egl-headless — No user interface, offload GL operations to a local DRI device. Graphical display needs to be paired with VNC or Spice. (Since 3.1)
curses — Display video output via curses. For graphics device models that support a text mode, QEMU can display this output using a curses/ncurses interface. Nothing is displayed when the graphics device is in graphical mode, or if the graphics device doesn't support a text mode. Generally only the VGA device models support text mode.
cocoa — The Cocoa user interface.
spice-app — Set up a Spice server and run the default associated application to connect to it. The server will redirect the serial console and QEMU monitors. (Since 4.0)
dbus — Start a D-Bus service for the display. (Since 7.0)

🫶 Object `DisplayOptions` (Since: 2.12) 🫶

Display (user interface) options. the main character object of this whole section honestly 👑

Members

type (DisplayType) — Which DisplayType QEMU should use.
full-screen (boolean, optional) — Start the user interface in fullscreen mode (default: off).
window-close (boolean, optional) — Allow quitting QEMU with the window close button (default: on).
show-cursor (boolean, optional) — Force showing the mouse cursor (default: off). (since: 5.0)
gl (DisplayGLMode, optional) — Enable OpenGL support (default: off).
When type is gtk: The members of DisplayGTK.
When type is cocoa: The members of DisplayCocoa.
When type is curses: The members of DisplayCurses.
When type is egl-headless: The members of DisplayEGLHeadless.
When type is dbus: The members of DisplayDBus.
When type is sdl: The members of DisplaySDL.

🔥 Command `query-display-options` (Since: 3.1) 🔥

Return information about display configuration.

Returns DisplayOptions. that's it, that's the command, she's simple and she slays 💅

🧚 Enum `DisplayReloadType` (Since: 6.0) 🧚

Available DisplayReload types.

Values

vnc — VNC display

🌸 Object `DisplayReloadOptionsVNC` (Since: 6.0) 🌸

Specify the VNC reload options.

Members

tls-certs (boolean, optional) — reload tls certs or not.

🎀 Object `DisplayReloadOptions` (Since: 6.0) 🎀

Options of the display configuration reload.

Members

type (DisplayReloadType) — Specify the display type.
When type is vnc: The members of DisplayReloadOptionsVNC.

👑 Command `display-reload` (Since: 6.0) 👑

Reload display configuration.

Arguments

The members of DisplayReloadOptions.

Example:

-> { "execute": "display-reload",
     "arguments": { "type": "vnc", "tls-certs": true  } }
<- { "return": {} }

💜 Enum `DisplayUpdateType` (Since: 7.1) 💜

Available DisplayUpdate types.

Values

vnc — VNC display

✨ Object `DisplayUpdateOptionsVNC` (Since: 7.1) ✨

Specify the VNC reload options.

Members

(and the members are coming right up in the next part bestie, don't leave me hanging 🫶)

addresses ([SocketAddress], optional) — if you pass this, it changes the set of addresses we listen on for connections. Lowkey important: addresses that were configured for websockets are not touched. Hands off. 🫶

Object `DisplayUpdateOptions` (Since: 7.1)

Options for reloading the display config. Yes bestie, you can hot-swap your display settings. ✨

Members

type (DisplayUpdateType) — pick the display type, bestie.
When type is vnc: the members of DisplayUpdateOptionsVNC apply.

Command `display-update` (Since: 7.1)

Updates your display configuration. Glow-up but for your display. 💅

Arguments

The members of DisplayUpdateOptions.

Example:

-> { "execute": "display-update",
     "arguments": { "type": "vnc", "addresses":
                    [ { "type": "inet", "host": "0.0.0.0",
                        "port": "5901" } ] } }
<- { "return": {} }

Command `client_migrate_info` (Since: 0.14)

Sets the migration info for a remote display. What this actually does: it makes the server ask the client to automatically reconnect using the new parameters once the migration finishes successfully. So the client just… comes back on its own. iconic behaviour honestly. 👑

Heads up fr fr: this is only implemented for SPICE. Not everything, just SPICE.

Arguments

protocol (string) — must be "spice"
hostname (string) — the migration target hostname
port (int, optional) — spice tcp port for plaintext channels
tls-port (int, optional) — spice tcp port for tls-secured channels
cert-subject (string, optional) — server certificate subject

Example:

-> { "execute": "client_migrate_info",
     "arguments": { "protocol": "spice",
                    "hostname": "virt42.lab.kraxel.org",
                    "port": 1234 } }
<- { "return": {} }

🔐 USER AUTHORIZATION 🔐

Okay so this whole section is about who's allowed in. Gatekeeping, but make it config. 💅

Enum `QAuthZListPolicy` (Since: 4.0)

The authorization policy result.

Values

deny — deny access 🙅
allow — allow access ✅

Enum `QAuthZListFormat` (Since: 4.0)

The match format for the authorization policy.

Values

exact — an exact string match
glob — string with ? and * shell wildcard support

Object `QAuthZListRule` (Since: 4.0)

One single authorization rule. Just one. 🎀

Members

match (string) — a string or glob to match against a user identity
policy (QAuthZListPolicy) — the result to return if match evaluates to true
format (QAuthZListFormat, optional) — the format of the match rule (default 'exact')

Object `AuthZListProperties` (Since: 4.0)

Properties for authz-list objects.

Members

policy (QAuthZListPolicy, optional) — Default policy to apply when no rule matches (default: deny)
rules ([QAuthZListRule], optional) — Authorization rules based on matching user

Object `AuthZListFileProperties` (Since: 4.0)

Properties for authz-listfile objects.

Members

filename (string) — File name to load the configuration from. The file must contain valid JSON for AuthZListProperties.
refresh (boolean, optional) — If true, inotify is used to monitor the file, automatically reloading changes. If an error occurs during reloading, all authorizations will fail until the file is next successfully loaded. (default: true if the binary was built with CONFIG_INOTIFY1, false otherwise)

Read that again bestie: if the reload errors out, everything gets denied until the file loads successfully. Not a drill. 💀

Object `AuthZPAMProperties` (Since: 4.0)

Properties for authz-pam objects.

Members

service (string) — PAM service name to use for authorization

Object `AuthZSimpleProperties` (Since: 4.0)

Properties for authz-simple objects.

Members

identity (string) — Identifies the allowed user. Its format depends on the network service that the authorization object is associated with. For authorizing based on TLS x509 certificates, the identity must be the x509 distinguished name.

🚚 MIGRATION 🚚

The whole "moving your VM somewhere else" saga. Buckle up. 🦋

Object `MigrationRAMStats` (Since: 0.14)

Detailed migration status. Every number you could possibly want. ✨

Members

transferred (int) — amount of bytes already transferred to the target VM
remaining (int) — amount of bytes remaining to be transferred to the target VM
total (int) — total amount of bytes involved in the migration process
duplicate (int) — number of duplicate (zero) pages (since 1.2)
normal (int) — number of normal pages (since 1.2)
normal-bytes (int) — number of normal bytes sent (since 1.2)
dirty-pages-rate (int) — number of pages dirtied by second by the guest (since 1.3)
mbps (number) — throughput in megabits/sec. (since 1.6)
dirty-sync-count (int) — number of times that dirty ram was synchronized (since 2.1)
postcopy-requests (int) — The number of page requests received from the destination (since 2.7)
page-size (int) — The number of bytes per page for the various page-based statistics (since 2.10)
multifd-bytes (int) — The number of bytes sent through multifd (since 3.0)
pages-per-second (int) — the number of memory pages transferred per second (Since 4.0)
precopy-bytes (int) — The number of bytes sent in the pre-copy phase (since 7.0).
downtime-bytes (int) — The number of bytes sent while the guest is paused (since 7.0).
postcopy-bytes (int) — The number of bytes sent during the post-copy phase (since 7.0).
dirty-sync-missed-zero-copy (int) — Number of times dirty RAM synchronization could not avoid copying dirty pages. This is between 0 and dirty-sync-count * multifd-channels. (since 7.1)

Object `XBZRLECacheStats` (Since: 1.2)

Detailed XBZRLE migration cache statistics.

Members

cache-size (int) — XBZRLE cache size
bytes (int) — amount of bytes already transferred to the target VM
pages (int) — amount of pages transferred to the target VM
cache-miss (int) — number of cache miss
cache-miss-rate (number) — rate of cache miss (since 2.1)
encoding-rate (number) — rate of encoded bytes (since 5.1)
overflow (int) — number of overflows

Object `CompressionStats` (Since: 3.1)

Detailed migration compression statistics. Squish era. 🗜️

Members

pages (int) — amount of pages compressed and transferred to the target VM
busy (int) — count of times that no free thread was available to compress data
busy-rate (number) — rate of thread busy
compressed-size (int) — amount of bytes after compression
compression-rate (number) — rate of compressed size

Enum `MigrationStatus` (Since: 2.3)

All the possible eras of a migration. The character arc, if you will. 🌈

Values

none — no migration has ever happened.
setup — migration process has been initiated.
cancelling — in the process of cancelling migration.
cancelled — cancelling migration is finished.
active — in the process of doing migration.
postcopy-active — like active, but now in postcopy mode. (since 2.5)
postcopy-device — like postcopy-active, but the destination is still loading device state and is not running yet. If migration fails during this state, the source side will resume. If there is no return-path from destination to source, this state is skipped. (since 10.2)
postcopy-paused — during postcopy but paused. (since 3.0)
postcopy-recover-setup — setup phase for a postcopy recovery process, preparing for a recovery phase to start. (since 9.1)
postcopy-recover — trying to recover from a paused postcopy. (since 3.0)
completed — migration is finished.
failing — error occurred during migration, clean-up underway. (since 11.0)
failed — error occurred during migration, clean-up done.
colo — VM is in the process of fault tolerance, VM can not get into this state unless colo capability is enabled for migration. (since 2.8)
pre-switchover — Paused before device serialisation. (since 2.11)
device — During device serialisation (also known as switchover phase). Before 9.2, this is only used when (1) in precopy, and (2) when pre-switchover capability is enabled. After 10.0, this state will always be present for every migration procedure as the switchover phase. (since 2.11)
wait-unplug — wait for device unplug request by guest OS to be completed. (since 4.2)

Object `VfioStats` (Since: 5.2)

Detailed VFIO devices migration statistics.

Members

transferred (int) — amount of bytes transferred to the target VM by VFIO devices

Object `MigrationInfo` (Since: 0.14)

Information about the current migration process. the way that this holds everything you'd ever ask about your migration >>> 💖

Members

status (MigrationStatus, optional) — the current migration status, bestie. If this field doesn't come back at all? Then no migration process has even been initiated, congrats, nothing's happening 💅
ram (MigrationRAMStats, optional) — the detailed migration RAM stats, and it's only returned if migration is in progress or completed (since 1.2)
xbzrle-cache (XBZRLECacheStats, optional) — all the detailed XBZRLE migration stats live in here, only returned if the XBZRLE feature is on and the status is 'active' or 'completed' (since 1.2)
total-time (int, optional) — total amount of milliseconds since migration started. If migration has ended, it returns the total migration time (since 1.2)
downtime (int, optional) — only present when migration finishes correctly, this is the total downtime in milliseconds for the guest (since 1.3)
expected-downtime (int, optional) — only present while migration is active: the expected downtime in milliseconds for the guest in the last walk of the dirty bitmap (since 1.3)
setup-time (int, optional) — amount of setup time in milliseconds before the iterations begin but after the QMP command is issued. It's literally designed to give you an accounting of any activities (like RDMA pinning) which may be expensive but don't actually occur during the iterative migration rounds themselves (since 1.6)
cpu-throttle-percentage (int, optional) — percentage of time guest cpus are being throttled during auto-converge. Only present when auto-converge has started throttling guest cpus (Since 2.7)
error-desc (string, optional) — the human readable error description string. Clients should not attempt to parse the error strings, okay? Just show them to a human (Since 2.7)
postcopy-blocktime (int, optional) — total time when all vCPU were blocked during postcopy live migration. Only present when the postcopy-blocktime migration capability is enabled (Since 3.0)
postcopy-vcpu-blocktime ([int], optional) — list of the postcopy blocktime per vCPU. Only present when the postcopy-blocktime migration capability is enabled (Since 3.0)
postcopy-latency (int, optional) — average remote page fault latency (in ns). Heads up: this does not include all faults, only the ones that require a remote page request. So it should always be bigger than the real average page fault latency 🔥 Only present when the postcopy-blocktime migration capability is enabled (Since 10.1)
postcopy-latency-dist ([int], optional) — remote page fault latency distributions. Each element of the array is the number of faults that fall into the bucket period. For the N-th bucket (N>=0), the latency window is [2^Nus, 2^(N+1)us). Example: the 8th element stores how many remote faults got resolved within the [256us, 512us) window. Only present when the postcopy-blocktime migration capability is enabled (Since 10.1)
postcopy-vcpu-latency ([int], optional) — average remote page fault latency per vCPU (in ns). Same definition as postcopy-latency, but this one is the per-vCPU statistics. Only present when the postcopy-blocktime migration capability is enabled (Since 10.1)
postcopy-non-vcpu-latency (int, optional) — average remote page fault latency for all faults that happened in non-vCPU threads (in ns). Same definition as postcopy-latency but this only provides statistics for non-vCPU faults. Only present when the postcopy-blocktime migration capability is enabled (Since 10.1)
socket-address ([SocketAddress], optional) — only used for tcp, so you can know what the real port is (Since 4.0)
vfio (VfioStats, optional) — VfioStats containing detailed VFIO devices migration statistics, only returned if a VFIO device is present, migration is supported by all VFIO devices and status is 'active' or 'completed' (since 5.2)
blocked-reasons ([string], optional) — a list of reasons an outgoing migration is blocked. Present and non-empty when migration is blocked (since 6.0)
dirty-limit-throttle-time-per-round (int, optional) — maximum throttle time (in microseconds) of virtual CPUs each dirty ring full round, which shows how MigrationCapability dirty-limit affects the guest during live migration (Since 8.1)
dirty-limit-ring-full-time (int, optional) — estimated average dirty ring full time (in microseconds) for each dirty ring full round. The value equals the dirty ring memory size divided by the average dirty page rate of the virtual CPU, which you can use to observe the average memory load of the virtual CPU indirectly 👀 Note that zero means the guest doesn't dirty memory (Since 8.1)
remaining (int, optional) — amount of bytes remaining to be migrated system-wide, includes both RAM and all devices (like VFIO) (Since 11.1)

✨ Features ✨

unstable — members postcopy-latency, postcopy-vcpu-latency, postcopy-latency-dist, postcopy-non-vcpu-latency are experimental 🧪

🔍 Command `query-migrate` (Since: 0.14)

Okay so this one returns info about the current migration process. If migration is active there will be another json-object with RAM migration status, bestie.

Returns MigrationInfo.

🌸 Example: Before the first migration

-> { "execute": "query-migrate" }
<- { "return": {} }

🌸 Example: Migration is done and has succeeded

-> { "execute": "query-migrate" }
<- { "return": {
        "status": "completed",
        "total-time":12345,
        "setup-time":12345,
        "downtime":12345,
        "ram":{
          "transferred":123,
          "remaining":123,
          "total":246,
          "duplicate":123,
          "normal":123,
          "normal-bytes":123456,
          "dirty-sync-count":15
        }
     }
   }

🌸 Example: Migration is done and has failed

-> { "execute": "query-migrate" }
<- { "return": { "status": "failed" } }

🌸 Example: Migration is being performed

-> { "execute": "query-migrate" }
<- {
      "return":{
         "status":"active",
         "total-time":12345,
         "setup-time":12345,
         "expected-downtime":12345,
         "ram":{
            "transferred":123,
            "remaining":123,
            "total":246,
            "duplicate":123,
            "normal":123,
            "normal-bytes":123456,
            "dirty-sync-count":15
         }
      }
   }

🌸 Example: Migration is being performed and XBZRLE is active

-> { "execute": "query-migrate" }
<- {
      "return":{
         "status":"active",
         "total-time":12345,
         "setup-time":12345,
         "expected-downtime":12345,
         "ram":{
            "total":1057024,
            "remaining":1053304,
            "transferred":3720,
            "duplicate":10,
            "normal":3333,
            "normal-bytes":3412992,
            "dirty-sync-count":15
         },
         "xbzrle-cache":{
            "cache-size":67108864,
            "bytes":20971520,
            "pages":2444343,
            "cache-miss":2244,
            "cache-miss-rate":0.123,
            "encoding-rate":80.1,
            "overflow":34434
         }
      }
   }

🎚️ Enum `MigrationCapability` (Since: 1.2)

The migration capabilities enumeration — think of it as the capability menu, and you're ordering à la carte 🍓

Values

xbzrle — migration supports xbzrle (Xor Based Zero Run Length Encoding). This feature lets us minimize migration traffic for certain work loads, by sending compressed difference of the pages, iconic behavior honestly
rdma-pin-all — controls whether or not the entire VM memory footprint is mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage. Disabled by default (since 2.0)
events — generate events for each migration state change (since 2.4)
auto-converge — if enabled, QEMU will automatically throttle down the guest to speed up convergence of RAM migration 🔥 (since 1.6)
postcopy-ram — start running on the migration target before all of RAM has been migrated, and pull the rest of the pages across as they're needed. ⚠️ The capacity has to be set the same on both source and target or migration won't even start. Also: if the migration fails during postcopy, the VM fails. 😭 (since 2.6)
x-colo — if you enable this, migration literally never ends, and the state of the VM on the primary side keeps getting migrated continuously over to the VM on the secondary side. That whole process is called COarse-Grain LOck Stepping (COLO) for Non-stop Service. (since 2.8)
release-ram — if enabled, QEMU frees the migrated RAM pages on the source while doing postcopy-ram migration. (since 2.9)
return-path — if enabled, migration uses the return path even for precopy. (since 2.10)
pause-before-switchover — pause outgoing migration before serialising device state and before disabling block IO. (since 2.11)
multifd — use more than one fd for migration. (since 4.0)
dirty-bitmaps — if enabled, QEMU migrates named dirty bitmaps. (since 2.12)
postcopy-blocktime — calculate downtime for postcopy live migration. (since 3.0)
late-block-activate — if enabled, the destination will not activate block devices (and thus won't take locks) immediately at the end of migration. (since 3.0)
x-ignore-shared — if enabled, QEMU won't migrate shared memory that's already accessible on the destination machine. (since 4.0)
validate-uuid — send the UUID of the source so the destination can make sure it's the same one. (since 4.2)
background-snapshot — if enabled, the migration stream is a snapshot of the VM exactly at the point where the migration procedure starts. The VM RAM gets saved with a running VM. (since 6.0)
zero-copy-send — controls the behaviour when sending memory pages during migration. When true, it enables a zero-copy mechanism for sending memory pages, if the host supports it. Requires that QEMU be permitted to use locked memory for guest RAM pages. (since 7.1)
postcopy-preempt — if enabled, the migration process lets postcopy requests preempt the precopy stream, so postcopy requests get handled faster. This is a performance feature and should not affect the correctness of postcopy migration. (since 7.1)
switchover-ack — if enabled, migration won't stop the source VM and complete the migration until the destination has acknowledged that it's OK to switch over. That acknowledgement may depend on, like, some device's data being loaded in the destination before doing the switchover. This can reduce downtime if devices that support this capability are present. Capability return-path must be enabled to use it. (since 8.1)
dirty-limit — if enabled, migration throttles vCPUs as needed to keep their dirty page rate within vcpu-dirty-limit. This can improve responsiveness of large guests during live migration, and can result in more stable read performance. Requires KVM with accelerator property "dirty-ring-size" set. (Since 8.1)
mapped-ram — migrate using fixed offsets in the migration file for each RAM page. Requires a migration URI that supports seeking, such as a file. (since 9.0)

🌸 Features 🌸

unstable — the members x-colo and x-ignore-shared are experimental. 👀

🫶 Object `MigrationCapabilityStatus` (Since: 1.2) 🫶

Migration capability information. Bestie, it's just a little status card for a capability.

Members

capability (MigrationCapability) — capability enum
state (boolean) — capability state bool

💅 Command `migrate-set-capabilities` (Since: 1.2) 💅

Enable/Disable the following migration capabilities (like xbzrle). Yes, it's giving "toggle the vibes".

Arguments

capabilities ([MigrationCapabilityStatus]) — json array of capability modifications to make

Example:

-> { "execute": "migrate-set-capabilities" , "arguments":
     { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
<- { "return": {} }

✨ Command `query-migrate-capabilities` (Since: 1.2) ✨

Return information about the current migration capabilities status. The receipts, basically. 🧾

Return [MigrationCapabilityStatus]

Example:

-> { "execute": "query-migrate-capabilities" }
<- { "return": [
      {"state": false, "capability": "xbzrle"},
      {"state": false, "capability": "rdma-pin-all"},
      {"state": false, "capability": "auto-converge"},
      {"state": true, "capability": "events"},
      {"state": false, "capability": "postcopy-ram"},
      {"state": false, "capability": "x-colo"}
   ]}

🎀 Enum `MultiFDCompression` (Since: 5.0) 🎀

An enumeration of multifd compression methods. Pick your fighter. 🥊

Values

none — no compression.
zlib — use zlib compression method.
zstd — use zstd compression method.
qatzip — use qatzip compression method. (Since 9.2)
qpl — use qpl compression method. Query Processing Library(qpl) is based on the deflate compression algorithm and use the Intel In-Memory Analytics Accelerator(IAA) accelerated compression and decompression. (Since 9.1)
uadk — use UADK library compression method. (Since 9.1)

🌈 Enum `MigMode` 🌈

Values

normal — the original form of migration. (since 8.2)
cpr-reboot —

The migrate command stops the VM and saves state to the URI. After quitting QEMU, the user resumes by running QEMU -incoming.

This mode allows the user to quit QEMU, optionally update and reboot the OS, and restart QEMU. If the user reboots, the URI must persist across the reboot, such as by using a file.

Unlike normal mode, the use of certain local storage options does not block the migration, but the user must not modify the contents of guest block devices between the quit and restart.

This mode supports VFIO devices provided the user first puts the guest in the suspended runstate, such as by issuing guest-suspend-ram <#command-QGA-qapi-schema.guest-suspend-ram> to the QEMU guest agent.

Best performance is achieved when the memory backend is shared and the x-ignore-shared migration capability is set, but this is not required. Further, if the user reboots before restarting such a configuration, the shared memory must persist across the reboot, such as by backing it with a dax device.

⚠️ cpr-reboot may not be used with postcopy, background-snapshot, or COLO.

(since 8.2)

cpr-transfer —

This mode allows the user to transfer a guest to a new QEMU instance on the same host with minimal guest pause time by preserving guest RAM in place.

Devices and their pinned pages are also preserved for VFIO and IOMMUFD. (since 10.1)

The user starts new QEMU on the same host as old QEMU, with command-line arguments to create the same machine, plus the -incoming option for the main migration channel, like normal live migration. In addition, the user adds a second -incoming option with channel type "cpr". This CPR channel must support file descriptor transfer with SCM_RIGHTS, i.e. it must be a UNIX domain socket.

To initiate CPR, the user issues a migrate command to old QEMU, adding a second migration channel of type "cpr" in the channels argument. Old QEMU stops the VM, saves state to the migration channels, and enters the postmigrate state. Execution resumes in new QEMU.

New QEMU reads the CPR channel before opening a monitor, hence the CPR channel cannot be specified in the list of channels for a migrate-incoming command. It may only be specified on the command line.

The main channel address cannot be a file type, and for an inet socket, the port cannot be 0 (meaning dynamically choose a port).

Memory-backend objects must have the share=on attribute, but memory-backend-epc is not supported. The VM must be started with the '-machine aux-ram-share=on' option.

When using -incoming defer, you must issue the migrate command to old QEMU before issuing any monitor commands to new QEMU. However, new QEMU does not open and read the migration stream until you issue the migrate-incoming command.

(since 10.0)

💀 and yes bestie, the original really does tag this one both (since 10.1) and (since 10.0) — both live here, we don't edit the source of truth.

cpr-exec —

The migrate command stops the VM, saves state to the migration channel, then directly exec's a new version of QEMU on the same host — replacing the original process while retaining its PID, and loads state back from the channel. Guest RAM is preserved in place. Devices and their pinned pages are also preserved for VFIO and IOMMUFD. 💅

Old QEMU starts new QEMU by exec'ing the command specified by the cpr-exec-command parameter. That command can be a direct invocation of new QEMU, or a wrapper that exec's the new QEMU binary. No drama either way.

Because old QEMU terminates when new QEMU starts, you literally cannot stream data between the two, so the channel must be a type — such as a file — that accepts all the data before old QEMU exits. Otherwise, old QEMU may quietly block writing to the channel. 😭 Not a crash, just... vibes of a hang. Beware.

Memory-backend objects must have the share=on attribute, but memory-backend-epc is not supported. The VM must be started with the '-machine aux-ram-share=on' option. No cap, that's just how it is.

(since 10.2) ✨

🌀 Enum ZeroPageDetection (Since: 9.0)

Values, bestie:

none — Do not perform zero page checking. Zero thoughts, head empty.
legacy — Perform zero page checking in main migration thread.
multifd — Perform zero page checking in multifd sender thread if multifd migration is enabled, else in the main migration thread as for legacy.

🎀 Object BitmapMigrationBitmapAliasTransform (Since: 6.0)

Members:

persistent (boolean, optional) — If present, the bitmap will be made persistent or transient depending on this parameter.

🦋 Object BitmapMigrationBitmapAlias (Since: 5.2)

Members:

name (string) — The name of the bitmap.
alias (string) — An alias name for migration (for example the bitmap name on the opposite site).
transform (BitmapMigrationBitmapAliasTransform, optional) — Allows the modification of the migrated bitmap. (since 6.0)

🌸 Object BitmapMigrationNodeAlias (Since: 5.2)

Maps a block node name and the bitmaps it has to aliases for dirty bitmap migration. Cute little matchmaker for node names, honestly.

Members:

node-name (string) — A block node name.
alias (string) — An alias block node name for migration (for example the node name on the opposite site).
bitmaps ([BitmapMigrationBitmapAlias]) — Mappings for the bitmaps on this node.

🔥 Enum MigrationParameter (Since: 2.4)

Migration parameters enumeration. The enumeration values mirror the members of MigrationParameters. Iconic mirroring behaviour, honestly.

Values:

announce-initial — Not documented
announce-max — Not documented
announce-rounds — Not documented
announce-step — Not documented
throttle-trigger-threshold — Not documented
cpu-throttle-initial — Not documented
cpu-throttle-increment — Not documented
cpu-throttle-tailslow — Not documented
tls-creds — Not documented
tls-hostname — Not documented
tls-authz — Not documented
max-bandwidth — Not documented
avail-switchover-bandwidth — Not documented
downtime-limit — Not documented
x-checkpoint-delay — Not documented
multifd-channels — Not documented
xbzrle-cache-size — Not documented
max-postcopy-bandwidth — Not documented
max-cpu-throttle — Not documented
multifd-compression — Not documented
multifd-zlib-level — Not documented
multifd-zstd-level — Not documented
multifd-qatzip-level — Not documented
block-bitmap-mapping — Not documented
x-vcpu-dirty-limit-period — Not documented
vcpu-dirty-limit — Not documented
mode — Not documented
zero-page-detection — Not documented
direct-io — Not documented
x-rdma-chunk-size — Not documented
cpr-exec-command — Not documented

Features:

unstable — Members x-checkpoint-delay, x-rdma-chunk-size, and x-vcpu-dirty-limit-period are experimental. ⚠️ You've been warned.

💜 Command migrate-set-parameters (Since: 2.4)

Set migration parameters. All arguments are optional. Very chill, very "no pressure".

Arguments:

The members of MigrationParameters.

Example:

-> { "execute": "migrate-set-parameters" ,
     "arguments": { "multifd-channels": 5 } }
<- { "return": {} }

🧚 Object MigrationParameters (Since: 2.4)

Members, and there are so many, buckle up:

announce-initial (int, optional) — Initial delay (in milliseconds) before sending the first announce (Since 4.0)
announce-max (int, optional) — Maximum delay (in milliseconds) between packets in the announcement (Since 4.0)
announce-rounds (int, optional) — Number of self-announce packets sent after migration (Since 4.0)
announce-step (int, optional) — Increase in delay (in milliseconds) between subsequent packets in the announcement (Since 4.0)
throttle-trigger-threshold (int, optional) — The ratio of bytes_dirty_period and bytes_xfer_period to trigger throttling. It is expressed as percentage. The default value is 50. (Since 5.0)
cpu-throttle-initial (int, optional) — Initial percentage of time guest cpus are throttled when migration auto-converge is activated. The default value is 20. (Since 2.7)
cpu-throttle-increment (int, optional) — throttle percentage increase each time auto-converge detects that migration is not making progress. The default value is 10. (Since 2.7)
cpu-throttle-tailslow (boolean, optional) — Make CPU throttling slower at tail stage. At the tail stage of throttling, the Guest is very sensitive to CPU percentage while the cpu-throttle-increment is excessive usually at tail stage. If this parameter is true, we will compute the ideal CPU percentage used by the Guest, which may exactly make the dirty rate match the dirty rate threshold. Then we will choose a smaller throttle increment between the one specified by cpu-throttle-increment and the one generated by ideal CPU percentage. Therefore, it is compatible to traditional throttling, meanwhile the throttle increment won't be excessive at tail stage. The default value is false. (Since 5.1)
tls-creds (StrOrNull, optional) — ID of the 'tls-creds' object that provides credentials for establishing a TLS connection over the migration data channel. On the outgoing side of the migration, the credentials must be for a 'client' endpoint, while for the incoming side the credentials must be for a 'server' endpoint. Setting this to a non-empty string enables TLS for all migrations. An empty string means that QEMU will use plain text mode for migration, rather than TLS. This is the default. (Since 2.7)
tls-hostname (StrOrNull, optional) — migration target's hostname for validating the server's x509 certificate identity. If empty, QEMU will use the hostname from the migration URI, if any. A non-empty value is required when using x509 based TLS credentials and the migration URI does not include a hostname, such as fd: or exec: based migration. (Since 2.7)

Note: empty value works only since 2.9. 🫶

tls-authz (StrOrNull, optional) — ID of the 'authz' object subclass that provides access control checking of the TLS x509 certificate distinguished name. This object is only resolved at time of use, so can be deleted and recreated on the fly while the migration server is active. If missing, it will default to denying access (Since 4.0)
max-bandwidth (int, optional) — maximum speed for migration, in bytes per second. (Since 2.8)
avail-switchover-bandwidth (int, optional) — to set the available bandwidth that migration can use during switchover phase, in bytes per second. Note: this does not limit the bandwidth during switchover, but only for calculations when making decisions to switch over. By default, this value is zero, which means QEMU will estimate the bandwidth automatically. This can be set when the estimated value is not accurate, while the user is able to guarantee such bandwidth is available when switching over. When specified correctly, this can make the switchover decision much more accurate. (Since 8.2) ✨
downtime-limit (int, optional) — set maximum tolerated downtime for migration. maximum downtime in milliseconds (Since 2.8)
x-checkpoint-delay (int, optional) — The delay time (in ms) between two COLO checkpoints in periodic mode. (Since 2.8)
multifd-channels (int, optional) — how many channels you're using to yeet the data in parallel. Same number as the number of sockets used for migration, bestie. Defaults to 2 (since 4.0) ✨
xbzrle-cache-size (int, optional) — the cache size XBZRLE migration gets to play with. It needs to be a multiple of the target page size and a power of 2, no exceptions (Since 2.11) 🎀
max-postcopy-bandwidth (int, optional) — background transfer bandwidth during postcopy. Defaults to 0 (which is unlimited, go off). In bytes per second. (Since 3.0) 🔥
max-cpu-throttle (int, optional) — maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
multifd-compression (MultiFDCompression, optional) — which compression method to use. Defaults to none. (Since 5.0) 🦋
multifd-zlib-level (int, optional) — set the compression level used in live migration. It's an integer between 0 and 9, where 0 means no compression, 1 means the best compression speed, and 9 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
multifd-qatzip-level (int, optional) — set the compression level used in live migration. The level is an integer between 1 and 9, where 1 means the best compression speed, and 9 means the best compression ratio which will consume more CPU. Defaults to 1. (Since 9.2) 💅
multifd-zstd-level (int, optional) — set the compression level used in live migration, integer between 0 and 20, where 0 means no compression, 1 means the best compression speed, and 20 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
block-bitmap-mapping ([BitmapMigrationNodeAlias], optional) — maps block nodes and bitmaps on them to aliases for the purpose of dirty bitmap migration. Those aliases might, for example, be the corresponding names on the opposite site. The mapping must be one-to-one, but not necessarily complete: on the source, unmapped bitmaps and all bitmaps on unmapped nodes will be ignored. On the destination, encountering an unmapped alias in the incoming migration stream will result in a report, and all further bitmap migration data will then be discarded. Note that the destination doesn't know about bitmaps it doesn't receive, so there's no limitation or requirement regarding the number of bitmaps received, or how they're named, or on which nodes they're placed. By default (when this parameter has never been set), bitmap names are mapped to themselves. Nodes are mapped to their block device name if there is one, and to their node name otherwise. (Since 5.2) 🌸
x-vcpu-dirty-limit-period (int, optional) — periodic time (in milliseconds) of dirty limit during live migration. Should be in the range 1 to 1000ms. Defaults to 1000ms. (Since 8.1)
vcpu-dirty-limit (int, optional) — dirtyrate limit (MB/s) during live migration. Defaults to 1. (Since 8.1)
mode (MigMode, optional) — migration mode. See description in MigMode. Default is 'normal'. (Since 8.2) ⭐
zero-page-detection (ZeroPageDetection, optional) — whether and how to detect zero pages. See description in ZeroPageDetection. Default is 'multifd'. (since 9.0)
direct-io (boolean, optional) — open migration files with O_DIRECT when possible. This only has effect if the mapped-ram capability is enabled. (Since 9.1)
cpr-exec-command ([string], optional) — command to start the new QEMU process when mode is cpr-exec. The first list element is the program's filename, the remainder its arguments. (Since 10.2)
x-rdma-chunk-size (int, optional) — RDMA memory registration chunk size in bytes. Default is 1MiB. Must be a power of 2 in the range [1MiB, 1024MiB]. Only applies when migrating via RDMA. Must be set to the same value on both source and destination before migration starts. (Since 11.1) 👑

✨ Features ✨

unstable — members x-checkpoint-delay, x-rdma-chunk-size, and x-vcpu-dirty-limit-period are experimental. Fr fr, treat them like they might change on you.

🌈 Command `query-migrate-parameters` (Since: 2.4)

Returns the info about the current migration parameters, bestie. Optional members of the return value are always present — except block-bitmap-mapping, which is only present if it has been previously set. (Not me gatekeeping one single field 😭)

Return MigrationParameters

Example:

-> { "execute": "query-migrate-parameters" }
<- { "return": {
          "multifd-channels": 2,
          "cpu-throttle-increment": 10,
          "cpu-throttle-initial": 20,
          "max-bandwidth": 33554432,
          "downtime-limit": 300
       }
    }

🦋 Command `migrate-start-postcopy` (Since: 2.5)

Followup to a migration command that switches the migration to postcopy mode. The postcopy-ram capability must be set on both source and destination before the original migration command — like, set it up first or it's not gonna work 💅

Example:

-> { "execute": "migrate-start-postcopy" }
<- { "return": {} }

💖 Event `MIGRATION` (Since: 2.4)

Emitted when a migration event happens. It's giving "something just went down" energy.

Members

status (MigrationStatus) — MigrationStatus describing the current migration status.

Example:

<- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
    "event": "MIGRATION",
    "data": {"status": "completed"} }

🎀 Event `MIGRATION_PASS` (Since: 2.6)

Emitted from the source side of a migration at the start of each pass (when it syncs the dirty bitmap). Every lap gets a number, slay.

Members

pass (int) — an incrementing count (starting at 1 on the first pass)

Example:

<- { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
      "event": "MIGRATION_PASS", "data": {"pass": 2} }

🧚 Enum `COLOMessage` (Since: 2.8)

The message transmission between Primary side and Secondary side. It's the group chat between the two VMs, basically.

Values

checkpoint-ready — Secondary VM (SVM) is ready for checkpointing
checkpoint-request — Primary VM (PVM) tells SVM to prepare for checkpointing
checkpoint-reply — SVM gets PVM's checkpoint request
vmstate-send — VM's state will be sent by PVM.
vmstate-size — the total size of VMstate.
vmstate-received — VM's state has been received by SVM.
vmstate-loaded — VM's state has been loaded by SVM.

🌸 Enum `COLOMode` (Since: 2.8)

The COLO current mode.

Values

none — COLO is disabled.
primary — COLO node in primary side.
secondary — COLO node in slave side.

💜 Enum `FailoverStatus` (Since: 2.8)

An enumeration of COLO failover status. All the possible plot twists:

Values

none — no failover has ever happened
require — got failover requirement but not handled
active — in the process of doing failover
completed — finish the process of failover
relaunch — restart the failover process, from 'none' -> 'completed' (Since 2.9)

🔥 Event `COLO_EXIT` (Since: 3.1)

Emitted when VM finishes COLO mode due to some errors happening or at the request of users. Either way, it's exiting the COLO lifestyle 😭

Members

mode (COLOMode) — report COLO mode when COLO exited.
reason (COLOExitReason) — describes the reason for the COLO exit.

Example:

<- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
     "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }

⭐ Enum `COLOExitReason` (Since: 3.1)

The reason for a COLO exit.

Values

none — failover has never happened. This state does not occur in the COLO_EXIT event, and is only visible in the result of query-colo-status.
request — COLO exit is due to an external request.
error — COLO exit is due to an internal error.
processing — COLO is currently handling a failover (since 4.0).

👑 Command `x-colo-lost-heartbeat` (Since: 2.8)

🚨 Heads up bestie: this command is unstable/experimental. Availability: CONFIG_REPLICATION

Tells QEMU that the heartbeat is lost, and requests it to do takeover procedures. If this command is sent to the PVM, the Primary side will exit COLO mode. If sent to the Secondary, the Secondary side will run failover work, then takes over server operation to become the service VM. Main character energy, honestly.

Features

unstable — this command is experimental.

Example:

-> { "execute": "x-colo-lost-heartbeat" }
<- { "return": {} }

💀 Command `migrate_cancel` (Since: 0.14)

Cancel the currently executing migration process. Allows a new migration to be started right after — no waiting around. When postcopy-ram is in use, cancelling is not allowed after the postcopy phase has started. Like, that door's closed, sorry 🫶

Note: this command succeeds even if there is no migration process running. Yes, it works on nothing. Iconic.

Example:

-> { "execute": "migrate_cancel" }
<- { "return": {} }

💅 Command `migrate-continue` (Since: 2.11)

okay so if your migration is like... paused (it's giving "brb" energy), this is the command that tells it to keep going. Slay.

Arguments

state (MigrationStatus) — the state your migration is expected to be in rn. Like, you're asserting the vibe.

Example:

-> { "execute": "migrate-continue" , "arguments":
     { "state": "pre-switchover" } }
<- { "return": {} }

🦋 Enum `MigrationAddressType` (Since: 8.2)

The migration stream transport mechanisms — basically how your migration data is traveling. Pick your fighter:

Values

socket — Migrate via socket.
exec — Direct the migration stream to another process.
rdma — Migrate via RDMA.
file — Direct the migration stream to a file.

🎀 Object `FileMigrationArgs` (Since: 8.2)

Members

filename (string) — The file to receive the migration stream 💾
offset (int) — The file offset where the migration stream will start

✨ Object `MigrationExecCommand` (Since: 8.2)

Members

args ([string]) — command (list head) and arguments to execute.

🌸 Object `MigrationAddress` (Since: 8.2)

Migration endpoint configuration. This is the "where's it going" of it all.

Members

transport (MigrationAddressType) — The migration stream transport mechanism
When transport is socket: The members of SocketAddress.
When transport is exec: The members of MigrationExecCommand.
When transport is rdma: The members of InetSocketAddress.
When transport is file: The members of FileMigrationArgs.

🧚 Enum `MigrationChannelType` (Since: 8.1)

The migration channel-type request options. iykyk.

Values

main — Main outbound migration channel.
cpr — Checkpoint and restart state channel.

💜 Object `MigrationChannel` (Since: 8.1)

Migration stream channel parameters.

Members

channel-type (MigrationChannelType) — Channel type for transferring packet information.
addr (MigrationAddress) — Migration endpoint configuration on destination interface.

🔥 Command `migrate` (Since: 0.14)

Migrates the current running guest to another Virtual Machine. Literally moving your whole VM. Main character energy fr fr.

Arguments

uri (string, optional) — the Uniform Resource Identifier of the destination VM
channels ([MigrationChannel], optional) — list of migration stream channels with each stream in the list connected to a destination interface endpoint.
resume (boolean, optional) — when set, use the new uri/channels specified to resume paused postcopy migration. This flag should only be used if the previous postcopy migration was interrupted. The command will fail unless migration is in "postcopy-paused" state. (default: false, since 3.0)

Notes

The query-migrate command should be used to check migration's progress and final result (this information is provided by the 'status' member).
The uri argument should have the Uniform Resource Identifier of default destination VM. This connection will be bound to default network.
For now, number of migration streams is restricted to one, i.e. number of items in 'channels' list is just 1.
The 'uri' and 'channels' arguments are mutually exclusive; exactly one of the two should be present.

Example:

-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
<- { "return": {} }

-> { "execute": "migrate",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "socket",
                                   "type": "inet",
                                   "host": "10.12.34.9",
                                   "port": "1050" } } ] } }
<- { "return": {} }

-> { "execute": "migrate",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "exec",
                                   "args": [ "/bin/nc", "-p", "6000",
                                             "/some/sock" ] } } ] } }
<- { "return": {} }

-> { "execute": "migrate",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "rdma",
                                   "host": "10.12.34.9",
                                   "port": "1050" } } ] } }
<- { "return": {} }

-> { "execute": "migrate",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "file",
                                   "filename": "/tmp/migfile",
                                   "offset": "0x1000" } } ] } }
<- { "return": {} }

🌈 Command `migrate-incoming` (Since: 2.3)

Start an incoming migration. Heads up bestie: QEMU must have been started with -incoming defer. No cap, it's required.

Arguments

uri (string, optional) — The Uniform Resource Identifier identifying the source or address to listen on
channels ([MigrationChannel], optional) — list of migration stream channels with each stream in the list connected to a destination interface endpoint.
exit-on-error (boolean, optional) — Exit on incoming migration failure. Default true. When set to false, the failure triggers a MIGRATION event, and error details could be retrieved with query-migrate. (since 9.1)

Notes

It's a bad idea to use a string for the uri, but it needs to stay compatible with -incoming and the format of the uri is already exposed above libvirt.
QEMU must be started with -incoming defer to allow migrate-incoming to be used.
The uri format is the same as for -incoming
For now, number of migration streams is restricted to one, i.e. number of items in 'channels' list is just 1.
The 'uri' and 'channels' arguments are mutually exclusive; exactly one of the two should be present.

Example:

-> { "execute": "migrate-incoming",
     "arguments": { "uri": "tcp:0:4446" } }
<- { "return": {} }

-> { "execute": "migrate-incoming",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "socket",
                                   "type": "inet",
                                   "host": "10.12.34.9",
                                   "port": "1050" } } ] } }
<- { "return": {} }

-> { "execute": "migrate-incoming",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "exec",
                                   "args": [ "/bin/nc", "-p", "6000",
                                             "/some/sock" ] } } ] } }
<- { "return": {} }

-> { "execute": "migrate-incoming",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "rdma",
                                   "host": "10.12.34.9",
                                   "port": "1050" } } ] } }
<- { "return": {} }

🫶 Command `xen-save-devices-state` (Since: 1.1)

Save the state of all devices to file. ⚠️ Important: the RAM and the block devices of the VM are not saved by this command. So like... don't expect a full snapshot, okay?

Arguments

filename (string) — the file to save the state of the devices to as binary data. See xen-save-devices-state.txt for a description of the binary format.
live (boolean, optional) — Optional argument to ask QEMU to treat this command as part of a live migration. Default to true. (since 2.11)

Example:

-> { "execute": "xen-save-devices-state",
     "arguments": { "filename": "/tmp/save" } }
<- { "return": {} }

👑 Command `xen-set-global-dirty-log` (Since: 1.3)

Enable or disable the global dirty log mode.

Arguments

enable (boolean) — true to enable, false to disable.

Example:

-> { "execute": "xen-set-global-dirty-log",
     "arguments": { "enable": true } }
<- { "return": {} }

🍓 Command `xen-load-devices-state` (Since: 2.7)

Load the state of all devices from file. And yeah — same deal as the save one: the RAM and the block devices of the VM are not loaded by this command. 🙈

Arguments

filename (string) — the file to load the state of the devices from as binary data. See xen-save-devices-state.txt for a description of the binary format.

Example:

-> { "execute": "xen-load-devices-state",
     "arguments": { "filename": "/tmp/resume" } }
<- { "return": {} }

⭐ Command `xen-set-replication` (Since: 2.9)

Availability: CONFIG_REPLICATION

Enable or disable replication.

Arguments

enable (boolean) — true to enable, false to disable.
primary (boolean) — true for primary or false for secondary.
failover (boolean, optional) — true means do the failover, false means stop. You literally cannot pass this if enable is true — they're mutually exclusive bestie, pick one. Default is false.

Example, because we love a demo:

-> { "execute": "xen-set-replication",
     "arguments": {"enable": true, "primary": false} }
<- { "return": {} }

🌀 Object `ReplicationStatus` (Since: 2.9)

Availability: CONFIG_REPLICATION

This is the result format for query-xen-replication-status. It's giving status report realness.

Members

error (boolean) — true if something went wrong, false if replication is being normal about it.
desc (string, optional) — the human-readable error description string, and it only shows up when error is 'true'.

🌸 Command `query-xen-replication-status` (Since: 2.9)

Availability: CONFIG_REPLICATION

Ask about replication status while the vm is running. vm says it's fine, vm is lying, who knows.

Returns ReplicationStatus.

Example:

-> { "execute": "query-xen-replication-status" }
<- { "return": { "error": false } }

✨ Command `xen-colo-do-checkpoint` (Since: 2.9)

Availability: CONFIG_REPLICATION

Xen uses this command to notify replication to trigger a checkpoint. It's the little ping that keeps everything in sync.

Example:

-> { "execute": "xen-colo-do-checkpoint" }
<- { "return": {} }

💅 Object `COLOStatus` (Since: 3.1)

Availability: CONFIG_REPLICATION

The result format for query-colo-status. COLO out here with a whole identity.

Members

mode (COLOMode) — COLO running mode. If COLO is running, this field returns 'primary' or 'secondary'.
last-mode (COLOMode) — COLO last running mode. If COLO is running, this field returns the same thing as the mode field. After failover you can use this field to get the last colo mode. (since 4.0)
reason (COLOExitReason) — describes the reason for the COLO exit. the ~why~ of it all.

🦋 Command `query-colo-status` (Since: 3.1)

Availability: CONFIG_REPLICATION

Query COLO status while the vm is running.

Returns COLOStatus.

Example:

-> { "execute": "query-colo-status" }
<- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } }

🔥 Command `migrate-recover` (Since: 3.0)

Provide a recovery migration stream URI. The "oops we need to recover" button, but make it a URI.

Arguments

uri (string) — the URI to be used for the recovery of migration stream.

Example:

-> { "execute": "migrate-recover",
     "arguments": { "uri": "tcp:192.168.1.200:12345" } }
<- { "return": {} }

⭐ Command `migrate-pause` (Since: 3.0)

Pause a migration. Currently it only supports postcopy — so if you were hoping for more, no bestie, not today.

Example:

-> { "execute": "migrate-pause" }
<- { "return": {} }

💀 Event `UNPLUG_PRIMARY` (Since: 4.2)

Emitted from source side of a migration when migration state is WAIT_UNPLUG. Device was unplugged by guest operating system. Device resources in QEMU are kept on standby to be able to re-plug it in case of migration failure. Standby era — nothing is thrown away, everything is on hold just in case.

Members

device-id (string) — QEMU device id of the unplugged device.

Example:

<- { "event": "UNPLUG_PRIMARY",
     "data": { "device-id": "hostdev0" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

🎀 Object `DirtyRateVcpu` (Since: 6.2)

Dirty rate of vcpu. Per-vcpu tea. ☕

Members

id (int) — vcpu index.
dirty-rate (int) — dirty rate.

🌈 Enum `DirtyRateStatus` (Since: 5.2)

Dirty page rate measurement status. the three moods of a measurement thread.

Values

unstarted — measuring thread has not been started yet
measuring — measuring thread is running
measured — dirty page rate is measured and the results are available

🍓 Enum `DirtyRateMeasureMode` (Since: 6.2)

Method used to measure dirty page rate. The differences between the available methods are explained in calc-dirty-rate. go read that one, it's got the lore.

Values

page-sampling — use page sampling
dirty-ring — use dirty ring
dirty-bitmap — use dirty bitmap

🧚 Enum `TimeUnit` (Since: 8.2)

Specifies the unit in which a time-related value is specified. we love an explicit unit, no more guessing games.

Values

second — value is in seconds
millisecond — value is in milliseconds

💜 Object `DirtyRateInfo` (Since: 5.2)

Information about measured dirty page rate. the receipts, basically.

Members

dirty-rate (int, optional) — an estimate of the dirty page rate of the VM in units of MiB/s. Value is present only when status is 'measured'.
status (DirtyRateStatus) — current status of dirty page rate measurements
start-time (int) — start time in units of second for calculation
calc-time (int) — time period for which dirty page rate was measured, expressed and rounded down to calc-time-unit.
calc-time-unit (TimeUnit) — time unit of calc-time (Since 8.2)
sample-pages (int) — number of sampled pages per GiB of guest memory. Valid only in page-sampling mode (Since 6.1)
mode (DirtyRateMeasureMode) — mode that was used to measure dirty page rate (Since 6.2)
vcpu-dirty-rate ([DirtyRateVcpu], optional) — dirty rate for each vCPU if dirty-ring mode was specified (Since 6.2)

🌸 Command `calc-dirty-rate` (Since: 5.2)

Start measuring the dirty page rate of the VM. Results can be retrieved with query-dirty-rate after measurements are completed. start it, then go get the results, that's the whole loop.

Dirty page rate is the number of pages changed in a given time period, expressed in MiB/s. The following methods of calculation are available:

In page sampling mode, a random subset of pages are selected and hashed twice: once at the beginning of measurement time period, and once again at the end. If two hashes for some page are different, the page is counted as changed. Since this method relies on sampling and hashing, the calculated dirty page rate is only an estimate of its true value. Increasing sample-pages improves estimation quality at the cost of higher computational overhead. so like, more pages = more accurate but also more work, pick your fighter.
Dirty bitmap mode captures writes to memory (for example by temporarily revoking write access to all pages) and counting page faults. Information about modified pages is collected into a bitmap, where each bit corresponds to one guest page. This mode requires that the KVM accelerator property "dirty-ring-size" is not set. not set, bestie. don't set it.
Dirty ring mode is similar to dirty bitmap mode, but the information about modified pages is collected into a ring buffer. This mode tracks page modification per each vCPU separately. It requires that the KVM accelerator property "dirty-ring-size" is set. opposite requirement, iconic.

Arguments

calc-time (int) — time period for which dirty page rate is calculated. By default it is specified in seconds, but the unit can be set explicitly with calc-time-unit. Note that larger calc-time values will typically result in smaller dirty page rates because page dirtying is a one-time event. Once some page is counted as dirty during the calc-time period, further writes to this page will not increase dirty page rate anymore. one-time event! it's already been counted, it's not doing it again.
calc-time-unit (TimeUnit, optional) — time unit in which calc-time is specified. By default it is seconds. (Since 8.2)
sample-pages (int, optional) — number of sampled pages per each GiB of guest memory. Default value is 512. For 4KiB guest pages this corresponds to a sampling ratio of 0.2%. This argument is used only in page sampling mode. (Since 6.1)
mode (DirtyRateMeasureMode, optional) — mechanism for tracking dirty pages. Default value is 'page-sampling'. Others are 'dirty-bitmap' and 'dirty-ring'. (Since 6.1)

Example:

-> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
                                                "sample-pages": 512} }
<- { "return": {} }

Example — measure dirty rate using dirty bitmap for 500 milliseconds:

-> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500,
    "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} }

<- { "return": {} }

🔥 Command `query-dirty-rate` (Since: 5.2)

Query results of the most recent invocation of calc-dirty-rate. the most recent one — not the one before that, not the one you're remembering fondly.

Arguments

calc-time-unit (TimeUnit, optional) — time unit in which to report calculation time. By default it is reported in seconds. (Since 8.2)

Returns DirtyRateInfo.

Example — measurement is in progress:

<- {"status": "measuring", "sample-pages": 512,
    "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10,
    "calc-time-unit": "second"}

Example — measurement has been completed:

<- {"status": "measured", "sample-pages": 512, "dirty-rate": 108,
    "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10,
    "calc-time-unit": "second"}

🫶 Object `DirtyLimitInfo` (Since: 7.1)

Dirty page rate limit information of a virtual CPU. we're putting a cap on the mess.

Members

cpu-index (int) — index of a virtual CPU.
limit-rate (int) — upper limit of dirty page rate (MB/s) for a virtual CPU, 0 means unlimited.
current-rate (int) — current dirty page rate (MB/s) for a virtual CPU.

👑 Command `set-vcpu-dirty-limit` (Since: 7.1)

Set the upper limit of dirty page rate for virtual CPUs.

Requires KVM with accelerator property "dirty-ring-size" set. A virtual CPU's dirty page rate is a measure of its memory load. To observe dirty page rates, use calc-dirty-rate. 😌✨

🧾 Arguments

cpu-index (int, optional) — index of a virtual CPU, default is all. 🎯
dirty-rate (int) — upper limit of dirty page rate (MB/s) for virtual CPUs. 🏃‍♀️💨

Example:

-> {"execute": "set-vcpu-dirty-limit"}
    "arguments": { "dirty-rate": 200,
                   "cpu-index": 1 } }
<- { "return": {} }

🛑 Command `cancel-vcpu-dirty-limit` (Since: 7.1)

Cancel the upper limit of dirty page rate for virtual CPUs.

Cancel the dirty page limit for the vCPU which has been set with set-vcpu-dirty-limit command. Note that this command requires support from dirty ring, same as the set-vcpu-dirty-limit. 💅 like, same prerequisites bestie, no skipping.

🧾 Arguments

cpu-index (int, optional) — index of a virtual CPU, default is all. 🎯

Example:

-> {"execute": "cancel-vcpu-dirty-limit"},
    "arguments": { "cpu-index": 1 } }
<- { "return": {} }

🔍 Command `query-vcpu-dirty-limit` (Since: 7.1)

Return information about virtual CPU dirty page rate limits, if any.

Return [DirtyLimitInfo] 🫶

Example:

-> {"execute": "query-vcpu-dirty-limit"}
<- {"return": [
       { "limit-rate": 60, "current-rate": 3, "cpu-index": 0},
       { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]}

📸 Command `snapshot-save` (Since: 6.0)

Save a VM snapshot ✨ iconic behaviour honestly

🧾 Arguments

job-id (string) — identifier for the newly created job 🏷️
tag (string) — name of the snapshot to create 🎀
vmstate (string) — block device node name to save vmstate to 💾
devices ([string]) — list of block device node names to save a snapshot to 📚

Applications should not assume that the snapshot save is complete when this command returns. The job commands / events must be used to determine completion and to fetch details of any errors that arise. ⚠️ like, don't @ me when it's still running bestie, watch the events.

Note that execution of the guest CPUs may be stopped during the time it takes to save the snapshot. A future version of QEMU may ensure CPUs are executing continuously. 😴 yeah they might freeze for a sec, that's just how it is rn.

It is strongly recommended that devices contain all writable block device nodes if a consistent snapshot is required. 🔥 fr fr, do it right.

If tag already exists, an error will be reported 🚨

Example:

-> { "execute": "snapshot-save",
     "arguments": {
        "job-id": "snapsave0",
        "tag": "my-snap",
        "vmstate": "disk0",
        "devices": ["disk0", "disk1"]
     }
   }
<- { "return": { } }
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1432121972, "microseconds": 744001},
    "data": {"status": "created", "id": "snapsave0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1432122172, "microseconds": 744001},
    "data": {"status": "running", "id": "snapsave0"}}
<- {"event": "STOP",
    "timestamp": {"seconds": 1432122372, "microseconds": 744001} }
<- {"event": "RESUME",
    "timestamp": {"seconds": 1432122572, "microseconds": 744001} }
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1432122772, "microseconds": 744001},
    "data": {"status": "waiting", "id": "snapsave0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1432122972, "microseconds": 744001},
    "data": {"status": "pending", "id": "snapsave0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1432123172, "microseconds": 744001},
    "data": {"status": "concluded", "id": "snapsave0"}}
-> {"execute": "query-jobs"}
<- {"return": [{"current-progress": 1,
                "status": "concluded",
                "total-progress": 1,
                "type": "snapshot-save",
                "id": "snapsave0"}]}

📥 Command `snapshot-load` (Since: 6.0)

Load a VM snapshot 🌸 bringing it back, main character energy

🧾 Arguments

job-id (string) — identifier for the newly created job 🏷️
tag (string) — name of the snapshot to load. 🎀
vmstate (string) — block device node name to load vmstate from 💾
devices ([string]) — list of block device node names to load a snapshot from 📚

Applications should not assume that the snapshot load is complete when this command returns. The job commands / events must be used to determine completion and to fetch details of any errors that arise. ⚠️ same deal as before, watch the job events.

Note that execution of the guest CPUs will be stopped during the time it takes to load the snapshot. 😭 yes, guaranteed stopped this time, no "may" about it.

It is strongly recommended that devices contain all writable block device nodes that can have changed since the original snapshot-save command execution. 🔥 like please include everything that moved since the save, or it's giving inconsistent.

Example:

-> { "execute": "snapshot-load",
     "arguments": {
        "job-id": "snapload0",
        "tag": "my-snap",
        "vmstate": "disk0",
        "devices": ["disk0", "disk1"]
     }
   }
<- { "return": { } }
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1472124172, "microseconds": 744001},
    "data": {"status": "created", "id": "snapload0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1472125172, "microseconds": 744001},
    "data": {"status": "running", "id": "snapload0"}}
<- {"event": "STOP",
    "timestamp": {"seconds": 1472125472, "microseconds": 744001} }
<- {"event": "RESUME",
    "timestamp": {"seconds": 1472125872, "microseconds": 744001} }
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1472126172, "microseconds": 744001},
    "data": {"status": "waiting", "id": "snapload0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1472127172, "microseconds": 744001},
    "data": {"status": "pending", "id": "snapload0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1472128172, "microseconds": 744001},
    "data": {"status": "concluded", "id": "snapload0"}}
-> {"execute": "query-jobs"}
<- {"return": [{"current-progress": 1,
                "status": "concluded",
                "total-progress": 1,
                "type": "snapshot-load",
                "id": "snapload0"}]}

🗑️ Command `snapshot-delete` (Since: 6.0)

Delete a VM snapshot 💀 bye bestie

🧾 Arguments

job-id (string) — identifier for the newly created job 🏷️
tag (string) — name of the snapshot to delete. 🎀
devices ([string]) — list of block device node names to delete a snapshot from 📚

Applications should not assume that the snapshot delete is complete when this command returns. The job commands / events must be used to determine completion and to fetch details of any errors that arise. ⚠️ yep, still async, still needs the events.

Example:

-> { "execute": "snapshot-delete",
     "arguments": {
        "job-id": "snapdelete0",
        "tag": "my-snap",
        "devices": ["disk0", "disk1"]
     }
   }
<- { "return": { } }
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1442124172, "microseconds": 744001},
    "data": {"status": "created", "id": "snapdelete0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1442125172, "microseconds": 744001},
    "data": {"status": "running", "id": "snapdelete0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1442126172, "microseconds": 744001},
    "data": {"status": "waiting", "id": "snapdelete0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1442127172, "microseconds": 744001},
    "data": {"status": "pending", "id": "snapdelete0"}}
<- {"event": "JOB_STATUS_CHANGE",
    "timestamp": {"seconds": 1442128172, "microseconds": 744001},
    "data": {"status": "concluded", "id": "snapdelete0"}}
-> {"execute": "query-jobs"}
<- {"return": [{"current-progress": 1,
                "status": "concluded",
                "total-progress": 1,
                "type": "snapshot-delete",
                "id": "snapdelete0"}]}

💸 TRANSACTIONS 💸

okay bestie, this is the section where QEMU lets you bundle a bunch of commands together and run them as one atomic lil group. iconic behavior tbh ✨

Object Abort (Since: 1.6)

This action can be used to test transaction failure. yes literally, it's the "let's see if the failure path works" button 🙈 it's giving QA main character energy.

Enum ActionCompletionMode (Since: 2.5)

An enumeration of transactional completion modes. this is the "how do we all go down together" setting 💅

Values

individual — Do not attempt to cancel any other Actions if any Actions fail after the Transaction request succeeds. All Actions that can complete successfully will do so without waiting on others. This is the default.
grouped — If any Action fails after the Transaction succeeds, cancel all Actions. Actions do not complete until all Actions are ready to complete. May be rejected by Actions that do not support this completion mode.

fr fr, grouped is the all-for-one vibe, but not every Action is gonna be into that. some will straight up reject it 😭

Enum TransactionActionKind (Since: 1.1)

the menu of what you can actually put in a transaction 🍓

Values

abort — Since 1.6
block-dirty-bitmap-add — Since 2.5
block-dirty-bitmap-remove — Since 4.2
block-dirty-bitmap-clear — Since 2.5
block-dirty-bitmap-enable — Since 4.0
block-dirty-bitmap-disable — Since 4.0
block-dirty-bitmap-merge — Since 4.0
blockdev-backup — Since 2.3
blockdev-snapshot — Since 2.5
blockdev-snapshot-internal-sync — Since 1.7
blockdev-snapshot-sync — since 1.1
drive-backup — Since 1.6

Features

deprecated — Member drive-backup is deprecated. Use member blockdev-backup instead.

⚠️ like, drive-backup is so 1.6. it's deprecated, babe. use blockdev-backup. periodt.

Object AbortWrapper (Since: 1.6)

Members

data (Abort) — Not documented

Object BlockDirtyBitmapAddWrapper (Since: 2.5)

Members

data (BlockDirtyBitmapAdd) — Not documented

Object BlockDirtyBitmapWrapper (Since: 2.5)

Members

data (BlockDirtyBitmap) — Not documented

Object BlockDirtyBitmapMergeWrapper (Since: 4.0)

Members

data (BlockDirtyBitmapMerge) — Not documented

Object BlockdevBackupWrapper (Since: 2.3)

Members

data (BlockdevBackup) — Not documented

Object BlockdevSnapshotWrapper (Since: 2.5)

Members

data (BlockdevSnapshot) — Not documented

Object BlockdevSnapshotInternalWrapper (Since: 1.7)

Members

data (BlockdevSnapshotInternal) — Not documented

Object BlockdevSnapshotSyncWrapper (Since: 1.1)

Members

data (BlockdevSnapshotSync) — Not documented

Object DriveBackupWrapper (Since: 1.6)

Members

data (DriveBackup) — Not documented

Object TransactionAction (Since: 1.1)

A discriminated record of operations that can be performed with transaction. it's the "which action am i" card every action carries around 🎀

Members

type (TransactionActionKind) — the operation to be performed
When type is abort: The members of AbortWrapper.
When type is block-dirty-bitmap-add: The members of BlockDirtyBitmapAddWrapper.
When type is block-dirty-bitmap-remove: The members of BlockDirtyBitmapWrapper.
When type is block-dirty-bitmap-clear: The members of BlockDirtyBitmapWrapper.
When type is block-dirty-bitmap-enable: The members of BlockDirtyBitmapWrapper.
When type is block-dirty-bitmap-disable: The members of BlockDirtyBitmapWrapper.
When type is block-dirty-bitmap-merge: The members of BlockDirtyBitmapMergeWrapper.
When type is blockdev-backup: The members of BlockdevBackupWrapper.
When type is blockdev-snapshot: The members of BlockdevSnapshotWrapper.
When type is blockdev-snapshot-internal-sync: The members of BlockdevSnapshotInternalWrapper.
When type is blockdev-snapshot-sync: The members of BlockdevSnapshotSyncWrapper.
When type is drive-backup: The members of DriveBackupWrapper.

Object TransactionProperties (Since: 2.5)

Optional arguments to modify the behavior of a Transaction. the little settings panel for your transaction vibes ✨

Members

completion-mode (ActionCompletionMode, optional) — Controls how jobs launched asynchronously by Actions will complete or fail as a group. See ActionCompletionMode for details.

Command transaction (Since: 1.1)

Executes a number of transactionable QMP commands atomically. If any operation fails, then the entire set of actions will be abandoned and the appropriate error returned. all-or-nothing, bestie — it's giving "we ride together, we die together" 💀

For external snapshots, the dictionary contains the device, the file to use for the new snapshot, and the format. The default format, if not specified, is qcow2.

Each new snapshot defaults to being created by QEMU (wiping any contents if the file already exists), but it is also possible to reuse an externally-created file. In the latter case, you should ensure that the new image file has the same contents as the current one; QEMU cannot perform any meaningful check. Typically this is achieved by using the current image file as the backing file for the new image.

🚨 lowkey important: if you're reusing an externally-created file, you have to make sure it matches. QEMU can't check that for you, no cap.

On failure, the original disks pre-snapshot attempt will be used.

For internal snapshots, the dictionary contains the device and the snapshot's name. If an internal snapshot matching name already exists, the request will be rejected. Only some image formats support it, for example, qcow2, and rbd,

On failure, QEMU will try delete the newly created internal snapshot in the transaction. When an I/O error occurs during deletion, the user needs to fix it later with qemu-img or other command.

Arguments

actions ([TransactionAction]) — List of TransactionAction; information needed for the respective operations.
properties (TransactionProperties, optional) — structure of additional options to control the execution of the transaction. See TransactionProperties for additional detail.

Errors

Any errors from commands in the transaction

Note: The transaction aborts on the first failure. Therefore, there will be information on only one failed operation returned in an error condition, and subsequent actions will not have been attempted.

Example:

-> { "execute": "transaction",
     "arguments": { "actions": [
         { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
                                                     "snapshot-file": "/some/place/my-image",
                                                     "format": "qcow2" } },
         { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
                                                     "snapshot-file": "/some/place/my-image2",
                                                     "snapshot-node-name": "node3432",
                                                     "mode": "existing",
                                                     "format": "qcow2" } },
         { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
                                                     "snapshot-file": "/some/place/my-image2",
                                                     "mode": "existing",
                                                     "format": "qcow2" } },
         { "type": "blockdev-snapshot-internal-sync", "data" : {
                                                     "device": "ide-hd2",
                                                     "name": "snapshot0" } } ] } }
<- { "return": {} }

🔍 TRACING 🔍

your fave "what is QEMU even doing rn" toolkit. detective mode: activated 🕵️‍♀️✨

Enum TraceEventState (Since: 2.2)

State of a tracing event. the vibe check result for an event 🌈

Values

unavailable — The event is statically disabled.
disabled — The event is dynamically disabled.
enabled — The event is dynamically enabled.

Object TraceEventInfo (Since: 2.2)

Information of a tracing event. the lil info card 📇

Members

name (string) — Event name.
state (TraceEventState) — Tracing state.

Command trace-event-get-state (Since: 2.2)

Query the state of events. literally just asking "hey bestie, what's your status" 💅

Arguments

name (string) — Event name pattern (case-sensitive glob).

Return [TraceEventInfo] — a list of info for the matching events

Example:

-> { "execute": "trace-event-get-state",
     "arguments": { "name": "qemu_memalign" } }
<- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }

Command trace-event-set-state (Since: 2.2)

Set the dynamic tracing state of events. flipping the switch, turning it on or off, main character energy 🔥

Arguments

name (string) — Event name pattern (case-sensitive glob).
enable (boolean) — Whether to enable tracing.
ignore-unavailable (boolean, optional) — Do not match unavailable events with name.

Example:

-> { "execute": "trace-event-set-state",
     "arguments": { "name": "qemu_memalign", "enable": true } }
<- { "return": {} }

🎀 reminder that name is a case-sensitive glob, so don't come crying to me if your pattern doesn't match. match the case, bestie 🫶

💅 COMPATIBILITY POLICY 💅

Okay bestie, this section is all about how QEMU handles the “funny” stuff — deprecated or unstable management interfaces. It’s giving test-lab energy, not production-vibe, so pay attention. 👀

🔮 Enum `CompatPolicyInput` (Since: 6.0) 🔮

Policy for handling “funny” input. Yes, that’s literally what the original says. No cap.

Values

accept — Accept silently. Zero complaints, zero drama. 🫶
reject — Reject with an error. The input gets told “no” and shown the door. 🚪
crash — abort() the process. Absolutely unhinged behaviour, but it’s listed, so here we are. 💀

🌸 Enum `CompatPolicyOutput` (Since: 6.0) 🌸

Policy for handling “funny” output. Same energy, but on the way out.

Values

accept — Pass on unchanged. Let it through, untouched. ✨
hide — Filter out. Pretend it was never there. 🙈

🎀 Object `CompatPolicy` (Since: 6.0) 🎀

Policy for handling deprecated management interfaces.

This is intended for testing users of the management interfaces. So it’s a sandbox-ish vibe check for management-interface consumers. 🧪

Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged with feature deprecated or unstable. We may want to extend it to cover semantic aspects and CLI. So rn it’s shallow, not deep. Keep that in mind.

Limitation: deprecated-output policy hide is not implemented for enumeration values. They behave the same as with policy accept. So enum values are lowkey exempt from the hiding game. 😭

Members

deprecated-input (CompatPolicyInput, optional) — how to handle deprecated input (default accept)
deprecated-output (CompatPolicyOutput, optional) — how to handle deprecated output (default accept)
unstable-input (CompatPolicyInput, optional) — how to handle unstable input (default accept) (since 6.2)
unstable-output (CompatPolicyOutput, optional) — how to handle unstable output (default accept) (since 6.2)

🦋 QMP MONITOR CONTROL 🦋

This is the QMP monitor’s own little command corner. Yes, the monitor has monitor controls. It’s very meta. Main character energy fr fr.

👑 Command `qmp_capabilities` (Since: 0.13) 👑

Enable QMP capabilities. This is the handshake, the “hey bestie, I’m ready” moment. 🤝

Arguments

enable ([QMPCapability], optional) — An optional list of QMPCapability values to enable. The client must not enable any capability that is not mentioned in the QMP greeting message. If the field is not provided, it means no QMP capabilities will be enabled. (since 2.12)

Example:

-> { "execute": "qmp_capabilities",
     "arguments": { "enable": [ "oob" ] } }
<- { "return": {} }

Note: This command is valid exactly when first connecting: it must be issued before any other command will be accepted, and will fail once the monitor is accepting other commands. (see QEMU Machine Protocol Specification <>)

Note: The QMP client needs to explicitly enable QMP capabilities, otherwise all the QMP capabilities will be turned off by default. So don’t assume they’re on — they are absolutely not. ✨

💜 Enum `QMPCapability` (Since: 2.12) 💜

Enumeration of capabilities to be advertised during initial client connection, used for agreeing on particular QMP extension behaviors. It’s basically the QMP “what are we doing here?” menu.

Values

oob — QMP ability to support out-of-band requests. (Please refer to qmp-spec.rst for more information on OOB.) 🏃‍♀️

🌈 Object `VersionTriple` (Since: 2.4) 🌈

A three-part version number. Very demure, very structured. 🎀

Members

major (int) — The major version number.
minor (int) — The minor version number.
micro (int) — The micro version number.

⭐ Object `VersionInfo` (Since: 0.14) ⭐

A description of QEMU’s version.

Members

qemu (VersionTriple) — The version of QEMU. By current convention, a micro version of 50 signifies a development branch. A micro version greater than or equal to 90 signifies a release candidate for the next minor version. A micro version of less than 50 signifies a stable release.
package (string) — QEMU will always set this field to an empty string. Downstream versions of QEMU should set this to a non-empty string. The exact format depends on the downstream however it highly recommended that a unique name is used.

🍓 Command `query-version` (Since: 0.14) 🍓

Return the current version of QEMU. Like a little “who am I?” moment but for the binary. 💅

Return VersionInfo — An object describing the current version of QEMU.

Example:

-> { "execute": "query-version" }
<- {
      "return":{
         "qemu":{
            "major":0,
            "minor":11,
            "micro":5
         },
         "package":""
      }
   }

🧚 Object `CommandInfo` (Since: 0.14) 🧚

Information about a QMP command. Tiny object, big purpose.

Members

name (string) — The command name

🔥 Command `query-commands` (Since: 0.14) 🔥

Return a list of supported QMP commands by this server. It’s the command menu, basically. 👑

Return [CommandInfo] — A list of all supported commands

Example:

-> { "execute": "query-commands" }
<- {
      "return":[
         {
            "name":"query-balloon"
         },
         {
            "name":"system_powerdown"
         },
         ...
      ]
    }

This example has been shortened as the real response is too long. So don’t come for the ..., it’s doing its best. 😭

🫶 Command `quit` (Since: 0.14) 🫶

Request graceful QEMU process termination. Please and thank you. 🕊️

While every attempt is made to send the QMP response before terminating, this is not guaranteed. When using this interface, a premature EOF would not be unexpected. So yes, bestie, the goodbye might get cut off mid-sentence. 💀

Example:

-> { "execute": "quit" }
<- { "return": {} }

🎀 Enum `MonitorMode` (Since: 5.0) 🎀

An enumeration of monitor modes. Pick your fighter. ⚔️

Values

readline — HMP monitor (human-oriented command line interface)
control — QMP monitor (JSON-based machine interface)

🌸 Object `MonitorOptions` (Since: 5.0) 🌸

Options to be used for adding a new monitor. New monitor, who dis? 💖

Members

id (string, optional) — Name of the monitor
mode (MonitorMode, optional) — Selects the monitor mode (default: readline in the system emulator, control in qemu-storage-daemon)
pretty (boolean, optional) — Enables pretty printing (QMP only)
chardev (string) — Name of a character device to expose the monitor on

✨ QMP INTROSPECTION ✨

🔍 Command `query-qmp-schema` (Since: 2.5)

Okay bestie, this one is the selfie-cam of QMP — it exposes the QMP wire ABI as an array of SchemaInfo. Translation: it lets QMP clients figure out what commands and events are available in this QEMU, plus their parameters and results. Iconic, right?

But listen, babes, the SchemaInfo can't reflect all the rules and restrictions that apply to QMP. It's interface introspection (figuring out what's there), not interface specification. The specification lives in the QAPI schema. Periodt.

And furthermore — while we strive to keep the QMP wire format backwards-compatible across QEMU versions — the introspection output is not guaranteed to have the same stability. For example, one version of QEMU may list an object member as an optional non-variant, while another lists the same member only through the object's variants; or the type of a member may change from a generic string into a specific enum, or from one specific type into an alternate that includes the original type alongside something else. So yeah, don't get too attached to the exact shape, ngl 💀

Return [SchemaInfo] —

an array where each element describes an entity in the ABI: command, event, type, ...

The order of the various elements is unspecified; however, all names are guaranteed to be unique (no name will be duplicated with different meta-types). So like, the vibes are unordered but the names are exclusive 😌

Note: The QAPI schema is also used to help define internal interfaces, by defining QAPI types. These are not part of the QMP wire ABI, and therefore not returned by this command. So if you're looking for those, they're not on the menu, bestie 🙈

🏷️ Enum `SchemaMetaType` (Since: 2.5)

This is a SchemaInfo's meta type — i.e. the kind of entity it describes. Like a little name tag at a party 🎀

Values

builtin — a predefined type such as 'int' or 'bool'.
enum — an enumeration type
array — an array type
object — an object type (struct or union)
alternate — an alternate type
command — a QMP command
event — a QMP event

📦 Object `SchemaInfo` (Since: 2.5)

Members

name (string) — the entity's name, inherited from base. The SchemaInfo is always referenced by this name. Commands and events have the name defined in the QAPI schema. Unlike command and event names, type names are not part of the wire ABI. Consequently, type names are meaningless strings here, although they are still guaranteed unique regardless of meta-type. (so like, they're just cute little labels, no cap)
meta-type (SchemaMetaType) — the entity's meta type, inherited from base.
features ([string], optional) — names of features associated with the entity, in no particular order. (since 4.1 for object types, 4.2 for commands, 5.0 for the rest)
When meta-type is builtin: The members of SchemaInfoBuiltin.
When meta-type is enum: The members of SchemaInfoEnum.
When meta-type is array: The members of SchemaInfoArray.
When meta-type is object: The members of SchemaInfoObject.
When meta-type is alternate: The members of SchemaInfoAlternate.
When meta-type is command: The members of SchemaInfoCommand.
When meta-type is event: The members of SchemaInfoEvent.

🧱 Object `SchemaInfoBuiltin` (Since: 2.5)

Additional SchemaInfo members for meta-type builtin.

Members

json-type (JSONType) — the JSON type used for this type on the wire.

🌈 Enum `JSONType` (Since: 2.5)

The four primitive and two structured types according to RFC 8259 section 1, plus int (split off number), plus the obvious top type value. Like a whole little taxonomy, honestly obsessed 🦋

Values

string — JSON string
number — JSON number
int — JSON number that is an integer
boolean — literal false or true
null — literal null
object — JSON object
array — JSON array
value — any JSON value

🎀 Object `SchemaInfoEnum` (Since: 2.5)

Additional SchemaInfo members for meta-type enum.

Members

members ([SchemaInfoEnumMember]) — the enum type's members, in no particular order. (since 6.2)
values ([string]) — the enumeration type's member names, in no particular order. Redundant with members. Just for backward compatibility.

Features

deprecated — Member values is deprecated. Use members instead.

Values of this type are JSON string on the wire.

🍓 Object `SchemaInfoEnumMember` (Since: 6.2)

An object member. Simple, clean, does exactly what it says 💅

Members

name (string) — the member's name, as defined in the QAPI schema.
features ([string], optional) — names of features associated with the member, in no particular order.

🌸 Object `SchemaInfoArray` (Since: 2.5)

Additional SchemaInfo members for meta-type array.

Members

element-type (string) — the array type's element type.

Values of this type are JSON array on the wire.

🫶 Object `SchemaInfoObject` (Since: 2.5)

Additional SchemaInfo members for meta-type object. This is the big one, bestie 👑

Members

members ([SchemaInfoObjectMember]) — the object type's (non-variant) members, in no particular order.
tag (string, optional) — the name of the member serving as type tag. An element of members with this name must exist.
variants ([SchemaInfoObjectVariant], optional) — variant members, i.e. additional members that depend on the type tag's value. Present exactly when tag is present. The variants are in no particular order, and may even differ from the order of the values of the enum type of the tag.

Values of this type are JSON object on the wire.

🌼 Object `SchemaInfoObjectMember` (Since: 2.5)

An object member.

Members

name (string) — the member's name, as defined in the QAPI schema.
type (string) — the name of the member's type.
default (value, optional) — default when used as command parameter. If absent, the parameter is mandatory. If present, the value must be null. The parameter is optional, and behavior when it's missing is not specified here. Future extension: if present and non-null, the parameter is optional, and defaults to this value.
features ([string], optional) — names of features associated with the member, in no particular order. (since 5.0)

🧚 Object `SchemaInfoObjectVariant` (Since: 2.5)

The variant members for a value of the type tag.

Members

case (string) — a value of the type tag.
type (string) — the name of the object type that provides the variant members when the type tag has value case.

⭐ Object `SchemaInfoAlternate` (Since: 2.5)

Additional SchemaInfo members for meta-type alternate.

Members

members ([SchemaInfoAlternateMember]) — the alternate type's members, in no particular order. The members' wire encoding is distinct, see How to use the QAPI code generator <> section Alternate types.

On the wire, this can be any of the members. Pick your fighter, literally any of them 💀

🎐 Object `SchemaInfoAlternateMember` (Since: 2.5)

An alternate member.

Members

type (string) — the name of the member's type.

👑 Object `SchemaInfoCommand` (Since: 2.5)

Additional SchemaInfo members for meta-type command.

Members

arg-type (string) — the name of the object type that provides the command's parameters.
ret-type (string) — the name of the command's result type.
allow-oob (boolean, optional) — whether the command allows out-of-band execution, defaults to false (Since: 2.12)

🔔 Object `SchemaInfoEvent` (Since: 2.5)

Additional SchemaInfo members for meta-type event.

Members

arg-type (string) — the name of the object type that provides the event's parameters.

🧸 QEMU OBJECT MODEL (QOM) 🧸

🔖 Object `ObjectPropertyInfo` (Since: 1.2)

Members

name (string) — the name of the property
type (string) —

the type of the property. This will typically come in one of four forms:

A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'. These types are mapped to the appropriate JSON type.
A child type in the form 'child<subtype>' where subtype is a qdev device type name. Child properties create the composition tree.
A link type in the form 'link<subtype>' where subtype is a qdev device type name. Link properties form the device model graph.

description (string, optional) — if specified, the description of the property.
default-value (value, optional) — the default value, if any (since 5.0)

🍬 Object `ObjectPropertyValue` (Since: 10.1)

Members

name (string) — the name of the property.
type (string) — the type of the property, as described in ObjectPropertyInfo.
value (value, optional) — the value of the property. Absent when the property cannot be read. (it's giving "no thoughts, head empty" 🙈)

✨ Object `ObjectPropertiesValues` (Since: 10.1)

Members

…and the member list is literally right there in the next bit, bestie 🫶

properties ([ObjectPropertyValue]) — a list of properties. That's the last member, bestie, we got there 💖

✨ Command `qom-list` (Since: 1.2)

List the properties of an object when you hand it a path in the object model. It's giving "tell me everything about this thing" energy 👑

Arguments

path (string) — the path within the object model. See qom-get for a description of this parameter. Yes, we're cross-referencing, keep up 🫶

Return [ObjectPropertyInfo] — a list that describe the properties of the object.

Example:

-> { "execute": "qom-list",
     "arguments": { "path": "/chardevs" } }
<- { "return": [ { "name": "type", "type": "string" },
                 { "name": "parallel0", "type": "child<chardev-vc>" },
                 { "name": "serial0", "type": "child<chardev-vc>" },
                 { "name": "mon0", "type": "child<chardev-stdio>" } ] }

🌸 Command `qom-get` (Since: 1.2)

Get a property value. Simple on the surface, lowkey iconic underneath 💅

Arguments

path (string) —

The path within the object model. There are two forms of supported paths--absolute and partial paths.

Absolute paths are derived from the root object and can follow child<> or link<> properties. Since they can follow link<> properties, they can be arbitrarily long. Absolute paths look like absolute filenames and are prefixed with a leading slash.

Partial paths look like relative filenames. They do not begin with a prefix. The matching rules for partial paths are subtle but designed to make specifying objects easy. At each level of the composition tree, the partial path is matched as an absolute path. The first match is not returned. At least two matches are searched for. A successful result is only returned if only one match is found. If more than one match is found, a flag is return to indicate that the match was ambiguous. (Yes — "a flag is return", that's the manpage's grammar not mine, don't come for me 😭)

property (string) — The property name to read.

Return value — The property value. The type depends on the property type. child<> and link<> properties are returned as #str pathnames. All integer property types (u8, u16, etc) are returned as #int.

Example: Use absolute path

 -> { "execute": "qom-get",
      "arguments": { "path": "/machine/unattached/device[0]",
                     "property": "hotplugged" } }
 <- { "return": false }

Example: Use partial path

 -> { "execute": "qom-get",
      "arguments": { "path": "unattached/sysbus",
                     "property": "type" } }
 <- { "return": "System" }

🎀 Command `qom-list-get` (Since: 10.1)

List properties and their values for every object path you drop in the input list. It's a lil combo deal, we love efficiency ✨

Arguments

paths ([string]) — The absolute or partial path for each object, as described in qom-get.

Errors

If any path is not valid or is ambiguous

Return [ObjectPropertiesValues] — A list where each element is the result for the corresponding element of paths.

🦋 Command `qom-set` (Since: 1.2)

Set a property value. Changing things, main character behavior fr fr 🔥

Arguments

path (string) — see qom-get for a description of this parameter
property (string) — the property name to set
value (value) — a value who's type is appropriate for the property type. See qom-get for a description of type mapping.

Example:

 -> { "execute": "qom-set",
      "arguments": { "path": "/machine",
                     "property": "graphics",
                     "value": false } }
 <- { "return": {} }

🌈 Object `ObjectTypeInfo` (Since: 1.1)

This structure describes a search result from qom-list-types. Basically a little receipt of what the search found 🧾

Members

name (string) — the type name found in the search
abstract (boolean, optional) — the type is abstract and can't be directly instantiated. Omitted if false. (since 2.10)
parent (string, optional) — Name of parent type, if any (since 2.10)

⭐ Command `qom-list-types` (Since: 1.1)

Return a list of types given search parameters. Type directory, but make it fashion 💅

Arguments

implements (string, optional) — if specified, only return types that implement this type name
abstract (boolean, optional) — if true, include abstract types in the results

Return [ObjectTypeInfo] — a list of types, or an empty list if no results are found

🫶 Command `qom-list-properties` (Since: 2.12)

List properties associated with a QOM object. Peak curiosity, obsessed 🍓

Arguments

typename (string) — the type name of an object

Note: Objects can create properties at runtime, for example to describe links between different devices and/or objects. These properties are not included in the output of this command. So don't @ me when something's missing, it's literally documented 🙈

Return [ObjectPropertyInfo] — a list describing object properties

🧚 Object `CanHostSocketcanProperties` (Since: 2.12)

Availability: CONFIG_LINUX

Properties for can-host-socketcan objects.

Members

if (string) — interface name of the host system CAN bus to connect to
canbus (string) — object ID of the can-bus object to connect to the host interface

💜 Object `ColoCompareProperties` (Since: 2.8)

Properties for colo-compare objects. Packet-comparing royalty 👑

Members

primary_in (string) — name of the character device backend to use for the primary input (incoming packets are redirected to outdev)
secondary_in (string) — name of the character device backend to use for secondary input (incoming packets are only compared to the input on primary_in and then dropped)
outdev (string) — name of the character device backend to use for output
iothread (string) — name of the iothread to run in
notify_dev (string, optional) — name of the character device backend to be used to communicate with the remote colo-frame (only for Xen COLO)
compare_timeout (int, optional) — the maximum time to hold a packet from primary_in for comparison with an incoming packet on secondary_in in milliseconds (default: 3000)
expired_scan_cycle (int, optional) — the interval at which colo-compare checks whether packets from primary have timed out, in milliseconds (default: 3000)
max_queue_size (int, optional) — the maximum number of packets to keep in the queue for comparing with incoming packets from secondary_in. If the queue is full and additional packets are received, the additional packets are dropped. (default: 1024)
vnet_hdr_support (boolean, optional) — if true, vnet header support is enabled (default: false)

🔥 Object `CryptodevBackendProperties` (Since: 2.8)

Properties for cryptodev-backend and cryptodev-backend-builtin objects. Crypto girlies rise 🫶

Members

queues (int, optional) — the number of queues for the cryptodev backend. Ignored for cryptodev-backend and must be 1 for cryptodev-backend-builtin. (default: 1)
throttle-bps (int, optional) — limit total bytes per second (Since 8.0)
throttle-ops (int, optional) — limit total operations per second (Since 8.0)

💀 Object `CryptodevVhostUserProperties` (Since: 2.12)

Availability: CONFIG_VHOST_CRYPTO

Properties for cryptodev-vhost-user objects.

Members

chardev (string) — the name of a Unix domain socket character device that connects to the vhost-user server
The members of CryptodevBackendProperties. (yes, it inherits, we love a nepo-baby object 😌)

🌸 Object `DBusVMStateProperties` (Since: 5.0)

Properties for dbus-vmstate objects.

Members

addr (string) — the name of the DBus bus to connect to
id-list (string, optional) — a comma separated list of DBus IDs of helpers whose data should be included in the VM state on migration

✨ Enum `NetfilterInsert` (Since: 5.0)

Indicates where to insert a netfilter relative to a given other filter. Positional drama, but make it networking 💅

Values

before — insert before the specified filter
behind — insert behind the specified filter

🎀 Object `NetfilterProperties` (Since: 2.5)

Properties for objects of classes derived from netfilter.

Members

netdev (string) — id of the network device backend to filter
queue (NetFilterDirection, optional) — indicates which queue(s) to filter (default: all)
status (string, optional) — indicates whether the filter is enabled ("on") or disabled ("off") (default: "on")
position (string, optional) — specifies where the filter should be inserted in the filter list. "head" means the filter is inserted at the head of the filter list, before any existing filters. "tail" means the filter is inserted at the tail of the filter list, behind any existing filters (default). "id=<id>" means the filter is inserted before or behind the filter specified by <id>, depending on the insert property. (default: "tail")
insert (NetfilterInsert, optional) — tells it where to insert the filter, relative to whatever filter you passed in position. Lowkey ignored if position is "head" or "tail", bestie. (default: behind)

🌸 Object `FilterBufferProperties` (Since: 2.5)

Properties for filter-buffer objects.

Members

interval (int) — a non-zero interval in microseconds. Every packet that shows up during that interval gets held back until the interval ends. Periodt, they wait their turn.
plus all the members of NetfilterProperties.

🎀 Object `FilterDumpProperties` (Since: 2.5)

Properties for filter-dump objects.

Members

file (string) — the filename where all those dumped packets get stored 💾
maxlen (int, optional) — the max number of bytes per packet that actually get stored (default: 65536)
plus all the members of NetfilterProperties.

🦋 Object `FilterMirrorProperties` (Since: 2.6)

Properties for filter-mirror objects.

Members

outdev (string) — the name of a character device backend that every incoming packet gets mirrored to 🪞
vnet_hdr_support (boolean, optional) — if true, vnet header support is enabled (default: false)
plus all the members of NetfilterProperties.

✨ Object `FilterRedirectorProperties` (Since: 2.6)

Properties for filter-redirector objects.

Heads up bestie: at least one of indev or outdev must be present. And if both are there, they can't point at the same character device backend — that's a no-no.

Members

indev (string, optional) — the name of a character device backend that packets are received from and then redirected to the filtered network device
outdev (string, optional) — the name of a character device backend that all incoming packets get redirected to
vnet_hdr_support (boolean, optional) — if true, vnet header support is enabled (default: false)
plus all the members of NetfilterProperties.

🧚 Object `FilterRewriterProperties` (Since: 2.8)

Properties for filter-rewriter objects.

Members

vnet_hdr_support (boolean, optional) — if true, vnet header support is enabled (default: false)
plus all the members of NetfilterProperties.

🌈 Object `InputBarrierProperties` (Since: 4.2)

Properties for input-barrier objects.

Members

name (string) — the screen name exactly as declared in the screens section of barrier.conf
server (string, optional) — hostname of the Barrier server (default: "localhost")
port (string, optional) — TCP port of the Barrier server (default: "24800")
x-origin (string, optional) — x coordinate of the leftmost pixel on the guest screen (default: "0")
y-origin (string, optional) — y coordinate of the topmost pixel on the guest screen (default: "0")
width (string, optional) — the width of the secondary screen in pixels (default: "1920")
height (string, optional) — the height of the secondary screen in pixels (default: "1080")

🐧 Object `InputLinuxProperties` (Since: 2.6)

Availability: CONFIG_LINUX

Properties for input-linux objects.

Members

evdev (string) — the path of the host evdev device you want to use
grab_all (boolean, optional) — if true, grab gets toggled for all devices (like, both keyboard and mouse) instead of just one device (default: false)
repeat (boolean, optional) — enables auto-repeat events (default: false)
grab-toggle (GrabToggleKeys, optional) — the key or key combo that toggles device grab (default: ctrl-ctrl)

💜 Object `EventLoopBaseProperties` (Since: 7.1)

Common properties for event loops. The shared lore, fr fr.

Members

aio-max-batch (int, optional) — maximum number of requests in a batch for the AIO engine; 0 means the engine just uses its own default. (default: 0)
thread-pool-min (int, optional) — minimum number of threads reserved in the thread pool (default:0)
thread-pool-max (int, optional) — maximum number of threads the thread pool can contain (default:64)

⭐ Object `IothreadProperties` (Since: 2.0)

Properties for iothread objects.

Members

poll-max-ns (int, optional) — the max number of nanoseconds to busy-wait for events. 0 means polling is fully disabled (default: 32768 on POSIX hosts, 0 otherwise)
poll-grow (int, optional) — the multiplier used to bump the polling time up when the algorithm notices it's missing events because it wasn't polling long enough. 0 picks a default behaviour (default: 0)
poll-shrink (int, optional) — the divisor used to shrink the polling time when the algorithm notices it's spending way too long polling without encountering any events. 0 picks a default behaviour (default: 0)
poll-weight (int, optional) — the weight factor for adaptive polling. It decides how much the most recent event interval affects the next polling duration calculation. If it's set to 0, the system default value of 3 is used. Typical values: 1 (high weight on recent interval), 2-4 (moderate weight on recent interval). (default: 0) (since 11.1)
plus all the members of EventLoopBaseProperties.

Little fun fact: the aio-max-batch option is available since 6.1.

🎀 Object `MainLoopProperties` (Since: 7.1)

Properties for the main-loop object.

Members

literally just the members of EventLoopBaseProperties. That's it. That's the whole object. 💅

🔥 Object `MemoryBackendProperties` (Since: 2.1)

Properties for objects of classes derived from memory-backend. Big one, buckle up.

Members

merge (boolean, optional) — if true, mark that memory as mergeable (default depends on the machine type)
dump (boolean, optional) — if true, include the memory in core dumps (default depends on the machine type)
host-nodes ([int], optional) — the list of NUMA host nodes to bind the memory to
policy (HostMemPolicy, optional) — the NUMA policy (default: 'default')
prealloc (boolean, optional) — if true, preallocate the memory (default: false)
prealloc-threads (int, optional) — number of CPU threads to use for prealloc (default: 1)
prealloc-context (string, optional) — thread context to use for creating the preallocation threads (default: none) (since 7.2)
share (boolean, optional) — if false, the memory is private to QEMU; if true, it's shared (default false for the backends memory-backend-file and memory-backend-ram, true for the backends memory-backend-epc, memory-backend-memfd, and memory-backend-shm)
reserve (boolean, optional) — if true, reserve swap space (or huge pages) if applicable (default: true) (since 6.1)
size (int) — size of the memory region in bytes
x-use-canonical-path-for-ramblock-id (boolean, optional) — if true, the canonical path is used for ramblock-id. Disable this for 4.0 machine types or older so migration with newer QEMU versions still works. (default: false generally, but true for machine types <= 4.0)

Note: prealloc=true and reserve=false cannot be set at the same time — pick one, bestie 😭. With reserve=true, the behaviour depends on the operating system: for example, Linux will not reserve swap space for shared file mappings — "not applicable". In contrast, reserve=false will bail out if it cannot be configured accordingly.

💖 Object `MemoryBackendFileProperties` (Since: 2.1)

Properties for memory-backend-file objects.

Members

align (int, optional) — the base address alignment when QEMU mmap(2)s mem-path. Some backend stores specified by mem-path require an alignment different from the default one QEMU uses — e.g. the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In cases like that, you can specify the required alignment with this option. 0 selects a default alignment (currently the page size). (default: 0)
offset (int, optional) — the offset into the target file that the region starts at. You can use this to back multiple regions with a single file. Must be a multiple of the page size. (default: 0) (since 8.1)
discard-data (boolean, optional) — if true, the file contents can be destroyed when QEMU exits, so we avoid unnecessarily flushing data to the backing file. Note that discard-data is only an optimization, and QEMU might not discard file contents if it aborts unexpectedly or gets terminated using SIGKILL. (default: false)
mem-path (string) — the path to either a shared memory or huge page filesystem mount
pmem (boolean, optional) — specifies whether the backing file given by mem-path is in host persistent memory that can be accessed using the SNIA NVM programming model (e.g. Intel NVDIMM).
readonly (boolean, optional) — if true, the backing file is opened read-only; if false, it's opened read-write. (default: false)
rom (OnOffAuto, optional) — do we make Read Only Memory (ROM) that the VM literally cannot touch? ✨ Any write to that ROM gets denied, periodt. Most setups want writable RAM instead of ROM (ngl that's the vibe 99% of the time), but some specific cases — like R/O NVDIMMs — actually eat ROM up. Set it to 'on' and you get ROM, set it to 'off' and you get writable RAM, and set it to 'auto' and the value of the readonly property decides for you. This one's mainly here for when you want proper RAM in configs that would traditionally create ROM before this property even existed: VM templating, where we open a file readonly (readonly set to true) and mark the memory private for QEMU (share set to false). For that whole situation you need writable RAM not ROM, so you set this to 'off'. (default: auto, since 8.2) 💅
The members of MemoryBackendProperties.

🧚 Object `MemoryBackendMemfdProperties` (Since: 2.12)

Availability: CONFIG_LINUX 🐧

Properties for memory-backend-memfd objects.

Members

hugetlb (boolean, optional) — if true, the file we're creating lives in the hugetlbfs filesystem (default: false)
hugetlbsize (int, optional) — the hugetlb page size on systems that support multiple hugetlb page sizes (it has to be a power of 2 value that the system actually supports, no cap). 0 selects a default page size. This option is completely ignored if hugetlb is false. (default: 0)
seal (boolean, optional) — if true, create a sealed-file, which blocks any further resizing of the memory (default: true)
The members of MemoryBackendProperties.

🌸 Object `MemoryBackendShmProperties` (Since: 9.1)

Availability: CONFIG_POSIX

Properties for memory-backend-shm objects.

This memory backend only does shared memory, which is the default. That's it, that's the whole personality. 💅

Members

The members of MemoryBackendProperties.

💜 Object `MemoryBackendEpcProperties` (Since: 6.2)

Availability: CONFIG_LINUX 🐧

Properties for memory-backend-epc objects.

The merge boolean option is false by default with epc.

The dump boolean option is false by default with epc.

Members

The members of MemoryBackendProperties.

🎀 Object `PrManagerHelperProperties` (Since: 2.11)

Availability: CONFIG_LINUX 🐧

Properties for pr-manager-helper objects.

Members

path (string) — the path to a Unix domain socket for connecting to the external helper

⭐ Object `QtestProperties` (Since: 6.0)

Properties for qtest objects.

Members

chardev (string) — the chardev used to receive qtest commands on
log (string, optional) — the path to a log file

🦋 Object `RemoteObjectProperties` (Since: 6.0)

Properties for x-remote-object objects.

Members

fd (string) — file descriptor name previously passed via the getfd command
devid (string) — the id of the device to be associated with the file descriptor

🔥 Object `VfioUserServerProperties` (Since: 7.1)

Properties for x-vfio-user-server objects.

Members

socket (SocketAddress) — socket to be used by the libvfio-user library
device (string) — the ID of the device to be emulated at the server

👑 Object `IOMMUFDProperties` (Since: 9.0)

Properties for iommufd objects.

Members

fd (string, optional) — file descriptor name previously passed via the getfd command, which represents a pre-opened /dev/iommu. This lets the iommufd object be shared across several subsystems (VFIO, VDPA, ...), and lets the file descriptor be shared with another process, e.g. DPDK. (default: QEMU opens /dev/iommu by itself)

🌈 Object `AcpiGenericInitiatorProperties` (Since: 9.0)

Properties for acpi-generic-initiator objects.

Members

pci-dev (string) — PCI device ID to be associated with the node
node (int) — NUMA node associated with the PCI device

🍓 Object `AcpiGenericPortProperties` (Since: 9.2)

Properties for acpi-generic-port objects.

Members

pci-bus (string) — QOM path of the PCI bus of the hostbridge associated with this SRAT Generic Port Affinity Structure. This is the same as the bus parameter for the root ports attached to this host bridge. The resulting SRAT Generic Port Affinity Structure will refer to the ACPI object in DSDT that represents the host bridge (e.g. ACPI0016 for CXL host bridges). See ACPI 6.5 Section 5.2.16.7 for more information.
node (int) — similar to a NUMA node ID, but instead of providing a reference point used for defining NUMA distances and access characteristics to memory or from an initiator (e.g. CPU), this node defines the boundary point between non-discoverable system buses which must be described by firmware, and a discoverable bus. NUMA distances and access characteristics are defined to and from that point. For system software to establish full initiator to target characteristics, this information must be combined with information retrieved from the discoverable part of the path. An example would use CDAT (see UEFI.org) information read from devices and switches in conjunction with link characteristics read from PCIe Configuration space. To get the full path latency from CPU to CXL attached DRAM CXL device: add the latency from CPU to Generic Port (from HMAT indexed via the node ID in this SRAT structure) to that for CXL bus links, the latency across intermediate switches and from the EP port to the actual memory. Bandwidth is more complex as there may be interleaving across multiple devices and shared links in the path.

🧸 Object `RngProperties` (Since: 1.3)

Properties for objects of classes derived from rng.

Members

opened (boolean, optional) — if true, the device is opened immediately when applying this option and will probably fail when processing the next option. Don't use this, bestie; it's only provided for compatibility. (default: false)

Features

deprecated — the opened member is deprecated. Setting it to true doesn't make sense, and false is already the default. 💀

🫶 Object `RngEgdProperties` (Since: 1.3)

Properties for rng-egd objects.

Members

chardev (string) — the name of a character device backend that provides the connection to the RNG daemon
The members of RngProperties.

💖 Object `RngRandomProperties` (Since: 1.3)

Availability: CONFIG_POSIX

Properties for rng-random objects.

Members

filename (string, optional) — the filename of the device on the host to obtain entropy from (default: "/dev/urandom")
The members of RngProperties.

🐣 Object `IgvmCfgProperties` (Since: 10.1)

Availability: CONFIG_IGVM

Properties common to objects that handle IGVM files.

Members

file (string) — IGVM file to use to configure guest

💅 Object `SevCommonProperties` (Since: 9.1)

Properties common to objects that are derivatives of sev-common.

Members

sev-device (string, optional) — SEV device to use (default: "/dev/sev")
cbitpos (int, optional) — C-bit location in page table entry (default: 0)
reduced-phys-bits (int) — number of bits in physical addresses that become unavailable when SEV is enabled
kernel-hashes (boolean, optional) — if true, add hashes of kernel/initrd/cmdline to a designated guest firmware page for measured boot with -kernel (default: false) (since 6.2)

Features

confidential-guest-reset — if present, the hypervisor supports confidential guest resets (since 11.0). 👑

✨ Object `SevGuestProperties` (Since: 2.12)

Properties for sev-guest objects.

Members

dh-cert-file (string, optional) — guest owners DH certificate (encoded with base64)
session-file (string, optional) — guest owners session parameters (encoded with base64)
policy (int, optional) — SEV policy value (default: 0x1)
handle (int, optional) — SEV firmware handle (default: 0)
legacy-vm-type (OnOffAuto, optional) — use the legacy KVM_SEV_INIT KVM interface for creating the VM. The newer KVM_SEV_INIT2 interface, from Linux >= 6.10, syncs additional vCPU state when initializing the VMSA structures, which results in a different guest measurement 🔥. Set this to 'on' to force compatibility with older QEMU or kernel versions that rely on legacy KVM_SEV_INIT behavior. 'auto' behaves identically to 'on', but will automatically switch to using KVM_SEV_INIT2 if the user specifies any additional options that require it. If set to 'off', QEMU will require KVM_SEV_INIT2 unconditionally. (default: off) (since 9.1)
The members of SevCommonProperties.

Fr fr, that legacy-vm-type one is the kind of setting that changes your measurement, so don't flip it casually unless you know exactly why iykyk 🫶

🌸 Object `SevSnpGuestProperties` (Since: 9.1)

Okay so these are the properties for sev-snp-guest objects 💖 and honestly most of them are just direct arguments for the KVM_SNP_* interfaces — those are documented in the Linux kernel source under Documentation/arch/x86/amd-memory-encryption.rst, and those are in turn super tightly coupled with the SNP_INIT/SNP_LAUNCH_* firmware commands documented in the SEV-SNP Firmware ABI Specification (Rev 0.9). iykyk ✨

There's more usage info chilling in the QEMU source tree under docs/amd-memory-encryption too 🫶

Members

policy (int, optional) — the 'POLICY' parameter to the SNP_LAUNCH_START command, as defined in the SEV-SNP firmware ABI (default: 0x30000)
guest-visible-workarounds (string, optional) — 16-byte, base64-encoded blob to report hypervisor-defined workarounds, corresponding to the 'GOSVW' parameter of the SNP_LAUNCH_START command defined in the SEV-SNP firmware ABI (default: all-zero)
id-block (string, optional) — 96-byte, base64-encoded blob to provide the 'ID Block' structure for the SNP_LAUNCH_FINISH command defined in the SEV-SNP firmware ABI (default: all-zero)
id-auth (string, optional) — 4096-byte, base64-encoded blob to provide the 'ID Authentication Information Structure' for the SNP_LAUNCH_FINISH command defined in the SEV-SNP firmware ABI (default: all-zero)
author-key-enabled (boolean, optional) — true if the 'id-auth' blob contains the 'AUTHOR_KEY' field defined SEV-SNP firmware ABI (default: false)
host-data (string, optional) — 32-byte, base64-encoded, user-defined blob to provide to the guest, as documented for the 'HOST_DATA' parameter of the SNP_LAUNCH_FINISH command in the SEV-SNP firmware ABI (default: all-zero)
vcek-disabled (boolean, optional) — guests are by default allowed to choose between VLEK (Versioned Loaded Endorsement Key) or VCEK (Versioned Chip Endorsement Key) when requesting attestation reports from firmware. Set this to true to disable the use of VCEK. (default: false) (since: 9.1)
The members of SevCommonProperties 💅

🦋 Object `TdxGuestProperties` (Since: 10.1)

Properties for tdx-guest objects, bestie ✨

Members

attributes (int, optional) — the 'attributes' of a TD guest that is passed to KVM_TDX_INIT_VM
sept-ve-disable (boolean, optional) — toggle bit 28 of TD attributes to control disabling of EPT violation conversion to #VE on guest TD access of PENDING pages. Some guest OS (e.g., Linux TD guest) may require this to be set, otherwise they refuse to boot 😭 like they literally just won't
mrconfigid (string, optional) — ID for non-owner-defined configuration of the guest TD, e.g., run-time or OS configuration (base64 encoded SHA384 digest). Defaults to all zeros.
mrowner (string, optional) — ID for the guest TD’s owner (base64 encoded SHA384 digest). Defaults to all zeros.
mrownerconfig (string, optional) — ID for owner-defined configuration of the guest TD, e.g., specific to the workload rather than the run-time or OS (base64 encoded SHA384 digest). Defaults to all zeros.
quote-generation-socket (SocketAddress, optional) — socket address for Quote Generation Service (QGS). QGS is a daemon running on the host. Without it, the guest will not be able to get a TD quote for attestation 👑

Features

confidential-guest-reset — If present, the hypervisor supports confidential guest resets (since 11.0).

🎀 Object `ThreadContextProperties` (Since: 7.2)

Properties for thread context objects 🌸

Members

cpu-affinity ([int], optional) — the list of host CPU numbers used as CPU affinity for all threads created in the thread context (default: QEMU main thread CPU affinity)
node-affinity ([int], optional) — the list of host node numbers that will be resolved to a list of host CPU numbers used as CPU affinity. This is a shortcut for specifying the list of host CPU numbers belonging to the host nodes manually by setting cpu-affinity. (default: QEMU main thread affinity)

💅 Object `MonitorProperties` (Since: 11.1)

Properties for all monitors, no cap 🫶

Members

chardev (string) — ID of the character device providing the monitor transport

⭐ Object `MonitorHMPProperties` (Since: 11.1)

Properties for the HMP monitor ✨

Members

readline (boolean, optional) — whether to enable readline for line editing (default: true)
The members of MonitorProperties.

🌈 Enum `MonitorQMPCloseAction` (Since: 11.1)

Action to take when the character device backend is closed. Vibe check on shutdown, basically 💀

Values

none — take no action
delete — delete both the 'monitor-qmp' object and its associated character device backend object

👑 Object `MonitorQMPProperties` (Since: 11.1)

Properties for the QMP monitor, main character energy fr fr 💖

Members

pretty (boolean, optional) — whether to pretty print JSON responses (default: false)
close-action (MonitorQMPCloseAction, optional) — action to take when the character device backend is closed (default: none)
The members of MonitorProperties.

🧚 Enum `ObjectType` (Since: 6.0)

Values

acpi-generic-initiator — Not documented
acpi-generic-port — Not documented
authz-list — Not documented
authz-listfile — Not documented
authz-pam — Not documented
authz-simple — Not documented
can-bus — Not documented
can-host-socketcan — Not documented
colo-compare — Not documented
cryptodev-backend — Not documented
cryptodev-backend-builtin — Not documented
cryptodev-backend-lkcf — Not documented
cryptodev-vhost-user — Not documented
dbus-vmstate — Not documented
filter-buffer — Not documented
filter-dump — Not documented
filter-mirror — Not documented
filter-redirector — Not documented
filter-replay — Not documented
filter-rewriter — Not documented
igvm-cfg — Not documented
input-barrier — Not documented
input-linux — Not documented
iommufd — Not documented
iothread — Not documented
main-loop — Not documented
memory-backend-epc — Not documented
memory-backend-file — Not documented
memory-backend-memfd — Not documented
memory-backend-ram — Not documented
memory-backend-shm — Not documented
monitor-hmp — Not documented
monitor-qmp — Not documented
pef-guest — Not documented
pr-manager-helper — Not documented
qtest — Not documented
rng-builtin — Not documented
rng-egd — Not documented
rng-random — Not documented
secret — Not documented
secret_keyring — Not documented
sev-guest — Not documented
sev-snp-guest — Not documented
thread-context — Not documented
s390-pv-guest — Not documented
tdx-guest — Not documented
throttle-group — Not documented
tls-creds-anon — Not documented
tls-creds-psk — Not documented
tls-creds-x509 — Not documented
tls-cipher-suites — Not documented
x-remote-object — Not documented
x-vfio-user-server — Not documented

Features

unstable — Members x-remote-object and x-vfio-user-server are experimental 🧪 (the x- prefix was the giveaway bestie)

🍓 Object `ObjectOptions` (Since: 6.0)

Describes the options of a user creatable QOM object 💖

Members

qom-type (ObjectType) — the class name for the object to be created
id (string) — the name of the new object
When qom-type is acpi-generic-initiator: The members of AcpiGenericInitiatorProperties.
When qom-type is acpi-generic-port: The members of AcpiGenericPortProperties.
When qom-type is authz-list: The members of AuthZListProperties.
When qom-type is authz-listfile: The members of AuthZListFileProperties.
When qom-type is authz-pam: The members of AuthZPAMProperties.
When qom-type is authz-simple: The members of AuthZSimpleProperties.
When qom-type is can-host-socketcan: The members of CanHostSocketcanProperties.
When qom-type is colo-compare: The members of ColoCompareProperties.
When qom-type is cryptodev-backend: The members of CryptodevBackendProperties.
When qom-type is cryptodev-backend-builtin: The members of CryptodevBackendProperties.
When qom-type is cryptodev-backend-lkcf: The members of CryptodevBackendProperties.
cryptodev-vhost-user — the members of CryptodevVhostUserProperties.
dbus-vmstate — the members of DBusVMStateProperties.
filter-buffer — the members of FilterBufferProperties.
filter-dump — the members of FilterDumpProperties.
filter-mirror — the members of FilterMirrorProperties.
filter-redirector — the members of FilterRedirectorProperties.
filter-replay — the members of NetfilterProperties.
filter-rewriter — the members of FilterRewriterProperties.
igvm-cfg — the members of IgvmCfgProperties.
input-barrier — the members of InputBarrierProperties.
input-linux — the members of InputLinuxProperties.
iommufd — the members of IOMMUFDProperties.
iothread — the members of IothreadProperties.
main-loop — the members of MainLoopProperties.
memory-backend-epc — the members of MemoryBackendEpcProperties.
memory-backend-file — the members of MemoryBackendFileProperties.
memory-backend-memfd — the members of MemoryBackendMemfdProperties.
memory-backend-ram — the members of MemoryBackendProperties.
memory-backend-shm — the members of MemoryBackendShmProperties.
monitor-hmp — the members of MonitorHMPProperties.
monitor-qmp — the members of MonitorQMPProperties.
pr-manager-helper — the members of PrManagerHelperProperties.
qtest — the members of QtestProperties.
rng-builtin — the members of RngProperties.
rng-egd — the members of RngEgdProperties.
rng-random — the members of RngRandomProperties.
secret — the members of SecretProperties.
secret_keyring — the members of SecretKeyringProperties.
sev-guest — the members of SevGuestProperties.
sev-snp-guest — the members of SevSnpGuestProperties.
tdx-guest — the members of TdxGuestProperties.
thread-context — the members of ThreadContextProperties.
throttle-group — the members of ThrottleGroupProperties.
tls-creds-anon — the members of TlsCredsAnonProperties.
tls-creds-psk — the members of TlsCredsPskProperties.
tls-creds-x509 — the members of TlsCredsX509Properties.
tls-cipher-suites — the members of TlsCredsProperties.
x-remote-object — the members of RemoteObjectProperties.
x-vfio-user-server — the members of VfioUserServerProperties.

🌸 Command `object-add` (Since: 2.0) 🌸

Okay bestie, this one does exactly what it says on the tin: it creates a QOM object. That's it. That's the whole vibe. ✨

Arguments

The members of ObjectOptions.

Errors

If qom-type is not a valid class name.

Example:

-> { "execute": "object-add",
     "arguments": { "qom-type": "rng-random", "id": "rng1",
                    "filename": "/dev/hwrng" } }
<- { "return": {} }

🎀 Command `object-del` (Since: 2.0) 🎀

And this is the breakup arc 💔 — it removes a QOM object. Bye bestie, we hardly knew ye.

Arguments

id (string) -- the name of the QOM object to remove

Errors

If id is not a valid id for a QOM object

Example:

-> { "execute": "object-del", "arguments": { "id": "rng1" } }
<- { "return": {} }

🛠️ DEVICE INFRASTRUCTURE (QDEV) 🛠️

This is where the actual devices live, omg. Everything you plug into a machine passes through here, and honestly it's giving main character energy for the whole of QEMU. 👑

⭐ Command `device-list-properties` (Since: 1.2) ⭐

It lists all the properties that come with a device. Like a little property tour 🏡 of whatever device you're curious about.

Arguments

typename (string) -- the type name of a device

Return [ObjectPropertyInfo] -- a list describing a devices properties

Note: Objects can create properties at runtime, for example to describe links between different devices and/or objects. These properties are not included in the output of this command. So yeah, the list is cute but it's not the whole story, iykyk. 😭

💅 Command `device_add` (Since: 0.13) 💅

Add a device. Slay. 💖

Arguments

driver (string) -- the name of the new device's driver
bus (string, optional) -- the device's parent bus (device tree path)
id (string, optional) -- the device's ID, must be unique

Features

json-cli -- If present, the -device command line option supports JSON syntax with a structure identical to the arguments of this command.
json-cli-hotplug -- If present, the -device command line option supports JSON syntax without the reference counting leak that broke hot-unplug. (RIP to that bug bestie, we do not miss her 💀)

Notes

Additional arguments depend on the type.
For detailed information about this command, please refer to the docs/qdev-device-use.txt file.
It's possible to list device properties by running QEMU with the -device DEVICE,help command-line argument, where DEVICE is the device's name.

Example:

-> { "execute": "device_add",
     "arguments": { "driver": "e1000", "id": "net1",
                    "bus": "pci.0",
                    "mac": "52:54:00:12:34:56" } }
<- { "return": {} }

🦋 Command `device_del` (Since: 0.14) 🦋

Remove a device from a guest. The unplug arc begins 🫶

Arguments

id (string) -- the device's ID or QOM path

Errors

If id is not a valid device, DeviceNotFound

Note: okay this part matters, listen up — when this command completes, the device may not be removed from the guest. Hot removal is an operation that requires guest cooperation. This command merely requests that the guest begin the hot removal process. Completion of the device removal process is signaled with a DEVICE_DELETED event. Guest reset will automatically complete removal for all devices. If a guest-side error in the hot removal process is detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event is sent. Some errors cannot be detected. 😭 No cap, read that twice.

Example:

-> { "execute": "device_del",
     "arguments": { "id": "net1" } }
<- { "return": {} }

Example:

-> { "execute": "device_del",
     "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
<- { "return": {} }

✨ Event `DEVICE_DELETED` (Since: 1.5) ✨

Emitted whenever the device removal completion is acknowledged by the guest. At this point, it's safe to reuse the specified device ID. Device removal can be initiated by the guest or by HMP/QMP commands. So like — now you can breathe, the device is actually gone. 🍓

Members

device (string, optional) -- the device's ID if it has one
path (string) -- the device's QOM path

Example:

<- { "event": "DEVICE_DELETED",
     "data": { "device": "virtio-net-pci-0",
               "path": "/machine/peripheral/virtio-net-pci-0" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

🧚 Event `DEVICE_UNPLUG_GUEST_ERROR` (Since: 6.2) 🧚

Emitted when a device hot unplug fails due to a guest reported error. It's giving "we tried to unplug it and the guest said no" energy 🙈

Members

device (string, optional) -- the device's ID if it has one
path (string) -- the device's QOM path

Example:

<- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
     "data": { "device": "core1",
               "path": "/machine/peripheral/core1" },
     "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }

🌈 Command `device-sync-config` (Since: 9.2) 🌈

This command is unstable/experimental. ⚠️ Like, proceed with that knowledge, bestie.

Synchronize device configuration from host to guest part. First, copy the configuration from the host part (backend) to the guest part (frontend). Then notify guest software that device configuration changed. Two steps, both iconic. ✨

The command may be used to notify the guest about block device capacity change. Currently only vhost-user-blk device supports this. (Not everyone got the invite to this party yet 💅)

Arguments

id (string) -- the device's ID or QOM path

Features

unstable -- The command is experimental.

💖 COMMON MACHINE TYPES 💖

Enum `S390CpuEntitlement` (Since: 8.2)

Okay so this is literally just a little list of the CPU entitlements a virtual S390 CPU can assume, bestie. That's the whole vibe.

Values

auto — Not documented 🙈
low — Not documented 🙈
medium — Not documented 🙈
high — Not documented 🙈

Enum `CpuTopologyLevel` (Since: 9.2)

An enumeration of CPU topology levels — like, all the different "levels" your CPU layout can be stacked at, you know? 🧚

Values

thread — thread level, which would also be called SMT level or logical processor level. The threads option in SMPConfiguration is used to configure the topology of this level.
core — core level. The cores option in SMPConfiguration is used to configure the topology of this level.
module — module level. The modules option in SMPConfiguration is used to configure the topology of this level.
cluster — cluster level. The clusters option in SMPConfiguration is used to configure the topology of this level.
die — die level. The dies option in SMPConfiguration is used to configure the topology of this level.
socket — socket level, which would also be called package level. The sockets option in SMPConfiguration is used to configure the topology of this level.
book — book level. The books option in SMPConfiguration is used to configure the topology of this level.
drawer — drawer level. The drawers option in SMPConfiguration is used to configure the topology of this level.
default — default level. Some architectures will have default topology settings (e.g., cache topology), and this special level means following the architecture-specific settings.

Enum `CacheLevelAndType` (Since: 9.2)

Caches a system may have, slay. The enumeration value here is the combination of cache level and cache type — two truths in one little string 💅

Values

l1d — L1 data cache.
l1i — L1 instruction cache.
l2 — L2 (unified) cache.
l3 — L3 (unified) cache

Object `SmpCacheProperties` (Since: 9.2)

Cache information for an SMP system. Iconic little info bundle, ngl.

Members

cache (CacheLevelAndType) — Cache name, which is the combination of cache level and cache type.
topology (CpuTopologyLevel) — Cache topology level. It accepts the CPU topology enumeration as the parameter, i.e., CPUs in the same topology container share the same cache. 🫶

Object `SmpCachePropertiesWrapper` (Since: 9.2)

List wrapper of SmpCacheProperties — the little container that holds the whole gang.

Members

caches ([SmpCacheProperties]) — the list of SmpCacheProperties.

🦋 MACHINES 🦋

Enum `SysEmuTarget` (Since: 3.0)

The comprehensive enumeration of QEMU system emulation ("softmmu") targets. Fr fr, this is the whole roster. Run "./configure --help" in the project root directory, and look for the *-softmmu targets near the "--target-list" option. The individual target constants are not documented here, for the time being. 😭

Values

rx — since 5.0
avr — since 5.1
loongarch64 — since 7.1
hexagon — since 11.0
aarch64 — Not documented
alpha — Not documented
arm — Not documented
hppa — Not documented
i386 — Not documented
m68k — Not documented
microblaze — Not documented
mips — Not documented
mips64 — Not documented
mips64el — Not documented
mipsel — Not documented
or1k — Not documented
ppc — Not documented
ppc64 — Not documented
riscv32 — Not documented
riscv64 — Not documented
s390x — Not documented
sh4 — Not documented
sh4eb — Not documented
sparc — Not documented
sparc64 — Not documented
tricore — Not documented
x86_64 — Not documented
xtensa — Not documented
xtensaeb — Not documented

Note: The resulting QMP strings can be appended to the "qemu-system-" prefix to produce the corresponding QEMU executable name. This is true even for "qemu-system-x86_64". 💡

Enum `S390CpuState` (Since: 2.12)

An enumeration of cpu states that can be assumed by a virtual S390 CPU — the moods your virtual CPU can be in, basically ✨

Values

uninitialized — Not documented
stopped — Not documented
check-stop — Not documented
operating — Not documented
load — Not documented

Object `CpuInfoS390` (Since: 2.12)

Additional information about a virtual S390 CPU. Extra little details, iykyk.

Members

cpu-state (S390CpuState) — the virtual CPU's state
dedicated (boolean, optional) — the virtual CPU's dedication (since 8.2)
entitlement (S390CpuEntitlement, optional) — the virtual CPU's entitlement (since 8.2)

Object `CpuInfoFast` (Since: 2.12)

Information about a virtual CPU — the whole glow-up profile of one CPU 💅

Members

cpu-index (int) — index of the virtual CPU
qom-type (string) — QOM type name of the CPU (since 10.1)
qom-path (string) — path to the CPU object in the QOM tree
thread-id (int) — ID of the underlying host thread
props (CpuInstanceProperties, optional) — properties associated with a virtual CPU, e.g. the socket id
target (SysEmuTarget) — the QEMU system emulation target, which determines which additional fields will be listed (since 3.0)
When target is s390x: The members of CpuInfoS390. 🎀

Command `query-cpus-fast` (Since: 2.12)

Return information about all virtual CPUs. All of them. Every single one. 👑

Return [CpuInfoFast]

Example:

-> { "execute": "query-cpus-fast" }
<- { "return": [
        {
            "thread-id": 25627,
            "props": {
                "core-id": 0,
                "thread-id": 0,
                "socket-id": 0
            },
            "qom-path": "/machine/unattached/device[0]",
            "target":"x86_64",
            "cpu-index": 0
        },
        {
            "thread-id": 25628,
            "props": {
                "core-id": 0,
                "thread-id": 0,
                "socket-id": 1
            },
            "qom-path": "/machine/unattached/device[2]",
            "target":"x86_64",
            "cpu-index": 1
        }
    ]
}

Object `CompatProperty` (Since: 9.1)

Property default values specific to a machine type, for use by scripts/compare-machine-types. Very ✨niche✨ very demure.

Members

qom-type (string) — name of the QOM type to which the default applies
property (string) — name of its property to which the default applies
value (string) — the default value (machine-specific default can overwrite the "default" default, to avoid this use -machine none) ⚠️

Object `MachineInfo` (Since: 1.2)

Information describing a machine — the full little profile card of a machine type 🫶

Members

name (string) — the name of the machine
alias (string, optional) — an alias for the machine name
is-default (boolean, optional) — whether the machine is default
cpu-max (int) — maximum number of CPUs supported by the machine type (since 1.5)
hotpluggable-cpus (boolean) — cpu hotplug via -device is supported (since 2.7)
numa-mem-supported (boolean) — true if '-numa node,mem' option is supported by the machine type and false otherwise (since 4.1)
deprecated (boolean) — if true, the machine type is deprecated and may be removed in future versions of QEMU according to the QEMU deprecation policy (since 4.1) 💀
default-cpu-type (string, optional) — default CPU model typename if none is requested via the -cpu argument. (since 4.2)
default-ram-id (string, optional) — the default ID of initial RAM memory backend (since 5.2)
acpi (boolean) — machine type supports ACPI (since 8.0)
compat-props ([CompatProperty], optional) — The machine type's compatibility properties. Only present when query-machines argument compat-props is true. (since 9.1)

Features

unstable — Member compat-props is experimental. 🧪

Command `query-machines` (Since: 1.2)

Return a list of supported machines — the whole machine-type menu, bestie 📋

Arguments

compat-props (boolean, optional) — if true, also return compatibility properties. (default: false) (since 9.1)

Return [MachineInfo]

Features

unstable — Argument compat-props is experimental. 🧪

Example:

                     -> { "execute": "query-machines", "arguments": { "compat-props": true } }
                     <- { "return": [
                               {
                                  "hotpluggable-cpus": true,
                                  "name": "pc-q35-6.2",
                                  "compat-props": [
                                       {
                                          "qom-type": "virtio-mem",
                                          "property": "unplugged-inaccessible",
                                          "value": "off"
                                       }
                                   ],
                                   "numa-mem-supported": false,
                                   "default-cpu-type": "qemu64-x86_64-cpu",
                                   "cpu-max": 288,
                                   "deprecated": false,
                                   "default-ram-id": "pc.ram"
                               },
                               ...
                        }

See how the compat-props array just slides in there when you ask nicely? Obsessed. 💅

🌸 Object `CurrentMachineParams` (Since: 4.0)

The tea on the machine that's actually running right now. ☕

Members

wakeup-suspend-support (boolean) — true if the machine can wake up from suspend. Like, it can be woken, bestie.

⭐ Command `query-current-machine` (Since: 4.0)

Hands you the deets on the current virtual machine. Returns CurrentMachineParams, no cap.

🦋 Object `QemuTargetInfo` (Since: 1.2)

Info about the target configuration that got baked straight into the QEMU binary. It's giving "built-in, not added later."

Members

arch (SysEmuTarget) — the target architecture. literally which arch we're on.

✨ Command `query-target` (Since: 1.2)

Returns the info about the target for this QEMU. Returns QemuTargetInfo. Simple, clean, iconic.

🎀 Object `UuidInfo` (Since: 0.14)

Guest UUID info — that's Universally Unique Identifier, for the uninitiated. 🫶

Members

UUID (string) — the UUID of the guest.

Note: if nobody specified a UUID for the guest, you get back the nil UUID (all zeroes). So like, don't panic when it's all 0s, that's just the default vibe. 💀

🔥 Command `query-uuid` (Since: 0.14)

Queries the guest UUID info. Returns UuidInfo.

Example, because we love a visual:

                     -> { "execute": "query-uuid" }
                     <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }

💜 Object `GuidInfo` (Since: 2.9)

GUID info. Yes, GUID. Different acronym, same energy. 🧚

Members

guid (string) — the globally unique identifier.

🌈 Command `query-vm-generation-id` (Since: 2.9)

Shows the Virtual Machine Generation ID. Returns GuidInfo. slay.

👑 Command `system_reset` (Since: 0.14)

Performs a hard reset of a guest. Full send. 🔥

Example:

                     -> { "execute": "system_reset" }
                     <- { "return": {} }

🍓 Command `system_powerdown` (Since: 0.14)

Asks the guest to do a powerdown operation. Politely. It's a request, not a demand. 🙈

Note: a guest may or may not respond to this command. The command returning does not mean the guest accepted the request or that it actually shut down. Many guests will respond by prompting the user in some way — so like, don't @ me when nothing happens. 😭

Example:

                     -> { "execute": "system_powerdown" }
                     <- { "return": {} }

🧚 Command `system_wakeup` (Since: 1.1)

Wakes the guest up from suspend. If the guest has wake-up-from-suspend support enabled (that's the wakeup-suspend-support flag from query-current-machine), it wakes the guest from suspend when the guest is in SUSPENDED state. Otherwise? It returns an error. No vibes, just an error.

Note: prior to 4.0, this command does absolutely nothing if the guest isn't suspended. Iconic behaviour honestly.

Example:

                     -> { "execute": "system_wakeup" }
                     <- { "return": {} }

💅 Enum `LostTickPolicy` (Since: 2.0)

The policy for handling lost ticks in timer devices. Ticks get lost when, say, the guest is paused. It happens to the best of us.

Values

discard — throws away the missed ticks and keeps injecting future ones like normal. The guest OS will see the timer jump ahead by a potentially quite significant amount, all at once, as if that chunk of time simply never existed. Needless to say, such a sudden jump can easily confuse a guest OS that isn't specifically prepared to deal with it. Assuming the guest OS can deal with the time jump, the time in the guest and in the host should now match. It's giving time skip plot twist. 💀
delay — keeps delivering ticks at the normal rate. The guest OS won't notice anything is amiss, because from its POV time flowed normally the whole time. The catch? The time in the guest should now be behind the time in the host by exactly the amount of time during which ticks were missed. lowkey tragic.
slew — delivers ticks at a higher rate to catch up with the missed ones. The guest OS won't notice anything is amiss, since from its point of view time continued to flow normally. Once the timer catches up with all the missing ticks, the time in the guest and in the host should match. bestie caught up. 🫶

🌸 Command `inject-nmi` (Since: 0.14)

Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64). The command fails when the guest doesn't support injecting. F around and find out, basically. 🎀

Note: prior to 2.1, this command was only supported for x86 and s390 VMs.

Example:

                     -> { "execute": "inject-nmi" }
                     <- { "return": {} }

⭐ Enum `NumaOptionsType` (Since: 2.1)

Values

node — NUMA nodes configuration
dist — NUMA distance configuration (since 2.10)
cpu — property based CPU(s) to node mapping (Since: 2.10)
hmat-lb — memory latency and bandwidth information (Since: 5.0)
hmat-cache — memory side cache information (Since: 5.0)

🦋 Object `NumaOptions` (Since: 2.1)

A discriminated record of NUMA options. (for OptsVisitor) — fancy words for "pick a type, get the matching members." 💅

Members

type (NumaOptionsType) — NUMA option type
When type is node: the members of NumaNodeOptions.
When type is dist: the members of NumaDistOptions.
When type is cpu: the members of NumaCpuOptions.
When type is hmat-lb: the members of NumaHmatLBOptions.
When type is hmat-cache: the members of NumaHmatCacheOptions.

🎀 Object `NumaNodeOptions` (Since: 2.1)

Creates a guest NUMA node. (for OptsVisitor) — we're literally building nodes out here. 🔥

Members

nodeid (int, optional) — NUMA node ID (increase by 1 from 0 if omitted)
cpus ([int], optional) — VCPUs belonging to this node (assign VCPUS round-robin if omitted)
mem (int, optional) — memory size of this node; mutually exclusive with memdev. Equally divide total memory among nodes if both mem and memdev are omitted.
memdev (string, optional) — memory backend object. If specified for one node, it must be specified for all nodes. no halfsies.
initiator (int, optional) — defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the nodeid which has the memory controller responsible for this NUMA node. This field provides additional information as to the initiator node that is closest (as in directly attached) to this node, and therefore has the best performance (since 5.0). it's giving "who's your closest friend." 🫶

🌈 Object `NumaDistOptions` (Since: 2.10)

Sets the distance between 2 NUMA nodes. It's a situationship metric. 📏

Members

src (int) — source NUMA node.
dst (int) — destination NUMA node.
val (int) — NUMA distance from source node to destination node. When a node is unreachable from another node, set the distance between them to 255. that's the "we're not talking" number. 💀

✨ Object `CXLFixedMemoryWindowOptions` (Since: 7.1)

Creates a CXL Fixed Memory Window. 🪟

Members

size (int) — size of the Fixed Memory Window in bytes. Must be a multiple of 256MiB. read that again, bestie.
interleave-granularity (int, optional) — number of contiguous bytes for which accesses will go to a given interleave target. Accepted values [256, 512, 1k, 2k, 4k, 8k, 16k]
targets ([string]) — target root bridge IDs from -device ...,id=<ID> for each root bridge.

💜 Object `CXLFMWProperties` (Since: 7.1)

A whole list of CXL Fixed Memory Windows. Plural. We contain multitudes. 👑

Members

cxl-fmw ([CXLFixedMemoryWindowOptions]) — list of CXLFixedMemoryWindowOptions

🍓 Enum `X86CPURegister32` (Since: 1.5)

A X86 32-bit register. the classics. 🎀

Values

EAX — Not documented
EBX — Not documented
ECX — Not documented
EDX — Not documented
ESP — Not documented
EBP — Not documented
ESI — Not documented
EDI — Not documented

(yeah, all "Not documented" — the manpage said it, not me 🙈)

🧚 Object `X86CPUFeatureWordInfo` (Since: 1.5)

Info about a X86 CPU feature word. ⚙️

Members

cpuid-input-eax (int) — input EAX value for CPUID instruction for that feature word
cpuid-input-ecx (int, optional) — input ECX value for CPUID instruction for that feature word
cpuid-register (X86CPURegister32) — output register containing the feature bits
features (int) — value of output register, containing the feature bits

🦋 Object `DummyForceArrays` (Since: 2.5)

Not used by QMP; hack to let us use X86CPUFeatureWordInfoList internally. honestly? relatable. we've all been a hack to let something work internally. 💀

Members

unused ([X86CPUFeatureWordInfo]) — Not documented

⭐ Object `NumaCpuOptions` (Since: 2.10)

Option "-numa cpu" overrides the default cpu to node mapping. It accepts the same set of cpu properties as returned by query-hotpluggable-cpus[].props, where node-id could be used to override the default node mapping. iykyk. 💅

Members

plus the members of CpuInstanceProperties — yeah, those ones, they're literally right below bestie, keep reading 💖

🌸 Enum `HmatLBMemoryHierarchy` (Since: 5.0)

So this is the memory hierarchy situation inside the System Locality Latency and Bandwidth Information Structure of HMAT — and yes that's the Heterogeneous Memory Attribute Table, the acronym ate 💅

For more about HmatLBMemoryHierarchy, go peek at chapter 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.

Values:

memory — this structure is representing the memory performance, no cap
first-level — first level of memory side cache
second-level — second level of memory side cache
third-level — third level of memory side cache

🌈 Enum `HmatLBDataType` (Since: 5.0)

The data type in the System Locality Latency and Bandwidth Information Structure of HMAT (Heterogeneous Memory Attribute Table), same vibe as above ✨

For more about HmatLBDataType, see chapter 5.2.27.4: Table 5-146: Field "Data Type" of ACPI 6.3 spec.

Values:

access-latency — access latency (nanoseconds)
read-latency — read latency (nanoseconds)
write-latency — write latency (nanoseconds)
access-bandwidth — access bandwidth (Bytes per second)
read-bandwidth — read bandwidth (Bytes per second)
write-bandwidth — write bandwidth (Bytes per second)

🎀 Object `NumaHmatLBOptions` (Since: 5.0)

Sets the system locality latency and bandwidth info between Initiator and Target proximity Domains. Iconic little handshake between domains, honestly 🫶

For more about NumaHmatLBOptions, see chapter 5.2.27.4: Table 5-146 of ACPI 6.3 spec.

Members:

initiator (int) — the Initiator Proximity Domain.
target (int) — the Target Proximity Domain.
hierarchy (HmatLBMemoryHierarchy) — the Memory Hierarchy. Tells you whether we're talking performance of memory or of side cache.
data-type (HmatLBDataType) — presents the type of data, access/read/write latency or hit latency.
latency (int, optional) — the value of latency from initiator to target proximity domain, and the latency unit is ns (nanosecond).
bandwidth (int, optional) — the value of bandwidth between initiator and target proximity domain, bandwidth unit is Bytes per second.

🦋 Enum `HmatCacheAssociativity` (Since: 5.0)

Cache associativity in the Memory Side Cache Information Structure of HMAT. Say that five times fast, I dare you 😭

For more info on HmatCacheAssociativity, see chapter 5.2.27.5: Table 5-147 of ACPI 6.3 spec.

Values:

none — None (no memory side cache in this proximity domain, or cache associativity unknown)
direct — Direct Mapped
complex — Complex Cache Indexing (implementation specific)

💜 Enum `HmatCacheWritePolicy` (Since: 5.0)

Cache write policy in the Memory Side Cache Information Structure of HMAT — the "what happens when we write" of it all.

For more info on HmatCacheWritePolicy, see chapter 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.

Values:

none — None (no memory side cache in this proximity domain, or cache write policy unknown)
write-back — Write Back (WB)
write-through — Write Through (WT)

⭐ Object `NumaHmatCacheOptions` (Since: 5.0)

Sets the memory side cache info for a given memory domain. Giving the cache its whole little identity, periodt 💅

For more info on NumaHmatCacheOptions, see chapter 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.

Members:

node-id (int) — the memory proximity domain to which the memory belongs.
size (int) — the size of memory side cache in bytes.
level (int) — the cache level described in this structure.
associativity (HmatCacheAssociativity) — the cache associativity, none/direct-mapped/complex (complex cache indexing).
policy (HmatCacheWritePolicy) — the write policy, none/write-back/write-through.
line (int) — the cache line size in bytes.

🧚 Command `memsave` (Since: 0.14)

Saves a portion of guest memory to a file. Little memory scrapbook, adorable ngl 🌸

Arguments:

val (int) — the virtual address of the guest to start from
size (int) — the size of memory region to save
filename (string) — the file to save the memory to as binary data
cpu-index (int, optional) — the index of the virtual CPU to use for translating the virtual address (defaults to CPU 0)

Caution: Errors were not reliably returned until 1.1. So like, if you're on something ancient, the errors are giving mysterious and unknowable 💀

Example:

-> { "execute": "memsave",
     "arguments": { "val": 10,
                    "size": 100,
                    "filename": "/tmp/virtual-mem-dump" } }
<- { "return": {} }

🍓 Command `pmemsave` (Since: 0.14)

Saves a portion of guest physical memory to a file. Same energy as memsave but the physical one, iykyk ✨

Arguments:

val (int) — the physical address of the guest to start from
size (int) — the size of memory region to save
filename (string) — the file to save the memory to as binary data

Caution: Errors were not reliably returned until 1.1. Same deal bestie, don't trust the silence on the old versions 😭

Example:

-> { "execute": "pmemsave",
     "arguments": { "val": 10,
                    "size": 100,
                    "filename": "/tmp/physical-mem-dump" } }
<- { "return": {} }

🫶 Object `Memdev` (Since: 2.1)

Information about a memory backend. The whole rundown, the full dossier 👑

Members:

id (string, optional) — backend's ID if backend has 'id' property (since 2.9)
size (int) — memory backend size
merge (boolean) — whether memory merge support is enabled
dump (boolean) — whether memory backend's memory is included in a core dump
prealloc (boolean) — whether memory was preallocated
share (boolean) — whether memory is private to QEMU or shared (since 6.1)
reserve (boolean, optional) — whether swap space (or huge pages) was reserved if applicable. This corresponds to the user configuration and not the actual behavior implemented in the OS to perform the reservation. For example, Linux will never reserve swap space for shared file mappings. (since 6.1)
host-nodes ([int]) — host nodes for its memory policy
policy (HostMemPolicy) — memory policy of memory backend

🔥 Command `query-memdev` (Since: 2.1)

Returns information for all memory backends. All of them, no crumbs left behind 💖

Return [Memdev]

Example:

-> { "execute": "query-memdev" }
<- { "return": [
       {
         "id": "mem1",
         "size": 536870912,
         "merge": false,
         "dump": true,
         "prealloc": false,
         "share": false,
         "host-nodes": [0, 1],
         "policy": "bind"
       },
       {
         "size": 536870912,
         "merge": false,
         "dump": true,
         "prealloc": true,
         "share": false,
         "host-nodes": [2, 3],
         "policy": "preferred"
       }
     ]
   }

👑 Object `CpuInstanceProperties` (Since: 2.7)

Properties that identify a CPU. It's giving passport but for processors 🦋

Which members are optional and which are mandatory depends on the architecture and board. So like, read the room (and the board).

For s390x see CPU topology on s390x <#cpu-topology-s390x>.

The ids other than the node-id specify the position of the CPU within the CPU topology (as defined by the machine property "smp", thus see also type SMPConfiguration) — yes, that's a whole other type, go look at it later bestie.

Members:

node-id (int, optional) — NUMA node ID the CPU belongs to
drawer-id (int, optional) — drawer number within CPU topology the CPU belongs to (since 8.2)
book-id (int, optional) — book number within parent container the CPU belongs to (since 8.2)
socket-id (int, optional) — socket number within parent container the CPU belongs to
die-id (int, optional) — die number within the parent container the CPU belongs to (since 4.1)
cluster-id (int, optional) — cluster number within the parent container the CPU belongs to (since 7.1)
module-id (int, optional) — module number within the parent container the CPU belongs to (since 9.1)
core-id (int, optional) — core number within the parent container the CPU belongs to
thread-id (int, optional) — thread number within the core the CPU belongs to

🌟 Object `HotpluggableCPU` (Since: 2.7)

Members:

type (string) — CPU object type for usage with device_add command
props (CpuInstanceProperties) — list of properties to pass for hotplugging a CPU with device_add
vcpus-count (int) — number of logical VCPU threads HotpluggableCPU provides
qom-path (string, optional) — link to existing CPU object if CPU is present or omitted if CPU is not present.

Note: Management should be prepared to pass through additional properties with device_add. Like, don't be rigid about it, leave room for surprises 🙈

💫 Command `query-hotpluggable-cpus` (Since: 2.7)

Return [HotpluggableCPU]

okay so we were literally mid-example-dump for query-hotpluggable-cpus — here's the rest of the receipts, fr fr:

Example:

For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:

-> { "execute": "query-hotpluggable-cpus" }
<- {"return": [
     { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
       "vcpus-count": 1 },
     { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
       "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
   ]}

Example:

For pc machine type started with -smp 1,maxcpus=2:

-> { "execute": "query-hotpluggable-cpus" }
<- {"return": [
     {
        "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
        "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
     },
     {
        "qom-path": "/machine/unattached/device[0]",
        "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
        "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
     }
   ]}

Example:

For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu:

-> { "execute": "query-hotpluggable-cpus" }
<- {"return": [
     {
        "type": "qemu-s390x-cpu", "vcpus-count": 1,
        "props": { "core-id": 1 }
     },
     {
        "qom-path": "/machine/unattached/device[0]",
        "type": "qemu-s390x-cpu", "vcpus-count": 1,
        "props": { "core-id": 0 }
     }
   ]}

Command `set-numa-node` (Since: 3.0)

This is the runtime glow-up of the -numa CLI option 💅 — it's available at the preconfigure stage, so you can set up your numa mapping before the machine gets initialized. Order matters, bestie.

Arguments

The members of NumaOptions.

Command `balloon` (Since: 0.14)

Asking the balloon driver to change its balloon size. Yes, that's the whole vibe. 🎈

Arguments

value (int) — the target logical size of the VM in bytes. You can deduce how big the balloon is with this formula:

logical_vm_size = vm_ram_size - balloon_size

and from that we get: balloon_size = vm_ram_size - value

Errors

If the balloon driver is enabled but not functional because the KVM kernel module cannot support it, KVMMissingCap
If no balloon device is present, DeviceNotActive

Note: this command literally just issues a request to the guest. When it returns, the balloon size may not have changed — a guest can change the balloon size independent of this command. So don't @ me if the number doesn't move. 🙈

Example:

-> { "execute": "balloon", "arguments": { "value": 536870912 } }
<- { "return": {} }

With a 2.5GiB guest, this command inflated the balloon to 3GiB. iconic behavior honestly.

Object `BalloonInfo` (Since: 0.14)

Information about the guest balloon device. 🎀

Members

actual (int) — the logical size of the VM in bytes. Formula used: logical_vm_size = vm_ram_size - balloon_size

Command `query-balloon` (Since: 0.14)

Returns the info about the balloon device. That's it, that's the query.

Return BalloonInfo

Errors

If the balloon driver is enabled but not functional because the KVM kernel module cannot support it, KVMMissingCap
If no balloon device is present, DeviceNotActive

Example:

-> { "execute": "query-balloon" }
<- { "return": {
          "actual": 1073741824
       }
    }

Event `BALLOON_CHANGE` (Since: 1.2)

Emitted when the guest changes the actual BALLOON level. This value is equivalent to the actual field returned by the query-balloon command. 🦋

Members

actual (int) — the logical size of the VM in bytes. Formula used: logical_vm_size = vm_ram_size - balloon_size

Note: this event is rate-limited.

Example:

<- { "event": "BALLOON_CHANGE",
     "data": { "actual": 944766976 },
     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }

Object `HvBalloonInfo` (Since: 8.2)

hv-balloon guest-provided memory status information — like the guest slid its memory stats into your DMs. 💌

Members

committed (int) — the amount of memory in use inside the guest plus the amount of the memory unusable inside the guest (ballooned out, offline, etc.)
available (int) — the amount of the memory inside the guest available for new allocations ("free")

Command `query-hv-balloon-status-report` (Since: 8.2)

Returns the hv-balloon driver data contained in the last received "STATUS" message from the guest.

Return HvBalloonInfo

Errors

If no hv-balloon device is present, guest memory status reporting is not enabled, or no guest memory status report has been received yet — GenericError

Example:

-> { "execute": "query-hv-balloon-status-report" }
<- { "return": {
          "committed": 816640000,
          "available": 3333054464
       }
    }

Event `HV_BALLOON_STATUS_REPORT` (Since: 8.2)

Emitted when the hv-balloon driver receives a "STATUS" message from the guest. 📬

Note: this event is rate-limited.

Members

The members of HvBalloonInfo.

Example:

<- { "event": "HV_BALLOON_STATUS_REPORT",
     "data": { "committed": 816640000, "available": 3333054464 },
     "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }

Object `MemoryInfo` (Since: 2.11)

Actual memory information, in bytes. the way that numbers are just numbers 💀

Members

base-memory (int) — size of "base" memory specified with the command line option -m.
plugged-memory (int, optional) — size of memory that can be hot-unplugged. This field is omitted if the target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE not defined at build time).

Command `query-memory-size-summary` (Since: 2.11)

Returns the amount of initially allocated memory, plus the present hotpluggable memory (if that's enabled), in bytes. 🌈

Return MemoryInfo

Example:

-> { "execute": "query-memory-size-summary" }
<- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }

Object `PCDIMMDeviceInfo` (Since: 2.1)

PCDIMMDevice state information. say hi to your memory device for me 🫶

Members

id (string, optional) — device's ID
addr (int) — physical address, where device is mapped
size (int) — size of memory that the device provides
slot (int) — slot number at which device is plugged in
node (int) — NUMA node number where device is plugged in
memdev (string) — memory backend linked with device
hotplugged (boolean) — true if device was hotplugged
hotpluggable (boolean) — true if device if could be added/removed while machine is running

Object `VirtioPMEMDeviceInfo` (Since: 4.1)

VirtioPMEM state information. ✨

Members

id (string, optional) — device's ID
memaddr (int) — physical address in memory, where device is mapped
size (int) — size of memory that the device provides
memdev (string) — memory backend linked with device

Object `VirtioMEMDeviceInfo` (Since: 5.1)

VirtioMEMDevice state information. this one has so many numbers, obsessed 💜

Members

id (string, optional) — device's ID
memaddr (int) — physical address in memory, where device is mapped
requested-size (int) — the user requested size of the device
size (int) — the (current) size of memory that the device provides
max-size (int) — the maximum size of memory that the device can provide
block-size (int) — the block size of memory that the device provides
node (int) — NUMA node number where device is assigned to
memdev (string) — memory backend linked with the region

Object `SgxEPCDeviceInfo` (Since: 6.2)

Sgx EPC state information. 🔥

Members

id (string, optional) — device's ID
memaddr (int) — physical address in memory, where device is mapped
size (int) — size of memory that the device provides
memdev (string) — memory backend linked with device
node (int) — the numa node (Since: 7.0)

Object `HvBalloonDeviceInfo` (Since: 8.2)

hv-balloon provided memory state information. 🎈

Members

id (string, optional) — device's ID
memaddr (int, optional) — physical address in memory, where device is mapped
max-size (int) — the maximum size of memory that the device can provide
memdev (string, optional) — memory backend linked with device

Object `SpMemDeviceInfo` (Since: 11.1)

sp-mem device state information — new drop, fresh off the release 🌸

Members

id (string, optional) — device's ID
addr (int) — physical address, where device is mapped
size (int) — size of memory that the device provides, in bytes
node (int) — NUMA proximity domain to which the device is assigned
memdev (string) — memory backend linked with device

Enum `MemoryDeviceInfoKind` (Since: 2.1)

Values

(the actual value list is right up next bestie, keep scrolling 🧚)

nvdimm — since 2.12
virtio-pmem — since 4.1
virtio-mem — since 5.1
sgx-epc — since 6.2.
hv-balloon — since 8.2.
sp-mem — since 11.1.
dimm — Not documented (bestie they literally just wrote "Not documented" and moved on, iconic honestly)

Object PCDIMMDeviceInfoWrapper (Since: 2.1)

Members

data (PCDIMMDeviceInfo) — PCDIMMDevice state information

Object VirtioPMEMDeviceInfoWrapper (Since: 2.1)

Members

data (VirtioPMEMDeviceInfo) — VirtioPMEM state information

Object VirtioMEMDeviceInfoWrapper (Since: 2.1)

Members

data (VirtioMEMDeviceInfo) — VirtioMEMDevice state information

Object SgxEPCDeviceInfoWrapper (Since: 6.2)

Members

data (SgxEPCDeviceInfo) — Sgx EPC state information

Object HvBalloonDeviceInfoWrapper (Since: 8.2)

Members

data (HvBalloonDeviceInfo) — hv-balloon provided memory state information

Object SpMemDeviceInfoWrapper (Since: 11.1)

Members

data (SpMemDeviceInfo) — sp-mem device state information

Object MemoryDeviceInfo (Since: 2.1)

It's a union carrying info about a memory device, okay so think "one shape, many possible fillings" 🍓

Members

type (MemoryDeviceInfoKind) — the memory device type
When type is dimm: the members of PCDIMMDeviceInfoWrapper.
When type is nvdimm: the members of PCDIMMDeviceInfoWrapper.
When type is virtio-pmem: the members of VirtioPMEMDeviceInfoWrapper.
When type is virtio-mem: the members of VirtioMEMDeviceInfoWrapper.
When type is sgx-epc: the members of SgxEPCDeviceInfoWrapper.
When type is hv-balloon: the members of HvBalloonDeviceInfoWrapper.
When type is sp-mem: the members of SpMemDeviceInfoWrapper.

Object SgxEPC (Since: 6.2)

Sgx EPC cmdline information — the receipts, basically ✨

Members

memdev (string) — memory backend linked with device
node (int) — the numa node (Since: 7.0)

Object SgxEPCProperties (Since: 6.2)

SGX properties of machine types.

Members

sgx-epc ([SgxEPC]) — list of ids of memory-backend-epc objects.

Command `query-memory-devices` (Since: 2.1)

Lists available memory devices and their state 💅

Return [MemoryDeviceInfo]

Example:

-> { "execute": "query-memory-devices" }
<- { "return": [ { "data":
                      { "addr": 5368709120,
                        "hotpluggable": true,
                        "hotplugged": true,
                        "id": "d1",
                        "memdev": "/objects/memX",
                        "node": 0,
                        "size": 1073741824,
                        "slot": 0},
                   "type": "dimm"
                 } ] }

Event `MEMORY_DEVICE_SIZE_CHANGE` (Since: 5.1)

Fires when the size of a memory device changes 🔥 Heads up tho: it's only emitted for memory devices that can actually change size (e.g., virtio-mem because the guest did something).

Members

id (string, optional) — the device's ID
size (int) — the new size of memory that the device provides
qom-path (string) — path to the device object in the QOM tree (since 6.2)

👑 Note: this event is rate-limited. Don't @ me, that's just how it is.

Example:

<- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
     "data": { "id": "vm0", "size": 1073741824,
               "qom-path": "/machine/unattached/device[2]" },
     "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }

Object BootConfiguration (Since: 7.1)

Schema for virtual machine boot configuration — the vibe of how do we wake this thing up 🌸

Members

order (string, optional) — boot order (a=floppy, c=hard disk, d=CD-ROM, n=network)
once (string, optional) — boot order to apply on first boot
menu (boolean, optional) — whether to show a boot menu
splash (string, optional) — the name of the file to be passed to the firmware as logo picture, if menu is true.
splash-time (int, optional) — how long to show the logo picture, in milliseconds
reboot-timeout (int, optional) — timeout before guest reboots after boot fails
strict (boolean, optional) — whether to attempt booting from devices not included in the boot order

Object SMPConfiguration (Since: 6.1)

Schema for CPU topology configuration 🧚 A missing value lets QEMU figure out a suitable value based on the ones that are provided — she's smart, she'll fill in the blanks.

The members other than cpus and maxcpus define a topology of containers.

The ordering from highest/coarsest to lowest/finest is: drawers, books, sockets, dies, clusters, cores, threads.

Different architectures support different subsets of topology containers.

For example, s390x does not have clusters and dies, and the socket is the parent container of cores. (yes bestie, architectures are built different, no cap)

Members

cpus (int, optional) — number of virtual CPUs in the virtual machine
maxcpus (int, optional) — maximum number of hotpluggable virtual CPUs in the virtual machine
drawers (int, optional) — number of drawers in the CPU topology (since 8.2)
books (int, optional) — number of books in the CPU topology (since 8.2)
sockets (int, optional) — number of sockets per parent container
dies (int, optional) — number of dies per parent container
clusters (int, optional) — number of clusters per parent container (since 7.0)
modules (int, optional) — number of modules per parent container (since 9.1)
cores (int, optional) — number of cores per parent container
threads (int, optional) — number of threads per core

Command `x-query-irq` (Since: 6.2)

This command is unstable/experimental. 🙈

Query interrupt statistics 🔔

Features

unstable — this command is meant for debugging.

Return HumanReadableText — interrupt statistics

Command `x-query-jit` (Since: 6.2)

This command is unstable/experimental. Availability: CONFIG_TCG 💀

Query TCG compiler statistics

Features

unstable — this command is meant for debugging.

Return HumanReadableText — TCG compiler statistics

Command `x-query-numa` (Since: 6.2)

This command is unstable/experimental.

Query NUMA topology information

Features

unstable — this command is meant for debugging.

Return HumanReadableText — topology information

Command `x-query-ramblock` (Since: 6.2)

This command is unstable/experimental.

Query system ramblock information

Features

unstable — this command is meant for debugging.

Return HumanReadableText — system ramblock information

Command `x-query-roms` (Since: 6.2)

This command is unstable/experimental.

Query information on the registered ROMS

Features

unstable — this command is meant for debugging.

Return HumanReadableText — registered ROMs

Command `x-query-usb` (Since: 6.2)

This command is unstable/experimental.

Query information on the USB devices

Features

unstable — this command is meant for debugging.

Return HumanReadableText — USB device information

Enum SmbiosEntryPointType (Since: 7.0)

Values

32 — SMBIOS version 2.1 (32-bit) Entry Point
64 — SMBIOS version 3.0 (64-bit) Entry Point
auto — either 2.x or 3.x SMBIOS version, 2.x if configuration can be described by it and 3.x otherwise (since: 9.0)

Object MemorySizeConfiguration (Since: 7.1)

Schema for memory size configuration 💾

Members

size (int, optional) — memory size in bytes
max-size (int, optional) — maximum hotpluggable memory size in bytes
slots (int, optional) — number of available memory slots for hotplug

Command `dumpdtb` (Since: 7.2)

Availability: CONFIG_FDT 🦋

Save the FDT in dtb format.

Arguments

filename (string) — name of the dtb file to be created

Example:

-> { "execute": "dumpdtb" }
     "arguments": { "filename": "fdt.dtb" } }
<- { "return": {} }

Command `x-query-interrupt-controllers` (Since: 9.1)

This command is unstable/experimental.

Query information on interrupt controller devices

Features

unstable — this command is meant for debugging.

Return HumanReadableText — Interrupt controller devices information

Object FirmwareLog (Since: 10.2)

Members

version (string, optional) — Firmware version.
log (string) — Firmware debug log, in base64 encoding. 🎀 First and last log line might be incomplete (ngl that's just how it is).

Command `query-firmware-log` (Since: 10.2)

Find firmware memory log buffer in guest memory, return content. Lowkey detective work 🔍

Arguments

max-size (int, optional) — limit the amount of log data returned. Up to 1 MiB of log data is allowed. In case the amount of log data is larger than max-size the tail of the log is returned.

Return FirmwareLog

🗝️ Command `dump-skeys` (Since: 2.5)

Okay so this one is s390x exclusive bestie — it dumps the storage keys for an s390x guest. That's it. That's the whole vibe. 💅

Arguments

filename (string) — the path to the file to dump to

Example:

-> { "execute": "dump-skeys",
     "arguments": { "filename": "/tmp/skeys" } }
<- { "return": {} }

🧬 Object `CpuModelInfo` (Since: 2.8)

A virtual CPU model, periodt. ✨

So a CPU model is literally just the name of a CPU definition, and then delta changes get applied on top of it (like features added or removed, iykyk). Most of the magic values that an architecture might need should be hidden behind the name — that's the whole point. But if it's actually required, architectures can expose the relevant properties.

Members

name (string) — the name of the CPU definition the model is based on
props (value, optional) — a dictionary of QOM properties to be applied

🌈 Enum `CpuModelExpansionType` (Since: 2.8)

An enumeration of CPU model expansion types. Two flavors, both iconic in their own way:

Values

static — Expand to a static CPU model, a combination of a static base model name and property delta changes. And here's the slay part: since the static base model will never change, the expanded CPU model will be the same, independent of QEMU version, machine type, machine options, and accelerator options. So the resulting model can be used by tooling without having to specify a compatibility machine — like, say, when displaying the "host" model. The static CPU models are migration-safe. 🫶
full — Expand all the properties. The produced model is not guaranteed to be migration-safe, but it lets tooling get an insight and work with model details.

Note: When a non-migration-safe CPU model is expanded in static mode, some features enabled by the CPU model may be omitted, because they can't be implemented by a static CPU model definition (e.g. cache info passthrough and PMU passthrough in x86). If you need an accurate representation of the features enabled by a non-migration-safe CPU model, use full. If you need a static representation that will keep ABI compatibility even when changing QEMU version or machine-type, use static — but keep in mind that some features may be omitted. 😭

⚖️ Enum `CpuModelCompareResult` (Since: 2.8)

An enumeration of CPU model comparison results. The result is usually calculated using, like, CPU features or CPU generations. Four possible outcomes bestie:

Values

incompatible — If model A is incompatible to model B, model A is not guaranteed to run where model B runs and the other way around.
identical — If model A is identical to model B, model A is guaranteed to run where model B runs and the other way around. 👯
superset — If model A is a superset of model B, model B is guaranteed to run where model A runs. There are no guarantees about the other way.
subset — If model A is a subset of model B, model A is guaranteed to run where model B runs. There are no guarantees about the other way.

🧾 Object `CpuModelBaselineInfo` (Since: 2.8)

The result of a CPU model baseline. Short and sweet.

Members

model (CpuModelInfo) — the baselined CpuModelInfo.

🔍 Object `CpuModelCompareInfo` (Since: 2.8)

The result of a CPU model comparison. This is the receipts bestie 📋

Members

result (CpuModelCompareResult) — The result of the compare operation.
responsible-properties ([string]) — List of properties that led to the comparison result not being identical.

So responsible-properties is a list of QOM property names that led to both CPUs not being detected as identical. For identical models, this list is empty. And if a QOM property is read-only, that means there's no known way to make the CPU models identical. If the special property name "type" is included, the models are by definition not identical and cannot be made identical. 💀

🥊 Command `query-cpu-model-comparison` (Since: 2.8)

Compares two CPU models, modela and modelb, returning how they compare in a specific configuration. The result indicates how both models compare regarding runnability. Tooling can use this to make decisions about whether a certain CPU model will run in a certain configuration, or whether a compatible CPU model has to be created by baselining. Very main character of it. 👑

Usually, a CPU model is compared against the maximum possible CPU model of a certain configuration (e.g. the "host" model for KVM). If that CPU model is identical or a subset, it will run in that configuration.

The result returned by this command may be affected by:

QEMU version: CPU models may look different depending on the QEMU version. (Except for CPU models reported as "static" in query-cpu-definitions.)
machine-type: CPU model may look different depending on the machine-type. (Except for CPU models reported as "static" in query-cpu-definitions.)
machine options (including accelerator): in some architectures, CPU models may look different depending on machine and accelerator options. (Except for CPU models reported as "static" in query-cpu-definitions.)
"-cpu" arguments and global properties: arguments to the -cpu option and global properties may affect expansion of CPU models. Using query-cpu-model-expansion while using these is not advised. 🙈

Some architectures may not support comparing CPU models. s390x supports comparing CPU models.

Arguments

modela (CpuModelInfo) — description of the first CPU model to compare, referred to as "model A" in CpuModelCompareResult
modelb (CpuModelInfo) — description of the second CPU model to compare, referred to as "model B" in CpuModelCompareResult

Return CpuModelCompareInfo — a CpuModelCompareInfo describing how both CPU models compare

Errors

if comparing CPU models is not supported by the target
if a model cannot be used
if a model contains an unknown cpu definition name, unknown properties or properties with wrong types.

🧱 Command `query-cpu-model-baseline` (Since: 2.8)

Baseline two CPU models, modela and modelb, creating a compatible third model. The created model will always be a static, migration-safe CPU model (see "static" CPU model expansion for details). We love a stable king. ✨

This interface can be used by tooling to create a compatible CPU model out of two CPU models. The created CPU model will be identical to or a subset of both CPU models when comparing them. Therefore, the created CPU model is guaranteed to run where the given CPU models run.

The result returned by this command may be affected by:

QEMU version: CPU models may look different depending on the QEMU version. (Except for CPU models reported as "static" in query-cpu-definitions.)
machine-type: CPU model may look different depending on the machine-type. (Except for CPU models reported as "static" in query-cpu-definitions.)
machine options (including accelerator): in some architectures, CPU models may look different depending on machine and accelerator options. (Except for CPU models reported as "static" in query-cpu-definitions.)
"-cpu" arguments and global properties: arguments to the -cpu option and global properties may affect expansion of CPU models. Using query-cpu-model-expansion while using these is not advised. 🙈

Some architectures may not support baselining CPU models. s390x supports baselining CPU models.

Arguments

modela (CpuModelInfo) — description of the first CPU model to baseline
modelb (CpuModelInfo) — description of the second CPU model to baseline

Return CpuModelBaselineInfo — a CpuModelBaselineInfo describing the baselined CPU model

Errors

if baselining CPU models is not supported by the target
if a model cannot be used
if a model contains an unknown cpu definition name, unknown properties or properties with wrong types.

🎁 Object `CpuModelExpansionInfo` (Since: 2.8)

The result of a cpu model expansion. 🦋

Members

model (CpuModelInfo) — the expanded CpuModelInfo.
deprecated-props ([string], optional) — an optional list of properties that are flagged as deprecated by the CPU vendor. The list depends on the CpuModelExpansionType: "static" properties are a subset of the enabled-properties for the expanded model; "full" properties are a set of properties that are deprecated across all models for the architecture. (since: 10.1 -- since 9.1 on s390x --).

🔬 Command `query-cpu-model-expansion` (Since: 2.8)

Expands a given CPU model, model, (or a combination of CPU model + additional options) to different granularities, specified by type, so tooling can get an understanding of what a specific CPU model actually looks like in QEMU under a certain configuration. It's giving magnifying glass energy 🔍✨

This interface can be used to query the "host" CPU model.

The data returned by this command may be affected by:

QEMU version: CPU models may look different depending on the QEMU version. (Except for CPU models reported as "static" in query-cpu-definitions.)
machine-type: CPU model may look different depending on the machine-type. (Except for CPU models reported as "static" in query-cpu-definitions.)
machine options (including accelerator) — in some architectures, CPU models may look different depending on machine and accelerator options. (Except for CPU models reported as "static" in query-cpu-definitions.) 👀
-cpu arguments and global properties — arguments to the -cpu option and global properties may affect expansion of CPU models. Using query-cpu-model-expansion while using these is not advised. 🙅‍♀️

Some architectures may not support all expansion types. s390x supports "full" and "static". Arm only supports "full". That's just how it is bestie 💅

Arguments 🎀

model (CpuModelInfo) — description of the CPU model to expand
type (CpuModelExpansionType) — expansion type, specifying how to expand the CPU model

Return CpuModelExpansionInfo — a CpuModelExpansionInfo describing the expanded CPU model ✨

Errors 😭

if expanding CPU models is not supported
if the model cannot be expanded
if the model contains an unknown CPU definition name, unknown properties or properties with a wrong type
if an expansion type is not supported

Object `CpuDefinitionInfo` (Since: 1.2) 🧚

Virtual CPU definition. Literally what it says on the tin 💖

Members

name (string) — the name of the CPU definition
migration-safe (boolean, optional) — whether a CPU definition can be safely used for migration in combination with a QEMU compatibility machine when migrating between different QEMU versions and between hosts with different sets of (hardware or software) capabilities. If not provided, information is not available and callers should not assume the CPU definition to be migration-safe. (since 2.8)
static (boolean) — whether a CPU definition is static and will not change depending on QEMU version, machine type, machine options and accelerator options. A static model is always migration-safe. (since 2.8)
unavailable-features ([string], optional) — List of properties that prevent the CPU model from running in the current host. (since 2.8)
typename (string) — Type name that can be used as argument to device-list-properties, to introspect properties configurable using -cpu or -global. (since 2.9)
alias-of (string, optional) — Name of CPU model this model is an alias for. The target of the CPU model alias may change depending on the machine type. Management software is supposed to translate CPU model aliases in the VM configuration, because aliases may stop being migration-safe in the future (since 4.1)
deprecated (boolean) — If true, this CPU model is deprecated and may be removed in some future version of QEMU according to the QEMU deprecation policy. (since 5.2)

unavailable-features is a list of QOM property names that represent CPU model attributes that prevent the CPU from running. If the QOM property is read-only, that means there's no known way to make the CPU model run in the current host. Implementations that choose not to provide specific information return the property name "type". If the property is read-write, it means that it MAY be possible to run the CPU model in the current host if that property is changed. Management software can use it as hints to suggest or choose an alternative for the user, or just to generate meaningful error messages explaining why the CPU model can't be used. If unavailable-features is an empty list, the CPU model is runnable using the current host and machine-type. If unavailable-features is not present, runnability information for the CPU is not available. 🫶

Command `query-cpu-definitions` (Since: 1.2) 🌸

Return a list of supported virtual CPU definitions

Return [CpuDefinitionInfo]

Enum `S390CpuPolarization` (Since: 8.2) 💜

An enumeration of CPU polarization that can be assumed by a virtual S390 CPU

Values

horizontal — Not documented
vertical — Not documented

Command `set-cpu-topology` (Since: 8.2) 🦋

This command is unstable/experimental. ⚠️

Modify the topology by moving the CPU inside the topology tree, or by changing a modifier attribute of a CPU. Absent values will not be modified.

Arguments

core-id (int) — the vCPU ID to be moved
socket-id (int, optional) — destination socket to move the vCPU to
book-id (int, optional) — destination book to move the vCPU to
drawer-id (int, optional) — destination drawer to move the vCPU to
entitlement (S390CpuEntitlement, optional) — entitlement to set
dedicated (boolean, optional) — whether the provisioning of real to virtual CPU is dedicated

Features

unstable — This command is experimental.

Event `CPU_POLARIZATION_CHANGE` (Since: 8.2) 🔥

This event is unstable/experimental. ⚠️

Emitted when the guest asks to change the polarization.

The guest can tell the host (via the PTF instruction) whether the CPUs should be provisioned using horizontal or vertical polarization.

On horizontal polarization the host is expected to provision all vCPUs equally.

On vertical polarization the host can provision each vCPU differently. The guest will get information on the details of the provisioning the next time it uses the STSI(15) instruction.

Members

polarization (S390CpuPolarization) — polarization specified by the guest

Features

unstable — This event is experimental.

Example: 👑

<- { "event": "CPU_POLARIZATION_CHANGE",
     "data": { "polarization": "horizontal" },
     "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }

Object `CpuPolarizationInfo` (Since: 8.2) ⭐

The result of a CPU polarization query.

Members

polarization (S390CpuPolarization) — the CPU polarization

Command `query-s390x-cpu-polarization` (Since: 8.2) 🌈

This command is unstable/experimental. ⚠️

Features

unstable — This command is experimental.

Return CpuPolarizationInfo — the machine's CPU polarization

Event `SCLP_CPI_INFO_AVAILABLE` (Since: 10.2) 🍓

This event is unstable/experimental. ⚠️

Emitted when the Control-Program Identification data is available in the QOM tree.

Features

unstable — This event is experimental.

Example: ✨

<- { "event": "SCLP_CPI_INFO_AVAILABLE",
     "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }

🎬 RECORD/REPLAY 🎬

Enum `ReplayMode` (Since: 2.5) 🎥

Mode of the replay subsystem.

Values

none — normal execution mode. Replay or record are not enabled.
record — record mode. All non-deterministic data is written into the replay log.
play — replay mode. Non-deterministic data required for system execution is read from the log.

Object `ReplayInfo` (Since: 5.2) 📼

Record/replay information.

Members

mode (ReplayMode) — current mode.
filename (string, optional) — name of the record/replay log file. It is present only in record or replay modes, when the log is recorded or replayed.
icount (int) — current number of executed instructions.

Command `query-replay` (Since: 5.2) 🕹️

Retrieve the record/replay information. It includes current instruction count which may be used for replay-break and replay-seek commands.

Return ReplayInfo — record/replay information.

Example: 💫

-> { "execute": "query-replay" }
<- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }

Command `replay-break` (Since: 5.2) ⏸️

Set replay breakpoint at instruction count icount. Execution stops when the specified instruction is reached. There can be at most one breakpoint. When breakpoint is set, any prior one is removed. The breakpoint may be set only in replay mode and only "in the future", i.e. at instruction counts greater than the current one. The current instruction count can be observed with query-replay.

Arguments

icount (int) — instruction count to stop at

Example: 🎀

-> { "execute": "replay-break", "arguments": { "icount": 220414 } }
<- { "return": {} }

Command `replay-delete-break` (Since: 5.2) 🗑️

Remove replay breakpoint which was set with replay-break. The command is ignored when there are no replay breakpoints.

Example: 🌸

-> { "execute": "replay-delete-break" }
<- { "return": {} }

Command `replay-seek` (Since: 5.2) ⏩

Automatically proceed to the instruction count icount, when replaying the execution. The command automatically loads nearest snapshot and replays the execution to find the desired instruction. When there is no preceding snapshot or the execution is not replayed, then the command fails. Instruction count can be obtained with the query-replay command.

Arguments

icount (int) — target instruction count

Example: 🦋

-> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
<- { "return": {} }

✨ YANK FEATURE ✨

Okay bestie, this whole section is about yanking things — and no, not the way you yank your phone charger out of the wall at 3%. It's about pulling QEMU out of a hang. Let's go 💅

Enum YankInstanceType (Since: 6.0)

A whole enumeration of yank instance types. Peep YankInstance for the full lore.

Values

block-node — not documented 🙈
chardev — not documented 🙈
migration — not documented 🙈

ngl, "Not documented" is literally the entire documentation for all three of these. We move.

Object YankInstanceBlockNode (Since: 6.0)

Tells you which block graph node to yank. See YankInstance for more.

Members

node-name (string) — the name of the block graph node

Object YankInstanceChardev (Since: 6.0)

Tells you which character device to yank. See YankInstance for more.

Members

id (string) — the chardev's ID

Object YankInstance (Since: 6.0)

A yank instance is literally the thing you can yank with the yank qmp command, and the whole point is recovering from a QEMU that's just… hanging there, giving nothing 😭

Members

type (YankInstanceType) — yank instance type
When type is block-node: The members of YankInstanceBlockNode.
When type is chardev: The members of YankInstanceChardev.

Currently implemented yank instances:

nbd block device: yanking it shuts down the connection to the nbd server without attempting to reconnect.
socket chardev: yanking it shuts down the connected socket.
migration: yanking it shuts down all migration connections. Unlike migrate_cancel, it will not notify the migration process, so migration will go into failed state, instead of cancelled state. yank should be used to recover from hangs.

Command yank (Since: 6.0)

Tryna recover from a hanging QEMU? Yank the specified instances. See YankInstance for more. 🪢

Arguments

instances ([YankInstance]) — the instances to be yanked

Errors

If any of the YankInstances doesn't exist, DeviceNotFound

Example:

-> { "execute": "yank",
     "arguments": {
         "instances": [
              { "type": "block-node",
                "node-name": "nbd0" }
         ] } }
<- { "return": {} }

Command query-yank (Since: 6.0)

Queries your yank instances. See YankInstance for more.

Return [YankInstance]

Example:

-> { "execute": "query-yank" }
<- { "return": [
         { "type": "block-node",
           "node-name": "nbd0" }
     ] }

🌈 MISCELLANEA 🌈

The grab-bag section. Random little icons, all doing their own thing. Obsessed honestly.

Command add_client (Since: 0.14)

Lets client connections for VNC, Spice and socket based character devices get passed into QEMU via SCM_RIGHTS. Iconic FD handoff behaviour 💅

Heads up: if the FD associated with fdname is not a socket, the command will fail and the FD will be closed.

Arguments

protocol (string) — protocol name. Valid names are "vnc", "spice", "dbus-display" or the name of a character device (e.g. from -chardev id=XXXX)
fdname (string) — file descriptor name previously passed via getfd command
skipauth (boolean, optional) — whether to skip authentication. Only applies to "vnc" and "spice" protocols
tls (boolean, optional) — whether to perform TLS. Only applies to the "spice" protocol

Example:

-> { "execute": "add_client", "arguments": { "protocol": "vnc",
                                             "fdname": "myclient" } }
<- { "return": {} }

Object NameInfo (Since: 0.14)

Guest name info. That's it, that's the object 🎀

Members

name (string, optional) — The name of the guest

Command query-name (Since: 0.14)

Returns the name information of a guest.

Return NameInfo

Example:

-> { "execute": "query-name" }
<- { "return": { "name": "qemu-name" } }

Object IOThreadInfo (Since: 2.0)

All the deets about an iothread.

Members

id (string) — the identifier of the iothread
thread-id (int) — ID of the underlying host thread
poll-max-ns (int) — maximum polling time in ns, 0 means polling is disabled (since 2.9)
poll-grow (int) — how many ns will be added to polling time, 0 means that it's not configured (since 2.9)
poll-shrink (int) — how many ns will be removed from polling time, 0 means that it's not configured (since 2.9)
poll-weight (int) — the weight factor for adaptive polling. Determines how much the current event interval contributes to the next polling time calculation. Valid values are 1 or greater (since 11.1)
aio-max-batch (int) — maximum number of requests in a batch for the AIO engine, 0 means that the engine will use its default (since 6.1)

Command query-iothreads (Since: 2.0)

Returns a list of info about each iothread. 🧵✨

Note: this list excludes the QEMU main loop thread, which is not declared using the -object iothread command-line option. It is always the main thread of the process.

Return [IOThreadInfo] — a list of info for each iothread

Example:

-> { "execute": "query-iothreads" }
<- { "return": [
         {
            "id":"iothread0",
            "thread-id":3134,
            "poll-max-ns":32768,
            "poll-grow":0,
            "poll-shrink":0,
            "aio-max-batch":0
         },
         {
            "id":"iothread1",
            "thread-id":3135,
            "poll-max-ns":32768,
            "poll-grow":0,
            "poll-shrink":0,
            "aio-max-batch":0
         }
      ]
   }

Command stop (Since: 0.14)

Stops guest VM execution. Freeze frame, periodt 🧊

Note: this function will succeed even if the guest is already in the stopped state. In "inmigrate" state, it will ensure that the guest remains paused once migration finishes, as if the -S option was passed on the command line. In the "suspended" state, it will completely stop the VM and cause a transition to the "paused" state. (Since 9.0)

Example:

-> { "execute": "stop" }
<- { "return": {} }

Command cont (Since: 0.14)

Resumes guest VM execution. And we're back 💖

Note: this command will succeed if the guest is currently running. It will also succeed if the guest is in the "inmigrate" state; in this case, the effect of the command is to make sure the guest starts once migration finishes, removing the effect of the -S command line option if it was passed. If the VM was previously suspended, and not been reset or woken, this command will transition back to the "suspended" state. (Since 9.0)

Example:

-> { "execute": "cont" }
<- { "return": {} }

Command x-exit-preconfig (Since: 3.0)

⚠️ This command is unstable/experimental.

Exit from "preconfig" state.

So basically this makes QEMU exit the preconfig state and proceed with VM initialization using configuration data provided on the command line and via the QMP monitor during the preconfig state. The command is only available during the preconfig state (i.e. when the --preconfig command line option was in use).

Features

unstable — This command is experimental.

Example:

-> { "execute": "x-exit-preconfig" }
<- { "return": {} }

Command human-monitor-command (Since: 0.14)

Executes a command on the human monitor and returns the output. Yes, it's QMP talking to HMP. Nested monitor realness 😭

Arguments

command-line (string) — the command to execute in the human monitor
cpu-index (int, optional) — The CPU to use for commands that require an implicit CPU

Features

savevm-monitor-nodes — If present, HMP command savevm only snapshots monitor-owned nodes if they have no parents. This allows the use of 'savevm' with -blockdev. (since 4.2)

Return string — the output of the command as a string

Note: this command only exists as a stop-gap. Its use is highly discouraged. The semantics of this command are not guaranteed: this means that command names, arguments and responses can change or be removed at any time. Applications that rely on long term stability guarantees should not use this command. Known limitations: - This command is stateless, this means that commands that depend on state information (such as getfd) might not work. - Commands that prompt the user for data don't currently work.

Example:

-> { "execute": "human-monitor-command",
     "arguments": { "command-line": "info kvm" } }
<- { "return": "kvm support: enabled\r\n" }

Command getfd (Since: 0.14)

Availability: CONFIG_POSIX

Receives a file descriptor via SCM rights and assigns it a name 🫶

Arguments

fdname (string) — file descriptor name

Note: if fdname already exists, the file descriptor assigned to it will be closed and replaced by the received file descriptor. The closefd command can be used to explicitly close the file descriptor when it is no longer needed.

Example:

-> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
<- { "return": {} }

💅 Command `get-win32-socket` (Since: 8.0)

Availability: CONFIG_WIN32 — Windows girlies only, sorry bestie 😭

Okay so this one adds a socket that was duplicated into the QEMU process with WSADuplicateSocketW() via WSASocket() & WSAPROTOCOL_INFOW structure, and then gives it a name (the SOCKET is associated with a CRT file descriptor). Iconic little handoff tbh 🫶

Arguments

info (string) — the WSAPROTOCOL_INFOW structure, encoded in base64 ✨
fdname (string) — file descriptor name

Note: if fdname already exists, the file descriptor assigned to it gets closed and replaced by the received file descriptor, fr fr. No warning, it just swaps 👀

Note: the closefd command can be used to explicitly close the file descriptor when it's no longer needed. Clean up after yourself babes 💖

Example:

-> { "execute": "get-win32-socket",
     "arguments": { "info": "abcd123..", "fdname": "skclient" } }
<- { "return": {} }

🎀 Command `closefd` (Since: 0.14)

Close a file descriptor previously passed via SCM rights. That's it, that's the whole vibe 🌸

Arguments

fdname (string) — file descriptor name

Example:

-> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
<- { "return": {} }

🦋 Object `AddfdInfo` (Since: 1.2)

Information about a file descriptor that was added to an fd set. The receipts, basically 🧾

Members

fdset-id (int) — The ID of the fd set that fd was added to.
fd (int) — The file descriptor that was received via SCM rights and added to the fd set.

✨ Command `add-fd` (Since: 1.2)

Add a file descriptor, that was passed via SCM rights, to an fd set. Matching socks energy 🧦

Arguments

fdset-id (int, optional) — The ID of the fd set to add the file descriptor to.
opaque (string, optional) — A free-form string that can be used to describe the fd.

Return AddfdInfo

Errors

If file descriptor was not received → GenericError
If fdset-id is a negative value → GenericError (negative fd set id?? in this economy?? 💀)

Note: the list of fd sets is shared by all monitor connections. Everybody sees the same pile, iykyk.

Note: if fdset-id is not specified, a new fd set will be created for you. Built-in ✨

Example:

-> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
<- { "return": { "fdset-id": 1, "fd": 3 } }

🌈 Command `remove-fd` (Since: 1.2)

Remove a file descriptor from an fd set. Marie Kondo but for fds 🧹

Arguments

fdset-id (int) — The ID of the fd set that the file descriptor belongs to.
fd (int, optional) — The file descriptor that is to be removed.

Errors

If fdset-id or fd is not found → GenericError

Note: the list of fd sets is shared by all monitor connections. Same shared pile as before, no cap.

Note: if fd is not specified, all file descriptors in fdset-id will be removed. Whole set, gone, periodt 💀

Example:

-> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
<- { "return": {} }

🍓 Object `FdsetFdInfo` (Since: 1.2)

Information about a file descriptor that belongs to an fd set. Little membership card 🎫

Members

fd (int) — The file descriptor value.
opaque (string, optional) — A free-form string that can be used to describe the fd.

💜 Object `FdsetInfo` (Since: 1.2)

Information about an fd set. The whole crew, not just one member 👑

Members

fdset-id (int) — The ID of the fd set.
fds ([FdsetFdInfo]) — A list of file descriptors that belong to this fd set.

🔥 Command `query-fdsets` (Since: 1.2)

Return information describing all fd sets. Full tour of the collection 🖼️

Return [FdsetInfo]

Note: the list of fd sets is shared by all monitor connections. Yes, again. It's shared. We know. 💅

Example:

-> { "execute": "query-fdsets" }
<- { "return": [
       {
         "fds": [
           {
             "fd": 30,
             "opaque": "rdonly:/path/to/file"
           },
           {
             "fd": 24,
             "opaque": "rdwr:/path/to/file"
           }
         ],
         "fdset-id": 1
       },
       {
         "fds": [
           {
             "fd": 28
           },
           {
             "fd": 29
           }
         ],
         "fdset-id": 0
       }
     ]
   }

🧚 Enum `CommandLineParameterType` (Since: 1.5)

Possible types for an option parameter. The whole little taxonomy 🌱

Values

string — accepts a character string
boolean — accepts "on" or "off"
number — accepts a number
size — accepts a number followed by an optional suffix: (K)ilo, (M)ega, (G)iga, (T)era

🎀 Object `CommandLineParameterInfo` (Since: 1.5)

Details about a single parameter of a command line option. One (1) parameter, fully described 💖

Members

name (string) — parameter name
type (CommandLineParameterType) — parameter CommandLineParameterType
help (string, optional) — human readable text string, not suitable for parsing. Human eyes only 👀
default (string, optional) — default value string (since 2.1)

🦋 Object `CommandLineOptionInfo` (Since: 1.5)

Details about a command line option, including its list of parameter details. The whole package deal 🎁

Members

option (string) — option name
parameters ([CommandLineParameterInfo]) — an array of CommandLineParameterInfo

⭐ Command `query-command-line-options` (Since: 1.5)

Query command line option schema. Like pulling up the ingredient list 📋

Arguments

option (string, optional) — option name

Return [CommandLineOptionInfo] — list of objects for all options (or for the given option).

Errors

if the given option doesn't exist 😭

Example:

-> { "execute": "query-command-line-options",
     "arguments": { "option": "option-rom" } }
<- { "return": [
        {
            "parameters": [
                {
                    "name": "romfile",
                    "type": "string"
                },
                {
                    "name": "bootindex",
                    "type": "number"
                }
            ],
            "option": "option-rom"
        }
     ]
   }

🕰️ Event `RTC_CHANGE` (Since: 0.13)

Emitted when the guest changes the RTC time. The guest touched the clock, we're all finding out about it 🫢

Members

offset (int) — offset in seconds between base RTC clock (as specified by -rtc base), and new RTC clock value
qom-path (string) — path to the RTC object in the QOM tree

Note: this event is rate-limited. It is not guaranteed that the RTC in the system implements this event, or even that the system has an RTC at all. Sometimes there's just no clock bestie 😭

Example:

<- { "event": "RTC_CHANGE",
     "data": { "offset": 78 },
     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }

💀 Event `VFU_CLIENT_HANGUP` (Since: 7.1)

Emitted when the client of a TYPE_VFIO_USER_SERVER closes the communication channel. They hung up. Rude but okay 📞

Members

vfu-id (string) — ID of the TYPE_VFIO_USER_SERVER object. It is the last component of vfu-qom-path referenced below.
vfu-qom-path (string) — path to the TYPE_VFIO_USER_SERVER object in the QOM tree
dev-id (string) — ID of attached PCI device
dev-qom-path (string) — path to attached PCI device in the QOM tree

Example:

<- { "event": "VFU_CLIENT_HANGUP",
     "data": { "vfu-id": "vfu1",
               "vfu-qom-path": "/objects/vfu1",
               "dev-id": "sas1",
               "dev-qom-path": "/machine/peripheral/sas1" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

👑 Object `GICCapability` (Since: 2.6)

The struct describes capability for a specific GIC (Generic Interrupt Controller) version. These bits are not only decided by QEMU/KVM software version, but also decided by the hardware that the program is running upon. So it's a whole collaboration between software and the silicon bestie 🤝

Members

version (int) — version of GIC to be described. Currently, only 2 and 3 are supported.
emulated (boolean) — whether current QEMU/hardware supports emulated GIC device in user space.
kernel (boolean) — whether current QEMU/hardware supports hardware accelerated GIC device in kernel.

🌸 Command `query-gic-capabilities` (Since: 2.6)

It will return a list of GICCapability objects that describe its capability bits. Renders the whole mood board 🎨

On non-ARM targets this command will report an error as the GIC technology is not applicable. Wrong platform, wrong party 🚫

Return [GICCapability]

Example:

-> { "execute": "query-gic-capabilities" }
<- { "return": [{ "version": 2, "emulated": true, "kernel": false },
                { "version": 3, "emulated": false, "kernel": true } ] }

🎀 Enum `SsidSizeMode` (Since: 11.0)

SMMUv3 SubstreamID size configuration mode. Big acronyms, very serious business ✨

Values

auto — derive from host IOMMU capabilities
0 — Not documented
1 — Not documented
2 — Not documented
3 — Not documented
4 — Not documented

Okay so real talk: the docs literally say "Not documented" for 0 through 4 and I'm not about to invent lore for y'all 🙈 that's exactly what the manpage says, no cap.

5 — Not documented 🙈
- 6 — Not documented 🙈
- 7 — Not documented 🙈
- 8 — Not documented 🙈
- 9 — Not documented 🙈
- 10 — Not documented 🙈
- 11 — Not documented 🙈
- 12 — Not documented 🙈
- 13 — Not documented 🙈
- 14 — Not documented 🙈
- 15 — Not documented 🙈
- 16 — Not documented 🙈
- 17 — Not documented 🙈
- 18 — Not documented 🙈
- 19 — Not documented 🙈
- 20 — Not documented 🙈

Values 0-20: SSIDSIZE value in bits. 0 disables SubstreamID. (yes bestie, zero literally turns it off, iconic)

✨ Enum OasMode (Since: 11.0)

SMMUv3 Output Address Size configuration mode. It's giving "how big is the address space, bestie" 💅

Values

auto — derive from host IOMMU capabilities 🧚
32 — 32-bit output address size
36 — 36-bit output address size
40 — 40-bit output address size
42 — 42-bit output address size
44 — 44-bit output address size
48 — 48-bit output address size
52 — 52-bit output address size
56 — 56-bit output address size

💖 Command rtc-reset-reinjection (Since: 2.1)

Resets the RTC interrupt reinjection backlog. Use it when some other mechanism is already handling guest time synchronization — like, for example, the QEMU guest agent's guest-set-time command 🔥.

Heads up bestie: this only does anything on x86 machines that have an RTC. On every other machine it just silently returns without performing any action — like, no error, no nothing, it's giving ghosting 💀

Example:

-> { "execute": "rtc-reset-reinjection" }
<- { "return": {} }

🌸 Enum SevState (Since: 2.12)

An enumeration of SEV state info, used during query-sev. Basically the guest's current mood ring 💅

Values

uninit — The guest is uninitialized.
launch-update — The guest is currently being launched; plaintext data and register state is being imported.
launch-secret — The guest is currently being launched; ciphertext data is being imported.
running — The guest is fully launched or migrated in. main character energy 👑
send-update — The guest is currently being migrated out to another machine.
receive-update — The guest is currently being migrated from another machine.

🎀 Enum SevGuestType (Since: 6.2)

Tells you which flavor of SEV guest is running 🍓

Values

sev — The guest is a legacy SEV or SEV-ES guest.
sev-snp — The guest is an SEV-SNP guest.

⭐ Object SevGuestInfo (Since: 2.12)

Info that's specific to legacy SEV/SEV-ES guests, no cap.

Members

policy (int) — SEV policy value
handle (int) — SEV firmware handle

🦋 Object SevSnpGuestInfo (Since: 9.1)

Info that's specific to SEV-SNP guests ✨

Members

snp-policy (int) — SEV-SNP policy value

💜 Object SevInfo (Since: 2.12)

All the tea about Secure Encrypted Virtualization (SEV) support ☕

Members

enabled (boolean) — true if SEV is active
api-major (int) — SEV API major version
api-minor (int) — SEV API minor version
build-id (int) — SEV FW build id
state (SevState) — SEV guest state
sev-type (SevGuestType) — Type of SEV guest being run
When sev-type is sev: The members of SevGuestInfo.
When sev-type is sev-snp: The members of SevSnpGuestInfo.

💅 Command query-sev (Since: 2.12)

Returns the info about SEV/SEV-ES/SEV-SNP. Slay.

If it's unavailable because the configuration is incompatible, the returned enabled field is set to 'false' and the state of all the other fields is unspecified 🙈 (so like, don't trust them, bestie).

Return SevInfo

Example:

-> { "execute": "query-sev" }
<- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
                 "build-id" : 0, "policy" : 0, "state" : "running",
                 "handle" : 1 } }

🧚 Object SevLaunchMeasureInfo (Since: 2.12)

SEV Guest Launch measurement information. Very demure, very measurement 🎀

Members

data (string) — the measurement value encoded in base64

🌈 Command query-sev-launch-measure (Since: 2.12)

Queries the SEV/SEV-ES guest launch information 🔍

This is only valid on x86 machines configured with KVM and the 'sev-guest' confidential virtualization object. And listen — the launch measurement for SEV-SNP guests is only available within the guest, so don't come looking for it out here 💀

Return SevLaunchMeasureInfo — The guest's SEV guest launch measurement info

Errors

If the launch measurement is unavailable, either due to an invalid guest configuration or if the guest has not reached the required SEV state, GenericError

Example:

-> { "execute": "query-sev-launch-measure" }
<- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }

🫶 Object SevCapability (Since: 2.12)

This struct describes capability for a Secure Encrypted Virtualization feature. It's giving "receipts" ✨

Members

pdh (string) — Platform Diffie-Hellman key (base64 encoded)
cert-chain (string) — PDH certificate chain (base64 encoded)
cpu0-id (string) — Unique ID of CPU0 (base64 encoded) (since 7.1)
cbitpos (int) — C-bit location in page table entry
reduced-phys-bits (int) — Number of physical address bit reduction when SEV is enabled

🔥 Command query-sev-capabilities (Since: 2.12)

Gets the SEV capabilities. Only supported on AMD X86 platforms with KVM enabled, so like, check your hardware bestie 💅

Return SevCapability

Errors

If SEV is not available on the platform, GenericError

Example:

-> { "execute": "query-sev-capabilities" }
<- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
                 "cpu0-id": "2lvmGwo+...61iEinw==",
                 "cbitpos": 47, "reduced-phys-bits": 1}}

👑 Command sev-inject-launch-secret (Since: 6.0)

Injects a secret blob into a SEV/SEV-ES guest's memory. Sneaky sneaky 🤫

This is only valid on x86 machines configured with KVM and the 'sev-guest' confidential virtualization object. And no — SEV-SNP guests do not support launch secret injection, periodt.

Arguments

packet-header (string) — the launch secret packet header encoded in base64
secret (string) — the launch secret data to be injected encoded in base64
gpa (int, optional) — the guest physical address where secret will be injected.

Errors

If launch secret injection is not possible, either due to an invalid guest configuration, or if the guest has not reached the required SEV state, GenericError

🍓 Object SevAttestationReport (Since: 6.1)

This struct describes the attestation report for a Secure Encrypted Virtualization feature 📜

Members

data (string) — guest attestation report (base64 encoded)

⭐ Command query-sev-attestation-report (Since: 6.1)

Gets the SEV attestation report. Show me the receipts 💅

This is only valid on x86 machines configured with KVM and the 'sev-guest' confidential virtualization object. And the attestation report for SEV-SNP guests is only available within the guest — iykyk.

Arguments

mnonce (string) — a random 16 bytes value encoded in base64 (it will be included in report)

Return SevAttestationReport

Errors

If the attestation report is unavailable, either due to an invalid guest configuration or because the guest has not reached the required SEV state, GenericError

Example:

-> { "execute" : "query-sev-attestation-report",
                 "arguments": { "mnonce": "aaaaaaa" } }
<- { "return" : { "data": "aaaaaaaabbbddddd"} }

🦋 Object SgxEpcSection (Since: 7.0)

Info about an intel SGX EPC section ✨

Members

node (int) — the numa node
size (int) — the size of EPC section

💖 Object SgxInfo (Since: 6.2)

Info about intel Safe Guard eXtension (SGX) support. Say that five times fast 😭

Members

sgx (boolean) — true if SGX is supported
sgx1 (boolean) — true if SGX1 is supported
sgx2 (boolean) — true if SGX2 is supported
flc (boolean) — true if FLC is supported
sections ([SgxEpcSection]) — The EPC sections information (Since: 7.0)

🌸 Command query-sgx (Since: 6.2)

Returns info about the configured SGX capabilities of the guest 🧚

Return SgxInfo

Example:

-> { "execute": "query-sgx" }
<- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
                 "flc": true,
                 "sections": [{"node": 0, "size": 67108864},
                 {"node": 1, "size": 29360128}]} }

🎀 Command query-sgx-capabilities (Since: 6.2)

Returns info about the SGX capabilities of the host — yes, the host, not the guest, don't mix them up bestie 🫶

Return SgxInfo

Example:

-> { "execute": "query-sgx-capabilities" }
<- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
                 "flc": true,
                 "section" : [{"node": 0, "size": 67108864},
                 {"node": 1, "size": 29360128}]} }

💜 Enum EvtchnPortType (Since: 8.0)

An enumeration of Xen event channel port types. Xen girlies rise 💅

Values

closed — The port is unused.
unbound — The port is allocated and ready to be bound.
interdomain — the port is wired up as an interdomain interrupt ✨
pirq — the port is bound to a physical IRQ (PIRQ)
virq — the port is bound to a virtual IRQ (VIRQ)
ipi — the post is an inter-processor interrupt (IPI)

Object `EvtchnInfo` (Since: 8.0) 🎀

All the deets on one Xen event channel port, bestie.

Members

port (int) — the port number
vcpu (int) — target vCPU for this port
type (EvtchnPortType) — the port type
remote-domain (string) — remote domain for interdomain ports
target (int) — remote port ID, or virq/pirq number
pending (boolean) — port is currently active pending delivery
masked (boolean) — port is masked 🙈

Command `xen-event-list` (Since: 8.0) 💅

Query the Xen event channels opened by the guest. Like, show me every port the guest has open, no gatekeeping.

Return [EvtchnInfo] — list of open event channel ports.

Example:

-> { "execute": "xen-event-list" }
<- { "return": [
        {
            "pending": false,
            "port": 1,
            "vcpu": 1,
            "remote-domain": "qemu",
            "masked": false,
            "type": "interdomain",
            "target": 1
        },
        {
            "pending": false,
            "port": 2,
            "vcpu": 0,
            "remote-domain": "",
            "masked": false,
            "type": "virq",
            "target": 0
        }
     ]
   }

Command `xen-event-inject` (Since: 8.0) 🔥

Inject a Xen event channel port (interrupt) to the guest. Yeah, we're just straight-up poking the guest with an interrupt, iconic behaviour.

Arguments

port (int) — The port number

Example:

-> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
<- { "return": { } }

🔥 AUDIO 🔥

Okay this is the audio chapter and it's giving long, but we're gonna get through it together. Every backend gets its own little moment, as it deserves. 🎧

Object `AudiodevPerDirectionOptions` (Since: 4.0) 🎶

The general audio backend options, and these bad boys get used for both playback and recording. Shared custody, we love to see it.

Members

mixing-engine (boolean, optional) — use QEMU's mixing engine to mix all streams inside QEMU and convert audio formats when not supported by the backend. When set to off, fixed-settings must be also off (default on, since 4.2)
fixed-settings (boolean, optional) — use fixed settings for host input/output. When off, frequency, channels and format must not be specified (default true)
frequency (int, optional) — frequency to use when using fixed settings (default 44100)
channels (int, optional) — number of channels when using fixed settings (default 2)
voices (int, optional) — number of voices to use (default 1)
format (AudioFormat, optional) — sample format to use when using fixed settings (default s16)
buffer-length (int, optional) — the buffer length in microseconds

Object `AudiodevGenericOptions` (Since: 4.0) ✨

Generic driver-specific options. The "we didn't feel like making a special one" options, respectfully.

Members

in (AudiodevPerDirectionOptions, optional) — options of the capture stream
out (AudiodevPerDirectionOptions, optional) — options of the playback stream

Object `AudiodevDBusOptions` (Since: 10.0) 🦋

Options of the D-Bus audio backend. Newer era, new backend, same vibes.

Members

in (AudiodevPerDirectionOptions, optional) — options of the capture stream
out (AudiodevPerDirectionOptions, optional) — options of the playback stream
nsamples (int, optional) — set the number of samples per read/write calls (default to 480, 10ms at 48kHz).

Object `AudiodevAlsaPerDirectionOptions` (Since: 4.0) 🐧

Options of the ALSA backend that are used for both playback and recording.

Members

dev (string, optional) — the name of the ALSA device to use (default 'default')
period-length (int, optional) — the period length in microseconds
try-poll (boolean, optional) — attempt to use poll mode, falling back to non-polling access on failure (default false)
The members of AudiodevPerDirectionOptions.

Object `AudiodevAlsaOptions` (Since: 4.0) 🌸

Options of the ALSA audio backend, the whole package.

Members

in (AudiodevAlsaPerDirectionOptions, optional) — options of the capture stream
out (AudiodevAlsaPerDirectionOptions, optional) — options of the playback stream
threshold (int, optional) — set the threshold (in microseconds) when playback starts

Object `AudiodevSndioOptions` (Since: 7.2) 🎀

Options of the sndio audio backend. BSD girlies rise.

Members

in (AudiodevPerDirectionOptions, optional) — options of the capture stream
out (AudiodevPerDirectionOptions, optional) — options of the playback stream
dev (string, optional) — the name of the sndio device to use (default 'default')
latency (int, optional) — play buffer size (in microseconds)

Object `AudiodevCoreaudioPerDirectionOptions` (Since: 4.0) 🍎

Options of the Core Audio backend that are used for both playback and recording.

Members

buffer-count (int, optional) — number of buffers
The members of AudiodevPerDirectionOptions.

Object `AudiodevCoreaudioOptions` (Since: 4.0) 🫶

Options of the coreaudio audio backend.

Members

in (AudiodevCoreaudioPerDirectionOptions, optional) — options of the capture stream
out (AudiodevCoreaudioPerDirectionOptions, optional) — options of the playback stream

Object `AudiodevDsoundOptions` (Since: 4.0) 💀

Options of the DirectSound audio backend. Windows noise, but make it QEMU.

Members

in (AudiodevPerDirectionOptions, optional) — options of the capture stream
out (AudiodevPerDirectionOptions, optional) — options of the playback stream
latency (int, optional) — add extra latency to playback in microseconds (default 10000)

Object `AudiodevJackPerDirectionOptions` (Since: 5.1) 🎸

Options of the JACK backend that are used for both playback and recording. This one's got lore, pay attention.

Members

server-name (string, optional) — select from among several possible concurrent server instances (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
client-name (string, optional) — the client name to use. The server will modify this name to create a unique variant, if needed unless exact-name is true (default: the guest's name)
connect-ports (string, optional) — if set, a regular expression of JACK client port name(s) to monitor for and automatically connect to
start-server (boolean, optional) — start a jack server process if one is not already present (default: false)
exact-name (boolean, optional) — use the exact name requested otherwise JACK automatically generates a unique one, if needed (default: false)
The members of AudiodevPerDirectionOptions.

Object `AudiodevJackOptions` (Since: 5.1) 🎧

Options of the JACK audio backend.

Members

in (AudiodevJackPerDirectionOptions, optional) — options of the capture stream
out (AudiodevJackPerDirectionOptions, optional) — options of the playback stream

Object `AudiodevOssPerDirectionOptions` (Since: 4.0) 🐚

Options of the OSS backend that are used for both playback and recording. Retro moment.

Members

dev (string, optional) — file name of the OSS device (default '/dev/dsp')
buffer-count (int, optional) — number of buffers
try-poll (boolean, optional) — attempt to use poll mode, falling back to non-polling access on failure (default true)
The members of AudiodevPerDirectionOptions.

Object `AudiodevOssOptions` (Since: 4.0) 🎵

Options of the OSS audio backend. Lots of knobs, we love a customizable queen.

Members

in (AudiodevOssPerDirectionOptions, optional) — options of the capture stream
out (AudiodevOssPerDirectionOptions, optional) — options of the playback stream
try-mmap (boolean, optional) — try using memory-mapped access, falling back to non-memory-mapped access on failure (default true)
exclusive (boolean, optional) — open device in exclusive mode (vmix won't work) (default false)
dsp-policy (int, optional) — set the timing policy of the device (between 0 and 10, where smaller number means smaller latency but higher CPU usage) or -1 to use fragment mode (option ignored on some platforms) (default 5)

Object `AudiodevPaPerDirectionOptions` (Since: 4.0) 💜

Options of the Pulseaudio backend that are used for both playback and recording.

Members

name (string, optional) — name of the sink/source to use

Picking up mid-list, bestie — here are the next members:

stream-name (string, optional) — name of the PulseAudio stream created by QEMU. Can be used to identify the stream in PulseAudio when you create multiple PulseAudio devices or run multiple QEMU instances (default: audiodev's id, since 4.2) 💅
latency (int, optional) — latency you want PulseAudio to achieve in microseconds (default 15000) ✨
The members of AudiodevPerDirectionOptions.

🎧 Object `AudiodevPaOptions` (Since: 4.0)

Options of the PulseAudio audio backend.

Members

in (AudiodevPaPerDirectionOptions, optional) — options of the capture stream 🎀
out (AudiodevPaPerDirectionOptions, optional) — options of the playback stream 🎀
server (string, optional) — PulseAudio server address (default: let PulseAudio choose) 🌸

🎧 Object `AudiodevPipewirePerDirectionOptions` (Since: 8.1)

Options of the PipeWire backend that are used for both playback and recording.

Members

name (string, optional) — name of the sink/source to use 🦋
stream-name (string, optional) — name of the PipeWire stream created by QEMU. Can be used to identify the stream in PipeWire when you create multiple PipeWire devices or run multiple QEMU instances (default: audiodev's id) 💖
latency (int, optional) — latency you want PipeWire to achieve in microseconds (default 46000) ✨
The members of AudiodevPerDirectionOptions.

🎧 Object `AudiodevPipewireOptions` (Since: 8.1)

Options of the PipeWire audio backend.

Members

in (AudiodevPipewirePerDirectionOptions, optional) — options of the capture stream 🎀
out (AudiodevPipewirePerDirectionOptions, optional) — options of the playback stream 🎀

🎧 Object `AudiodevSdlPerDirectionOptions` (Since: 6.0)

Options of the SDL audio backend that are used for both playback and recording.

Members

buffer-count (int, optional) — number of buffers (default 4) 🫶
The members of AudiodevPerDirectionOptions.

🎧 Object `AudiodevSdlOptions` (Since: 6.0)

Options of the SDL audio backend.

Members

in (AudiodevSdlPerDirectionOptions, optional) — options of the recording stream 🎀
out (AudiodevSdlPerDirectionOptions, optional) — options of the playback stream 🎀

🎧 Object `AudiodevWavOptions` (Since: 4.0)

Options of the wav audio backend.

Members

in (AudiodevPerDirectionOptions, optional) — options of the capture stream 🎀
out (AudiodevPerDirectionOptions, optional) — options of the playback stream 🎀
path (string, optional) — name of the wav file to record (default 'qemu.wav') 🍓

🌈 Enum `AudioFormat` (Since: 4.0)

An enumeration of possible audio formats.

Values

u8 — unsigned 8 bit integer 🧚
s8 — signed 8 bit integer 🧚
u16 — unsigned 16 bit integer 🧚
s16 — signed 16 bit integer 🧚
u32 — unsigned 32 bit integer 🧚
s32 — signed 32 bit integer 🧚
f32 — single precision floating-point (since 5.0) ⭐

🌈 Enum `AudiodevDriver` (Since: 4.0)

An enumeration of possible audio backend drivers.

Values

jack — JACK audio backend (since 5.1) 🔥
none — Not documented 🙈
alsa — Not documented 🙈
coreaudio — Not documented 🙈
dbus — Not documented 🙈
dsound — Not documented 🙈
oss — Not documented 🙈
pa — Not documented 🙈
pipewire — Not documented 🙈
sdl — Not documented 🙈
sndio — Not documented 🙈
spice — Not documented 🙈
wav — Not documented 🙈

🎧 Object `Audiodev` (Since: 4.0)

Options of an audio backend.

Members

id (string) — identifier of the backend 👑
driver (AudiodevDriver) — the backend driver to use 💅
timer-period (int, optional) — timer period (in microseconds, 0: use lowest possible) ⏱️
When driver is none: The members of AudiodevGenericOptions.
When driver is alsa: The members of AudiodevAlsaOptions.
When driver is coreaudio: The members of AudiodevCoreaudioOptions.
When driver is dbus: The members of AudiodevDBusOptions.
When driver is dsound: The members of AudiodevDsoundOptions.
When driver is jack: The members of AudiodevJackOptions.
When driver is oss: The members of AudiodevOssOptions.
When driver is pa: The members of AudiodevPaOptions.
When driver is pipewire: The members of AudiodevPipewireOptions.
When driver is sdl: The members of AudiodevSdlOptions.
When driver is sndio: The members of AudiodevSndioOptions.
When driver is spice: The members of AudiodevGenericOptions.
When driver is wav: The members of AudiodevWavOptions.

📡 Command `query-audiodevs` (Since: 8.0)

Return information about audiodev configuration

Return [Audiodev]

🌸 ACPI 🌸

okay bestie, this whole section is about ACPI — the Advanced Configuration and Power Interface stuff, aka how the guest and host whisper about power, slots and errors. let's get into it 💅

🎀 Object AcpiTableOptions (Since: 1.5) 🎀

So you wanna specify an ACPI table on the command line to load. iconic. here's the tea:

at most one of file and data can be specified. the list of files specified by any one of them gets loaded and concatenated in order. and if you omit both? then data is implied, no cap.

other fields / optargs can be used to override fields of the generic ACPI table header — go look at the ACPI specification 5.0, section 5.2.6 System Description Table Header, iykyk. If a header field isn't overridden, then the corresponding value from the concatenated blob is used (when it's file), or it gets filled in with a hard-coded value (when it's data).

String fields get copied into the matching ACPI member from lowest address upwards, and are silently truncated / NUL-padded to length. cute but ruthless 💀

Members

sig (string, optional) — table signature / identifier (4 bytes)
rev (int, optional) — table revision number (dependent on signature, 1 byte)
oem_id (string, optional) — OEM identifier (6 bytes)
oem_table_id (string, optional) — OEM table identifier (8 bytes)
oem_rev (int, optional) — OEM-supplied revision number (4 bytes)
asl_compiler_id (string, optional) — identifier of the utility that created the table (4 bytes)
asl_compiler_rev (int, optional) — revision number of the utility that created the table (4 bytes)
file (string, optional) — colon (:) separated list of pathnames to load and concatenate as table data. the resultant binary blob is expected to have an ACPI table header. at least one file is required. this field excludes data.
data (string, optional) — colon (:) separated list of pathnames to load and concatenate as table data. the resultant binary blob must not have an ACPI table header. at least one file is required. this field excludes file.

🌈 Enum ACPISlotType 🌈

Values

DIMM — memory slot
CPU — logical CPU slot (since 2.7)

✨ Object ACPIOSTInfo (Since: 2.1) ✨

OSPM Status Indication for a device, bestie. for a description of the possible values of the source and status fields, go read the "_OST (OSPM Status Indication)" chapter of the ACPI5.0 spec 🫶

Members

device (string, optional) — device ID associated with slot
slot (string) — slot ID, unique per slot of a given slot-type
slot-type (ACPISlotType) — type of the slot
source (int) — an integer containing the source event
status (int) — an integer containing the status code

💜 Command query-acpi-ospm-status (Since: 2.1) 💜

Returns a list of ACPIOSTInfo for devices that support status reporting via the ACPI _OST method. lowkey handy.

Return [ACPIOSTInfo]

Example:

-> { "execute": "query-acpi-ospm-status" }
<- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
                 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
                 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
                 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
   ]}

🦋 Event ACPI_DEVICE_OST (Since: 2.1) 🦋

Emitted when the guest executes the ACPI _OST method. it's giving notification energy 📣

Members

info (ACPIOSTInfo) — OSPM Status Indication

Example:

<- { "event": "ACPI_DEVICE_OST",
     "data": { "info": { "device": "d1", "slot": "0",
                         "slot-type": "DIMM", "source": 1, "status": 0 } },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

🔥 GHESv2 CPER Error Injection 🔥

Defined since ACPI Specification 6.1, section 18.3.2.8 Generic Hardware Error Source version 2. See:

<https://uefi.org/sites/default/files/resources/ACPI_6_1.pdf>

💥 Command inject-ghes-v2-error (Since: 10.2) 💥

⚠️ bestie, heads up: this command is unstable/experimental.

Inject an error with additional ACPI 6.1 GHESv2 error information.

Arguments

cper (string) — contains a base64 encoded string with raw data for a single CPER record with Generic Error Status Block, Generic Error Data Entry and generic error data payload, as described at <https://uefi.org/specs/UEFI/2.10/Apx_N_Common_Platform_Error_Record.html#format>

Features

unstable — This command is experimental.

that's the ACPI chapter, bestie — tables, slots, OSPM status and a lil error injection on the side. more coming, don't go anywhere 🧚💖

🌸 PCI 🌸

Ok bestie, this is the PCI corner of the QMP universe — buses, bridges, devices, all of it. Every object below is a little JSON-shaped snack that tells you what's plugged in where. Let's go 💅

🎀 Object `PciMemoryRange` (Since: 0.14)

A PCI device memory region. That's the whole vibe.

Members

base (int) — the starting address (guest physical)
limit (int) — the ending address (guest physical)

🎀 Object `PciMemoryRegion` (Since: 0.14)

All the deets about a PCI device I/O region. Iconic.

Members

bar (int) — the index of the Base Address Register for this region
type (string) — the type of the region, and it's one of these two:
- 'io' if the region is a PIO region
- 'memory' if the region is a MMIO region
address (int) — memory address
size (int) — memory size
prefetch (boolean, optional) — if type is 'memory', true if the memory is prefetchable
mem_type_64 (boolean, optional) — if type is 'memory', true if the BAR is 64-bit

🎀 Object `PciBusInfo` (Since: 2.4)

The tea on a PCI Bridge device's bus 🫖

Members

number (int) — primary bus interface number. This should be the number of the bus the device resides on.
secondary (int) — secondary bus interface number. This is the number of the main bus for the bridge
subordinate (int) — this is the highest number bus that resides below the bridge.
io_range (PciMemoryRange) — the PIO range for all devices on this bridge
memory_range (PciMemoryRange) — the MMIO range for all devices on this bridge
prefetchable_range (PciMemoryRange) — the range of prefetchable MMIO for all devices on this bridge

🎀 Object `PciBridgeInfo` (Since: 0.14)

Information about a PCI Bridge device. Bridge era 💅

Members

bus (PciBusInfo) — information about the bus the device resides on
devices ([PciDeviceInfo], optional) — a list of PciDeviceInfo for each device on this bridge

🎀 Object `PciDeviceClass` (Since: 2.4)

Information about the Class of a PCI device.

Members

desc (string, optional) — a string description of the device's class (not stable, and should only be treated as informational — so like, don't build anything on this, bestie 💀)
class (int) — the class code of the device

🎀 Object `PciDeviceId` (Since: 2.4)

Information about the Id of a PCI device. The name-tag energy ✨

Members

device (int) — the PCI device id
vendor (int) — the PCI vendor id
subsystem (int, optional) — the PCI subsystem id (since 3.1)
subsystem-vendor (int, optional) — the PCI subsystem vendor id (since 3.1)

Heads up: subsystem and subsystem-vendor are both dated (since 3.1) — they show up in the member list with that note, so don't forget it 🫶

🎀 Object `PciDeviceInfo` (Since: 0.14)

Okay this is the main character of the section — information about a PCI device 💖

Members

bus (int) — the bus number of the device
slot (int) — the slot the device is located in
function (int) — the function of the slot used by the device
class_info (PciDeviceClass) — the class of the device
id (PciDeviceId) — the PCI device id
irq (int, optional) — if an IRQ is assigned to the device, the IRQ number
irq_pin (int) — the IRQ pin, zero means no IRQ (since 5.1)
qdev_id (string) — the device name of the PCI device
pci_bridge (PciBridgeInfo, optional) — if the device is a PCI bridge, the bridge information
regions ([PciMemoryRegion]) — a list of the PCI I/O regions associated with the device

🎀 Object `PciInfo` (Since: 0.14)

Information about a PCI bus. Simple, clean, slays.

Members

bus (int) — the bus index
devices ([PciDeviceInfo]) — a list of devices on this bus

🎀 Command `query-pci` (Since: 0.14)

Return information about the PCI bus topology of the guest. Literally the map of everything plugged in 🗺️

Return [PciInfo] — a list of info for each PCI bus. Each bus is represented by a json-object, which has a key with a json-array of all PCI devices attached to it. Each device is represented by a json-object.

⭐ Example:

-> { "execute": "query-pci" }
<- { "return": [
         {
            "bus": 0,
            "devices": [
               {
                  "bus": 0,
                  "qdev_id": "",
                  "slot": 0,
                  "class_info": {
                     "class": 1536,
                     "desc": "Host bridge"
                  },
                  "id": {
                     "device": 32902,
                     "vendor": 4663
                  },
                  "function": 0,
                  "regions": [
                  ]
               },
               {
                  "bus": 0,
                  "qdev_id": "",
                  "slot": 1,
                  "class_info": {
                     "class": 1537,
                     "desc": "ISA bridge"
                  },
                  "id": {
                     "device": 32902,
                     "vendor": 28672
                  },
                  "function": 0,
                  "regions": [
                  ]
               },
               {
                  "bus": 0,
                  "qdev_id": "",
                  "slot": 1,
                  "class_info": {
                     "class": 257,
                     "desc": "IDE controller"
                  },
                  "id": {
                     "device": 32902,
                     "vendor": 28688
                  },
                  "function": 1,
                  "regions": [
                     {
                        "bar": 4,
                        "size": 16,
                        "address": 49152,
                        "type": "io"
                     }
                  ]
               },
               {
                  "bus": 0,
                  "qdev_id": "",
                  "slot": 2,
                  "class_info": {
                     "class": 768,
                     "desc": "VGA controller"
                  },
                  "id": {
                     "device": 4115,
                     "vendor": 184
                  },
                  "function": 0,
                  "regions": [
                     {
                        "prefetch": true,
                        "mem_type_64": false,
                        "bar": 0,
                        "size": 33554432,
                        "address": 4026531840,
                        "type": "memory"
                     },
                     {
                        "prefetch": false,
                        "mem_type_64": false,
                        "bar": 1,
                        "size": 4096,
                        "address": 4060086272,
                        "type": "memory"
                     },
                     {
                        "prefetch": false,
                        "mem_type_64": false,
                        "bar": 6,
                        "size": 65536,
                        "address": -1,
                        "type": "memory"
                     }
                  ]
               },
               {
                  "bus": 0,
                  "qdev_id": "",
                  "irq": 11,
                  "slot": 4,
                  "class_info": {
                     "class": 1280,
                     "desc": "RAM controller"
                  },
                  "id": {
                     "device": 6900,
                     "vendor": 4098
                  },
                  "function": 0,
                  "regions": [
                     {
                        "bar": 0,
                        "size": 32,
                        "address": 49280,
                        "type": "io"
                     }
                  ]
               }
            ]
         }
      ]
   }

Ngl this example has been shortened as the real response is too long 😭 — so don't be surprised when your actual output is way chunkier.

Enum StatsType (Since: 7.1)

okay so this one is literally just the ✨vibe check✨ for what kind of number a stat is. Enumeration of statistics types 💅

Values

cumulative — stat is cumulative; value can only increase. it only goes up, bestie, no take-backs 📈
instant — stat is instantaneous; value can increase or decrease. this one's a free spirit, up or down, whatever it feels 🦋
peak — stat is the peak value; value can only increase. it's giving "highest score ever," it never comes back down 👑
linear-histogram — stat is a linear histogram.
log2-histogram — stat is a logarithmic histogram, with one bucket for each power of two.

Enum StatsUnit (Since: 7.1)

Enumeration of unit of measurement for statistics — like, what are we even counting here 🎀

Values

bytes — stat reported in bytes.
seconds — stat reported in seconds.
cycles — stat reported in clock cycles.
boolean — stat is a boolean value. yes/no energy, fr fr.

Enum StatsProvider (Since: 7.1)

Enumeration of statistics providers. who's out here handing us the numbers 💖

Values

kvm — since 7.1
cryptodev — since 8.0

Enum StatsTarget (Since: 7.1)

The kinds of objects on which one can request statistics. like, which thing are we snooping on 👀

Values

vm — statistics that apply to the entire virtual machine or the entire QEMU process.
vcpu — statistics that apply to a single virtual CPU.
cryptodev — statistics that apply to a crypto device (since 8.0)

Object StatsRequest (Since: 7.1)

Indicates a set of statistics that should be returned by query-stats.

Members

provider (StatsProvider) — provider for which to return statistics.
names ([string], optional) — statistics to be returned (all if omitted).

Object StatsVCPUFilter (Since: 7.1)

Members

vcpus ([string], optional) — list of QOM paths for the desired vCPU objects.

Object StatsFilter (Since: 7.1)

The arguments to the query-stats command; specifies a target for which to request statistics and optionally the required subset of information for that target.

Members

target (StatsTarget) — the kind of objects to query. Note that each possible target may enable additional filtering options
providers ([StatsRequest], optional) — which providers to request statistics from, and optionally which named values to return within each provider
When target is vcpu: The members of StatsVCPUFilter.

Alternate StatsValue (Since: 7.1)

Alternatives

scalar (int) — single unsigned 64-bit integers.
boolean (boolean) — single boolean value.
list ([int]) — list of unsigned 64-bit integers (used for histograms).

Object Stats (Since: 7.1)

Members

name (string) — name of stat.
value (StatsValue) — stat value.

Object StatsResult (Since: 7.1)

Members

provider (StatsProvider) — provider for this set of statistics.
qom-path (string, optional) — Path to the object for which the statistics are returned, if the object is exposed in the QOM tree
stats ([Stats]) — list of statistics.

Command query-stats (Since: 7.1)

Return runtime-collected statistics for objects such as the VM or its vCPUs. this is the main character of the whole STATISTICS section ngl 🫶

The arguments are a StatsFilter and specify the provider and objects to return statistics about.

Arguments

The members of StatsFilter.

Return [StatsResult] — a list of statistics, one for each provider and object (e.g., for each vCPU).

Object StatsSchemaValue (Since: 7.1)

Schema for a single statistic. it's the blueprint, basically 💅

Members

name (string) — name of the statistic; each element of the schema is uniquely identified by a target, a provider (both available in StatsSchema) and the name.
type (StatsType) — kind of statistic.
unit (StatsUnit, optional) — basic unit of measure for the statistic; if missing, the statistic is a simple number or counter.
base (int, optional) — base for the multiple of unit in which the statistic is measured. Only present if exponent is non-zero; base and exponent together form a SI prefix (e.g., nano- for base=10 and exponent=-9) or IEC binary prefix (e.g. kibi- for base=2 and exponent=10)
exponent (int) — exponent for the multiple of unit in which the statistic is expressed, or 0 for the basic unit
bucket-size (int, optional) — Present when type is "linear-histogram", contains the width of each bucket of the histogram.

Object StatsSchema (Since: 7.1)

Schema for all available statistics for a provider and target. the whole catalog, bestie 🎀

Members

provider (StatsProvider) — provider for this set of statistics.
target (StatsTarget) — the kind of object that can be queried through the provider.
stats ([StatsSchemaValue]) — list of statistics.

Command query-stats-schemas (Since: 7.1)

Return the schema for all available runtime-collected statistics. like window shopping but for stats 🛍️

Arguments

provider (StatsProvider, optional) — a provider to restrict the query to.

Return [StatsSchema]

Note: Runtime-collected statistics and their names fall outside QEMU's usual deprecation policies. QEMU will try to keep the set of available data stable, together with their names, but will not guarantee stability at all costs; the same is true of providers that source statistics externally, e.g. from Linux. For example, if the same value is being tracked with different names on different architectures or by different providers, one of them might be renamed. A statistic might go away if an algorithm is changed or some code is removed; changing a default might cause previously useful statistics to always report 0. Such changes, however, are expected to be rare. 😭 so like, don't build your whole personality on these names, k? they probably won't change but nobody's promising forever.

🔥 VIRTIO DEVICES 🔥

Object VirtioInfo (Since: 7.2)

Basic information about a given VirtIODevice — the little ID card for each one 💳

Members

path (string) — The VirtIODevice's canonical QOM path
name (string) — Name of the VirtIODevice

Command x-query-virtio (Since: 7.2)

This command is unstable/experimental. ⚠️ like, it works, but it's in its experimental era.

Return a list of all realized VirtIODevices

Features

unstable — This command is meant for debugging.

Return [VirtioInfo] — List of gathered VirtIODevices

Example:

-> { "execute": "x-query-virtio" }
<- { "return": [
         {
             "name": "virtio-input",
             "path": "/machine/peripheral-anon/device[4]/virtio-backend"
         },
         {
             "name": "virtio-crypto",
             "path": "/machine/peripheral/crypto0/virtio-backend"
         },
         {
             "name": "virtio-scsi",
             "path": "/machine/peripheral-anon/device[2]/virtio-backend"
         },
         {
             "name": "virtio-net",
             "path": "/machine/peripheral-anon/device[1]/virtio-backend"
         },
         {
             "name": "virtio-serial",
             "path": "/machine/peripheral-anon/device[0]/virtio-backend"
         }
     ]
   }

Object VhostStatus (Since: 7.2)

Information about a vhost device. This information will only be displayed if the vhost device is active. so if it's not active, you get nothing, sorry bestie 🙈

Members

n-mem-sections (int) — vhost_dev n_mem_sections
n-tmp-sections (int) — vhost_dev n_tmp_sections
nvqs (int) — vhost_dev nvqs (number of virtqueues being used)
vq-index (int) — vhost_dev vq_index
features (VirtioDeviceFeatures) — vhost_dev features
acked-features (VirtioDeviceFeatures) — vhost_dev acked_features
protocol-features (VhostDeviceProtocols) — vhost_dev protocol_features
max-queues (int) — vhost_dev max_queues
backend-cap (int) — vhost_dev backend_cap
log-enabled (boolean) — vhost_dev log_enabled flag
log-size (int) — vhost_dev log_size

Object VirtioStatus (Since: 7.2)

Full status of the virtio device with most VirtIODevice members. Also includes the full status of the corresponding vhost device if the vhost device is active. the whole lore drop, basically 📖✨

Members

name (string) — VirtIODevice name
device-id (int) — VirtIODevice ID
vhost-started (boolean) — VirtIODevice vhost_started flag
guest-features (VirtioDeviceFeatures) — VirtIODevice guest_features
host-features (VirtioDeviceFeatures) — VirtIODevice host_features
backend-features (VirtioDeviceFeatures) — VirtIODevice backend_features
device-endian (string) — VirtIODevice device_endian
num-vqs (int) — VirtIODevice virtqueue count. This is the number of active virtqueues being used by the VirtIODevice.
status (VirtioDeviceStatus) — VirtIODevice configuration status (VirtioDeviceStatus)
isr (int) — VirtIODevice ISR
queue-sel (int) — VirtIODevice queue_sel
vm-running (boolean) — VirtIODevice vm_running flag
broken (boolean) — the VirtIODevice broken flag, i.e. is this thing busted 😭
disabled (boolean) — the VirtIODevice disabled flag
use-started (boolean) — the VirtIODevice use_started flag
started (boolean) — the VirtIODevice started flag
start-on-kick (boolean) — the VirtIODevice start_on_kick flag
disable-legacy-check (boolean) — the VirtIODevice disabled_legacy_check flag
bus-name (string) — the VirtIODevice bus_name
use-guest-notifier-mask (boolean) — the VirtIODevice use_guest_notifier_mask flag
vhost-dev (VhostStatus, optional) — the corresponding vhost device info for a given VirtIODevice. It's present only if that VirtIODevice actually has an active vhost device, bestie — no vhost, no field 👑

🌈 Command `x-query-virtio-status` (Since: 7.2)

⚠️ Heads up: this command is unstable/experimental. Treat it gently, it's still in its testing era 💅

Poll for a comprehensive status of a given virtio device. Like, the whole vibe report 🫶

💖 Arguments

path (string) — Canonical QOM path of the VirtIODevice

✨ Features

unstable — this command is meant for debugging. It's giving "dev tool", not "production icon" 🔥

🦋 Return `VirtioStatus` — the status of the virtio device

Example:

Poll for the status of virtio-crypto (no vhost-crypto active)

-> { "execute": "x-query-virtio-status",
     "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
   }
<- { "return": {
         "device-endian": "little",
         "bus-name": "",
         "disable-legacy-check": false,
         "name": "virtio-crypto",
         "started": true,
         "device-id": 20,
         "backend-features": {
             "transports": [],
             "dev-features": []
         },
         "start-on-kick": false,
         "isr": 1,
         "broken": false,
         "status": {
             "statuses": [
                 "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
                 "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
                 "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
                 "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
             ]
         },
         "num-vqs": 2,
         "guest-features": {
             "dev-features": [],
             "transports": [
                 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
                 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
                 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
             ]
         },
         "host-features": {
             "unknown-dev-features": 1073741824,
             "unknown-dev-features2": 0,
             "dev-features": [],
             "transports": [
                 "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
                 "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
                 "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
                 "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
                 "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
             ]
         },
         "use-guest-notifier-mask": true,
         "vm-running": true,
         "queue-sel": 1,
         "disabled": false,
         "vhost-started": false,
         "use-started": true
     }
   }

Example:

Poll for the status of virtio-net (vhost-net is active)

okay so picture this: you just fired x-query-virtio-status at your virtio-net device and this absolute unit of a JSON came back 😭 this is what "thorough" looks like, bestie — every feature bit, every vhost section, all of it, in one blessed payload.

                     -> { "execute": "x-query-virtio-status",
                          "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
                        }
                     <- { "return": {
                              "device-endian": "little",
                              "bus-name": "",
                              "disabled-legacy-check": false,
                              "name": "virtio-net",
                              "started": true,
                              "device-id": 1,
                              "vhost-dev": {
                                  "n-tmp-sections": 4,
                                  "n-mem-sections": 4,
                                  "max-queues": 1,
                                  "backend-cap": 2,
                                  "log-size": 0,
                                  "backend-features": {
                                      "dev-features": [],
                                      "transports": []
                                  },
                                  "nvqs": 2,
                                  "protocol-features": {
                                      "protocols": []
                                  },
                                  "vq-index": 0,
                                  "log-enabled": false,
                                  "acked-features": {
                                      "dev-features": [
                                          "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
                                      ],
                                      "transports": [
                                          "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
                                          "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
                                          "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
                                      ]
                                  },
                                  "features": {
                                      "dev-features": [
                                          "VHOST_F_LOG_ALL: Logging write descriptors supported",
                                          "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers"
                                      ],
                                      "transports": [
                                          "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
                                          "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
                                          "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform",
                                          "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
                                          "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
                                          "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
                                      ]
                                  }
                              },
                              "backend-features": {
                                  "dev-features": [
                                      "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
                                      "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
                                      "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
                                      "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
                                      "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
                                      "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
                                      "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
                                      "VIRTIO_NET_F_CTRL_VQ: Control channel available",
                                      "VIRTIO_NET_F_STATUS: Configuration status field available",
                                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
                                      "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
                                      "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
                                      "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
                                      "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
                                      "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
                                      "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
                                      "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
                                      "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
                                      "VIRTIO_NET_F_MAC: Device has given MAC address",
                                      "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
                                      "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
                                      "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
                                  ],
                                  "transports": [
                                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
                                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
                                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
                                      "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
                                      "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
                                  ]
                              },
                              "start-on-kick": false,
                              "isr": 1,
                              "broken": false,
                              "status": {
                                  "statuses": [
                                      "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found",
                                      "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device",
                                      "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete",
                                      "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready"
                                  ]
                              },
                              "num-vqs": 3,
                              "guest-features": {
                                  "dev-features": [
                                      "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
                                      "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
                                      "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
                                      "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
                                      "VIRTIO_NET_F_CTRL_VQ: Control channel available",
                                      "VIRTIO_NET_F_STATUS: Configuration status field available",
                                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
                                      "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
                                      "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
                                      "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
                                      "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
                                      "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
                                      "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
                                      "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
                                      "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
                                      "VIRTIO_NET_F_MAC: Device has given MAC address",
                                      "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
                                      "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
                                      "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
                                  ],
                                  "transports": [
                                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
                                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",
                                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)"
                                 ]
                              },
                              "host-features": {
                                  "dev-features": [
                                      "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported",
                                      "VIRTIO_NET_F_GSO: Handling GSO-type packets supported",
                                      "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel",
                                      "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported",
                                      "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported",
                                      "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported",
                                      "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported",
                                      "VIRTIO_NET_F_CTRL_VQ: Control channel available",
                                      "VIRTIO_NET_F_STATUS: Configuration status field available",
                                      "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers",
                                      "VIRTIO_NET_F_HOST_UFO: Device can receive UFO",
                                      "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN",
                                      "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6",
                                      "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4",
                                      "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO",
                                      "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN",
                                      "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6",
                                      "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4",
                                      "VIRTIO_NET_F_MAC: Device has given MAC address",
                                      "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported",
                                      "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported",
                                      "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported"
                                  ],
                                  "transports": [
                                      "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled",
                                      "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported",

okay let's do a little vibe check on what you're looking at here, because this thing is dense and nobody should have to freestyle it ✨

the outer object is giving device-level tea: device-endian is "little", bus-name is "", disabled-legacy-check is false, name is "virtio-net", started is true, device-id is 1, num-vqs is 3, start-on-kick is false, isr is 1, and broken is false 🫶
status.statuses is the glow-up list: VIRTIO_CONFIG_S_ACKNOWLEDGE, VIRTIO_CONFIG_S_DRIVER, VIRTIO_CONFIG_S_FEATURES_OK, and VIRTIO_CONFIG_S_DRIVER_OK — like, driver fully set up and thriving 👑
then there's the vhost-dev block, which is nested and honestly iconic: n-tmp-sections 4, n-mem-sections 4, max-queues 1, backend-cap 2, log-size 0, nvqs 2, vq-index 0, log-enabled false, plus its own backend-features, protocol-features, acked-features, and features sub-objects 🎀
and then the three big siblings — backend-features, guest-features, and host-features — each with a dev-features array and a transports array 🌸

not to be dramatic but this is a lot of feature strings, and every single one of them matters. no skipping, bestie 😤 the next chunk keeps going through host-features.transports, so hold that thought 💅

                                      "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)",
                                      "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts",
                                      "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ"
                                 ]
                              },
                              "use-guest-notifier-mask": true,
                              "vm-running": true,
                              "queue-sel": 2,
                              "disabled": false,
                              "vhost-started": true,
                              "use-started": true
                          }
                        }

…and that's the tail end of that response bestie, we're literally sliding straight into the next objects 🛝✨

🌸 Object `VirtioDeviceStatus` (Since: 7.2)

A structure defined to list the configuration statuses of a virtio device 💅

Members — here's the tea:

statuses ([string]) — List of decoded configuration statuses of the virtio device
unknown-statuses (int, optional) — Virtio device statuses bitmap that have not been decoded

🦋 Object `VhostDeviceProtocols` (Since: 7.2)

A structure defined to list the vhost user protocol features of a Vhost User device 🫶

Members:

protocols ([string]) — List of decoded vhost user protocol features of a vhost user device
unknown-protocols (int, optional) — Vhost user device protocol features bitmap that have not been decoded

🎀 Object `VirtioDeviceFeatures` (Since: 7.2)

The common fields that apply to most Virtio devices. Some devices may not have their own device-specific features (e.g. virtio-rng) — so don't @ them for not having extra ✨

Members:

transports ([string]) — List of transport features of the virtio device
dev-features ([string], optional) — List of device-specific features (if the device has unique features)
unknown-dev-features (int, optional) — Virtio device features bitmap that have not been decoded (bits 0-63)
unknown-dev-features2 (int, optional) — Virtio device features bitmap that have not been decoded (bits 64-127) (since 10.2)

🧚 Note the two unknowns bestie — unknown-dev-features covers bits 0-63 and unknown-dev-features2 covers bits 64-127. Two buckets, no cap 💜

🌈 Object `VirtQueueStatus` (Since: 7.2)

Information of a VirtIODevice VirtQueue, including most members of the VirtQueue data structure. It's giving "full backstage pass" 🎤

Members:

name (string) — Name of the VirtIODevice that uses this VirtQueue
queue-index (int) — VirtQueue queue_index
inuse (int) — VirtQueue inuse
vring-num (int) — VirtQueue vring.num
vring-num-default (int) — VirtQueue vring.num_default
vring-align (int) — VirtQueue vring.align
vring-desc (int) — VirtQueue vring.desc (descriptor area)
vring-avail (int) — VirtQueue vring.avail (driver area)
vring-used (int) — VirtQueue vring.used (device area)
last-avail-idx (int, optional) — VirtQueue last_avail_idx or return of vhost_dev vhost_get_vring_base (if vhost active)
shadow-avail-idx (int, optional) — VirtQueue shadow_avail_idx
used-idx (int) — VirtQueue used_idx
signalled-used (int) — VirtQueue signalled_used
signalled-used-valid (boolean) — VirtQueue signalled_used_valid flag

💅 Command `x-query-virtio-queue-status` (Since: 7.2)

This command is unstable/experimental. 👀 (the x- prefix is literally the universe telling you it might change)

Return the status of a given VirtIODevice's VirtQueue 💖

Arguments:

path (string) — VirtIODevice canonical QOM path
queue (int) — VirtQueue index to examine

Features:

unstable — This command is meant for debugging.

Return VirtQueueStatus — Status of the queue

⚠️ Note: last_avail_idx will not be displayed in the case where the selected VirtIODevice has a running vhost device and the VirtIODevice VirtQueue index (queue) does not exist for the corresponding vhost device vhost_virtqueue. Also, shadow_avail_idx will not be displayed in the case where the selected VirtIODevice has a running vhost device. Like, it's not hiding from you, it just doesn't exist in that config bestie 😭

Example:

Get VirtQueueStatus for virtio-vsock (vhost-vsock running)

-> { "execute": "x-query-virtio-queue-status",
     "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
                    "queue": 1 }
   }
<- { "return": {
         "signalled-used": 0,
         "inuse": 0,
         "name": "vhost-vsock",
         "vring-align": 4096,
         "vring-desc": 5217370112,
         "signalled-used-valid": false,
         "vring-num-default": 128,
         "vring-avail": 5217372160,
         "queue-index": 1,
         "last-avail-idx": 0,
         "vring-used": 5217372480,
         "used-idx": 0,
         "vring-num": 128
     }
   }

Example:

Get VirtQueueStatus for virtio-serial (no vhost)

-> { "execute": "x-query-virtio-queue-status",
     "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
                    "queue": 20 }
   }
<- { "return": {
         "signalled-used": 0,
         "inuse": 0,
         "name": "virtio-serial",
         "vring-align": 4096,
         "vring-desc": 5182074880,
         "signalled-used-valid": false,
         "vring-num-default": 128,
         "vring-avail": 5182076928,
         "queue-index": 20,
         "last-avail-idx": 0,
         "vring-used": 5182077248,
         "used-idx": 0,
         "shadow-avail-idx": 0,
         "vring-num": 128
     }
   }

🍓 Peep the difference babe: the no-vhost one has shadow-avail-idx, and the vhost one has last-avail-idx. That's the note from up there happening live, we love consistency 👑

⭐ Object `VirtVhostQueueStatus` (Since: 7.2)

Information of a vhost device's vhost_virtqueue, including most members of the vhost_dev vhost_virtqueue data structure ✨

Members:

name (string) — Name of the VirtIODevice that uses this vhost_virtqueue
kick (int) — vhost_virtqueue kick
call (int) — vhost_virtqueue call
num (int) — vhost_virtqueue num
desc-phys (int) — vhost_virtqueue desc_phys (descriptor area physical address)
desc-size (int) — vhost_virtqueue desc_size
avail-phys (int) — vhost_virtqueue avail_phys (driver area physical address)
avail-size (int) — vhost_virtqueue avail_size
used-phys (int) — vhost_virtqueue used_phys (device area physical address)
used-size (int) — vhost_virtqueue used_size

🔥 Command `x-query-virtio-vhost-queue-status` (Since: 7.2)

This command is unstable/experimental. 🙈 Again, debugging-only energy, do not build your whole production pipeline on it bestie.

Return information of a given vhost device's vhost_virtqueue 💜

Arguments:

path (string) — VirtIODevice canonical QOM path
queue (int) — vhost_virtqueue index to examine

Features:

unstable — This command is meant for debugging.

Return VirtVhostQueueStatus — Status of the vhost_virtqueue

Example: Get vhost_virtqueue status for vhost-crypto

-> { "execute": "x-query-virtio-vhost-queue-status",
     "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
                    "queue": 0 }
   }
<- { "return": {
         "avail-phys": 5216124928,
         "name": "virtio-crypto",
         "used-phys": 5216127040,
         "avail-size": 2054,
         "desc-size": 16384,
         "used-size": 8198,
         "num": 1024,
         "call": 0,
         "desc-phys": 5216108544,
         "kick": 0
     }
   }

Example: Get vhost_virtqueue status for vhost-vsock

-> { "execute": "x-query-virtio-vhost-queue-status",
     "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
                    "queue": 0 }
   }
<- { "return": {
         "avail-phys": 5182261248,
         "name": "vhost-vsock",
         "used-phys": 5182261568,
         "avail-size": 262,
         "desc-size": 2048,
         "used-size": 1030,
         "num": 128,
         "call": 0,
         "desc-phys": 5182259200,
         "kick": 0
     }
   }

💀 Not the crypto queue having num of 1024 while vsock is out here with 128. Different sizes for different vibes, both valid, periodt.

🧚 Object `VirtioRingDesc` (Since: 7.2)

Information regarding the vring descriptor area 🎀

Members:

addr (int) — Guest physical address of the descriptor area
len (int) — Length of the descriptor area
flags ([string]) — List of descriptor flags

🌸 Object `VirtioRingAvail` (Since: 7.2)

Information regarding the avail vring (a.k.a. driver area) — yes bestie it's the same thing, two names, iykyk 🫶

Members:

flags (int) — VRingAvail flags
idx (int) — VRingAvail index
ring (int) — VRingAvail ring[] entry at provided index

🎀 Object `VirtioRingUsed` (Since: 7.2)

Information regarding the used vring (a.k.a. device area) — the other half of the ring duo 💫

Members:

flags (int) — VRingUsed flags
idx (int) — VRingUsed index

🌈 Object `VirtioQueueElement` (Since: 7.2)

Information regarding a VirtQueue's VirtQueueElement including descriptor, driver, and device areas 🔥

Main character energy, all three areas in one object — and there's more coming, so stay tuned 👑

name (string) — the name of the VirtIODevice that's using this VirtQueue 🎀
index (int) — which element in the queue we're talking about
descs ([VirtioRingDesc]) — the list of descriptors (VirtioRingDesc), bestie
avail (VirtioRingAvail) — the VRingAvail info
used (VirtioRingUsed) — the VRingUsed info

Command `x-query-virtio-queue-element` (Since: 7.2)

⚠️ Heads up: this command is unstable/experimental. She's still in beta, okay?

Returns the tea on a VirtQueue's VirtQueueElement ✨

Arguments

path (string) — the VirtIODevice canonical QOM path
queue (int) — which VirtQueue index to examine
index (int, optional) — index of the element in the queue (default: the head of the queue, iykyk)

Returns VirtQueueElement

Features

unstable — this command is literally meant for debugging 🫶

Example: Introspect on virtio-net's `VirtQueue` 0 at index 5

-> { "execute": "x-query-virtio-queue-element",
     "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
                    "queue": 0,
                    "index": 5 }
   }
<- { "return": {
         "index": 5,
         "name": "virtio-net",
         "descs": [
             {
                 "flags": ["write"],
                 "len": 1536,
                 "addr": 5257305600
             }
         ],
         "avail": {
             "idx": 256,
             "flags": 0,
             "ring": 5
         },
         "used": {
             "idx": 13,
             "flags": 0
         }
     }
   }

Example: Introspect on virtio-crypto's `VirtQueue` 1 at head

-> { "execute": "x-query-virtio-queue-element",
     "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
                    "queue": 1 }
   }
<- { "return": {
         "index": 0,
         "name": "virtio-crypto",
         "descs": [
             {
                 "flags": [],
                 "len": 0,
                 "addr": 8080268923184214134
             }
         ],
         "avail": {
             "idx": 280,
             "flags": 0,
             "ring": 0
         },
         "used": {
             "idx": 280,
             "flags": 0
         }
     }
   }

Example: Introspect on virtio-scsi's `VirtQueue` 2 at head

-> { "execute": "x-query-virtio-queue-element",
     "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
                    "queue": 2 }
   }
<- { "return": {
         "index": 19,
         "name": "virtio-scsi",
         "descs": [
             {
                 "flags": ["used", "indirect", "write"],
                 "len": 4099327944,
                 "addr": 12055409292258155293
             }
         ],
         "avail": {
             "idx": 1147,
             "flags": 0,
             "ring": 19
         },
         "used": {
             "idx": 280,
             "flags": 0
         }
     }
   }

Object `IOThreadVirtQueueMapping` (Since: 9.0)

Describes which subset of virtqueues got assigned to an IOThread 🧵

Members

iothread (string) — the id of the IOThread object
vqs ([int], optional) — an optional array of virtqueue indices that this IOThread will handle. When it's absent, virtqueues get assigned round-robin across all the IOThreadVirtQueueMappings you provided. And fr fr, either all IOThreadVirtQueueMappings must have vqs or none of them must have it — no mixing, bestie 💅

Object `VirtIOGPUOutput` (Since: 10.1)

Describes the configuration of a VirtIO GPU output 🖥️ Okay so here's the rule: if both xres and yres are set, they take precedence over the root virtio-gpu resolution configuration and enable the corresponding output. If neither xres nor yres are set, the root virtio-gpu resolution configuration takes precedence and only the first output is enabled. And setting only one of xres or yres? That's an error. Periodt 🚫

Members

name (string) — the name of the output
xres (int, optional) — horizontal resolution of the output in pixels (since 11.0)
yres (int, optional) — vertical resolution of the output in pixels (since 11.0)

Object `DummyVirtioForceArrays` (Since: 9.0)

Not used by QMP at all — it's a hack to let us use IOThreadVirtQueueMappingList and VirtIOGPUOutputList internally 🙈

Members

unused-iothread-vq-mapping ([IOThreadVirtQueueMapping]) — Not documented
unused-virtio-gpu-output ([VirtIOGPUOutput]) — Not documented

Enum `GranuleMode` (Since: 9.0)

Values

4k — granule page size of 4KiB
8k — granule page size of 8KiB
16k — granule page size of 16KiB
64k — granule page size of 64KiB
host — granule matches the host page size

Enum `VMAppleVirtioBlkVariant` (Since: 9.2)

Values

unspecified — the default, and not a valid setting (iconic of her honestly)
root — block device holding the root volume
aux — block device holding auxiliary data required for boot

🔥 VFIO DEVICES 🔥

Enum `QapiVfioMigrationState` (Since: 9.1)

An enumeration of the VFIO device migration states ✨ And okay, besides the regular states there are prepare states (with a 'prepare' suffix) which mean the device is just about to transition to the corresponding state. Big caveat though: seeing a prepare state for state X does not guarantee the next state will be X, because the state transition can fail and the device may transition to a different state instead. So don't come for her when it doesn't line up 💀

Values

stop — the device is stopped.
running — the device is running.
stop-copy — the device is stopped and its internal state is available for reading.
resuming — the device is stopped and its internal state is available for writing.
running-p2p — the device is running in the P2P quiescent state.
pre-copy — the device is running, tracking its internal state, and its internal state is available for reading.
pre-copy-p2p — the device is running in the P2P quiescent state, tracking its internal state, and its internal state is available for reading.
pre-copy-p2p-prepare — the device is just about to move to pre-copy-p2p state. (since 11.0)

Event `VFIO_MIGRATION` (Since: 9.1)

This event fires when a VFIO device migration state is changed 📣

Members

device-id (string) — the device's id, if it has one.
qom-path (string) — the device's QOM path.
device-state (QapiVfioMigrationState) — the new changed device migration state.

Example:

<- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 },
     "event": "VFIO_MIGRATION",
     "data": {
         "device-id": "vfio_dev1",
         "qom-path": "/machine/peripheral/vfio_dev1",
         "device-state": "stop" } }

🔐 CRYPTOGRAPHY DEVICES 🔐

Enum `QCryptodevBackendAlgoType` (Since: 8.0)

The supported algorithm types of a crypto device 🧚

Values

sym — symmetric encryption
asym — asymmetric encryption

Enum `QCryptodevBackendServiceType` (Since: 8.0)

The supported service types of a crypto device 💜

Values

cipher — Symmetric Key Cipher service
hash — Hash service
mac — Message Authentication Codes service
aead — Authenticated Encryption with Associated Data service
akcipher — Asymmetric Key Cipher service

Enum `QCryptodevBackendType` (Since: 8.0)

The crypto device backend type 👑

Values

builtin — the QEMU builtin support
vhost-user — vhost-user
lkcf — Linux kernel cryptographic framework

Object `QCryptodevBackendClient` (Since: 8.0)

Info about a queue of a crypto device 🌸

Members

queue (int) — the queue index of the crypto device
type (QCryptodevBackendType) — the type of the crypto device

Object `QCryptodevInfo` (Since: 8.0)

Info about a crypto device ✨

Members

id (string) — the id of the crypto device
service ([QCryptodevBackendServiceType]) — supported service types of a crypto device
client ([QCryptodevBackendClient]) — the additional information of the crypto device

Command `query-cryptodev` (Since: 8.0)

Returns info about the current crypto devices 💖

Returns [QCryptodevInfo]

✨ CXL DEVICES ✨

Okay bestie, this is the CXL part and it is a lot, but we're gonna get through it together, fr fr. 💖

🌸 Enum `CxlEventLog` (Since: 8.1) 🌸

So CXL keeps a bunch of separate event logs for different kinds of events, and each one is handled and signaled all on its own — no mixing, no drama. 🎀

Values

informational — the Information Event Log
warning — the Warning Event Log
failure — the Failure Event Log
fatal — the Fatal Event Log

🌈 Object `CXLCommonEventBase` (Since: 8.1) 🌈

This is the common event base that every CXL Event builds on — straight from CXL r3.2 8.2.10.2.1 Table 8-55, the Common Event Record Format. It's giving "shared foundation" energy. 👑

Members

path (string) — the canonical QOM path of the CXL type 3 device
log (CxlEventLog) — which event log to add the event to
flags (int) — the Event Record Flags. Peep CXL r3.2 Table 8-55 Common Event Record Format, Event Record Flags for all the subfield definitions, iykyk.
maint-op-class (int, optional) — the maintenance operation class the device is asking to initiate
maint-op-subclass (int, optional) — the maintenance operation subclass the device is asking to initiate
ld-id (int, optional) — the Logical Device (LD) ID of the LD where the event came from
head-id (int, optional) — the ID of the device head where the event came from

🦋 Object `CXLGeneralMediaEvent` (Since: 8.1) 🦋

The event record for a General Media Event (CXL r3.2 8.2.10.2.1.1). Slay. 💅

Members

dpa (int) — Device Physical Address (relative to the path device). Heads up bestie, the lower bits include some flags — see CXL r3.2 Table 8-57 General Media Event Record, Physical Address.
descriptor (int) — the Memory Event Descriptor with extra memory event info. See CXL r3.2 Table 8-57 General Media Event Record, Memory Event Descriptor for the bit definitions.
type (int) — the type of memory event that happened. See CXL r3.2 Table 8-57 General Media Event Record, Memory Event Type for the possible values.
transaction-type (int) — the type of the first transaction that caused the event. See CXL r3-2 Table 8-57 General Media Event Record, Transaction Type for the possible values.
channel (int, optional) — the channel of the memory event location. A channel is an interface that can be independently accessed for a transaction.
rank (int, optional) — the rank of the memory event location. A rank is a set of memory devices on a channel that together execute a transaction.
device (int, optional) — a bitmask representing all the devices in the rank associated with the memory event location.
component-id (string, optional) — a device-specific component identifier for the event. It may describe a field replaceable sub-component of the device.
is-comp-id-pldm (boolean, optional) — this flag says whether the device-specific component identifier format follows PLDM.
cme-ev-flags (int, optional) — the advanced programmable corrected memory error threshold event flags.
cme-count (int, optional) — the corrected memory error count at the time of the event.
sub-type (int) — the memory event sub-type.
The members of CXLCommonEventBase.

💜 Command `cxl-inject-general-media-event` (Since: 8.1) 💜

Injects an event record for a General Media Event (CXL r3.2 8.2.10.2.1.1). This event type gets reported through one of the event logs you picked with the log parameter. 🫶

Arguments

The members of CXLGeneralMediaEvent.

🍓 Object `CXLDRAMEvent` (Since: 8.1) 🍓

The event record for a DRAM Event (CXL r3.2 8.2.10.2.1.2). Obsessed with how many fields this has tbh. 😭

Members

dpa (int) — Device Physical Address (relative to the path device). Note that the lower bits include some flags — see CXL r3.2 Table 8-58 DRAM Event Record, Physical Address.
descriptor (int) — the Memory Event Descriptor with extra memory event info. See CXL r3.2 Table 8-58 DRAM Event Record, Memory Event Descriptor for the bit definitions.
type (int) — the type of memory event that happened. See CXL r3.2 Table 8-58 DRAM Event Record, Memory Event Type for the possible values.
transaction-type (int) — the type of the first transaction that caused the event. See CXL r3.2 Table 8-58 DRAM Event Record, Transaction Type for the possible values.
channel (int, optional) — the channel of the memory event location. A channel is an interface that can be independently accessed for a transaction.
rank (int, optional) — the rank of the memory event location. A rank is a set of memory devices on a channel that together execute a transaction.
nibble-mask (int, optional) — identifies one or more nibbles that the error affects.
bank-group (int, optional) — the bank group of the memory event location, which incorporates a number of banks.
bank (int, optional) — the bank of the memory event location. A single bank is accessed per read or write of the memory.
row (int, optional) — the row address within the DRAM.
column (int, optional) — the column address within the DRAM.
correction-mask ([int], optional) — the bits within each nibble. It's used in the order of the bits set in the nibble-mask. Up to 4 nibbles may be covered.
component-id (string, optional) — a device-specific component identifier for the event. It may describe a field replaceable sub-component of the device.
is-comp-id-pldm (boolean, optional) — this flag says whether the device-specific component identifier format follows PLDM.
sub-channel (int, optional) — the sub-channel of the memory event location.
cme-ev-flags (int, optional) — the advanced programmable corrected memory error threshold event flags.
cvme-count (int, optional) — the corrected volatile memory error count at the time of the event.
sub-type (int) — the memory event sub-type.
The members of CXLCommonEventBase.

🧚 Command `cxl-inject-dram-event` (Since: 8.1) 🧚

Injects an event record for a DRAM Event (CXL r3.2 8.2.10.2.1.2). Just like the media one, this event type gets reported through one of the event logs you specified with the log parameter. ✨

Arguments

The members of CXLDRAMEvent.

🔥 Object `CXLMemModuleEvent` (Since: 8.1) 🔥

The event record for a Memory Module Event (CXL r3.2 8.2.10.2.1.3). Main character energy, honestly. 👑

Members

type (int) — the Device Event Type. See CXL r3.2 Table 8-59 Memory Module Event Record for the bit definitions. (Yes, the original says "bit definiions" — we're keeping that typo, it's iconic. 💀)
health-status (int) — the overall health summary bitmap. See CXL r3.2 Table 8-148 Get Health Info Output Payload, Health Status for the bit definitions.
media-status (int) — the overall media health summary. See CXL r3.2 Table 8-148 Get Health Info Output Payload, Media Status for the bit definitions.
additional-status (int) — see CXL r3.2 Table 8-148 Get Health Info Output Payload, Additional Status for the subfield definitions.
life-used (int) — percentage (0-100) of the factory expected life span.
temperature (int) — the device temperature in degrees Celsius.
dirty-shutdown-count (int) — the number of times the device couldn't figure out whether data loss may have occurred.
corrected-volatile-error-count (int) — the total number of correctable errors in volatile memory.
corrected-persistent-error-count (int) — the total number of correctable errors in persistent memory.
component-id (string, optional) — a device-specific component identifier for the event. It may describe a field replaceable sub-component of the device.
is-comp-id-pldm (boolean, optional) — this flag says whether the device-specific component identifier format follows PLDM.
sub-type (int) — the device event sub-type.
The members of CXLCommonEventBase.

💀 Command `cxl-inject-memory-module-event` (Since: 8.1) 💀

Injects an event record for a Memory Module Event (CXL r3.2 8.2.10.2.1.3). Fun fact bestie: this event carries a whole copy of the Device Health info from the exact moment the event went down. Not me being obsessed with the details. 💅

Arguments

The members of CXLMemModuleEvent.

💖 Command `cxl-inject-poison` (Since: 8.1) 💖

So poison records are basically the device going "bestie, this memory region might be corrupted." It might be because of errors it detected locally (like an ECC failure) or because of poisoned writes it received from other components in the system. This injection mechanism lets you test how the OS handles poison records, which you can query through the CXL mailbox. So useful, so iconic. 🌸

Arguments

path (string) — the canonical QOM path of the CXL type 3 device
start (int) — the start address; must be 64 byte aligned.
length (int) — the length of poison to inject; must be a multiple of 64 bytes.

⚠️ Ok so those alignment rules are not a suggestion, alright? start has to be 64 byte aligned and length has to be a multiple of 64 bytes. Do not come for me if you skip that. 😭

⭐ Enum `CxlUncorErrorType` (Since: 8.0) ⭐

The type of uncorrectable CXL error to inject. These errors get reported through an AER uncorrectable internal error, with additional information logged over at the CXL device. 🔥

Values

cache-data-parity — a data error, like a data parity or data ECC error CXL.cache 💅
cache-address-parity — an address parity or other error tied to the address field on CXL.cache
cache-be-parity — a byte enable parity or other byte enable error on CXL.cache
cache-data-ecc — an ECC error on CXL.cache
mem-data-parity — a data error, like a data parity or data ECC error, on CXL.mem
mem-address-parity — an address parity or other error tied to the address field on CXL.mem
mem-be-parity — a byte enable parity or other byte enable error on CXL.mem.
mem-data-ecc — a data ECC error on CXL.mem.
reinit-threshold — the REINIT threshold got hit.
rsvd-encoding — an unrecognized encoding showed up. rsvd = reserved, iykyk 👀
poison-received — poison received from the peer. toxic fr 💀
receiver-overflow — buffer overflows (the first 3 bits of the header log tell you which one 👑)
internal — a component specific error
cxl-ide-tx — integrity and data encryption tx error.
cxl-ide-rx — integrity and data encryption rx error.

🎀 Object `CXLUncorErrorRecord` (Since: 8.0)

A record of one single error, header log included. Like a little receipt for your uncorrectable oopsie 🧾

Members

type (CxlUncorErrorType) — the type of error
header ([int]) — 16 DWORD of header.

✨ Command `cxl-inject-uncorrectable-errors` (Since: 8.0)

A command that lets you inject multiple errors in one go. Why? So you can test how the OS handles multiple header logs, bestie. Very much giving "chaos, but controlled" 🔥

Arguments

path (string) — the CXL Type 3 device canonical QOM path
errors ([CXLUncorErrorRecord]) — the errors to inject

💜 Enum `CxlCorErrorType` (Since: 8.0)

The type of CXL correctable error you're gonna inject. Correctable = it's fine, we fixed it, no drama (allegedly) 🫶

Values

cache-data-ecc — a data ECC error on CXL.cache
mem-data-ecc — a data ECC error on CXL.mem
crc-threshold — component specific, and it only applies to 68 byte Flit mode. no cap.
retry-threshold — retry threshold hit in the Local Retry State Machine, 68B Flits only.
cache-poison-received — poison received from a peer on CXL.cache.
mem-poison-received — poison received from a peer on CXL.mem
physical — an error indication received from the physical layer.

🌸 Command `cxl-inject-correctable-error` (Since: 8.0)

Inject a single correctable error. And ngl, injecting multiple of this error type isn't interesting, because there's no associated header log to go with it — so there's just nothing extra to test. These errors get reported via AER as a correctable internal error, with extra detail available from the CXL device 💖

Arguments

path (string) — the CXL Type 3 device canonical QOM path
type (CxlCorErrorType) — the type of error.

🦋 Object `CxlDynamicCapacityExtent` (Since: 9.1)

One single dynamic capacity extent. It's a contiguous allocation of memory by Device Physical Address, living inside a single Dynamic Capacity Region on a CXL Type 3 Device. Think of it as a little chunk with a home address 🏠

Members

offset (int) — the offset (in bytes) to the start of the region that the extent belongs to.
len (int) — the length of the extent, in bytes.

🌈 Enum `CxlExtentSelectionPolicy` (Since: 9.1)

The policy for picking which extents make up the added capacity — as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-70. Basically: who's in charge of choosing the vibes ✨

Values

free — the device is responsible for allocating the requested memory capacity, and it's free to do that using any combination of supported extents.
contiguous — the device is responsible for allocating the requested memory capacity, but it must do it as a single contiguous extent. no mix-and-match 💅
prescriptive — the precise set of extents to be allocated is specified by the command. So allocation is managed by whoever issued the allocation command, not the device. you're the main character now 👑
enable-shared-access — the capacity has already been allocated to a different host using the free, contiguous or prescriptive policy, with a known tag. This policy then tells the device to make the capacity with the specified tag available to an additional host. The capacity is implicit because it matches what's already associated with the tag. Note that the extent list (and hence the Device Physical Addresses) used is per host, so a device may use different representations on each host. The ordering of the extents given to each host is indicated to the host using per extent sequence numbers generated by the device. It has a similar meaning for temporal sharing, but in that case there may be only one host involved. sharing is caring fr fr 🫶

💫 Command `cxl-add-dynamic-capacity` (Since: 9.1)

⚠️ This command is unstable/experimental.

Kick off adding dynamic capacity extents to a host. It simulates the operations defined in Compute Express Link (CXL) Specification, Revision 3.1, Section 7.6.7.6.5. Heads up though: currently, establishing success or failure of the full Add Dynamic Capacity flow requires out of band communication with the OS of the CXL host. so like, don't expect a text back 😭

Arguments

path (string) — path to the CXL Dynamic Capacity Device in the QOM tree.
host-id (int) — the "Host ID" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-70.
selection-policy (CxlExtentSelectionPolicy) — the "Selection Policy" bits as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-70. It specifies the policy to use for selecting which extents comprise the added capacity.
region (int) — the "Region Number" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-70. Valid range is from 0-7.
tag (string, optional) — the "Tag" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-70.
extents ([CxlDynamicCapacityExtent]) — the "Extent List" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-70.

Features

unstable — for now this command is subject to change. live laugh 🫠

🍓 Enum `CxlExtentRemovalPolicy` (Since: 9.1)

The policy for picking which extents make up the released capacity, defined in the "Flags" field in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-71. it's giving closure 💔

Values

tag-based — extents are selected by the device based on tag, with no requirement for contiguous extents.
prescriptive — the extent list of capacity to release is included in the request payload.

🧚 Command `cxl-release-dynamic-capacity` (Since: 9.1)

⚠️ This command is unstable/experimental.

Kick off the release of dynamic capacity extents from a host. It simulates the operations defined in Compute Express Link (CXL) Specification, Revision 3.1, Section 7.6.7.6.6. And again, currently, establishing success or failure of the full Release Dynamic Capacity flow requires out of band communication with the OS of the CXL host. same deal, bestie 🙈

Arguments

path (string) — path to the CXL Dynamic Capacity Device in the QOM tree.
host-id (int) — the "Host ID" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-71.
removal-policy (CxlExtentRemovalPolicy) — Bit[3:0] of the "Flags" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-71.
forced-removal (boolean, optional) — Bit[4] of the "Flags" field in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-71. When set, the device does not wait for a Release Dynamic Capacity command from the host. Instead, the host immediately looses access to the released capacity. brutal 💀
sanitize-on-release (boolean, optional) — Bit[5] of the "Flags" field in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-71. When set, the device should sanitize all released capacity as a result of this request. This ensures that all user data and metadata is made permanently unavailable by whatever means is appropriate for the media type. Note that changing encryption keys is not sufficient. like, actually gone-gone 🫧
region (int) — the "Region Number" field as defined in Compute Express Link Specification, Revision 3.1, Table 7-71. Valid range is from 0-7.
tag (string, optional) — the "Tag" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-71.
extents ([CxlDynamicCapacityExtent]) — the "Extent List" field as defined in Compute Express Link (CXL) Specification, Revision 3.1, Table 7-71.

Features

unstable — for now this command is subject to change.

🎀 UEFI VARIABLE STORE 🎀

okay so the QEMU efi variable store implementation (that's hw/uefi/ bestie) uses this format to stash non-volatile variables as json on disk. cute, right? ✨

and like — this is already an existing format, no cap, it's supported by (at least) two other projects, specifically https://gitlab.com/kraxel/virt-firmware and https://github.com/awslabs/python-uefivars. so you're not out here inventing a new thing, you're joining a whole ecosystem, iykyk 🦋

🌸 Object UefiVariable (Since: 10.0) 🌸

a UEFI Variable 💖 and fr, go check the UEFI specification if you want the deep lore on all these fields — it's giving required reading.

Members

guid (string) — the variable namespace GUID ✨
name (string) — the variable name, in UTF-8 encoding.
attr (int) — the variable attributes.
data (string) — the variable value, encoded as hex string.
time (string, optional) — the variable modification time. it's an EFI_TIME struct, encoded as hex string. only used for authenticated variables, where the EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS attribute bit is set 🫶
digest (string, optional) — the variable certificate digest. this one's used to verify the signature of updates for authenticated variables. and ok so UEFI has two kinds of authenticated variables, right? the secure boot variables ('PK', 'KEK', 'db' and 'dbx') have hard coded signature checking rules ✨ but for all the other authenticated variables, the firmware stores a digest of the signing certificate at variable creation time, and any updates must be signed with the same certificate 💅

👑 Object UefiVarStore (Since: 10.0) 👑

Members

version (int) — currently always 2. yes queen, always.
variables ([UefiVariable]) — list of UEFI variables 🌈

and that's the whole page bestie!! we did it!! 81 parts, every single flag, every single field, all of it, iconic behaviour honestly 🎀✨ literally the entire QMP reference, consumed, ate, left no crumbs 👑

Copyright 2026, The QEMU Project Developers 💜

so yeah — QEMU-QMP-REF(7), version 11.1.3, dated Oct 29, 2026, from the QEMU 11.1.3 era 🌸 go forth and query your monitors, you absolute main character 🦋💖

📦 where this page comes from

arch rolling: qemu-common 11.1.3-1 · BSD-2-Clause AND BSD-2-Clause-Patent AND BSD-3-Clause AND CC0-1.0 AND FSFAP AND GPL-1.0-or-later AND GPL-2.0-only AND GPL-2.0-only WITH Linux-syscall-note AND GPL-2.0-only WITH Linux-syscall-note OR BSD-2-Clause AND GPL-2.0-only WITH Linux-syscall-note OR BSD-3-Clause AND GPL-2.0-or-later AND GPL-2.0-or-later OR BSD-3-Clause AND GPL-2.0-or-later WITH Linux-syscall-note AND ISC AND LGPL-2.1-only OR BSD-3-Clause AND LGPL-2.0-or-later AND LGPL-2.1-or-later AND LicenseRef-Public-Domain AND MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

QEMU-QMP-REF(7)

🎀 qemu-qmp-ref — QEMU QMP Reference Manual 🎀

✨ INTRODUCTION ✨

🫶 QMP ERRORS 🫶

🌸 Enum QapiErrorClass (Since: 1.2)

🌟 COMMON DATA TYPES 🌟

🦋 Enum IoOperationType (Since: 2.1)

🎀 Enum OnOffAuto (Since: 2.2)

🌼 Enum OnOffSplit (Since: 2.6)

🧚 Alternate StrOrNull (Since: 2.10)

💜 Enum OffAutoPCIBAR (Since: 2.12)

🌈 Enum PCIELinkSpeed (Since: 4.0)

🍓 Enum PCIELinkWidth (Since: 4.0)

🔥 Enum HostMemPolicy (Since: 2.1)

🌸 Enum NetFilterDirection (Since: 2.5)

🦋 Enum GrabToggleKeys (Since: 4.0)

💖 Object HumanReadableText (Since: 6.2)

🌈 Enum EndianMode (Since: 10.0)

🎀 SOCKET DATA TYPES 🎀

Enum NetworkAddressFamily (Since: 2.1)

Object InetSocketAddressBase

Object InetSocketAddress (Since: 1.3)

Object UnixSocketAddress (Since: 1.3)

Object VsockSocketAddress (Since: 2.8)

Object FdSocketAddress (Since: 1.2)

Object InetSocketAddressWrapper (Since: 1.3)

Object UnixSocketAddressWrapper (Since: 1.3)

Object VsockSocketAddressWrapper (Since: 2.8)

Object FdSocketAddressWrapper (Since: 1.3)

Object SocketAddressLegacy (Since: 1.3)

Enum SocketAddressType (Since: 2.9)

Object SocketAddress (Since: 2.9)

🦋 VM RUN STATE 🦋

Enum RunState

Enum ShutdownCause

Object StatusInfo (Since: 0.14)

Command query-status (Since: 0.14)

Event SHUTDOWN (Since: 0.12)

Event POWERDOWN (Since: 0.12) ⚡

Event RESET (Since: 0.12) 🔄

Event STOP (Since: 0.12) 🛑

Event RESUME (Since: 0.12) ▶️

Event SUSPEND (Since: 1.1) 😴

Event SUSPEND_DISK (Since: 1.2) 💾

Event WAKEUP (Since: 1.1) 🌞

Event WATCHDOG (Since: 0.13) 🐕

Enum WatchdogAction (Since: 2.1) 🐾

Enum RebootAction (Since: 6.0) 🔁

Enum ShutdownAction (Since: 6.0) 🚪

Enum PanicAction (Since: 6.0) 😱

Command watchdog-set-action (Since: 2.11) 🐕‍🦺

Command set-action (Since: 6.0) 🎛️

Event GUEST_PANICKED (Since: 1.5) 😵‍💫

Event GUEST_CRASHLOADED (Since: 5.0) 💥

Event GUEST_PVSHUTDOWN (Since: 9.1) 🧚

Enum GuestPanicAction (Since: 2.1) 🫠

Enum GuestPanicInformationType (Since: 2.9) 🧾

Object GuestPanicInformation (Since: 2.9) 📦

Object GuestPanicInformationHyperV (Since: 2.9) 🪟

Enum S390CrashReason (Since: 2.12) 🧊

Object GuestPanicInformationS390 (Since: 2.12) 💥

Object GuestPanicInformationTdx (Since: 10.1) 🛡️

Object GuestPanicInformationSev (Since: 11.0) 🌸

Event MEMORY_FAILURE (Since: 5.2) 💀

Enum MemoryFailureRecipient (Since: 5.2) 🫶

Enum MemoryFailureAction (Since: 5.2) 🔥

Object MemoryFailureFlags (Since: 5.2) 🎀

Enum NotifyVmexitOption (Since: 7.2) 👑

✨ CRYPTOGRAPHY ✨ 🔐

Enum QCryptoTLSCredsEndpoint (Since: 2.5) 🦋

Enum QCryptoSecretFormat (Since: 2.6) 🍓

Enum QCryptoHashAlgo (Since: 2.6) 🌈

Enum QCryptoCipherAlgo (Since: 2.6) 🧚

Enum QCryptoCipherMode (Since: 2.6) 🌀

Enum QCryptoIVGenAlgo (Since: 2.6) 🌟

Enum QCryptoBlockFormat (Since: 2.6) 💖

Object QCryptoBlockOptionsBase (Since: 2.6) 🎀

Object QCryptoBlockOptionsQCow (Since: 2.6) 🦋

Object QCryptoBlockOptionsLUKS (Since: 2.6) 🌸

Object QCryptoBlockCreateOptionsLUKS (Since: 2.6) 🔥

🎀 `qemu-qmp-ref` — QEMU QMP Reference Manual 🎀

🌸 Enum `QapiErrorClass` (Since: 1.2)

🦋 Enum `IoOperationType` (Since: 2.1)

🎀 Enum `OnOffAuto` (Since: 2.2)

🌼 Enum `OnOffSplit` (Since: 2.6)

🧚 Alternate `StrOrNull` (Since: 2.10)

💜 Enum `OffAutoPCIBAR` (Since: 2.12)

🌈 Enum `PCIELinkSpeed` (Since: 4.0)

🍓 Enum `PCIELinkWidth` (Since: 4.0)

🔥 Enum `HostMemPolicy` (Since: 2.1)

🌸 Enum `NetFilterDirection` (Since: 2.5)

🦋 Enum `GrabToggleKeys` (Since: 4.0)

💖 Object `HumanReadableText` (Since: 6.2)

🌈 Enum `EndianMode` (Since: 10.0)

Object `GuestPanicInformationS390` (Since: 2.12) 💥

Object `GuestPanicInformationTdx` (Since: 10.1) 🛡️

Object `GuestPanicInformationSev` (Since: 11.0) 🌸

Event `MEMORY_FAILURE` (Since: 5.2) 💀

Enum `MemoryFailureRecipient` (Since: 5.2) 🫶

Enum `MemoryFailureAction` (Since: 5.2) 🔥

Object `MemoryFailureFlags` (Since: 5.2) 🎀

Enum `NotifyVmexitOption` (Since: 7.2) 👑

Enum `QCryptoTLSCredsEndpoint` (Since: 2.5) 🦋

Enum `QCryptoSecretFormat` (Since: 2.6) 🍓

Enum `QCryptoHashAlgo` (Since: 2.6) 🌈

Enum `QCryptoCipherAlgo` (Since: 2.6) 🧚

Enum `QCryptoCipherMode` (Since: 2.6) 🌀

Enum `QCryptoIVGenAlgo` (Since: 2.6) 🌟

Enum `QCryptoBlockFormat` (Since: 2.6) 💖

Object `QCryptoBlockOptionsBase` (Since: 2.6) 🎀

Object `QCryptoBlockOptionsQCow` (Since: 2.6) 🦋

Object `QCryptoBlockOptionsLUKS` (Since: 2.6) 🌸

Object `QCryptoBlockCreateOptionsLUKS` (Since: 2.6) 🔥

Object `QCryptoBlockOpenOptions` (Since: 2.6) 🫶

Object `QCryptoBlockCreateOptions` (Since: 2.6) ⭐

Object `QCryptoBlockInfoBase` (Since: 2.7)

Object `QCryptoBlockInfoLUKSSlot` (Since: 2.7)

Object `QCryptoBlockInfoLUKS` (Since: 2.7)

Object `QCryptoBlockInfo` (Since: 2.7)

Enum `QCryptoBlockLUKSKeyslotState` (Since: 5.1)

Object `QCryptoBlockAmendOptionsLUKS` (Since: 5.1)

Object `QCryptoBlockAmendOptions` (Since: 5.1)

Object `SecretCommonProperties` (Since: 2.6)

Object `SecretProperties` (Since: 2.6)

Object `SecretKeyringProperties` (Since: 5.1)

Object `TlsCredsProperties` (Since: 2.5)

Object `TlsCredsAnonProperties` (Since: 2.5)

Object `TlsCredsPskProperties` (Since: 3.0)

Object `TlsCredsX509Properties` (Since: 2.5)

Enum `QCryptoAkCipherAlgo` (Since: 7.1)

Enum `QCryptoAkCipherKeyType` (Since: 7.1)

Enum `QCryptoRSAPaddingAlgo` (Since: 7.1)

Object `QCryptoAkCipherOptionsRSA` (Since: 7.1)

Object `QCryptoAkCipherOptions` (Since: 7.1)

🧩 Object `KvmInfo` (Since: 0.14)

🛠️ Command `query-kvm` (Since: 0.14)

🛠️ Command `x-accel-stats` (Since: 10.1)

🔢 Enum `Accelerator` (Since: 10.2.0)

🧩 Object `AcceleratorInfo` (Since: 10.2.0)

🛠️ Command `query-accelerators` (Since: 10.2.0)

🧩 Object `SnapshotInfo` (Since: 1.3)

🧩 Object `ImageInfoSpecificQCow2EncryptionBase` (Since: 2.10)

🧩 Object `ImageInfoSpecificQCow2Encryption` (Since: 2.10)

🧩 Object `ImageInfoSpecificQCow2` (Since: 1.7)

🧩 Object `ImageInfoSpecificVmdk` (Since: 1.7)

🧩 Object `VmdkExtentInfo` (Since: 8.0)

🧩 Object `ImageInfoSpecificRbd` (Since: 6.1)

🧩 Object `ImageInfoSpecificFile` (Since: 8.0)

🔢 Enum `ImageInfoSpecificKind` (Since: 1.7)

🧩 Object `ImageInfoSpecificQCow2Wrapper` (Since: 1.7)

🧩 Object `ImageInfoSpecificVmdkWrapper` (Since: 6.1)

🧩 Object `ImageInfoSpecificLUKSWrapper` (Since: 2.7)

🧩 Object `ImageInfoSpecificRbdWrapper` (Since: 6.1)

🧩 Object `ImageInfoSpecificFileWrapper` (Since: 8.0)

🧩 Object `ImageInfoSpecific` (Since: 1.7)

🧩 Object `BlockLimitsInfo`

🖼️ Object `BlockNodeInfo` (Since: 8.0)

🫶 Object `ImageInfo` (Since: 1.3)

🌸 Object `BlockChildInfo` (Since: 8.0)

🦋 Object `BlockGraphInfo` (Since: 8.0)