QEMU-STORAGE-DAEMON-QMP-REF(7)

💖 qemu-storage-daemon-qmp-ref — the QEMU Storage Daemon QMP Reference Manual 💖

okay so bestie, welcome to the QEMU Storage Daemon QMP Reference Manual — this is the glow-up doc for the QEMU storage daemon QMP, and it's genuinely a lot, so buckle up 🎀

Here's the whole map, literally everything in this thing:

Introduction
Common data types
Socket data types
Cryptography
Background jobs
Block devices
- Block core (VM unrelated)
- Block device exports
Character devices
User authorization
Transactions
QMP monitor control
QMP introspection
QEMU Object Model (QOM)

✨ INTRODUCTION ✨

This manual describes the commands and events supported by the QEMU storage daemon QMP. That's it, that's the whole vibe.

For locating a particular item, please see the QSD Index <>. (iykyk — go look it up, it's right there.)

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. (yes, one long line, no cap — that's just how the protocol likes it 💅)

Please refer to the QEMU Machine Protocol Specification <> for the general format of commands, responses, and events. Like, the whole general format situation lives over there, bestie.

🦋 COMMON DATA TYPES 🦋

Enum `IoOperationType` (Since: 2.1)

An enumeration of the I/O operation types. Just the two, that's the whole menu.

Values

read — read operation
write — write operation

Enum `OnOffAuto` (Since: 2.2)

An enumeration of three options: on, off, and auto. The classic little trio 🎀

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.

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 like, "no string here" is a whole distinct mood from "didn't say anything at all" — very main character of it honestly.

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. Pick your fighter 🌈

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. Go fast, queen ⚡

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 is a vibe too ✨

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 the memory gets to live, basically 🏠

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. Which queue is getting the filter, 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. Pick your keyboard combo, make it iconic ⌨

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)

For when the output is meant to be, you know, read by a human 💖

Members

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

Enum `EndianMode` (Since: 10.0)

Which way the bytes go 🌀

Values

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

💖 SOCKET DATA TYPES 💖

Ok bestie, this whole section is just how we describe addresses. Like, a socket needs to know where it lives, and there are So Many Flavors. Buckle up. 🎀

✨ Enum `NetworkAddressFamily` (Since: 2.1) ✨

It's giving "what kind of address are you, bestie?" — the network address family.

Values

ipv4 — the IPV4 family, classic, iconic, still here
ipv6 — the IPV6 family, the future (allegedly)
unix — unix socket, local vibes only
vsock — vsock family (since 2.8)
unknown — otherwise. literally the "idk her" option 🙈

🌸 Object `InetSocketAddressBase` 🌸

The base-layer glue that the internet-y addresses inherit from, no cap.

Members

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

🦋 Object `InetSocketAddress` (Since: 1.3) 🦋

Captures a socket address or address range in the Internet namespace. Yes, a range. She contains multitudes 💅

Members

numeric (boolean, optional) — true if the host/port are guaranteed to be numeric, false if 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.
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)
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)
The members of InetSocketAddressBase. (yes, she inherits, we love a legacy moment)

Ngl the OpenBSD erasure in those keep-alive notes is sending me 😭 — those three options are TCP-socket-only and defined-option-only, fr fr.

🧚 Object `UnixSocketAddress` (Since: 1.3) 🧚

Captures a socket address in the local ("Unix socket") namespace. Cozy. Local. No internet drama. 🍓

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)

💜 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 like, strings now, options later, iykyk ✨)

🎀 Object `FdSocketAddress` (Since: 1.2) 🎀

A file descriptor name or number. Short king.

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-QMP-misc.getfd> command. Decimal file descriptors are permitted at startup or other contexts where no monitor context is active.

🌈 The Wrapper Objects 🌈

These are literally just little envelopes. One member each. data. That's it. She's a one-trick pony and honestly? Respect. 🫶

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. The name says legacy bestie, you know what that means 👀

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. The vibe check of addresses.

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. She's the glow-up version — notice she pulls the non-wrapper types, main character energy only 💅

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.

🔐 CRYPTOGRAPHY 🔐

Locking things down, bestie. This is the whole vault: TLS creds, secrets, hashes, ciphers, IV generation, and full disk encryption formats. Slay but make it secure. 🧚‍♀️

💅 Enum `QCryptoTLSCredsEndpoint` (Since: 2.5) 💅

The type of network endpoint that will be using the credentials. Most types of credential require different setup / structures depending on whether they will be used in a server versus a client. (like, server you and client you are two different girls, ok?)

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. Pick your girlies carefully ✨

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)

Fr fr: md5 and sha1 are legacy-compat only. Do not put them in any new code. I'm not gonna be nice about that one 😤

🦋 Enum `QCryptoCipherAlgo` (Since: 2.6) 🦋

The supported algorithms for content encryption ciphers. A whole lineup, we stan a diverse cast.

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)

des is right there with a whole "Do not use except in VNC" warning bestie. She's on thin ice 💀

💖 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 (say that five times fast 😭)
ctr — Counter (Since: 2.8)

🎀 Enum `QCryptoIVGenAlgo` (Since: 2.6) 🎀

The supported algorithms for generating initialization vectors for full disk encryption.

Okay this one has an actual warning so pay attention: 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, only if you must, 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. (she's a rescue mission, not a lifestyle 🫶)
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 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 image for metadata only.

Read that twice: key-secret is optional only in the metadata-probing case. Everywhere else she's required, no exceptions, periodt. 💅

🌸 Object `QCryptoBlockOptionsLUKS` (Since: 2.6)

okay so these are 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 you're just probing an image for metadata only — that's the one lil exception, bestie 🫶

✨ Object `QCryptoBlockCreateOptionsLUKS` (Since: 2.6)

the options that apply to LUKS encryption format initialization — aka when you're making a new one, not opening an old one 🎀

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)
plus, obvi, the members of QCryptoBlockOptionsLUKS ⭐

🦋 Object `QCryptoBlockOpenOptions` (Since: 2.6)

the options that are available for all encryption formats when opening an existing volume — it's giving "one interface, many formats" 🙈

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.
When format is qcow: the members of QCryptoBlockOptionsQCow.
When format is luks: the members of QCryptoBlockCreateOptionsLUKS.

🎀 Object `QCryptoBlockInfoBase` (Since: 2.7)

the common info that applies to all full disk encryption formats, no cap 💅

Members

format (QCryptoBlockFormat) — the encryption format

🌈 Object `QCryptoBlockInfoLUKSSlot` (Since: 2.7)

info about the LUKS block encryption key slot options — yes, the slots have lore 🗝️

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)

info about the LUKS block encryption options — the whole glow-up report 🫶

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, the general version 🦋

Members

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

💀 Enum `QCryptoBlockLUKSKeyslotState` (Since: 5.1)

defines the state of keyslots that are affected by the update — pick a lane, slot 💅

Values

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

🔥 Object `QCryptoBlockAmendOptionsLUKS` (Since: 5.1)

this struct defines the update parameters that activate/de-activate a set of keyslots — it's literally the keyslot glow-up/down control panel 🎛️

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, 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 😭 — but it's possible if the 'force' parameter is given. If 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 that are available for all encryption formats when amending encryption settings — the "we're changing things, bestie" bundle 💅

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 — the shared secret lore 🔐

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, babe, not both 🙈

Members

data (string, optional) — the associated with the secret from (yeah that's the whole sentence in the source, slay)
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 edition 👑

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 — the whole TLS vibe check 🌈

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 creds, iconic, no name needed 💅

Members

The members of TlsCredsProperties.

⭐ Object `TlsCredsPskProperties` (Since: 3.0)

properties for tls-creds-psk objects — pre-shared key girlies rise 🗝️

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, but make it cute 🎀

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)

Okay so this enum is the supported algorithms for asymmetric encryption ciphers 💖

Values

rsa — RSA algorithm 👑

Enum `QCryptoAkCipherKeyType` (Since: 7.1)

This one tells you the type of asymmetric keys you're working with, bestie 🔑

Values

public — public key 🌸
private — private key 🙈

Enum `QCryptoRSAPaddingAlgo` (Since: 7.1)

The padding algorithm for RSA — yes, paddings have lore 💅

Values

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

Object `QCryptoAkCipherOptionsRSA` (Since: 7.1)

This object holds the specific parameters for the RSA algorithm 🧚

Members

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

Object `QCryptoAkCipherOptions` (Since: 7.1)

These are the options that are available for all asymmetric key algorithms when creating a new QCryptoAkCipher ✨

Members

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

✨ BACKGROUND JOBS ✨

Enum JobType (Since: 1.7)

The vibe check on what kind of background job we're dealing with, bestie.

Values

commit — block commit job type, see block-commit
stream — block stream job type, see block-stream
mirror — drive mirror job type, see drive-mirror
backup — drive backup job type, see 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 whole character arc of a job, like its present state in its own little lifetime. Every era of the job's existence lives here.

Values

undefined — erroneous, default state. Should not ever be visible. Like fr, if you see this one something went sideways. 💀
created — the job has been created, but not yet started. Baby job, still in the group chat but hasn't said anything yet.
running — the job is currently running. Main character era, it's doing the thing.
paused — the job is running, but paused. The pause may be requested by either the QMP user or by internal processes.
ready — the job is running, but is ready for the user to signal completion. This is used for long-running jobs like mirror that are designed to run indefinitely. So it's basically "i could be done but i'm living here now" energy.
standby — the job is ready, but paused. Nearly identical to paused. The job may return to ready or otherwise be canceled.
waiting — the job is waiting for other jobs in the transaction to converge to the waiting state. This status will likely not be visible for the last job in a transaction. (The last one never has to wait for anyone, iconic.)
pending — the job has finished its work, but has finalization steps that it needs to make prior to completing. These changes will require manual intervention via job-finalize if auto-finalize was set to false. These pending changes may still fail. 🫠
aborting — the job is in the process of being aborted, and will finish with an error. The job will afterwards report that it is concluded. This status may not be visible to the management process.
concluded — the job has finished all work. If auto-dismiss was set to false, the job will remain in this state until it is dismissed via job-dismiss.
null — the job is in the process of being dismantled. This state should not ever be visible externally. We don't talk about this one. 🙈

Enum JobVerb (Since: 2.12)

The list of command verbs that can be applied to a job. Like, all the things you're allowed to say to it.

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 when a job transitions to a different status. It's the job's "not me changing my whole personality rn" moment. ✨

Members

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

Command job-pause (Since: 3.0)

Okay so, this one pauses an active job. 🎀

This command returns immediately after marking the active job for pausing. Pausing an already paused job is an error — yeah, you can't double-pause, that's not a thing.

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. (Little plot twist for you there.)

Arguments

id (string) — the job identifier.

Command job-resume (Since: 3.0)

Resumes a paused job. The "okay come back, i miss you" of commands. 🫶

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

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

Arguments

id (string) — the job identifier.

Command job-cancel (Since: 3.0)

Instructs an active background job to cancel at the next opportunity. This command returns immediately after marking the active job for cancellation. No waiting around, we just leave a note. 💅

The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE event. Usually, the status will change to ABORTING, but it is possible that a job successfully completes (e.g. because it was almost done and there was no opportunity to cancel earlier than completing the job) and transitions to PENDING instead. So like, it might just finish anyway. Noted.

Arguments

id (string) — the job identifier.

Command job-complete (Since: 3.0)

Manually trigger completion of an active job in the READY or STANDBY state. Completing the job in any other state is an error — don't try it, it's not that kind of party.

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.

the command itself will fail;
the error will be processed according to the rerror/werror arguments that were specified when starting the operation.

Arguments

id (string) — the job identifier.

Command job-dismiss (Since: 3.0)

Deletes a job that is in the CONCLUDED state. Goodbye, you did great, go rest. 🦋

This command only needs to be run explicitly for jobs that don't have automatic dismiss enabled. In turn, automatic dismiss may be enabled only for jobs that have 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 these jobs.

This command will refuse to operate on any job that has not yet reached its terminal state, CONCLUDED. For jobs that make use of the JOB_READY event, job-cancel or job-complete will still need to be used as appropriate.

Arguments

id (string) — the job identifier.

Command job-finalize (Since: 3.0)

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

For jobs in a transaction, instructing one job to finalize will force ALL jobs in the transaction to finalize, so it is only necessary to instruct a single member job to finalize. One text, whole group chat shows up. 😭

The command is applicable only to jobs which have 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)

All the tea about a job. ☕

Members

id (string) — the job identifier
type (JobType) — the kind of job that is 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 like, it only ever goes up. Respect.
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. Yeah it can go backwards, don't @ me, that's just how it is.
error (string, optional) —

If this field is present, the job failed; if it is still missing in the CONCLUDED state, this indicates successful completion.

The value is a human-readable error message to describe the reason for the job failure. It should not be parsed by applications. (Read it with your eyes, not your parser. 💅)

Command query-jobs (Since: 3.0)

Return information about jobs. The "so what's everyone up to" command.

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

🌸 BLOCK DEVICES 🌸

Block core (VM unrelated)

Object SnapshotInfo (Since: 1.3)

Members

id (string) — unique snapshot id
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) — yes, literally time travel, we said what we said. ⭐

Object ImageInfoSpecificQCow2EncryptionBase (Since: 2.10)

Members

format (BlockdevQcow2EncryptionFormat) — the encryption format, bestie 💅

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) 🌸

Information about a VMDK extent file, iykyk 🫶

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.

⚠️ Okay so this next bit matters, bestie: 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. No cap. 💀

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. Basically a little pick-your-format situation 💅

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) — Maximum number of scatter/gather elements allowed by the hardware. Applies whenever transfers to the device bypass the kernel I/O scheduler, for example with SG_IO. If not present, the hardware limits is unknown and max-iov is always used.
min-mem-alignment (int) — Minimal required memory alignment in bytes for zero-copy I/O to succeed. For unaligned requests, a bounce buffer will be used.
opt-mem-alignment (int) — Optimal memory alignment in bytes. This is the alignment used for any buffer allocations QEMU performs internally.

Object `BlockNodeInfo` (Since: 8.0) 👑

Information about a QEMU image file ✨

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 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) 🎀

Information about a QEMU image file, and potentially its backing image. The way it can just… have a whole other image behind it 😭

Members

backing-image (ImageInfo, optional) — info of the backing image
The members of BlockNodeInfo.

Object `BlockChildInfo` (Since: 8.0) 🦋

Information about all nodes in the block graph starting at some node, annotated with information about that node in relation to its parent. It's giving family tree but make it block devices 🌸

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)

Okay so this is the full picture of every node in a block (sub)graph, and it comes at you in the form of BlockNodeInfo data. The base BlockNodeInfo struct is holding the info for the (sub)graph's root node, bestie — that's the anchor of the whole thing.

Members 💅

children ([BlockChildInfo]) — array of links to this node's child nodes' information. It's giving family tree, but for block nodes 🫶
The members of BlockNodeInfo. — yep, it inherits all of those too, no cap.

🩺 Object `ImageCheck` (Since: 1.4)

All the tea about a QEMU image file check. Like, what happened when we went poking at that image.

Members ✨

filename (string) — name of the image file checked
format (string) — format of the image file checked
check-errors (int) — number of unexpected errors occurred during 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)

The mapping info that connects a virtual block range to a host file range. Lowkey the translator between two worlds.

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 that 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. Basically the vibe check on how it's caching.

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)

Not me leaving this one without a description — the original literally just gives you the members, so that's what you get, bestie 🙈

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)

Information about the backing device for a block device. Big one incoming, stay with me 🔥

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)
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)

Yeah the drv list really does say 'file' twice in the original and yes we are keeping it, character for character, because that is the assignment 💅

📊 Enum `BlockDeviceIoStatus` (Since: 1.0)

An enumeration of block device I/O status. Just the three moods an I/O operation can be in, honestly.

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 💀

🧼 Object `BlockDirtyInfo` (Since: 1.3)

Block dirty bitmap information. Tracking what's changed, iconic behaviour.

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 got stored improperly 😬. It implies persistent is true, and recording and busy are false. Basically this bitmap is not usable, bestie. To get rid of it, hit it with block-dirty-bitmap-remove. (Since 4.0)

✨ Enum `Qcow2BitmapInfoFlags` (Since: 4.0)

An enumeration of flags that a bitmap can report to you, the user 🫶.

Values

in-use — this flag gets set by any process that's actively modifying the qcow2 file, and it's cleared when the updated bitmap is flushed to the qcow2 image. So if you see this flag on an offline image, that means the bitmap wasn't saved correctly after its last usage 😭 — and it may contain inconsistent data.
auto — the bitmap must reflect all changes of the virtual disk made by any application that would write to this qcow2 file.

🎀 Object `Qcow2BitmapInfo` (Since: 4.0)

Qcow2 bitmap information, iconic.

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. It's giving data visualization 💅.

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 the corresponding histogram looks like:

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

🦋 Object `BlockInfo` (Since: 0.14)

Block device information. This structure describes a virtual device and the backing device associated with it. Main character energy fr fr.

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, and it should not be used (it always returns 'unknown'). Lowkey a fossil, ignore it 💀.
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 🧚.

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 an internal snapshot or further bitmap creation, may require additional space, and that's not covered here 🙈.

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. Slay.

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 time, bestie:

-> { "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)

Statistics of a block device during a given interval of time. Numbers go brrr 📊.

Members

interval_length (int) — interval used for calculating the statistics, in seconds.
min_rd_latency_ns (int) — minimum latency of read operations in the defined interval, in nanoseconds.
min_wr_latency_ns (int) — minimum latency of write operations in the defined interval, in nanoseconds.
min_zone_append_latency_ns (int) — 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 the defined interval, in nanoseconds.
max_rd_latency_ns (int) — 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) — the maximum latency of zone append ops in the defined interval, in nanoseconds (since 8.1) 🦋
max_flush_latency_ns (int) — the max latency of flush ops in the defined interval, in nanoseconds. periodt.
avg_rd_latency_ns (int) — average latency of read ops in the defined interval, nanoseconds bestie.
avg_wr_latency_ns (int) — average latency of write ops in the defined interval, nanoseconds.
avg_zone_append_latency_ns (int) — average latency of zone append ops in the defined interval, in nanoseconds (since 8.1) ✨
avg_flush_latency_ns (int) — average latency of flush ops in the defined interval, nanoseconds.
avg_rd_queue_depth (number) — average number of pending read ops in the defined interval 👑
avg_wr_queue_depth (number) — average number of pending write ops in the defined interval.
avg_zone_append_queue_depth (number) — average number of pending zone append ops in the defined interval (since 8.1). 🫶

🌸 Object `BlockDeviceStats` (Since: 0.14)

Stats of a virtual block device or a block backing device. It's giving "receipts for your disk" 💅

Members

rd_bytes (int) — how many bytes the device read.
wr_bytes (int) — how many bytes the device wrote.
zone_append_bytes (int) — how many bytes the zoned devices appended (since 8.1) 🎀
unmap_bytes (int) — how many bytes the device unmapped (Since 4.2).
rd_operations (int) — number of read operations the device performed.
wr_operations (int) — number of write operations the device performed.
zone_append_operations (int) — number of zone append ops performed by the zoned devices (since 8.1) 🌈
flush_operations (int) — number of cache flush ops the device performed (since 0.15).
unmap_operations (int) — number of unmap ops the device performed (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 ops, in nanoseconds (Since 4.2).
wr_highest_offset (int) — the offset right after the greatest byte ever written to the device. The whole point of this one is growable sparse files (like qcow2) that live on top of a physical device, iykyk.
rd_merged (int) — number of read requests that got merged into another request (Since 2.3).
wr_merged (int) — number of write requests that got merged into another request (Since 2.3).
zone_append_merged (int) — number of zone append requests merged into another request (since 8.1) 🔥
unmap_merged (int) — number of unmap requests merged into another request (Since 4.2).
idle_time_ns (int, optional) — time since the last I/O operation, in nanoseconds. Not me telling you that if this field is absent it means there haven't been any operations yet (Since 2.5). 😭
failed_rd_operations (int) — number of failed read ops the device performed (Since 2.5).
failed_wr_operations (int) — number of failed write ops the device performed (Since 2.5).
failed_zone_append_operations (int) — number of failed zone append write ops performed by the zoned devices (since 8.1) 💀
failed_flush_operations (int) — number of failed flush ops the device performed (Since 2.5).
failed_unmap_operations (int) — number of failed unmap ops the device performed (Since 4.2).
invalid_rd_operations (int) — number of invalid read ops the device performed (Since 2.5).
invalid_wr_operations (int) — number of invalid write ops the device performed (Since 2.5).
invalid_zone_append_operations (int) — number of invalid zone append ops performed by the zoned device (since 8.1) 🙈
invalid_flush_operations (int) — number of invalid flush ops the device performed (Since 2.5).
invalid_unmap_operations (int) — number of invalid unmap ops the device performed (Since 4.2).
account_invalid (boolean) — whether invalid operations get counted in the last access statistics (Since 2.5).
account_failed (boolean) — whether failed operations get counted in the latency and last access statistics (Since 2.5). both, bestie 💅
timed_stats ([BlockDeviceTimedStats]) — statistics specific to the set of previously defined intervals of time (Since 2.5).
rd_latency_histogram (BlockLatencyHistogramInfo, optional) — BlockLatencyHistogramInfo. (Since 4.0)
wr_latency_histogram (BlockLatencyHistogramInfo, optional) — BlockLatencyHistogramInfo. (Since 4.0)
zone_append_latency_histogram (BlockLatencyHistogramInfo, optional) — BlockLatencyHistogramInfo. (since 8.1) ⭐
flush_latency_histogram (BlockLatencyHistogramInfo, optional) — BlockLatencyHistogramInfo. (Since 4.0)

🧚 Object `BlockStatsSpecificFile` (Since: 4.2)

Stats for the file driver. Very "what happens on the filesystem stays on the filesystem" energy 🌸

Members

discard-nb-ok (int) — how many discard operations the driver pulled off successfully.
discard-nb-failed (int) — how many discard operations the driver failed. it happens 😔
discard-bytes-ok (int) — how many bytes the driver discarded.

💜 Object `BlockStatsSpecificNvme` (Since: 5.2)

NVMe driver stats, for the storage girlies who like it fast 🔥

Members

completion-errors (int) — the number of completion errors.
aligned-accesses (int) — the number of aligned accesses the driver performed. slay.
unaligned-accesses (int) — the number of unaligned accesses the driver performed. chaotic but we respect it 💀

🎀 Object `BlockStatsSpecific` (Since: 4.2)

Block driver specific stats — the part where the driver finally gets to be a main character.

Members

driver (BlockdevDriver) — block driver name.
When driver is file: the members of BlockStatsSpecificFile. 👑
When driver is host_device: the members of BlockStatsSpecificFile. (yes, same ones, bestie)
When driver is nvme: the members of BlockStatsSpecificNvme. ✨

🦋 Object `BlockStats` (Since: 0.14)

Statistics of a virtual block device or a block backing device. The full picture, with lore.

Members

device (string, optional) — if the stats are for a virtual block device, this is the name that corresponds to 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 no ID is assigned, the QOM path of the block device. (since 3.0) 🫶
stats (BlockDeviceStats) — a BlockDeviceStats for the device.
driver-specific (BlockStatsSpecific, optional) — optional driver-specific stats. (Since 4.2)
parent (BlockStats, optional) — this describes the file block device if it has one. It recursively contains the statistics of the underlying protocol (e.g. the host file for a qcow2 image) 🎀. If there's no underlying protocol, this field is just... omitted.
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 virtual block devices. Receipts for everyone. 💅

Arguments

query-nodes (boolean, optional) — if true, the command queries all the block nodes that have a node name, in a list that includes "parent" information but not "backing". If false or omitted, the behavior is as before — query all the device backends, recursively including their "parent" and "backing". Nodes that were created implicitly are skipped over in this mode. (Since 2.3) 👑

Return [BlockStats] — a list of statistics for each virtual block device.

Example:

okay so this is what an actual query-blockstats round-trip looks like in the wild — the request goes up, and the whole reply comes back like:

                     -> { "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)

okay so this one is literally the "what do we do when I/O goes wrong" menu 💅 it's an enumeration of possible behaviors for errors on I/O operations, and bestie, the exact meaning depends on whether the I/O was initiated by a guest or by a block job — so keep that in mind, it's giving dual citizenship.

Values

report — for guest operations, report the error to the guest; for jobs, cancel the job
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 continues to stream and will complete with an error.
enospc — same as stop on ENOSPC, same as report otherwise.
stop — for guest operations, stop the virtual machine; for jobs, pause the job
auto — inherit the error handling policy of the backend (since: 2.7)

🦋 Enum MirrorSyncMode (Since: 1.3)

the "what do we copy first" dropdown for the initial synchronization phase of storage mirroring ✨ an enumeration of possible behaviors, and every option hits different.

Values

top — copies data in the topmost image to the destination
full — copies data from all images to the destination
none — only copy data written from now on
incremental — only copy data described by the dirty bitmap. (since: 2.4)
bitmap — only copy data described by the dirty bitmap. Behavior on completion is determined by the BitmapSyncMode. (since: 4.2)

🎀 Enum BitmapSyncMode (Since: 4.2)

so when you're using a bitmap for data copy operations, this enum is the "how do we sync it tho" enum 🫶 possible behaviors, coming right up.

Values

on-success — The bitmap is only synced when the operation is successful. This is the behavior always used for incremental backups.
never — The bitmap is never synchronized with the operation, and is treated solely as a read-only manifest of blocks to copy.
always — The bitmap is always synchronized with the operation, regardless of whether or not the operation was successful.

💅 Enum MirrorCopyMode (Since: 3.0)

an enumeration whose values tell the mirror block job when to trigger writes to the target — like, the timing of it all, iconic honestly.

Values

background — copy data in background only.
write-blocking — when data is written to the source, write it (synchronously) to the target as well. In addition, data is copied in background just like in background mode.

🌟 Object BlockJobInfoMirror (Since: 8.2)

the little extra info packet that's specific to mirror block jobs only 💖 it's a choose-your-own-member situation and there's literally one.

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.

👑 Object BlockJobInfo (Since: 1.1)

the full vibe check on a long-running block device operation — every field you need to know what it's doing and how far along it is 👑

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
len (int) — Estimated offset value at the completion of the job. This value can arbitrarily change while the job is running, in both directions.
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. The value is monotonically increasing.
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.

🔥 Command query-block-jobs (Since: 1.1)

Return information about long-running block device operations — like, "hey what are all my jobs up to rn" 🔥

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

💖 Command block_resize (Since: 0.14)

Resize a block image while a guest is running — live resize, no shutdown era 💖

bestie listen: either device or node-name must be set but not both. Pick a lane, okay? 🙈

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:

(the example JSON is literally right there in the next chunk — stay with me, bestie ✨)

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

...and that's the block_resize example wrapping up, bestie. Back to business 💖

Enum NewImageMode (Since: 1.1)

Okay so this little enum is literally just QEMU's little instruction card for how to set the backing file path inside a brand-new image file. That's it. That's the whole job. 🎀

Values

existing — QEMU should look for an existing image file. Go find it, girly. 🔍
absolute-paths — QEMU should create a new image with absolute paths for the backing file. And if there's no backing file available? Then the new image won't be backed either. No backing, no problem. ✨

Object BlockdevSnapshotSync

Heads up bestie, this one has a rule: either device or node-name must be set but not both. Pick one. Not both. I'm serious. 🫶

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. Very "if it exists, use it" of it. 💅
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)

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 — and like, you can achieve that by passing "backing": null to blockdev-add. Slay. 🌸

Object BackupPerf (Since: 6.0)

Optional parameters for backup. These parameters don't affect functionality — they're purely a performance vibe. But ngl, they may significantly affect performance. So like… pay attention. 🔥

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 glow-up that both backup flavors inherit. 💜

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. Like: all the disk, only the sectors allocated in the topmost image, from a dirty bitmap, or only new I/O. Pick your fighter. ⭐
speed (int, optional) — the maximum speed, in bytes per second. The default is 0, for unlimited.
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. (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)
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 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. It's giving "we're still cooking" 🧚

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. So like, don't blame these two for everything, okay? 😭

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. (Look up, bestie, they're all right there 👑)

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. Syn-chro-nous. It waits. Iconic behavior honestly. 💅

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.

So here's the tea: it takes a snapshot by installing 'node' as the backing image of 'overlay'. And on top of that, if 'node' is associated with a block device, the block device changes to using 'overlay' as its new active image. Main character energy, truly. 🦋

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 a 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. Important caveat bestie, lowkey crucial: 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 you wanna mess with 💅. The device argument gets used to double-check that image-node-name is actually in the chain that device describes — like, no sneaking random nodes in, bestie.
device (string) — the device name, or the node-name of the root node that owns image-node-name.
backing-file (string) — the string that gets written as the backing file. Heads up: this string is not validated 🫣 so be careful what you put here, or the image chain might not be reopenable later. Not a drill.

Errors

If device doesn't exist or can't be determined → DeviceNotFound

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

Live commit of data from overlay image nodes down into backing nodes — like, it literally writes the data between top and base into base. Very "tidying up my room by shoving everything into the closet" energy 🧹✨

If top == base, that's an error, periodt. And if top has no overlays sitting on top of it, or if it's in use by a writer, the job will not finish by itself — you, the user, have to complete it with the job-complete command after you get the ready event. (Since 2.0) 👑

If the base image is smaller than top, then base gets resized to be the same size as top. If top is smaller than base, base does not get truncated. If you want the base image size to match the smaller top, you can safely truncate it yourself once the commit operation has successfully completed — but only then, okay? 🫶

Arguments

job-id (string, optional) — identifier for the newly-created block job. If you omit it, the device name gets used instead. (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 you don't specify it, it's the deepest backing image. (since: 3.1)
base (string, optional) — same as base-node, except it's a file name instead of a node name. This has to be the exact filename string that was used to open the node; other strings — even ones pointing at the same actual file — are not accepted 😤
top-node (string, optional) — the node name of the backing image within the image chain that contains the topmost data to be committed down. If not specified, it's the active layer. (since: 3.1)
top (string, optional) — same as top-node, except it's a file name rather than a node name. Again: this must be the exact filename string used to open the node; other strings, even if they address the same file, are not accepted 🙅‍♀️
backing-file (string, optional) —

The backing file string to write into the overlay image of top. If top doesn't 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 can't be resolved by QEMU, that means any subsequent QMP or HMP commands must use node-names for that image, because filename lookup methods will fail 💀

If you don't specify it, QEMU will automatically figure out the backing file string to use — or error out if there's no obvious choice. So be careful when specifying the string: give a valid filename or protocol. (Since 2.1)

backing-mask-protocol (boolean, optional) — if true, replaces any protocol mentioned in the 'backing file format' with raw, rather than storing the protocol name as the backing format. Works 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 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 you don't give this option, a node name gets autogenerated. (Since: 2.9)
auto-finalize (boolean, optional) — when false, this job waits in a PENDING state after it's finished its work, waiting for job-finalize before making any block graph changes. When true, the job automatically performs its abort or commit actions. Defaults to true. (Since 3.1)
auto-dismiss (boolean, optional) — when false, this job waits in a CONCLUDED state after it has completely ceased all work, and awaits job-dismiss. When true, this job automatically disappears without any user intervention. Defaults to true. (Since 3.1)

Features

deprecated — the base and top members are deprecated 🫠 use base-node and top-node instead.

Errors

If device doesn't exist → DeviceNotFound

Example:

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

⚠️ Command `drive-backup` (Since: 1.6)

🚨 This command is deprecated. Like, fully. Use blockdev-backup instead, bestie.

Start a point-in-time copy of a block device to a new destination. You can check on the status of ongoing drive-backup operations with query-block-jobs, where the BlockJobInfo.type field has the value 'backup' 👀 And you can stop the operation before it finishes using the job-cancel or block-job-cancel command.

Arguments

The members of DriveBackup.

Features

deprecated — This command is deprecated. Use blockdev-backup instead.

Errors

If device isn't 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 shiny non-deprecated one 🌟 Status of ongoing blockdev-backup operations can be checked with query-block-jobs, where the BlockJobInfo.type field has the value 'backup'. And yep, you can stop it before it's done with the job-cancel or block-job-cancel command.

Arguments

The members of BlockdevBackup.

Errors

If device isn't 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 📋 — literally just hands you the list, no cap.

Arguments

flat (boolean, optional) — omit the nested data about the backing image (the "backing-image" key) if true. Default is false (Since 5.0).

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
                                           }
                                        } } ] }

okay so that was the full return payload — look at her, she's gorgeous, she's thorough, she has everything. 🎀

✨ Enum XDbgBlockGraphNodeType (Since: 4.0) ✨

so this one's just a lil tag that says what kinda thing a graph node is 💅

Values

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

🦋 Object XDbgBlockGraphNode (Since: 4.0) 🦋

a single node in the block graph, bestie. like a little dot on the map 🗺️

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. (she's her own main character, no cap)
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 like… don't assume two nodes with the same name are the same node, mmkay? 🙈

💜 Enum BlockPermission (Since: 4.0) 💜

"Enum of base block permissions." — the permission slips of the block world, fr fr 🎫

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. (tl;dr: usually promised, occasionally not — she's honest about it 💀)
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." — it's the line connecting two dots, the situationship between two nodes 😭

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." — the whole friend group, honestly 🫶

Members

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

not documented is so real of them honestly. sometimes the mystery IS the lore.

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

This command is unstable/experimental.

Get the block graph.

Return XDbgBlockGraph

Features

unstable — This command is meant for debugging.

so like… it's a debug tool, it's experimental, it's unstable. use it, love it, but don't build your whole personality on it 💅

👑 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.

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." — the settings menu for your mirroring 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 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). like… the vibes must be a power of two, no exceptions 🧚
buf-size (int, optional) — maximum amount of data in flight from source to target (since 1.4).
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).
unmap (boolean, optional) — Whether to try to unmap target sectors where source has only zero. If true, and target unallocated sectors will read as zero, target image sectors will be unmapped; otherwise, zeroes will be written. Both will result in identical contents. Default is true. (Since 2.4)
copy-mode (MirrorCopyMode, optional) — when to copy data to the destination; defaults to 'background' (Since: 3.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) — bestie, when this is false the job just… sits there in a CONCLUDED state after it's fully finished all its work, vibing and waiting for job-dismiss to come get it. When true, it dips automatically, no user intervention needed. Defaults to true. (Since 3.1)

🌸 Object `BlockDirtyBitmap` (Since: 2.4) 🌸

Members

node (string) — the name of the device/node that this bitmap is out here tracking, periodt
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) — the name of the dirty bitmap (and heads up, 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, like it's saved to the corresponding block device image file when it closes. For now only Qcow2 disks support persistent bitmaps, iykyk. Default is false for block-dirty-bitmap-add. ⚠️ This fails if the node is read-only or inactive, because such a bitmap could never be stored — it's giving "no thoughts, no storage".
disabled (boolean, optional) — the bitmap gets created in the disabled state, meaning it will not 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 a specified node

🦋 Object `BlockDirtyBitmapMerge` (Since: 4.0) 🦋

Members

node (string) — name of the device/node that 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. The latter 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 behavior fr.

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 — like fully clearing it out, no leftovers. 🧹

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 backup clusters modified after this clear operation. Like a fresh start, a glow-up for your bitmap. ✨

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 that it will begin tracking disk changes. Wake up babe, the bitmap is back on duty. 💅

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 that it will stop tracking disk changes. It's taking a little nap, respect it. 😴

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. Dirty bitmaps in bitmaps will be unchanged — except if one of them also appears 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 cap. 🫡

The resulting bitmap will count as dirty any clusters that were dirty in any of the source bitmaps. This can be used to achieve backup checkpoints, or, in simpler usages, to copy bitmaps. Iconic multitasking tbh.

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. Very "I hashed it for science" energy.

Members

sha256 (string) — ASCII representation of the SHA256 bitmap hash

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

⚠️ This command is unstable/experimental. Like, handle with care bestie.

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. It's giving "copy me but make it live". 🪞

Arguments

job-id (string, optional) — identifier for the newly-created block job. If you omit it, the device name gets used instead. (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 the 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. This can be used to repair broken Quorum files, which is lowkey iconic. 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, else the cluster size. Must be a power of 2 between 512 and 64M.
buf-size (int, optional) — maximum amount of data in flight from source to target
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)
filter-node-name (string, optional) — the node name that should be assigned to the filter driver that the mirror job inserts into the graph above device. If this option is not given, a node name is autogenerated. (Since: 2.9)
copy-mode (MirrorCopyMode, optional) — when to copy data to the destination; defaults to 'background' (Since: 3.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) — so when you set this to false, the job just… sits there in a CONCLUDED state once it's fully done with all its work, lowkey waiting for you to come dismiss it with job-dismiss. Set it to true and the job dips out on its own, no user intervention needed. Defaults to true. (Since 3.1) ✨
target-is-zero (boolean, optional) — tells QEMU to assume the destination already reads as all zeroes before the mirror even started. Flipping this to true can speed up the mirror, bestie. But ⚠️ if the destination is not actually all zero, setting this to true can corrupt the destination — no cap, that's the whole warning. (Since 10.1)

Example:

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

🎀 Object BlockIOThrottle (Since: 1.1)

A whole little bundle of parameters that describes block throttling. It's giving "how hard am I allowed to yeet I/O at this thing" energy.

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) — the maximum length of the bps_max burst period, in seconds. Heads up: you can only set this if bps_max is set as well. Defaults to 1. (Since 2.6)
bps_rd_max_length (int, optional) — the maximum length of the bps_rd_max burst period, in seconds. Only set it if bps_rd_max is set as well. Defaults to 1. (Since 2.6)
bps_wr_max_length (int, optional) — the maximum length of the bps_wr_max burst period, in seconds. Only set it if bps_wr_max is set as well. Defaults to 1. (Since 2.6)
iops_max_length (int, optional) — the maximum length of the iops burst period, in seconds. Only set it if iops_max is set as well. Defaults to 1. (Since 2.6)
iops_rd_max_length (int, optional) — the maximum length of the iops_rd_max burst period, in seconds. Only set it if iops_rd_max is set as well. Defaults to 1. (Since 2.6)
iops_wr_max_length (int, optional) — the maximum length of the iops_wr_max burst period, in seconds. Only set it 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, fr fr.

🦋 Object ThrottleLimits (Since: 2.11)

Limit parameters for throttling. Okay so real talk: some limit combos are just straight-up illegal, so limits should always be set in one transaction — don't be out here setting them one at a time. Every single field is optional, and when you're setting limits, if a field is missing, its current value stays exactly as it is (no sneaky resets). 🫶

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, the max size of an I/O in bytes

🌈 Object ThrottleGroupProperties (Since: 2.11)

Properties for throttle-group objects. Slay, very demure, very mindful.

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 — okay bestie, listen: all members starting with x- are just aliases for the same key without the x-, over in the limits object. This is not a stable interface and it may be removed or changed incompatibly in the future 😭. Use limits if you want a supported, stable interface. Periodt.

💅 Command block-stream (Since: 1.1)

Copy data from a backing file into a block device. Iconic behaviour, honestly.

The block streaming operation runs in the background until the entire backing file has been copied. The command returns immediately once streaming has started — it does not wait around for the whole thing like some clingy main character. You can check the status of ongoing block streaming operations with query-block-jobs. And if you wanna stop it before it's finished, that's what job-cancel or block-job-cancel are for. 🎀

The node that receives the data is called the top image. It can live in any part of the chain (but always above the base image — see below), and you can name it with its device or node name. Earlier QEMU versions only let device name the top level node; if you spot the base-node parameter during introspection, that's your witness that you've got the enhanced semantics of device. ✨

If a base file is specified, then sectors are not copied from that base file and its backing chain. That's the whole point, actually — it lets 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 got 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. Noted, bestie.

Arguments

job-id (string, optional) — the identifier for the brand-new block job ✨ if you don't give one, the device name gets used instead. (Since 2.7)
- device (string) — the device name or node name of the top image 💅
- base (string, optional) — the common backing file name. Heads up: you literally cannot set this if base-node or bottom is also set 🙅
- base-node (string, optional) — the node name of the backing file. Also can't be set if base or bottom is set. (Since 2.8)
- bottom (string, optional) — the last node in the chain that should be streamed into top. Nope, can't set this if base or base-node is set either. And it cannot be a filter node. (Since 6.0)
- backing-file (string, optional) — okay so this one's got lore:

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, because 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 isn't 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's 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:

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

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

Set the maximum speed for a background block operation 🔥

This command can only be issued when there is an active block job, so don't come at it with nothing running.

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. iykyk 💫
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's an error to call this command if no operation is in progress, bestie. No notes.

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, so don't spam it.

Cancelling a paused job automatically resumes it. Slay.

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. Iconic behaviour, honestly.

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, no cap.

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. Note that if an I/O error occurs during the processing of this command: 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 😭

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-complete instead 👑

Errors

If no background operation is active on this device, DeviceNotActive

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

⚠️ This command is deprecated.

Deletes a job that is in the CONCLUDED state 🗑️ this command only needs to be run explicitly for jobs that don't have automatic dismiss enabled. In turn, automatic dismiss may be enabled only 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 these jobs 💖

This command will refuse to operate on any job that has not yet reached its terminal state, CONCLUDED. For jobs that make use of the BLOCK_JOB_READY event, job-cancel, block-job-cancel or job-complete will still need to be used as appropriate.

Arguments

id (string) — the job identifier.

Features

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

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

⚠️ This command is deprecated.

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

For jobs in a transaction, instructing one job to finalize will force ALL jobs in the transaction to finalize, so it is only necessary to instruct a single member job to finalize.

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. (yes bestie, it's giving legacy energy, switch already 🙈)

🦋 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. (literally just the one glow-up so far ✨)

👑 Object `BlockJobChangeOptions` (Since: 8.2)

Block job options that can be changed after job creation. (post-launch edits, iykyk 💅)

Members

id (string) — the job identifier
type (JobType) — the job type
When type is mirror: the members of BlockJobChangeOptionsMirror. (so it's giving "depends on your type" main character energy 🌈)

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

Change the block job's options. (a little post-creation remix, no cap)

Arguments

The members of BlockJobChangeOptions.

🎀 Enum `BlockdevDiscardOptions` (Since: 2.9)

Determines how to handle discard requests. (aka: what even happens when something says "throw this away" 🤔)

Values

ignore — ignore the request (respectfully, no thank you ✋)
unmap — forward as an unmap request (okay go off, tell the next layer 🫶)

🌸 Enum `BlockdevDetectZeroesOptions` (Since: 2.1)

Describes the operation mode for the automatic conversion of plain zero writes by the OS to driver specific optimized zero write commands. (turning boring zero-writes into ✨optimized✨ zero-writes)

Values

off — disabled (default)
on — enabled
unmap — enabled and even try to unmap blocks if possible. This requires also that BlockdevDiscardOptions is set to unmap for this device. (so slay but read the fine print bestie 💀)

⭐ Enum `BlockdevAioOptions` (Since: 2.9)

Selects the AIO backend to handle I/O requests. (picking your fave worker, they all different vibes)

Values

threads — use QEMU's thread pool
native — use 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 caching corner of the group chat 🧚)

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. (the whole roster, fr fr 👑)

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

The "not documented" girlies are all valid values too, they're just mysterious. Don't come for me, I'm only relaying what the page says 💀

🍓 Object `BlockdevOptionsFile` (Since: 2.9)

Driver specific block device options for the file backend. (the classic, the blueprint, the file-on-your-disk icon 🎀)

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)

Features

dynamic-auto-read-only — if present, enabled auto-read-only means that 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. (so it's giving "permissions on demand", very considerate of it 🫶)
unstable — member x-check-cache-dropped is meant for debugging. (debug-only, do NOT ship it, bestie 😭)

🧚 Object `BlockdevOptionsNull` (Since: 2.9)

Driver specific block device options for the null backend. (the void, the nothing, the /dev/null of it all)

Members

size (int, optional) — size of the device in bytes.
latency-ns (int, optional) — emulated latency (in nanoseconds) in processing requests. Default 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.

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.

Note that the PCI device must have been unbound from any host kernel driver before instructing QEMU to add the blockdev.

Fr fr, unbind it first. QEMU can't just snatch a device that some kernel driver is already holding hands with 🙈

🌸 Object `BlockdevOptionsVVFAT` (Since: 2.9)

Driver specific block device options for the vvfat protocol.

Members

dir (string) — directory to be exported as FAT image
fat-type (int, optional) — FAT type: 12, 16 or 32
floppy (boolean, optional) — whether to export a floppy image (true) or partitioned hard disk (false; default)
label (string, optional) — set the volume label, limited to 11 bytes. FAT16 and FAT32 traditionally have some restrictions on labels, which are ignored by most operating systems. Defaults to "QEMU VVFAT". (since 2.4)
rw (boolean, optional) — whether to allow write operations (default: false)

🦋 Object `BlockdevOptionsGenericFormat` (Since: 2.9)

Driver specific block device options for image format that have no option besides their data source. (minimalist queen, only has her source and her vibes ✨)

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. (encrypted, mysterious, locked-down icon behavior 🔥)

Members

key-secret (string, optional) — the ID of a QCryptoSecret object providing the decryption key. Mandatory except when doing a metadata-only probe of the image. (since 2.6)
header (BlockdevRef, optional) — block device holding a detached LUKS header. (since 9.0)
The members of BlockdevOptionsGenericFormat. (yes, they come too, package deal 💖)

🎀 Object `BlockdevOptionsGenericCOWFormat` (Since: 2.9)

Driver specific block device options for image format that have no option besides their data source and an optional backing file. (the COW girlies, copy-on-write and thriving 🐄✨)

Members

backing (BlockdevRefOrNull, optional) — a reference to, or a whole inline definition of, the backing file block device. Setting it to null kills the backing file completely, no backing file, none, gone 💀. If you don't say anything, it defaults to the backing file stored in the image file.
plus everything from BlockdevOptionsGenericFormat 🫶

🌸 Enum `Qcow2OverlapCheckMode` (Since: 2.9) 🌸

The general vibe check modes for overlap checking ✨

Values

none — do literally no checks, live your truth 🙈
constant — only run the checks that can be done in constant time and without reading anything from disk
cached — only run checks that can be done without reading anything from disk
all — run every single check available 👑

🎀 Object `Qcow2OverlapCheckFlags` (Since: 2.9) 🎀

This is the flags struct for each metadata structure. Set a field to true and QEMU will guard that Qcow2 format structure against unintended overwriting 🛡️. For the detailed lore on these structures, go check the Qcow2 format specification — it's all there, iykyk. The default value gets picked according to the template you give it.

Members

template (Qcow2OverlapCheckMode, optional) — picks a template mode that you can then tweak 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 👀

Alternatives

flags (Qcow2OverlapCheckFlags) — a set of flags so you can specify each metadata structure type separately, one by one, very main character energy
mode (Qcow2OverlapCheckMode) — a named mode that just 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, bestie.

Members

encrypt (BlockdevQcowEncryption, optional) — image decryption options. This one's mandatory for encrypted images — except when you're just 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 💀

🧚 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 and doing preallocation in the protocol node on write ✍️

Members

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

👑 Object `BlockdevOptionsQcow2` (Since: 2.9) 👑

Driver-specific block device options for qcow2 — this is the big one, buckle up bestie 🎢

Members

lazy-refcounts (boolean, optional) — whether to enable the lazy refcounts feature. The default is taken from the image file, so the image kinda decides for you.
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 (e.g. 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 even when they're no longer used, e.g. because they got discarded or converted to zero clusters. As usual, whether the old data is actually discarded or kept at the protocol level (i.e. in the image file) depends on how you set the pass-discard-request option. Keeping the clusters preallocated prevents qcow2 fragmentation that would otherwise happen from freeing and re-allocating them later. And heads up: besides potential performance degradation, that kind of fragmentation can lead to increased allocation of clusters past the end of the image file, which means image files whose file length can grow much larger than their guest disk size would suggest 😭. If image file length is something you care about (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. 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) — clean unused entries in the L2 and refcount caches. The interval is in seconds. 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) — a reference to, or definition of, the external data file. This may only be specified for images that require an external data file. If you don't specify it for such an image, the data file name gets 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, yolo 🙈
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 given hash is an sha1 hash
sha256 — the given hash is an sha256 hash

✨ Object `SshHostKeyHash` (Since: 2.12) ✨

Members

type (SshHostKeyCheckHashType) — the hash algorithm used for the hash
hash (string) — the expected hash value

💅 Object `SshHostKeyCheck` (Since: 2.12) 💅

Members

mode (SshHostKeyCheckMode) — how to check the host key
when mode is hash: the members of SshHostKeyHash 🔑

🦋 Object `BlockdevOptionsSsh` (Since: 2.9) 🦋

Members

server (InetSocketAddress) — host address
path (string) — path to the image on the host
user (string, optional) — the user to connect as. Defaults to the current local user name.
host-key-check (SshHostKeyCheck, optional) — defines how and what to check the host key against. Default: known_hosts.

💀 Enum `BlkdebugEvent` (Since: 2.9) 💀

The trigger events blkdebug supports 🎯

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 due to copy-on-read (since 2.11)
cluster_alloc_space — an allocation of file space for a cluster (since 4.1)
none — triggers once at 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 🙈 (bestie, they really just left us on read)
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 💀
pwritev_done — Not documented 💀
empty_image_prepare — Not documented 🫶

okay that's the whole "Not documented" era of the list, we made it through together ✨

🎀 Enum `BlkdebugIOType` (Since: 4.1)

The different flavors of I/O that blkdebug is allowed to inject errors into. It's giving "let me ruin your day, but, like, on purpose and in a very specific way" 💅

Values

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

🌸 Object `BlkdebugInjectErrorOptions` (Since: 2.9)

Describes exactly one error injection for blkdebug. One error, fully described, very much main character energy 👑

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) — the type of I/O operations 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) — the sector index that has to be affected for the event to actually trigger; defaults to "any sector"
once (boolean, optional) — turns off further events after this one has fired; defaults to false
immediately (boolean, optional) — fail immediately; defaults to false

💜 Object `BlkdebugSetStateOptions` (Since: 2.9)

Describes a single state-change event for blkdebug. Glow-up, but for state machines ✨

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 once this event is triggered

🦋 Object `BlockdevOptionsBlkdebug` (Since: 2.9)

Driver-specific block device options for blkdebug. This is the whole menu, bestie, every flag on it 🍓

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 the 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 (it does not have to be a power of 2), or 0 for the 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 (doesn't need to be a power of 2), or 0 for the default (since 2.10)
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 (power of 2 not required), or 0 for the 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 (again, no power-of-2 requirement), or 0 for the 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 (still not required to be a power of 2), or 0 for the 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 is necessary anyway (which depends on how the blkdebug node is used). Defaults to none. (since 5.0)
unshare-child-perms ([BlockPermission], optional) — permissions not to share on image, on top of whatever cannot be shared anyway (which depends on how the blkdebug node is used). Defaults to none. (since 5.0)

🌈 Object `BlockdevOptionsBlklogwrites` (Since: 3.0)

Driver-specific block device options for blklogwrites. Logging your writes like a little 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; this decides the granularity of the offsets and sizes of writes (default: 512)
log-append (boolean, optional) — append to an existing log (default: false)
log-super-update-interval (int, optional) — interval of write requests after which the log super block gets updated to disk (default: 4096)

⭐ Object `BlockdevOptionsBlkverify` (Since: 2.9)

Driver-specific block device options for blkverify. Trust but verify, bestie 👀

Members

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

🧚 Object `BlockdevOptionsBlkreplay` (Since: 4.2)

Driver-specific block device options for blkreplay.

Members

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

🎀 Enum `QuorumReadPattern` (Since: 2.9)

An enumeration of quorum read patterns. Democracy, but for reads 🗳️

Values

quorum — read all the children and do a quorum vote on reads
fifo — read only from the first child that has not failed

👑 Object `BlockdevOptionsQuorum` (Since: 2.9)

Driver-specific block device options for Quorum 🫶

Members

blkverify (boolean, optional) — true if the driver must print content mismatch; set to false by default
children ([BlockdevRef]) — the children block devices to use
vote-threshold (int) — the vote limit under which a read will fail
rewrite-corrupted (boolean, optional) — rewrite corrupted data when quorum is reached (Since 2.1)
read-pattern (QuorumReadPattern, optional) — choose the read pattern; set to quorum by default (Since 2.2)