type: SheepdogRedundancyType
Not documented
SheepdogRedundancyFull
when type
is "full"SheepdogRedundancyErasureCoded
when type
is "erasure-coded"Since: 2.12
Driver specific image creation options for Sheepdog.
Members:
location: BlockdevOptionsSheepdog
Where to store the new image file
size: int
Size of the virtual disk in bytes
backing-file: string
(optional)File name of a base image
preallocation: PreallocMode
(optional)Preallocation mode for the new image (default: off; allowed values: off, full)
redundancy: SheepdogRedundancy
(optional)Redundancy of the image
object-size: int
(optional)Object size of the image
Since: 2.12
Driver specific image creation options for SSH.
Members:
location: BlockdevOptionsSsh
Where to store the new image file
size: int
Size of the virtual disk in bytes
Since: 2.12
Driver specific image creation options for VDI.
Members:
file: BlockdevRef
Node to create the image format on
size: int
Size of the virtual disk in bytes
preallocation: PreallocMode
(optional)Preallocation mode for the new image (default: off; allowed values: off, metadata)
Since: 2.12
Values:
dynamic
Growing image file
fixed
Preallocated fixed-size image file
Since: 2.12
Driver specific image creation options for vhdx.
Members:
file: BlockdevRef
Node to create the image format on
size: int
Size of the virtual disk in bytes
log-size: int
(optional)Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
block-size: int
(optional)Block size in bytes, must be a multiple of 1 MB and not larger than 256 MB (default: automatically choose a block size depending on the image size)
subformat: BlockdevVhdxSubformat
(optional)vhdx subformat (default: dynamic)
block-state-zero: boolean
(optional)Force use of payload blocks of type ’ZERO’. Non-standard, but default. Do not set to ’off’ when using ’qemu-img convert’ with subformat=dynamic.
Since: 2.12
Values:
dynamic
Growing image file
fixed
Preallocated fixed-size image file
Since: 2.12
Driver specific image creation options for vpc (VHD).
Members:
file: BlockdevRef
Node to create the image format on
size: int
Size of the virtual disk in bytes
subformat: BlockdevVpcSubformat
(optional)vhdx subformat (default: dynamic)
force-size: boolean
(optional)Force use of the exact byte size instead of rounding to the next size that can be represented in CHS geometry (default: false)
Since: 2.12
Options for creating an image format on a given node.
Members:
driver: BlockdevDriver
block driver to create the image format
BlockdevCreateOptionsFile
when driver
is "file"BlockdevCreateOptionsGluster
when driver
is "gluster"BlockdevCreateOptionsLUKS
when driver
is "luks"BlockdevCreateOptionsNfs
when driver
is "nfs"BlockdevCreateOptionsParallels
when driver
is "parallels"BlockdevCreateOptionsQcow
when driver
is "qcow"BlockdevCreateOptionsQcow2
when driver
is "qcow2"BlockdevCreateOptionsQed
when driver
is "qed"BlockdevCreateOptionsRbd
when driver
is "rbd"BlockdevCreateOptionsSheepdog
when driver
is "sheepdog"BlockdevCreateOptionsSsh
when driver
is "ssh"BlockdevCreateOptionsVdi
when driver
is "vdi"BlockdevCreateOptionsVhdx
when driver
is "vhdx"BlockdevCreateOptionsVmdk
when driver
is "vmdk"BlockdevCreateOptionsVpc
when driver
is "vpc"Since: 2.12
Starts a job to create an image format on a given node. The job is automatically finalized, but a manual job-dismiss is required.
Arguments:
job-id: string
Identifier for the newly created job.
options: BlockdevCreateOptions
Options for the image creation.
Since: 3.0
Driver specific image amend options for LUKS.
Members:
QCryptoBlockAmendOptionsLUKS
Since: 5.1
Driver specific image amend options for qcow2. For now, only encryption options can be amended
encrypt
Encryption options to be amended
Members:
encrypt: QCryptoBlockAmendOptions
(optional)Not documented
Since: 5.1
Options for amending an image format
Members:
driver: BlockdevDriver
Block driver of the node to amend.
BlockdevAmendOptionsLUKS
when driver
is "luks"BlockdevAmendOptionsQcow2
when driver
is "qcow2"Since: 5.1
Starts a job to amend format specific options of an existing open block device The job is automatically finalized, but a manual job-dismiss is required.
Arguments:
job-id: string
Identifier for the newly created job.
node-name: string
Name of the block node to work on
options: BlockdevAmendOptions
Options (driver specific)
force: boolean
(optional)Allow unsafe operations, format specific For luks that allows erase of the last active keyslot (permanent loss of data), and replacement of an active keyslot (possible loss of data if IO error happens)
Since: 5.1
An enumeration of action that has been taken when a DISK I/O occurs
Values:
ignore
error has been ignored
report
error has been reported to the device
stop
error caused VM to be stopped
Since: 2.1
Emitted when a disk image is being marked corrupt. The image can be identified by its device or node name. The ’device’ field is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated.
Arguments:
device: string
device name. This is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated.
node-name: string
(optional)node name (Since: 2.4)
msg: string
informative message for human consumption, such as the kind of corruption being detected. It should not be parsed by machine as it is not guaranteed to be stable
offset: int
(optional)if the corruption resulted from an image access, this is the host’s access offset into the image
size: int
(optional)if the corruption resulted from an image access, this is the access size
fatal: boolean
if set, the image is marked corrupt and therefore unusable after this event and must be repaired (Since 2.2; before, every BLOCK_IMAGE_CORRUPTED event was fatal)
Note: If action is "stop", a STOP event will eventually follow the BLOCK_IO_ERROR event.
Example:
<- { "event": "BLOCK_IMAGE_CORRUPTED", "data": { "device": "ide0-hd0", "node-name": "node0", "msg": "Prevented active L1 table overwrite", "offset": 196608, "size": 65536 }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 966463 } }
Since: 1.7
Emitted when a disk I/O error occurs
Arguments:
device: string
device name. This is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated.
node-name: string
(optional)node name. Note that errors may be reported for the root node that is directly attached to a guest device rather than for the node where the error occurred. The node name is not present if the drive is empty. (Since: 2.8)
operation: IoOperationType
I/O operation
action: BlockErrorAction
action that has been taken
nospace: boolean
(optional)true if I/O error was caused due to a no-space condition. This key is only present if query-block’s io-status is present, please see query-block documentation for more information (since: 2.2)
reason: string
human readable string describing the error cause. (This field is a debugging aid for humans, it should not be parsed by applications) (since: 2.2)
Note: If action is "stop", a STOP event will eventually follow the BLOCK_IO_ERROR event
Since: 0.13.0
Example:
<- { "event": "BLOCK_IO_ERROR", "data": { "device": "ide0-hd1", "node-name": "#block212", "operation": "write", "action": "stop" }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 450486 } }
Emitted when a block job has completed
Arguments:
type: JobType
job type
device: string
The job identifier. Originally the device name but other values are allowed since QEMU 2.7
len: int
maximum progress value
offset: int
current progress value. On success this is equal to len. On failure this is less than len
speed: int
rate limit, bytes per second
error: string
(optional)error message. Only present on failure. This field contains a human-readable error message. There are no semantics other than that streaming has failed and clients should not try to interpret the error string
Since: 1.1
Example:
<- { "event": "BLOCK_JOB_COMPLETED", "data": { "type": "stream", "device": "virtio-disk0", "len":<PHONE_NUMBER>0, "offset":<PHONE_NUMBER>0, "speed": 0 }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 959568 } }
Emitted when a block job has been cancelled
Arguments:
type: JobType
job type
device: string
The job identifier. Originally the device name but other values are allowed since QEMU 2.7
len: int
maximum progress value
offset: int
current progress value. On success this is equal to len. On failure this is less than len
speed: int
rate limit, bytes per second
Since: 1.1
Example:
<- { "event": "BLOCK_JOB_CANCELLED", "data": { "type": "stream", "device": "virtio-disk0", "len":<PHONE_NUMBER>0, "offset": 134217728, "speed": 0 }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 959568 } }
Emitted when a block job encounters an error
Arguments:
device: string
The job identifier. Originally the device name but other values are allowed since QEMU 2.7
operation: IoOperationType
I/O operation
action: BlockErrorAction
action that has been taken
Since: 1.3
Example:
<- { "event": "BLOCK_JOB_ERROR", "data": { "device": "ide0-hd1", "operation": "write", "action": "stop" }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 450486 } }
Emitted when a block job is ready to complete
Arguments:
type: JobType
job type
device: string
The job identifier. Originally the device name but other values are allowed since QEMU 2.7
len: int
maximum progress value
offset: int
current progress value. On success this is equal to len. On failure this is less than len
speed: int
rate limit, bytes per second
Note:
The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
event
Since: 1.3
Example:
<- { "event": "BLOCK_JOB_READY", "data": { "device": "drive0", "type": "mirror", "speed": 0, "len": 2097152, "offset": 2097152 } "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 450486 } }
Emitted when a block job is awaiting explicit authorization to finalize graph
changes via block-job-finalize
. If this job is part of a transaction, it will
not emit this event until the transaction has converged first.
Arguments:
type: JobType
job type
id: string
The job identifier.
Since: 2.12
Example:
<- { "event": "BLOCK_JOB_WAITING", "data": { "device": "drive0", "type": "mirror" }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 450486 } }
Preallocation mode of QEMU image file
Values:
off
no preallocation
metadata
preallocate only for metadata
falloc
like full
preallocation but allocate disk space by
posix_fallocate() rather than writing data.
full
preallocate all data by writing it to the device to ensure
disk space is really available. This data may or may not be
zero, depending on the image format and storage.
full
preallocation also sets up metadata correctly.
Since: 2.2
Emitted when writes on block device reaches or exceeds the configured write threshold. For thin-provisioned devices, this means the device should be extended to avoid pausing for disk exhaustion. The event is one shot. Once triggered, it needs to be re-registered with another block-set-write-threshold command.
Arguments:
node-name: string
graph node name on which the threshold was exceeded.
amount-exceeded: int
amount of data which exceeded the threshold, in bytes.
write-threshold: int
last configured threshold, in bytes.
Since: 2.3
Change the write threshold for a block drive. An event will be delivered if a write to this block drive crosses the configured threshold. The threshold is an offset, thus must be non-negative. Default is no write threshold. Setting the threshold to zero disables it.
This is useful to transparently resize thin-provisioned drives without the guest OS noticing.
Arguments:
node-name: string
graph node name on which the threshold must be set.
write-threshold: int
configured threshold for the block device, bytes. Use 0 to disable the threshold.
Since: 2.3
Example:
-> { "execute": "block-set-write-threshold", "arguments": { "node-name": "mydev", "write-threshold":<PHONE_NUMBER>4 } } <- { "return": {} }
Dynamically reconfigure the block driver state graph. It can be used to add, remove, insert or replace a graph node. Currently only the Quorum driver implements this feature to add or remove its child. This is useful to fix a broken quorum child.
If node
is specified, it will be inserted under parent
. child
may not be specified in this case. If both parent
and child
are
specified but node
is not, child
will be detached from parent
.
Arguments:
parent: string
the id or name of the parent node.
child: string
(optional)the name of a child under the given parent node.
node: string
(optional)the name of the node that will be added.
Note: this command is experimental, and its API is not stable. It does not support all kinds of operations, all kinds of children, nor all block drivers.
FIXME Removing children from a quorum node means introducing gaps in the child indices. This cannot be represented in the ’children’ list of BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
Warning: The data in a new quorum child MUST be consistent with that of the rest of the array.
Since: 2.7
Example:
1. Add a new node to a quorum -> { "execute": "blockdev-add", "arguments": { "driver": "raw", "node-name": "new_node", "file": { "driver": "file", "filename": "test.raw" } } } <- { "return": {} } -> { "execute": "x-blockdev-change", "arguments": { "parent": "disk1", "node": "new_node" } } <- { "return": {} } 2. Delete a quorum's node -> { "execute": "x-blockdev-change", "arguments": { "parent": "disk1", "child": "children.1" } } <- { "return": {} }
Move node
and its children into the iothread
. If iothread
is null then
move node
and its children into the main loop.
The node must not be attached to a BlockBackend.
Arguments:
node-name: string
the name of the block driver node
iothread: StrOrNull
the name of the IOThread object or null for the main loop
force: boolean
(optional)true if the node and its children should be moved when a BlockBackend is already attached
Note: this command is experimental and intended for test cases that need control over IOThreads only.
Since: 2.12
Example:
1. Move a node into an IOThread -> { "execute": "x-blockdev-set-iothread", "arguments": { "node-name": "disk1", "iothread": "iothread0" } } <- { "return": {} } 2. Move a node into the main loop -> { "execute": "x-blockdev-set-iothread", "arguments": { "node-name": "disk1", "iothread": null } } <- { "return": {} }
Members:
addr: SocketAddress
Address on which to listen.
tls-creds: string
(optional)ID of the TLS credentials object (since 2.6).
tls-authz: string
(optional)ID of the QAuthZ authorization object used to validate the client’s x509 distinguished name. This object is is only resolved at time of use, so can be deleted and recreated on the fly while the NBD server is active. If missing, it will default to denying access (since 4.0).
Keep this type consistent with the nbd-server-start arguments. The only intended difference is using SocketAddress instead of SocketAddressLegacy.
Since: 4.2
Start an NBD server listening on the given host and port. Block
devices can then be exported using nbd-server-add
. The NBD
server will present them as named exports; for example, another
QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
Arguments:
addr: SocketAddressLegacy
Address on which to listen.
tls-creds: string
(optional)ID of the TLS credentials object (since 2.6).
tls-authz: string
(optional)ID of the QAuthZ authorization object used to validate the client’s x509 distinguished name. This object is is only resolved at time of use, so can be deleted and recreated on the fly while the NBD server is active. If missing, it will default to denying access (since 4.0).
Returns: error if the server is already running.
Keep this type consistent with the NbdServerOptions type. The only intended difference is using SocketAddressLegacy instead of SocketAddress.
Since: 1.3.0
An NBD block export.
Members:
device: string
The device name or node name of the node to be exported
name: string
(optional)Export name. If unspecified, the device
parameter is used as the
export name. (Since 2.12)
description: string
(optional)Free-form description of the export, up to 4096 bytes. (Since 5.0)
writable: boolean
(optional)Whether clients should be able to write to the device via the NBD connection (default false).
bitmap: string
(optional)Also export the dirty bitmap reachable from device
, so the
NBD client can use NBD_OPT_SET_META_CONTEXT with
"qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0)
Since: 5.0
Export a block node to QEMU’s embedded NBD server.
Arguments: the members of BlockExportNbd
Returns: error if the server is not running, or export with the same name already exists.
Since: 1.3.0
Mode for removing an NBD export.
Values:
safe
Remove export if there are no existing connections, fail otherwise.
hard
Drop all connections immediately and remove export.
Potential additional modes to be added in the future:
hide: Just hide export from new clients, leave existing connections as is. Remove export after all clients are disconnected.
soft: Hide export from new clients, answer with ESHUTDOWN for all further requests from existing clients.
Since: 2.12
Remove NBD export by name.
Arguments:
name: string
Export name.
mode: NbdServerRemoveMode
(optional)Mode of command operation. See NbdServerRemoveMode
description.
Default is ’safe’.
Returns: error if
Since: 2.12
Stop QEMU’s embedded NBD server, and unregister all devices previously
added via nbd-server-add
.
Since: 1.3.0
An enumeration of block export types
Values:
nbd
NBD export
Since: 4.2
Describes a block export, i.e. how single node should be exported on an external interface.
Members:
type: BlockExportType
Not documented
BlockExportNbd
when type
is "nbd"Since: 4.2
An enumeration of the quorum operation types
Values:
read
read operation
write
write operation
flush
flush operation
Since: 2.6
Emitted by the Quorum block driver if it fails to establish a quorum
Arguments:
reference: string
device name if defined else node name
sector-num: int
number of the first sector of the failed read operation
sectors-count: int
failed read operation sector count
Note: This event is rate-limited.
Since: 2.0
Example:
<- { "event": "QUORUM_FAILURE", "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 745528 } }
Emitted to report a corruption of a Quorum file
Arguments:
type: QuorumOpType
quorum operation type (Since 2.6)
error: string
(optional)error message. Only present on failure. This field contains a human-readable error message. There are no semantics other than that the block layer reported an error and clients should not try to interpret the error string.
node-name: string
the graph node name of the block driver state
sector-num: int
number of the first sector of the failed read operation
sectors-count: int
failed read operation sector count
Note: This event is rate-limited.
Since: 2.0
Example:
1. Read operation { "event": "QUORUM_REPORT_BAD", "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, "type": "read" }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 745528 } } 2. Flush operation { "event": "QUORUM_REPORT_BAD", "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, "type": "flush", "error": "Broken pipe" }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 291763 } }
Members:
device: string
the device name or node-name of a root node to generate the snapshot from
name: string
the name of the internal snapshot to be created
Notes:
In transaction, if name
is empty, or any snapshot matching name
exists, the operation will fail. Only some image formats support it,
for example, qcow2, rbd, and sheepdog.
Since: 1.7
Synchronously take an internal snapshot of a block device, when the format of the image used supports it. If the name is an empty string, or a snapshot with name already exists, the operation will fail.
For the arguments, see the documentation of BlockdevSnapshotInternal.
Returns:
device
is not a valid block device, GenericError
name
exists, or name
is empty,
GenericError
Since: 1.7
Example:
-> { "execute": "blockdev-snapshot-internal-sync", "arguments": { "device": "ide-hd0", "name": "snapshot0" } } <- { "return": {} }
Synchronously delete an internal snapshot of a block device, when the format of the image used support it. The snapshot is identified by name or id or both. One of the name or id is required. Return SnapshotInfo for the successfully deleted snapshot.
Arguments:
device: string
the device name or node-name of a root node to delete the snapshot from
id: string
(optional)optional the snapshot’s ID to be deleted
name: string
(optional)optional the snapshot’s name to be deleted
Returns:
device
is not a valid block device, GenericError
id
and name
are both not specified, GenericError
Since: 1.7
Example:
-> { "execute": "blockdev-snapshot-delete-internal-sync", "arguments": { "device": "ide-hd0", "name": "snapshot0" } } <- { "return": { "id": "1", "name": "snapshot0", "vm-state-size": 0, "date-sec": 1000012, "date-nsec": 10, "vm-clock-sec": 100, "vm-clock-nsec": 20 } }
Policy that BIOS should use to interpret cylinder/head/sector addresses. Note that Bochs BIOS and SeaBIOS will not actually translate logical CHS to physical; instead, they will use logical block addressing.
Values:
auto
If cylinder/heads/sizes are passed, choose between none and LBA depending on the size of the disk. If they are not passed, choose none if QEMU can guess that the disk had 16 or fewer heads, large if QEMU can guess that the disk had 131072 or fewer tracks across all heads (i.e. cylinders*heads<131072), otherwise LBA.
none
The physical disk geometry is equal to the logical geometry.
lba
Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 heads (if fewer than 255 are enough to cover the whole disk with 1024 cylinders/head). The number of cylinders/head is then computed based on the number of sectors and heads.
large
The number of cylinders per head is scaled down to 1024 by correspondingly scaling up the number of heads.
rechs
Same as large
, but first convert a 16-head geometry to
15-head, by proportionally scaling up the number of
cylinders/head.
Since: 2.0
Type of Floppy drive to be emulated by the Floppy Disk Controller.
Values:
144
1.44MB 3.5" drive
288
2.88MB 3.5" drive
120
1.2MB 5.25" drive
none
No drive connected
auto
Automatically determined by inserted media at boot
Since: 2.6
Information about a persistent reservation manager
Members:
id: string
the identifier of the persistent reservation manager
connected: boolean
true if the persistent reservation manager is connected to the underlying storage or helper
Since: 3.0
Returns a list of information about each persistent reservation manager.
Returns:
a list of PRManagerInfo
for each persistent reservation manager
Since: 3.0
Ejects the medium from a removable drive.
Arguments:
device: string
(optional)Block device name
id: string
(optional)The name or QOM path of the guest device (since: 2.8)
force: boolean
(optional)If true, eject regardless of whether the drive is locked. If not specified, the default value is false.
Features:
deprecated
Member device
is deprecated. Use id
instead.
Returns:
device
is not a valid block device, DeviceNotFound
Notes: Ejecting a device with no media results in success
Since: 0.14.0
Example:
-> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } <- { "return": {} }
Opens a block device’s tray. If there is a block driver state tree inserted as a medium, it will become inaccessible to the guest (but it will remain associated to the block device, so closing the tray will make it accessible again).
If the tray was already open before, this will be a no-op.
Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in which no such event will be generated, these include:
force
is false and the guest does not
respond to the eject request
device
does not have a guest device attached
to it
Arguments:
device: string
(optional)Block device name
id: string
(optional)The name or QOM path of the guest device (since: 2.8)
force: boolean
(optional)if false (the default), an eject request will be sent to the guest if it has locked the tray (and the tray will not be opened immediately); if true, the tray will be opened regardless of whether it is locked
Features:
deprecated
Member device
is deprecated. Use id
instead.
Since: 2.5
Example:
-> { "execute": "blockdev-open-tray", "arguments": { "id": "ide0-1-0" } } <- { "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 716996 }, "event": "DEVICE_TRAY_MOVED", "data": { "device": "ide1-cd0", "id": "ide0-1-0", "tray-open": true } } <- { "return": {} }
Closes a block device’s tray. If there is a block driver state tree associated with the block device (which is currently ejected), that tree will be loaded as the medium.
If the tray was already closed before, this will be a no-op.
Arguments:
device: string
(optional)Block device name
id: string
(optional)The name or QOM path of the guest device (since: 2.8)
Features:
deprecated
Member device
is deprecated. Use id
instead.
Since: 2.5
Example:
-> { "execute": "blockdev-close-tray", "arguments": { "id": "ide0-1-0" } } <- { "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 272147 }, "event": "DEVICE_TRAY_MOVED", "data": { "device": "ide1-cd0", "id": "ide0-1-0", "tray-open": false } } <- { "return": {} }
Removes a medium (a block driver state tree) from a block device. That block device’s tray must currently be open (unless there is no attached guest device).
If the tray is open and there is no medium inserted, this will be a no-op.
Arguments:
id: string
The name or QOM path of the guest device
Since: 2.12
Example:
-> { "execute": "blockdev-remove-medium", "arguments": { "id": "ide0-1-0" } } <- { "error": { "class": "GenericError", "desc": "Tray of device 'ide0-1-0' is not open" } } -> { "execute": "blockdev-open-tray", "arguments": { "id": "ide0-1-0" } } <- { "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 549958 }, "event": "DEVICE_TRAY_MOVED", "data": { "device": "ide1-cd0", "id": "ide0-1-0", "tray-open": true } } <- { "return": {} } -> { "execute": "blockdev-remove-medium", "arguments": { "id": "ide0-1-0" } } <- { "return": {} }
Inserts a medium (a block driver state tree) into a block device. That block device’s tray must currently be open (unless there is no attached guest device) and there must be no medium inserted already.
Arguments:
id: string
The name or QOM path of the guest device
node-name: string
name of a node in the block driver state graph
Since: 2.12
Example:
-> { "execute": "blockdev-add", "arguments": { "node-name": "node0", "driver": "raw", "file": { "driver": "file", "filename": "fedora.iso" } } } <- { "return": {} } -> { "execute": "blockdev-insert-medium", "arguments": { "id": "ide0-1-0", "node-name": "node0" } } <- { "return": {} }
Specifies the new read-only mode of a block device subject to the
blockdev-change-medium
command.
Values:
retain
Retains the current read-only mode
read-only
Makes the device read-only
read-write
Makes the device writable
Since: 2.3
Changes the medium inserted into a block device by ejecting the current medium and loading a new image file which is inserted as the new medium (this command combines blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium and blockdev-close-tray).
Arguments:
device: string
(optional)Block device name
id: string
(optional)The name or QOM path of the guest device (since: 2.8)
filename: string
filename of the new image to be loaded
format: string
(optional)format to open the new image with (defaults to the probed format)
read-only-mode: BlockdevChangeReadOnlyMode
(optional)change the read-only mode of the device; defaults to ’retain’
Features:
deprecated
Member device
is deprecated. Use id
instead.
Since: 2.5
Examples:
1. Change a removable medium -> { "execute": "blockdev-change-medium", "arguments": { "id": "ide0-1-0", "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", "format": "raw" } } <- { "return": {} } 2. Load a read-only medium into a writable drive -> { "execute": "blockdev-change-medium", "arguments": { "id": "floppyA", "filename": "/srv/images/ro.img", "format": "raw", "read-only-mode": "retain" } } <- { "error": { "class": "GenericError", "desc": "Could not open '/srv/images/ro.img': Permission denied" } } -> { "execute": "blockdev-change-medium", "arguments": { "id": "floppyA", "filename": "/srv/images/ro.img", "format": "raw", "read-only-mode": "read-only" } } <- { "return": {} }
Emitted whenever the tray of a removable device is moved by the guest or by HMP/QMP commands
Arguments:
device: string
Block device name. This is always present for compatibility reasons, but it can be empty ("") if the image does not have a device name associated.
id: string
The name or QOM path of the guest device (since 2.8)
tray-open: boolean
true if the tray has been opened or false if it has been closed
Since: 1.1
Example:
<- { "event": "DEVICE_TRAY_MOVED", "data": { "device": "ide1-cd0", "id": "/machine/unattached/device[22]", "tray-open": true }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 450486 } }
Emitted whenever the connected status of a persistent reservation manager changes.
Arguments:
id: string
The id of the PR manager object
connected: boolean
true if the PR manager is connected to a backend
Since: 3.0
Example:
<- { "event": "PR_MANAGER_STATUS_CHANGED", "data": { "id": "pr-helper0", "connected": true }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 450486 } }
Change I/O throttle limits for a block drive.
Since QEMU 2.4, each device with I/O limits is member of a throttle group.
If two or more devices are members of the same group, the limits will apply to the combined I/O of the whole group in a round-robin fashion. Therefore, setting new I/O limits to a device will affect the whole group.
The name of the group can be specified using the ’group’ parameter. If the parameter is unset, it is assumed to be the current group of that device. If it’s not in any group yet, the name of the device will be used as the name for its group.
The ’group’ parameter can also be used to move a device to a different group. In this case the limits specified in the parameters will be applied to the new group only.
I/O limits can be disabled by setting all of them to 0. In this case the device will be removed from its group and the rest of its members will not be affected. The ’group’ parameter is ignored.
Arguments: the members of BlockIOThrottle
Returns:
device
is not a valid block device, DeviceNotFound
Since: 1.1
Example:
-> { "execute": "block_set_io_throttle", "arguments": { "id": "virtio-blk-pci0/virtio-backend", "bps": 0, "bps_rd": 0, "bps_wr": 0, "iops": 512, "iops_rd": 0, "iops_wr": 0, "bps_max": 0, "bps_rd_max": 0, "bps_wr_max": 0, "iops_max": 0, "iops_rd_max": 0, "iops_wr_max": 0, "bps_max_length": 0, "iops_size": 0 } } <- { "return": {} } -> { "execute": "block_set_io_throttle", "arguments": { "id": "ide0-1-0", "bps": 1000000, "bps_rd": 0, "bps_wr": 0, "iops": 0, "iops_rd": 0, "iops_wr": 0, "bps_max": 8000000, "bps_rd_max": 0, "bps_wr_max": 0, "iops_max": 0, "iops_rd_max": 0, "iops_wr_max": 0, "bps_max_length": 60, "iops_size": 0 } } <- { "return": {} }
Manage read, write and flush latency histograms for the device.
If only id
parameter is specified, remove all present latency histograms
for the device. Otherwise, add/reset some of (or all) latency histograms.
Arguments:
id: string
The name or QOM path of the guest device.
boundaries: array of int
(optional)list of interval boundary values (see description in
BlockLatencyHistogramInfo definition). If specified, all
latency histograms are removed, and empty ones created for all
io types with intervals corresponding to boundaries
(except for
io types, for which specific boundaries are set through the
following parameters).
boundaries-read: array of int
(optional)list of interval boundary values for read latency
histogram. If specified, old read latency histogram is
removed, and empty one created with intervals
corresponding to boundaries-read
. The parameter has higher
priority then boundaries
.
boundaries-write: array of int
(optional)list of interval boundary values for write latency histogram.
boundaries-flush: array of int
(optional)list of interval boundary values for flush latency histogram.
Returns: error if device is not found or any boundary arrays are invalid.
Since: 4.0
Example:
set new histograms for all io types with intervals [0, 10), [10, 50), [50, 100), [100, +inf): -> { "execute": "block-latency-histogram-set", "arguments": { "id": "drive0", "boundaries": [10, 50, 100] } } <- { "return": {} }
Example:
set new histogram only for write, other histograms will remain not changed (or not created): -> { "execute": "block-latency-histogram-set", "arguments": { "id": "drive0", "boundaries-write": [10, 50, 100] } } <- { "return": {} }
Example:
set new histograms with the following intervals: read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000, 5000), [5000, +inf) -> { "execute": "block-latency-histogram-set", "arguments": { "id": "drive0", "boundaries": [10, 50, 100], "boundaries-write": [1000, 5000] } } <- { "return": {} }
Example:
remove all latency histograms: -> { "execute": "block-latency-histogram-set", "arguments": { "id": "drive0" } } <- { "return": {} }
Information about a character device.
Members:
label: string
the label of the character device
filename: string
the filename of the character device
frontend-open: boolean
shows whether the frontend device attached to this backend (eg. with the chardev=... option) is in open or closed state (since 2.1)
Notes:
filename
is encoded using the QEMU command line character device
encoding. See the QEMU man page for details.
Since: 0.14.0
Returns information about current character devices.
Returns:
a list of ChardevInfo
Since: 0.14.0
Example:
-> { "execute": "query-chardev" } <- { "return": [ { "label": "charchannel0", "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server", "frontend-open": false }, { "label": "charmonitor", "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server", "frontend-open": true }, { "label": "charserial0", "filename": "pty:/dev/pts/2", "frontend-open": true } ] }
Information about a character device backend
Members:
name: string
The backend name
Since: 2.0
Returns information about character device backends.
Returns:
a list of ChardevBackendInfo
Since: 2.0
Example:
-> { "execute": "query-chardev-backends" } <- { "return":[ { "name":"udp" }, { "name":"tcp" }, { "name":"unix" }, { "name":"spiceport" } ] }
An enumeration of data format.
Values:
utf8
Data is a UTF-8 string (RFC 3629)
base64
Data is Base64 encoded binary (RFC 3548)
Since: 1.4
Write to a ring buffer character device.
Arguments:
device: string
the ring buffer character device name
data: string
data to write
format: DataFormat
(optional)data encoding (default ’utf8’).
Returns: Nothing on success
Since: 1.4
Example:
-> { "execute": "ringbuf-write", "arguments": { "device": "foo", "data": "abcdefgh", "format": "utf8" } } <- { "return": {} }
Read from a ring buffer character device.
Arguments:
device: string
the ring buffer character device name
size: int
how many bytes to read at most
format: DataFormat
(optional)data encoding (default ’utf8’).
Returns: data read from the device
Since: 1.4
Example:
-> { "execute": "ringbuf-read", "arguments": { "device": "foo", "size": 1000, "format": "utf8" } } <- { "return": "abcdefgh" }
Configuration shared across all chardev backends
Members:
logfile: string
(optional)The name of a logfile to save output
logappend: boolean
(optional)true to append instead of truncate (default to false to truncate)
Since: 2.6
Configuration info for file chardevs.
Members:
in: string
(optional)The name of the input file
out: string
The name of the output file
append: boolean
(optional)Open the file in append mode (default false to truncate) (Since 2.6)
ChardevCommon
Since: 1.4
Configuration info for device and pipe chardevs.
Members:
device: string
The name of the special file for the device, i.e. /dev/ttyS0 on Unix or COM1: on Windows
ChardevCommon
Since: 1.4
Configuration info for (stream) socket chardevs.
Members:
addr: SocketAddressLegacy
socket address to listen on (server=true) or connect to (server=false)
tls-creds: string
(optional)the ID of the TLS credentials object (since 2.6)
tls-authz: string
(optional)the ID of the QAuthZ authorization object against which the client’s x509 distinguished name will be validated. This object is only resolved at time of use, so can be deleted and recreated on the fly while the chardev server is active. If missing, it will default to denying access (since 4.0)
server: boolean
(optional)create server socket (default: true)
wait: boolean
(optional)wait for incoming connection on server sockets (default: false). Silently ignored with server: false. This use is deprecated.
nodelay: boolean
(optional)set TCP_NODELAY socket option (default: false)
telnet: boolean
(optional)enable telnet protocol on server sockets (default: false)
tn3270: boolean
(optional)enable tn3270 protocol on server sockets (default: false) (Since: 2.10)
websocket: boolean
(optional)enable websocket protocol on server sockets (default: false) (Since: 3.1)
reconnect: int
(optional)For a client socket, if a socket is disconnected, then attempt a reconnect after the given number of seconds. Setting this to zero disables this function. (default: 0) (Since: 2.2)
ChardevCommon
Since: 1.4
Configuration info for datagram socket chardevs.
Members:
remote: SocketAddressLegacy
remote address
local: SocketAddressLegacy
(optional)local address
ChardevCommon
Since: 1.5
Configuration info for mux chardevs.
Members:
chardev: string
name of the base chardev.
ChardevCommon
Since: 1.5
Configuration info for stdio chardevs.
Members:
signal: boolean
(optional)Allow signals (such as SIGINT triggered by ^C) be delivered to qemu. Default: true in -nographic mode, false otherwise.
ChardevCommon
Since: 1.5
Configuration info for spice vm channel chardevs.
Members:
type: string
kind of channel (for example vdagent).
ChardevCommon
Since: 1.5
If: defined(CONFIG_SPICE)
Configuration info for spice port chardevs.
Members:
fqdn: string
name of the channel (see docs/spice-port-fqdn.txt)
ChardevCommon
Since: 1.5
If: defined(CONFIG_SPICE)
Configuration info for virtual console chardevs.
Members:
width: int
(optional)console width, in pixels
height: int
(optional)console height, in pixels
cols: int
(optional)console width, in chars
rows: int
(optional)console height, in chars
ChardevCommon
Since: 1.5
Configuration info for ring buffer chardevs.
Members:
size: int
(optional)ring buffer size, must be power of two, default is 65536
ChardevCommon
Since: 1.5
Configuration info for the new chardev backend.
Members:
type
One of "file", "serial", "parallel", "pipe", "socket", "udp", "pty", "null", "mux", "msmouse", "wctablet", "braille", "testdev", "stdio", "console", "spicevmc", "spiceport", "vc", "ringbuf", "memory"
data: ChardevFile
when type
is "file"data: ChardevHostdev
when type
is "serial"data: ChardevHostdev
when type
is "parallel"data: ChardevHostdev
when type
is "pipe"data: ChardevSocket
when type
is "socket"data: ChardevUdp
when type
is "udp"data: ChardevCommon
when type
is "pty"data: ChardevCommon
when type
is "null"data: ChardevMux
when type
is "mux"data: ChardevCommon
when type
is "msmouse"data: ChardevCommon
when type
is "wctablet"data: ChardevCommon
when type
is "braille"data: ChardevCommon
when type
is "testdev"data: ChardevStdio
when type
is "stdio"data: ChardevCommon
when type
is "console"data: ChardevSpiceChannel
when type
is "spicevmc" (If: defined(CONFIG_SPICE)
)data: ChardevSpicePort
when type
is "spiceport" (If: defined(CONFIG_SPICE)
)data: ChardevVC
when type
is "vc"data: ChardevRingbuf
when type
is "ringbuf"data: ChardevRingbuf
when type
is "memory"Since: 1.4 (testdev since 2.2, wctablet since 2.9)
Return info about the chardev backend just created.
Members:
pty: string
(optional)name of the slave pseudoterminal device, present if and only if a chardev of type ’pty’ was created
Since: 1.4
Add a character device backend
Arguments:
id: string
the chardev’s ID, must be unique
backend: ChardevBackend
backend type and parameters
Returns: ChardevReturn.
Since: 1.4
Example:
-> { "execute" : "chardev-add", "arguments" : { "id" : "foo", "backend" : { "type" : "null", "data" : {} } } } <- { "return": {} } -> { "execute" : "chardev-add", "arguments" : { "id" : "bar", "backend" : { "type" : "file", "data" : { "out" : "/tmp/bar.log" } } } } <- { "return": {} } -> { "execute" : "chardev-add", "arguments" : { "id" : "baz", "backend" : { "type" : "pty", "data" : {} } } } <- { "return": { "pty" : "/dev/pty/42" } }
Change a character device backend
Arguments:
id: string
the chardev’s ID, must exist
backend: ChardevBackend
new backend type and parameters
Returns: ChardevReturn.
Since: 2.10
Example:
-> { "execute" : "chardev-change", "arguments" : { "id" : "baz", "backend" : { "type" : "pty", "data" : {} } } } <- { "return": { "pty" : "/dev/pty/42" } } -> {"execute" : "chardev-change", "arguments" : { "id" : "charchannel2", "backend" : { "type" : "socket", "data" : { "addr" : { "type" : "unix" , "data" : { "path" : "/tmp/charchannel2.socket" } }, "server" : true, "wait" : false }}}} <- {"return": {}}
Remove a character device backend
Arguments:
id: string
the chardev’s ID, must exist and not be in use
Returns: Nothing on success
Since: 1.4
Example:
-> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } <- { "return": {} }
Send a break to a character device
Arguments:
id: string
the chardev’s ID, must exist
Returns: Nothing on success
Since: 2.10
Example:
-> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } <- { "return": {} }
Emitted when the guest opens or closes a virtio-serial port.
Arguments:
id: string
device identifier of the virtio-serial port
open: boolean
true if the guest has opened the virtio-serial port
Since: 2.1
Example:
<- { "event": "VSERPORT_CHANGE", "data": { "id": "channel0", "open": true }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 422329 } }
An enumeration of guest-memory-dump’s format.
Values:
elf
elf format
kdump-zlib
kdump-compressed format with zlib-compressed
kdump-lzo
kdump-compressed format with lzo-compressed
kdump-snappy
kdump-compressed format with snappy-compressed
win-dmp
Windows full crashdump format, can be used instead of ELF converting (since 2.13)
Since: 2.0
Dump guest’s memory to vmcore. It is a synchronous operation that can take very long depending on the amount of guest memory.
Arguments:
paging: boolean
if true, do paging to get guest’s memory mapping. This allows using gdb to process the core file.
IMPORTANT: this option can make QEMU allocate several gigabytes of RAM. This can happen for a large guest, or a malicious guest pretending to be large.
Also, paging=true has the following limitations:
protocol: string
the filename or file descriptor of the vmcore. The supported protocols are:
detach: boolean
(optional)if true, QMP will return immediately rather than waiting for the dump to finish. The user can track progress using "query-dump". (since 2.6).
begin: int
(optional)if specified, the starting physical address.
length: int
(optional)if specified, the memory size, in bytes. If you don’t
want to dump all guest’s memory, please specify the start begin
and length
format: DumpGuestMemoryFormat
(optional)if specified, the format of guest memory dump. But non-elf
format is conflict with paging and filter, ie. paging
, begin
and
length
is not allowed to be specified with non-elf format
at the
same time (since 2.0)
Note: All boolean arguments default to false
Returns: nothing on success
Since: 1.2
Example:
-> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } } <- { "return": {} }
Describe the status of a long-running background guest memory dump.
Values:
none
no dump-guest-memory has started yet.
active
there is one dump running in background.
completed
the last dump has finished successfully.
failed
the last dump has failed.
Since: 2.6
The result format for ’query-dump’.
Members:
status: DumpStatus
enum of DumpStatus
, which shows current dump status
completed: int
bytes written in latest dump (uncompressed)
total: int
total bytes to be written in latest dump (uncompressed)
Since: 2.6
Query latest dump status.
Returns:
A DumpStatus
object showing the dump status.
Since: 2.6
Example:
-> { "execute": "query-dump" } <- { "return": { "status": "active", "completed": 1024000, "total": 2048000 } }
Emitted when background dump has completed
Arguments:
result: DumpQueryResult
final dump status
error: string
(optional)human-readable error string that provides hint on why dump failed. Only presents on failure. The user should not try to interpret the error string.
Since: 2.6
Example:
{ "event": "DUMP_COMPLETED", "data": {"result": {"total":<PHONE_NUMBER>, "status": "completed", "completed":<PHONE_NUMBER>} } }
A list of the available formats for dump-guest-memory
Members:
formats: array of DumpGuestMemoryFormat
Not documented
Since: 2.0
Returns the available formats for dump-guest-memory
Returns:
A DumpGuestMemoryCapability
object listing available formats for
dump-guest-memory
Since: 2.0
Example:
-> { "execute": "query-dump-guest-memory-capability" } <- { "return": { "formats": ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
Sets the link status of a virtual network adapter.
Arguments:
name: string
the device name of the virtual network adapter
up: boolean
true to set the link status to be up
Returns:
Nothing on success
If name
is not a valid network device, DeviceNotFound
Since: 0.14.0
Notes: Not all network adapters support setting link status. This command will succeed even if the network adapter does not support link status notification.
Example:
-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } } <- { "return": {} }
Add a network backend.
Additional arguments depend on the type.
Arguments: the members of Netdev
Since: 0.14.0
Returns:
Nothing on success
If type
is not a valid network backend, DeviceNotFound
Example:
-> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1", "dnssearch": "example.org" } } <- { "return": {} }
Remove a network backend.
Arguments:
id: string
the name of the network backend to remove
Returns:
Nothing on success
If id
is not a valid network backend, DeviceNotFound
Since: 0.14.0
Example:
-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } <- { "return": {} }
Create a new Network Interface Card.
Members:
netdev: string
(optional)id of -netdev to connect to
macaddr: string
(optional)MAC address
model: string
(optional)device model (e1000, rtl8139, virtio etc.)
addr: string
(optional)PCI device address
vectors: int
(optional)number of MSI-x vectors, 0 to disable MSI-X
Since: 1.2
Use the user mode network stack which requires no administrator privilege to run.
Members:
hostname: string
(optional)client hostname reported by the builtin DHCP server
restrict: boolean
(optional)isolate the guest from the host
ipv4: boolean
(optional)whether to support IPv4, default true for enabled (since 2.6)
ipv6: boolean
(optional)whether to support IPv6, default true for enabled (since 2.6)
ip: string
(optional)legacy parameter, use net= instead
net: string
(optional)IP network address that the guest will see, in the form addr[/netmask] The netmask is optional, and can be either in the form a.b.c.d or as a number of valid top-most bits. Default is <IP_ADDRESS>/24.
host: string
(optional)guest-visible address of the host
tftp: string
(optional)root directory of the built-in TFTP server
bootfile: string
(optional)BOOTP filename, for use with tftp=
dhcpstart: string
(optional)the first of the 16 IPs the built-in DHCP server can assign
dns: string
(optional)guest-visible address of the virtual nameserver
dnssearch: array of String
(optional)list of DNS suffixes to search, passed as DHCP option to the guest
domainname: string
(optional)guest-visible domain name of the virtual nameserver (since 3.0)
ipv6-prefix: string
(optional)IPv6 network prefix (default is fec0::) (since 2.6). The network prefix is given in the usual hexadecimal IPv6 address notation.
ipv6-prefixlen: int
(optional)IPv6 network prefix length (default is 64) (since 2.6)
ipv6-host: string
(optional)guest-visible IPv6 address of the host (since 2.6)
ipv6-dns: string
(optional)guest-visible IPv6 address of the virtual nameserver (since 2.6)
smb: string
(optional)root directory of the built-in SMB server
smbserver: string
(optional)IP address of the built-in SMB server
hostfwd: array of String
(optional)redirect incoming TCP or UDP host connections to guest endpoints
guestfwd: array of String
(optional)forward guest TCP connections
tftp-server-name: string
(optional)RFC2132 "TFTP server name" string (Since 3.1)
Since: 1.2
Used to configure a host TAP network interface backend.
Members:
ifname: string
(optional)interface name
fd: string
(optional)file descriptor of an already opened tap
fds: string
(optional)multiple file descriptors of already opened multiqueue capable tap
script: string
(optional)script to initialize the interface
downscript: string
(optional)script to shut down the interface
br: string
(optional)bridge name (since 2.8)
helper: string
(optional)command to execute to configure bridge
sndbuf: int
(optional)send buffer limit. Understands [TGMKkb] suffixes.
vnet_hdr: boolean
(optional)enable the IFF_VNET_HDR flag on the tap interface
vhost: boolean
(optional)enable vhost-net network accelerator
vhostfd: string
(optional)file descriptor of an already opened vhost net device
vhostfds: string
(optional)file descriptors of multiple already opened vhost net devices
vhostforce: boolean
(optional)vhost on for non-MSIX virtio guests
queues: int
(optional)number of queues to be created for multiqueue capable tap
poll-us: int
(optional)maximum number of microseconds that could be spent on busy polling for tap (since 2.7)
Since: 1.2
Socket netdevs are used to establish a network connection to another QEMU virtual machine via a TCP socket.
Members:
fd: string
(optional)file descriptor of an already opened socket
listen: string
(optional)port number, and optional hostname, to listen on
connect: string
(optional)port number, and optional hostname, to connect to
mcast: string
(optional)UDP multicast address and port number
localaddr: string
(optional)source address and port for multicast and udp packets
udp: string
(optional)UDP unicast address and port number
Since: 1.2
Configure an Ethernet over L2TPv3 tunnel.
Members:
src: string
source address
dst: string
destination address
srcport: string
(optional)source port - mandatory for udp, optional for ip
dstport: string
(optional)destination port - mandatory for udp, optional for ip
ipv6: boolean
(optional)force the use of ipv6
udp: boolean
(optional)use the udp version of l2tpv3 encapsulation
cookie64: boolean
(optional)use 64 bit coookies
counter: boolean
(optional)have sequence counter
pincounter: boolean
(optional)pin sequence counter to zero - workaround for buggy implementations or networks with packet reorder
txcookie: int
(optional)32 or 64 bit transmit cookie
rxcookie: int
(optional)32 or 64 bit receive cookie
txsession: int
32 bit transmit session
rxsession: int
(optional)32 bit receive session - if not specified set to the same value as transmit
offset: int
(optional)additional offset - allows the insertion of additional application-specific data before the packet payload
Since: 2.1
Connect to a vde switch running on the host.
Members:
sock: string
(optional)socket path
port: int
(optional)port number
group: string
(optional)group owner of socket
mode: int
(optional)permissions for socket
Since: 1.2
Connect a host TAP network interface to a host bridge device.
Members:
br: string
(optional)bridge name
helper: string
(optional)command to execute to configure bridge
Since: 1.2
Connect two or more net clients through a software hub.
Members:
hubid: int
hub identifier number
netdev: string
(optional)used to connect hub to a netdev instead of a device (since 2.12)
Since: 1.2
Connect a client to a netmap-enabled NIC or to a VALE switch port
Members:
ifname: string
Either the name of an existing network interface supported by netmap, or the name of a VALE port (created on the fly). A VALE port name is in the form ’valeXXX:YYY’, where XXX and YYY are non-negative integers. XXX identifies a switch and YYY identifies a port of the switch. VALE ports having the same XXX are therefore connected to the same switch.
devname: string
(optional)path of the netmap device (default: ’/dev/netmap’).
Since: 2.0
Vhost-user network backend
Members:
chardev: string
name of a unix socket chardev
vhostforce: boolean
(optional)vhost on for non-MSIX virtio guests (default: false).
queues: int
(optional)number of queues to be created for multiqueue vhost-user (default: 1) (Since 2.5)
Since: 2.1
Vhost-vdpa network backend
vDPA device is a device that uses a datapath which complies with the virtio specifications with a vendor specific control path.
Members:
vhostdev: string
(optional)path of vhost-vdpa device (default:’/dev/vhost-vdpa-0’)
queues: int
(optional)number of queues to be created for multiqueue vhost-vdpa (default: 1)
Since: 5.1
Available netdev drivers.
Values:
none
Not documented
nic
Not documented
user
Not documented
tap
Not documented
l2tpv3
Not documented
socket
Not documented
vde
Not documented
bridge
Not documented
hubport
Not documented
netmap
Not documented
vhost-user
Not documented
vhost-vdpa
Not documented
Since: 2.7
vhost-vdpa
since 5.1
Captures the configuration of a network device.
Members:
id: string
identifier for monitor commands.
type: NetClientDriver
Specify the driver used for interpreting remaining arguments.
NetLegacyNicOptions
when type
is "nic"NetdevUserOptions
when type
is "user"NetdevTapOptions
when type
is "tap"NetdevL2TPv3Options
when type
is "l2tpv3"NetdevSocketOptions
when type
is "socket"NetdevVdeOptions
when type
is "vde"NetdevBridgeOptions
when type
is "bridge"NetdevHubPortOptions
when type
is "hubport"NetdevNetmapOptions
when type
is "netmap"NetdevVhostUserOptions
when type
is "vhost-user"NetdevVhostVDPAOptions
when type
is "vhost-vdpa"Since: 1.2
’l2tpv3’ - since 2.1
Indicates whether a netfilter is attached to a netdev’s transmit queue or receive queue or both.
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.
Since: 2.5
Packets receiving state
Values:
normal
filter assigned packets according to the mac-table
none
don’t receive any assigned packet
all
receive all assigned packets
Since: 1.6
Rx-filter information for a NIC.
Members:
name: string
net client name
promiscuous: boolean
whether promiscuous mode is enabled
multicast: RxState
multicast receive state
unicast: RxState
unicast receive state
vlan: RxState
vlan receive state (Since 2.0)
broadcast-allowed: boolean
whether to receive broadcast
multicast-overflow: boolean
multicast table is overflowed or not
unicast-overflow: boolean
unicast table is overflowed or not
main-mac: string
the main macaddr string
vlan-table: array of int
a list of active vlan id
unicast-table: array of string
a list of unicast macaddr string
multicast-table: array of string
a list of multicast macaddr string
Since: 1.6
Return rx-filter information for all NICs (or for the given NIC).
Arguments:
name: string
(optional)net client name
Returns:
list of RxFilterInfo
for all NICs (or for the given NIC).
Returns an error if the given name
doesn’t exist, or given
NIC doesn’t support rx-filter querying, or given net client
isn’t a NIC.
Since: 1.6
Example:
-> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } <- { "return": [ { "promiscuous": true, "name": "vnet0", "main-mac": "52:54:00:12:34:56", "unicast": "normal", "vlan": "normal", "vlan-table": [ 4, 0 ], "unicast-table": [ ], "multicast": "normal", "multicast-overflow": false, "unicast-overflow": false, "multicast-table": [ "01:00:5e:00:00:01", "33:33:00:00:00:01", "33:33:ff:12:34:56" ], "broadcast-allowed": false } ] }
Emitted once until the ’query-rx-filter’ command is executed, the first event will always be emitted
Arguments:
name: string
(optional)net client name
path: string
device path
Since: 1.6
Example:
<- { "event": "NIC_RX_FILTER_CHANGED", "data": { "name": "vnet0", "path": "/machine/peripheral/vnet0/virtio-backend" }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 326866 } } }
Parameters for self-announce timers
Members:
initial: int
Initial delay (in ms) before sending the first GARP/RARP announcement
max: int
Maximum delay (in ms) between GARP/RARP announcement packets
rounds: int
Number of self-announcement attempts
step: int
Delay increase (in ms) after each self-announcement attempt
interfaces: array of string
(optional)An optional list of interface names, which restricts the announcement to the listed interfaces. (Since 4.1)
id: string
(optional)A name to be used to identify an instance of announce-timers and to allow it to modified later. Not for use as part of the migration parameters. (Since 4.1)
Since: 4.0
Trigger generation of broadcast RARP frames to update network switches. This can be useful when network bonds fail-over the active slave.
Arguments: the members of AnnounceParameters
Example:
-> { "execute": "announce-self", "arguments": { "initial": 50, "max": 550, "rounds": 10, "step": 50, "interfaces": ["vn2", "vn3"], "id": "bob" } } <- { "return": {} }
Since: 4.0
Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation. Failover primary devices which were hidden (not hotplugged when requested) before will now be hotplugged by the virtio-net standby device.
device-id: QEMU device id of the unplugged device
Arguments:
device-id: string
Not documented
Since: 4.2
Example:
<- { "event": "FAILOVER_NEGOTIATED", "data": "net1" }
Emitted when guest driver adds/deletes GID to/from device
Arguments:
netdev: string
RoCE Network Device name
gid-status: boolean
Add or delete indication
subnet-prefix: int
Subnet Prefix
interface-id: int
Not documented
interface-id
: Interface ID
Since: 4.0
Example:
<- {"timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 986760}, "event": "RDMA_GID_STATUS_CHANGED", "data": {"netdev": "bridge0", "interface-id":<PHONE_NUMBER>7475447892, "gid-status": true, "subnet-prefix": 33022}}
Rocker switch information.
Members:
name: string
switch name
id: int
switch ID
ports: int
number of front-panel ports
Since: 2.4
Return rocker switch information.
Arguments:
name: string
Not documented
Returns:
Rocker
information
Since: 2.4
Example:
-> { "execute": "query-rocker", "arguments": { "name": "sw1" } } <- { "return": {"name": "sw1", "ports": 2, "id":<PHONE_NUMBER>938}}
An eumeration of port duplex states.
Values:
half
half duplex
full
full duplex
Since: 2.4
An eumeration of port autoneg states.
Values:
off
autoneg is off
on
autoneg is on
Since: 2.4
Rocker switch port information.
Members:
name: string
port name
enabled: boolean
port is enabled for I/O
link-up: boolean
physical link is UP on port
speed: int
port link speed in Mbps
duplex: RockerPortDuplex
port link duplex
autoneg: RockerPortAutoneg
port link autoneg
Since: 2.4
Return rocker switch port information.
Arguments:
name: string
Not documented
Returns:
a list of RockerPort
information
Since: 2.4
Example:
-> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", "autoneg": "off", "link-up": true, "speed": 10000}, {"duplex": "full", "enabled": true, "name": "sw1.2", "autoneg": "off", "link-up": true, "speed": 10000} ]}
Rocker switch OF-DPA flow key
Members:
priority: int
key priority, 0 being lowest priority
tbl-id: int
flow table ID
in-pport: int
(optional)physical input port
tunnel-id: int
(optional)tunnel ID
vlan-id: int
(optional)VLAN ID
eth-type: int
(optional)Ethernet header type
eth-src: string
(optional)Ethernet header source MAC address
eth-dst: string
(optional)Ethernet header destination MAC address
ip-proto: int
(optional)IP Header protocol field
ip-tos: int
(optional)IP header TOS field
ip-dst: string
(optional)IP header destination address
Note: optional members may or may not appear in the flow key depending if they’re relevant to the flow key.
Since: 2.4
Rocker switch OF-DPA flow mask
Members:
in-pport: int
(optional)physical input port
tunnel-id: int
(optional)tunnel ID
vlan-id: int
(optional)VLAN ID
eth-src: string
(optional)Ethernet header source MAC address
eth-dst: string
(optional)Ethernet header destination MAC address
ip-proto: int
(optional)IP Header protocol field
ip-tos: int
(optional)IP header TOS field
Note: optional members may or may not appear in the flow mask depending if they’re relevant to the flow mask.
Since: 2.4
Rocker switch OF-DPA flow action
Members:
goto-tbl: int
(optional)next table ID
group-id: int
(optional)group ID
tunnel-lport: int
(optional)tunnel logical port ID
vlan-id: int
(optional)VLAN ID
new-vlan-id: int
(optional)new VLAN ID
out-pport: int
(optional)physical output port
Note: optional members may or may not appear in the flow action depending if they’re relevant to the flow action.
Since: 2.4
Rocker switch OF-DPA flow
Members:
cookie: int
flow unique cookie ID
hits: int
count of matches (hits) on flow
key: RockerOfDpaFlowKey
flow key
mask: RockerOfDpaFlowMask
flow mask
action: RockerOfDpaFlowAction
flow action
Since: 2.4
Return rocker OF-DPA flow information.
Arguments:
name: string
switch name
tbl-id: int
(optional)flow table ID. If tbl-id is not specified, returns flow information for all tables.
Returns: rocker OF-DPA flow information
Since: 2.4
Example:
-> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } } <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0}, "hits": 138, "cookie": 0, "action": {"goto-tbl": 10}, "mask": {"in-pport":<PHONE_NUMBER>} }, {...more...}, ]}
Rocker switch OF-DPA group
Members:
id: int
group unique ID
type: int
group type
vlan-id: int
(optional)VLAN ID
pport: int
(optional)physical port number
index: int
(optional)group index, unique with group type
out-pport: int
(optional)output physical port number
group-id: int
(optional)next group ID
set-vlan-id: int
(optional)VLAN ID to set
pop-vlan: int
(optional)pop VLAN headr from packet
group-ids: array of int
(optional)list of next group IDs
set-eth-src: string
(optional)set source MAC address in Ethernet header
set-eth-dst: string
(optional)set destination MAC address in Ethernet header
ttl-check: int
(optional)perform TTL check
Note: optional members may or may not appear in the group depending if they’re relevant to the group type.
Since: 2.4
Return rocker OF-DPA group information.
Arguments:
name: string
switch name
type: int
(optional)group type. If type is not specified, returns group information for all group types.
Returns: rocker OF-DPA group information
Since: 2.4
Example:
-> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } } <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841, "pop-vlan": 1, "id": 251723778}, {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841, "pop-vlan": 1, "id": 251723776}, {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840, "pop-vlan": 1, "id": 251658241}, {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840, "pop-vlan": 1, "id": 251658240} ]}
An enumeration of TPM models
Values:
tpm-tis
TPM TIS model
tpm-crb
TPM CRB model (since 2.12)
tpm-spapr
TPM SPAPR model (since 5.0)
Since: 1.5
Return a list of supported TPM models
Returns: a list of TpmModel
Since: 1.5
Example:
-> { "execute": "query-tpm-models" } <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
An enumeration of TPM types
Values:
passthrough
TPM passthrough type
emulator
Software Emulator TPM type Since: 2.11
Since: 1.5
Return a list of supported TPM types
Returns: a list of TpmType
Since: 1.5
Example:
-> { "execute": "query-tpm-types" } <- { "return": [ "passthrough", "emulator" ] }
Information about the TPM passthrough type
Members:
path: string
(optional)string describing the path used for accessing the TPM device
cancel-path: string
(optional)string showing the TPM’s sysfs cancel file for cancellation of TPM commands while they are executing
Since: 1.5
Information about the TPM emulator type
Members:
chardev: string
Name of a unix socket chardev
Since: 2.11
A union referencing different TPM backend types’ configuration options
Members:
type
data: TPMPassthroughOptions
when type
is "passthrough"data: TPMEmulatorOptions
when type
is "emulator"Since: 1.5
Information about the TPM
Members:
id: string
The Id of the TPM
model: TpmModel
The TPM frontend model
options: TpmTypeOptions
The TPM (backend) type configuration options
Since: 1.5
Return information about the TPM device
Returns:
TPMInfo
on success
Since: 1.5
Example:
-> { "execute": "query-tpm" } <- { "return": [ { "model": "tpm-tis", "options": { "type": "passthrough", "data": { "cancel-path": "/sys/class/misc/tpm0/device/cancel", "path": "/dev/tpm0" } }, "id": "tpm0" } ] }
Sets the password of a remote display session.
Arguments:
protocol: string
password: string
the new password
connected: string
(optional)how to handle existing clients when changing the password. If nothing is specified, defaults to ’keep’ ’fail’ to fail the command if clients are connected ’disconnect’ to disconnect existing clients ’keep’ to maintain existing clients
Returns:
Since: 0.14.0
Example:
-> { "execute": "set_password", "arguments": { "protocol": "vnc", "password": "secret" } } <- { "return": {} }
Expire the password of a remote display server.
Arguments:
protocol: string
the name of the remote display protocol ’vnc’ or ’spice’
time: string
when to expire the password.
Returns:
protocol
is ’spice’ and Spice is not active, DeviceNotFound
Since: 0.14.0
Notes:
Time is relative to the server and currently there is no way to
coordinate server time with client time. It is not recommended to
use the absolute time version of the time
parameter unless you’re
sure you are on the same machine as the QEMU instance.
Example:
-> { "execute": "expire_password", "arguments": { "protocol": "vnc", "time": "+60" } } <- { "return": {} }
Write a PPM of the VGA screen to a file.
Arguments:
filename: string
the path of a new PPM file to store the image
device: string
(optional)ID of the display device that should be dumped. If this parameter is missing, the primary display will be used. (Since 2.12)
head: int
(optional)head to use in case the device supports multiple heads. If this parameter is missing, head #0 will be used. Also note that the head can only be specified in conjunction with the device ID. (Since 2.12)
Returns: Nothing on success
Since: 0.14.0
Example:
-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } } <- { "return": {} }
The basic information for SPICE network connection
Members:
host: string
IP address
port: string
port number
family: NetworkAddressFamily
address family
Since: 2.1
If: defined(CONFIG_SPICE)
Information about a SPICE server
Members:
auth: string
(optional)authentication method
SpiceBasicInfo
Since: 2.1
If: defined(CONFIG_SPICE)
Information about a SPICE client channel.
Members:
connection-id: int
SPICE connection id number. All channels with the same id belong to the same SPICE session.
channel-type: int
SPICE channel type number. "1" is the main control channel, filter for this one if you want to track spice sessions only
channel-id: int
SPICE channel ID number. Usually "0", might be different when multiple channels of the same type exist, such as multiple display channels in a multihead setup
tls: boolean
true if the channel is encrypted, false otherwise.
SpiceBasicInfo
Since: 0.14.0
If: defined(CONFIG_SPICE)
An enumeration of Spice mouse states.
Values:
client
Mouse cursor position is determined by the client.
server
Mouse cursor position is determined by the server.
unknown
No information is available about mouse mode used by the spice server.
Note: spice/enums.h has a SpiceMouseMode already, hence the name.
Since: 1.1
If: defined(CONFIG_SPICE)
Information about the SPICE session.
Members:
enabled: boolean
true if the SPICE server is enabled, false otherwise
migrated: boolean
true if the last guest migration completed and spice migration had completed as well. false otherwise. (since 1.4)
host: string
(optional)The hostname the SPICE server is bound to. This depends on the name resolution on the host and may be an IP address.
port: int
(optional)The SPICE server’s port number.
compiled-version: string
(optional)SPICE server version.
tls-port: int
(optional)The SPICE server’s TLS port number.
auth: string
(optional)the current authentication type used by the server
mouse-mode: SpiceQueryMouseMode
The mode in which the mouse cursor is displayed currently. Can be determined by the client or the server, or unknown if spice server doesn’t provide this information. (since: 1.1)
channels: array of SpiceChannel
(optional)a list of SpiceChannel
for each active spice channel
Since: 0.14.0
If: defined(CONFIG_SPICE)
Returns information about the current SPICE server
Returns:
SpiceInfo
Since: 0.14.0
Example:
-> { "execute": "query-spice" } <- { "return": { "enabled": true, "auth": "spice", "port": 5920, "tls-port": 5921, "host": "<IP_ADDRESS>", "channels": [ { "port": "54924", "family": "ipv4", "channel-type": 1, "connection-id":<PHONE_NUMBER>, "host": "<IP_ADDRESS>", "channel-id": 0, "tls": true }, { "port": "36710", "family": "ipv4", "channel-type": 4, "connection-id":<PHONE_NUMBER>, "host": "<IP_ADDRESS>", "channel-id": 0, "tls": false }, [ ... more channels follow ... ] ] } }
If: defined(CONFIG_SPICE)
Emitted when a SPICE client establishes a connection
Arguments:
server: SpiceBasicInfo
server information
client: SpiceBasicInfo
client information
Since: 0.14.0
Example:
<- { "timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 388707}, "event": "SPICE_CONNECTED", "data": { "server": { "port": "5920", "family": "ipv4", "host": "<IP_ADDRESS>"}, "client": {"port": "52873", "family": "ipv4", "host": "<IP_ADDRESS>"} }}
If: defined(CONFIG_SPICE)
Emitted after initial handshake and authentication takes place (if any) and the SPICE channel is up and running
Arguments:
server: SpiceServerInfo
server information
client: SpiceChannel
client information
Since: 0.14.0
Example:
<- { "timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 417172}, "event": "SPICE_INITIALIZED", "data": {"server": {"auth": "spice", "port": "5921", "family": "ipv4", "host": "<IP_ADDRESS>"}, "client": {"port": "49004", "family": "ipv4", "channel-type": 3, "connection-id":<PHONE_NUMBER>, "host": "<IP_ADDRESS>", "channel-id": 0, "tls": true} }}
If: defined(CONFIG_SPICE)
Emitted when the SPICE connection is closed
Arguments:
server: SpiceBasicInfo
server information
client: SpiceBasicInfo
client information
Since: 0.14.0
Example:
<- { "timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 388707}, "event": "SPICE_DISCONNECTED", "data": { "server": { "port": "5920", "family": "ipv4", "host": "<IP_ADDRESS>"}, "client": {"port": "52873", "family": "ipv4", "host": "<IP_ADDRESS>"} }}
If: defined(CONFIG_SPICE)
Emitted when SPICE migration has completed
Since: 1.3
Example:
<- { "timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 417172}, "event": "SPICE_MIGRATE_COMPLETED" }
If: defined(CONFIG_SPICE)
The basic information for vnc network connection
Members:
host: string
IP address
service: string
The service name of the vnc port. This may depend on the host system’s service database so symbolic names should not be relied on.
family: NetworkAddressFamily
address family
websocket: boolean
true in case the socket is a websocket (since 2.3).
Since: 2.1
If: defined(CONFIG_VNC)
The network connection information for server
Members:
auth: string
(optional)authentication method used for the plain (non-websocket) VNC server
VncBasicInfo
Since: 2.1
If: defined(CONFIG_VNC)
Information about a connected VNC client.
Members:
x509_dname: string
(optional)If x509 authentication is in use, the Distinguished Name of the client.
sasl_username: string
(optional)If SASL authentication is in use, the SASL username used for authentication.
VncBasicInfo
Since: 0.14.0
If: defined(CONFIG_VNC)
Information about the VNC session.
Members:
enabled: boolean
true if the VNC server is enabled, false otherwise
host: string
(optional)The hostname the VNC server is bound to. This depends on the name resolution on the host and may be an IP address.
family: NetworkAddressFamily
(optional)service: string
(optional)The service name of the server’s port. This may depends on the host system’s service database so symbolic names should not be relied on.
auth: string
(optional)the current authentication type used by the server
clients: array of VncClientInfo
(optional)a list of VncClientInfo
of all currently connected clients
Since: 0.14.0
If: defined(CONFIG_VNC)
vnc primary authentication method.
Values:
none
Not documented
vnc
Not documented
ra2
Not documented
ra2ne
Not documented
tight
Not documented
ultra
Not documented
tls
Not documented
vencrypt
Not documented
sasl
Not documented
Since: 2.3
If: defined(CONFIG_VNC)
vnc sub authentication method with vencrypt.
Values:
plain
Not documented
tls-none
Not documented
x509-none
Not documented
tls-vnc
Not documented
x509-vnc
Not documented
tls-plain
Not documented
x509-plain
Not documented
tls-sasl
Not documented
x509-sasl
Not documented
Since: 2.3
If: defined(CONFIG_VNC)
The network connection information for server
Members:
auth: VncPrimaryAuth
The current authentication type used by the servers
vencrypt: VncVencryptSubAuth
(optional)The vencrypt sub authentication type used by the servers, only specified in case auth == vencrypt.
VncBasicInfo
Since: 2.9
If: defined(CONFIG_VNC)
Information about a vnc server
Members:
id: string
vnc server name.
server: array of VncServerInfo2
A list of VncBasincInfo
describing all listening sockets.
The list can be empty (in case the vnc server is disabled).
It also may have multiple entries: normal + websocket,
possibly also ipv4 + ipv6 in the future.
clients: array of VncClientInfo
A list of VncClientInfo
of all currently connected clients.
The list can be empty, for obvious reasons.
auth: VncPrimaryAuth
The current authentication type used by the non-websockets servers
vencrypt: VncVencryptSubAuth
(optional)The vencrypt authentication type used by the servers, only specified in case auth == vencrypt.
display: string
(optional)The display device the vnc server is linked to.
Since: 2.3
If: defined(CONFIG_VNC)
Returns information about the current VNC server
Returns:
VncInfo
Since: 0.14.0
Example:
-> { "execute": "query-vnc" } <- { "return": { "enabled":true, "host":"<IP_ADDRESS>", "service":"50402", "auth":"vnc", "family":"ipv4", "clients":[ { "host":"<IP_ADDRESS>", "service":"50401", "family":"ipv4" } ] } }
If: defined(CONFIG_VNC)
Returns a list of vnc servers. The list can be empty.
Returns:
a list of VncInfo2
Since: 2.3
If: defined(CONFIG_VNC)
Change the VNC server password.
Arguments:
password: string
the new password to use with VNC authentication
Since: 1.1
Notes: An empty password in this command will set the password to the empty string. Existing clients are unaffected by executing this command.
If: defined(CONFIG_VNC)
Emitted when a VNC client establishes a connection
Arguments:
server: VncServerInfo
server information
client: VncBasicInfo
client information
Note: This event is emitted before any authentication takes place, thus the authentication ID is not provided
Since: 0.13.0
Example:
<- { "event": "VNC_CONNECTED", "data": { "server": { "auth": "sasl", "family": "ipv4", "service": "5901", "host": "<IP_ADDRESS>" }, "client": { "family": "ipv4", "service": "58425", "host": "<IP_ADDRESS>" } }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 975795 } }
If: defined(CONFIG_VNC)
Emitted after authentication takes place (if any) and the VNC session is made active
Arguments:
server: VncServerInfo
server information
client: VncClientInfo
client information
Since: 0.13.0
Example:
<- { "event": "VNC_INITIALIZED", "data": { "server": { "auth": "sasl", "family": "ipv4", "service": "5901", "host": "<IP_ADDRESS>"}, "client": { "family": "ipv4", "service": "46089", "host": "<IP_ADDRESS>", "sasl_username": "luiz" } }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 150772 } }
If: defined(CONFIG_VNC)
Emitted when the connection is closed
Arguments:
server: VncServerInfo
server information
client: VncClientInfo
client information
Since: 0.13.0
Example:
<- { "event": "VNC_DISCONNECTED", "data": { "server": { "auth": "sasl", "family": "ipv4", "service": "5901", "host": "<IP_ADDRESS>" }, "client": { "family": "ipv4", "service": "58425", "host": "<IP_ADDRESS>", "sasl_username": "luiz" } }, "timestamp": { "seconds":<PHONE_NUMBER>, "microseconds": 975795 } }
If: defined(CONFIG_VNC)
Information about a mouse device.
Members:
name: string
the name of the mouse device
index: int
the index of the mouse device
current: boolean
true if this device is currently receiving mouse events
absolute: boolean
true if this device supports absolute coordinates as input
Since: 0.14.0
Returns information about each active mouse device
Returns:
a list of MouseInfo
for each device
Since: 0.14.0
Example:
-> { "execute": "query-mice" } <- { "return": [ { "name":"QEMU Microsoft Mouse", "index":0, "current":false, "absolute":false }, { "name":"QEMU PS/2 Mouse", "index":1, "current":true, "absolute":true } ] }
An enumeration of key name.
This is used by the send-key
command.
Values:
unmapped
since 2.0
pause
since 2.0
ro
since 2.4
kp_comma
since 2.4
kp_equals
since 2.6
power
since 2.6
hiragana
since 2.9
henkan
since 2.9
yen
since 2.9
sleep
since 2.10
wake
since 2.10
audionext
since 2.10
audioprev
since 2.10
audiostop
since 2.10
audioplay
since 2.10
audiomute
since 2.10
volumeup
since 2.10
volumedown
since 2.10
mediaselect
since 2.10
mail
since 2.10
calculator
since 2.10
computer
since 2.10
ac_home
since 2.10
ac_back
since 2.10
ac_forward
since 2.10
ac_refresh
since 2.10
ac_bookmarks
since 2.10
muhenkan
since 2.12
katakanahiragana
since 2.12
shift
Not documented
shift_r
Not documented
alt
Not documented
alt_r
Not documented
ctrl
Not documented
ctrl_r
Not documented
menu
Not documented
esc
Not documented
1
Not documented
2
Not documented
3
Not documented
4
Not documented
5
Not documented
6
Not documented
7
Not documented
8
Not documented
9
Not documented
0
Not documented
minus
Not documented
equal
Not documented
backspace
Not documented
tab
Not documented
q
Not documented
w
Not documented
e
Not documented
r
Not documented
t
Not documented
y
Not documented
u
Not documented
i
Not documented
o
Not documented
p
Not documented
bracket_left
Not documented
bracket_right
Not documented
ret
Not documented
a
Not documented
s
Not documented
d
Not documented
f
Not documented
g
Not documented
h
Not documented
j
Not documented
k
Not documented
l
Not documented
semicolon
Not documented
apostrophe
Not documented
grave_accent
Not documented
backslash
Not documented
z
Not documented
x
Not documented
c
Not documented
v
Not documented
b
Not documented
n
Not documented
m
Not documented
comma
Not documented
dot
Not documented
slash
Not documented
asterisk
Not documented
spc
Not documented
caps_lock
Not documented
f1
Not documented
f2
Not documented
f3
Not documented
f4
Not documented
f5
Not documented
f6
Not documented
f7
Not documented
f8
Not documented
f9
Not documented
f10
Not documented
num_lock
Not documented
scroll_lock
Not documented
kp_divide
Not documented
kp_multiply
Not documented
kp_subtract
Not documented
kp_add
Not documented
kp_enter
Not documented
kp_decimal
Not documented
sysrq
Not documented
kp_0
Not documented
kp_1
Not documented
kp_2
Not documented
kp_3
Not documented
kp_4
Not documented
kp_5
Not documented
kp_6
Not documented
kp_7
Not documented
kp_8
Not documented
kp_9
Not documented
less
Not documented
f11
Not documented
f12
Not documented
print
Not documented
home
Not documented
pgup
Not documented
pgdn
Not documented
end
Not documented
left
Not documented
up
Not documented
down
Not documented
right
Not documented
insert
Not documented
delete
Not documented
stop
Not documented
again
Not documented
props
Not documented
undo
Not documented
front
Not documented
copy
Not documented
open
Not documented
paste
Not documented
find
Not documented
cut
Not documented
lf
Not documented
help
Not documented
meta_l
Not documented
meta_r
Not documented
compose
Not documented
’sysrq’ was mistakenly added to hack around the fact that the ps2 driver was not generating correct scancodes sequences when ’alt+print’ was pressed. This flaw is now fixed and the ’sysrq’ key serves no further purpose. Any further use of ’sysrq’ will be transparently changed to ’print’, so they are effectively synonyms.
Since: 1.3.0
Represents a keyboard key.
Members:
type
One of "number", "qcode"
data: int
when type
is "number"data: QKeyCode
when type
is "qcode"Since: 1.3.0
Send keys to guest.
Arguments:
keys: array of KeyValue
An array of KeyValue
elements. All KeyValues
in this array are
simultaneously sent to the guest. A KeyValue
.number value is sent
directly to the guest, while KeyValue
.qcode must be a valid
QKeyCode
value
hold-time: int
(optional)time to delay key up events, milliseconds. Defaults to 100
Returns:
Since: 1.3.0
Example:
-> { "execute": "send-key", "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, { "type": "qcode", "data": "alt" }, { "type": "qcode", "data": "delete" } ] } } <- { "return": {} }
Button of a pointer input device (mouse, tablet).
Values:
side
front side button of a 5-button mouse (since 2.9)
extra
rear side button of a 5-button mouse (since 2.9)
left
Not documented
middle
Not documented
right
Not documented
wheel-up
Not documented
wheel-down
Not documented
Since: 2.0
Position axis of a pointer input device (mouse, tablet).
Values:
x
Not documented
y
Not documented
Since: 2.0
Keyboard input event.
Members:
key: KeyValue
Which key this event is for.
down: boolean
True for key-down and false for key-up events.
Since: 2.0
Pointer button input event.
Members:
button: InputButton
Which button this event is for.
down: boolean
True for key-down and false for key-up events.
Since: 2.0
Pointer motion input event.
Members:
axis: InputAxis
Which axis is referenced by value
.
value: int
Pointer position. For absolute coordinates the valid range is 0 -> 0x7ffff
Since: 2.0
Input event union.
Members:
type
the input type, one of:
data: InputKeyEvent
when type
is "key"data: InputBtnEvent
when type
is "btn"data: InputMoveEvent
when type
is "rel"data: InputMoveEvent
when type
is "abs"Since: 2.0
Send input event(s) to guest.
The device
and head
parameters can be used to send the input event
to specific input devices in case (a) multiple input devices of the
same kind are added to the virtual machine and (b) you have
configured input routing (see docs/multiseat.txt) for those input
devices. The parameters work exactly like the device and head
properties of input devices. If device
is missing, only devices
that have no input routing config are admissible. If device
is
specified, both input devices with and without input routing config
are admissible, but devices with input routing config take
precedence.
Arguments:
device: string
(optional)display device to send event(s) to.
head: int
(optional)head to send event(s) to, in case the display device supports multiple scanouts.
events: array of InputEvent
List of InputEvent union.
Returns: Nothing on success.
Since: 2.6
Note: The consoles are visible in the qom tree, under /backend/console[$index]. They have a device link and head property, so it is possible to map which console belongs to which device and display.
Example:
1. Press left mouse button. -> { "execute": "input-send-event", "arguments": { "device": "video0", "events": [ { "type": "btn", "data" : { "down": true, "button": "left" } } ] } } <- { "return": {} } -> { "execute": "input-send-event", "arguments": { "device": "video0", "events": [ { "type": "btn", "data" : { "down": false, "button": "left" } } ] } } <- { "return": {} } 2. Press ctrl-alt-del. -> { "execute": "input-send-event", "arguments": { "events": [ { "type": "key", "data" : { "down": true, "key": {"type": "qcode", "data": "ctrl" } } }, { "type": "key", "data" : { "down": true, "key": {"type": "qcode", "data": "alt" } } }, { "type": "key", "data" : { "down": true, "key": {"type": "qcode", "data": "delete" } } } ] } } <- { "return": {} } 3. Move mouse pointer to absolute coordinates (20000, 400). -> { "execute": "input-send-event" , "arguments": { "events": [ { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } <- { "return": {} }
Keys to toggle input-linux between host and guest.
Values:
ctrl-ctrl
Not documented
alt-alt
Not documented
shift-shift
Not documented
meta-meta
Not documented
scrolllock
Not documented
ctrl-scrolllock
Not documented
Since: 4.0
GTK display options.
Members:
grab-on-hover: boolean
(optional)Grab keyboard input on mouse hover.
zoom-to-fit: boolean
(optional)Zoom guest display to fit into the host window. When turned off the host window will be resized instead. In case the display device can notify the guest on window resizes (virtio-gpu) this will default to "on", assuming the guest will resize the display to match the window size then. Otherwise it defaults to "off". Since 3.1
Since: 2.12
EGL headless display options.
Members:
rendernode: string
(optional)Which DRM render node should be used. Default is the first available node on the host.
Since: 3.1
Display OpenGL mode.
Values:
off
Disable OpenGL (default).
on
Use OpenGL, pick context type automatically. Would better be named ’auto’ but is called ’on’ for backward compatibility with bool type.
core
Use OpenGL with Core (desktop) Context.
es
Use OpenGL with ES (embedded systems) Context.
Since: 3.0
Curses display options.
Members:
charset: string
(optional)Font charset used by guest (default: CP437).
Since: 4.0
Display (user interface) type.
Values:
default
The default user interface, selecting from the first available of gtk, sdl, cocoa, and vnc.
none
No user interface or video output display. The guest will still see an emulated graphics card, but its output will not be displayed to the QEMU user.
gtk
The GTK user interface.
sdl
The SDL user interface.
egl-headless
No user interface, offload GL operations to a local DRI device. Graphical display need to be paired with VNC or Spice. (Since 3.1)
curses
Display video output via curses. For graphics device models which support a text mode, QEMU can display this output using a curses/ncurses interface. Nothing is displayed when the graphics device is in graphical mode or if the graphics device does not support a text mode. Generally only the VGA device models support text mode.
cocoa
The Cocoa user interface.
spice-app
Set up a Spice server and run the default associated application to connect to it. The server will redirect the serial console and QEMU monitors. (Since 4.0)
Since: 2.12
Display (user interface) options.
Members:
type: DisplayType
Which DisplayType qemu should use.
full-screen: boolean
(optional)Start user interface in fullscreen mode (default: off).
window-close: boolean
(optional)Allow to quit qemu with window close button (default: on).
show-cursor: boolean
(optional)Force showing the mouse cursor (default: off). (since: 5.0)
gl: DisplayGLMode
(optional)Enable OpenGL support (default: off).
DisplayGTK
when type
is "gtk"DisplayCurses
when type
is "curses"DisplayEGLHeadless
when type
is "egl-headless"Since: 2.12
Returns information about display configuration
Returns:
DisplayOptions
Since: 3.1
The authorization policy result
Values:
deny
deny access
allow
allow access
Since: 4.0
The authorization policy match format
Values:
exact
an exact string match
glob
string with ? and * shell wildcard support
Since: 4.0
A single authorization rule.
Members:
match: string
a string or glob to match against a user identity
policy: QAuthZListPolicy
the result to return if match
evaluates to true
format: QAuthZListFormat
(optional)the format of the match
rule (default ’exact’)
Since: 4.0
Not exposed via QMP; hack to generate QAuthZListRuleList for use internally by the code.
Members:
unused: array of QAuthZListRule
Not documented
Since: 4.0
Detailed migration status.
Members:
transferred: int
amount of bytes already transferred to the target VM
remaining: int
amount of bytes remaining to be transferred to the target VM
total: int
total amount of bytes involved in the migration process
duplicate: int
number of duplicate (zero) pages (since 1.2)
skipped: int
number of skipped zero pages (since 1.5)
normal: int
number of normal pages (since 1.2)
normal-bytes: int
number of normal bytes sent (since 1.2)
dirty-pages-rate: int
number of pages dirtied by second by the guest (since 1.3)
mbps: number
throughput in megabits/sec. (since 1.6)
dirty-sync-count: int
number of times that dirty ram was synchronized (since 2.1)
postcopy-requests: int
The number of page requests received from the destination (since 2.7)
page-size: int
The number of bytes per page for the various page-based statistics (since 2.10)
multifd-bytes: int
The number of bytes sent through multifd (since 3.0)
pages-per-second: int
the number of memory pages transferred per second (Since 4.0)
Since: 0.14.0
Detailed XBZRLE migration cache statistics
Members:
cache-size: int
XBZRLE cache size
bytes: int
amount of bytes already transferred to the target VM
pages: int
amount of pages transferred to the target VM
cache-miss: int
number of cache miss
cache-miss-rate: number
rate of cache miss (since 2.1)
encoding-rate: number
rate of encoded bytes (since 5.1)
overflow: int
number of overflows
Since: 1.2
Detailed migration compression statistics
Members:
pages: int
amount of pages compressed and transferred to the target VM
busy: int
count of times that no free thread was available to compress data
busy-rate: number
rate of thread busy
compressed-size: int
amount of bytes after compression
compression-rate: number
rate of compressed size
Since: 3.1
An enumeration of migration status.
Values:
none
no migration has ever happened.
setup
migration process has been initiated.
cancelling
in the process of cancelling migration.
cancelled
cancelling migration is finished.
active
in the process of doing migration.
postcopy-active
like active, but now in postcopy mode. (since 2.5)
postcopy-paused
during postcopy but paused. (since 3.0)
postcopy-recover
trying to recover from a paused postcopy. (since 3.0)
completed
migration is finished.
failed
some error occurred during migration process.
colo
VM is in the process of fault tolerance, VM can not get into this state unless colo capability is enabled for migration. (since 2.8)
pre-switchover
Paused before device serialisation. (since 2.11)
device
During device serialisation when pause-before-switchover is enabled (since 2.11)
wait-unplug
wait for device unplug request by guest OS to be completed. (since 4.2)
Since: 2.3
Information about current migration process.
Members:
status: MigrationStatus
(optional)MigrationStatus
describing the current migration status.
If this field is not returned, no migration process
has been initiated
ram: MigrationStats
(optional)MigrationStats
containing detailed migration
status, only returned if status is ’active’ or
’completed’(since 1.2)
disk: MigrationStats
(optional)MigrationStats
containing detailed disk migration
status, only returned if status is ’active’ and it is a block
migration
xbzrle-cache: XBZRLECacheStats
(optional)XBZRLECacheStats
containing detailed XBZRLE
migration statistics, only returned if XBZRLE feature is on and
status is ’active’ or ’completed’ (since 1.2)
total-time: int
(optional)total amount of milliseconds since migration started. If migration has ended, it returns the total migration time. (since 1.2)
downtime: int
(optional)only present when migration finishes correctly total downtime in milliseconds for the guest. (since 1.3)
expected-downtime: int
(optional)only present while migration is active expected downtime in milliseconds for the guest in last walk of the dirty bitmap. (since 1.3)
setup-time: int
(optional)amount of setup time in milliseconds before the iterations begin but after the QMP command is issued. This is designed to provide an accounting of any activities (such as RDMA pinning) which may be expensive, but do not actually occur during the iterative migration rounds themselves. (since 1.6)
cpu-throttle-percentage: int
(optional)percentage of time guest cpus are being throttled during auto-converge. This is only present when auto-converge has started throttling guest cpus. (Since 2.7)
error-desc: string
(optional)the human readable error description string, when
status
is ’failed’. Clients should not attempt to parse the
error strings. (Since 2.7)
postcopy-blocktime: int
(optional)total time when all vCPU were blocked during postcopy live migration. This is only present when the postcopy-blocktime migration capability is enabled. (Since 3.0)
postcopy-vcpu-blocktime: array of int
(optional)list of the postcopy blocktime per vCPU. This is only present when the postcopy-blocktime migration capability is enabled. (Since 3.0)
compression: CompressionStats
(optional)migration compression statistics, only returned if compression feature is on and status is ’active’ or ’completed’ (Since 3.1)
socket-address: array of SocketAddress
(optional)Only used for tcp, to know what the real port is (Since 4.0)
Since: 0.14.0
Returns information about current migration process. If migration is active there will be another json-object with RAM migration status and if block migration is active another one with block migration status.
Returns:
MigrationInfo
Since: 0.14.0
Example:
1. Before the first migration -> { "execute": "query-migrate" } <- { "return": {} } 2. Migration is done and has succeeded -> { "execute": "query-migrate" } <- { "return": { "status": "completed", "total-time":12345, "setup-time":12345, "downtime":12345, "ram":{ "transferred":123, "remaining":123, "total":246, "duplicate":123, "normal":123, "normal-bytes":123456, "dirty-sync-count":15 } } } 3. Migration is done and has failed -> { "execute": "query-migrate" } <- { "return": { "status": "failed" } } 4. Migration is being performed and is not a block migration: -> { "execute": "query-migrate" } <- { "return":{ "status":"active", "total-time":12345, "setup-time":12345, "expected-downtime":12345, "ram":{ "transferred":123, "remaining":123, "total":246, "duplicate":123, "normal":123, "normal-bytes":123456, "dirty-sync-count":15 } } } 5. Migration is being performed and is a block migration: -> { "execute": "query-migrate" } <- { "return":{ "status":"active", "total-time":12345, "setup-time":12345, "expected-downtime":12345, "ram":{ "total":1057024, "remaining":1053304, "transferred":3720, "duplicate":123, "normal":123, "normal-bytes":123456, "dirty-sync-count":15 }, "disk":{ "total":20971520, "remaining":20880384, "transferred":91136 } } } 6. Migration is being performed and XBZRLE is active: -> { "execute": "query-migrate" } <- { "return":{ "status":"active", "total-time":12345, "setup-time":12345, "expected-downtime":12345, "ram":{ "total":1057024, "remaining":1053304, "transferred":3720, "duplicate":10, "normal":3333, "normal-bytes":3412992, "dirty-sync-count":15 }, "xbzrle-cache":{ "cache-size":67108864, "bytes":20971520, "pages":2444343, "cache-miss":2244, "cache-miss-rate":0.123, "encoding-rate":80.1, "overflow":34434 } } }
Migration capabilities enumeration
Values:
xbzrle
Migration supports xbzrle (Xor Based Zero Run Length Encoding). This feature allows us to minimize migration traffic for certain work loads, by sending compressed difference of the pages
rdma-pin-all
Controls whether or not the entire VM memory footprint is mlock()’d on demand or all at once. Refer to docs/rdma.txt for usage. Disabled by default. (since 2.0)
zero-blocks
During storage migration encode blocks of zeroes efficiently. This essentially saves 1MB of zeroes per block on the wire. Enabling requires source and target VM to support this feature. To enable it is sufficient to enable the capability on the source VM. The feature is disabled by default. (since 1.6)
compress
Use multiple compression threads to accelerate live migration. This feature can help to reduce the migration traffic, by sending compressed pages. Please note that if compress and xbzrle are both on, compress only takes effect in the ram bulk stage, after that, it will be disabled and only xbzrle takes effect, this can help to minimize migration traffic. The feature is disabled by default. (since 2.4 )
events
generate events for each migration state change (since 2.4 )
auto-converge
If enabled, QEMU will automatically throttle down the guest to speed up convergence of RAM migration. (since 1.6)
postcopy-ram
Start executing on the migration target before all of RAM has been migrated, pulling the remaining pages along as needed. The capacity must have the same setting on both source and target or migration will not even start. NOTE: If the migration fails during postcopy the VM will fail. (since 2.6)
x-colo
If enabled, migration will never end, and the state of the VM on the primary side will be migrated continuously to the VM on secondary side, this process is called COarse-Grain LOck Stepping (COLO) for Non-stop Service. (since 2.8)
release-ram
if enabled, qemu will free the migrated ram pages on the source during postcopy-ram migration. (since 2.9)
block
If enabled, QEMU will also migrate the contents of all block devices. Default is disabled. A possible alternative uses mirror jobs to a builtin NBD server on the destination, which offers more flexibility. (Since 2.10)
return-path
If enabled, migration will use the return path even for precopy. (since 2.10)
pause-before-switchover
Pause outgoing migration before serialising device state and before disabling block IO (since 2.11)
multifd
Use more than one fd for migration (since 4.0)
dirty-bitmaps
If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
postcopy-blocktime
Calculate downtime for postcopy live migration (since 3.0)
late-block-activate
If enabled, the destination will not activate block devices (and thus take locks) immediately at the end of migration. (since 3.0)
x-ignore-shared
If enabled, QEMU will not migrate shared memory (since 4.0)
validate-uuid
Send the UUID of the source to allow the destination to ensure it is the same. (since 4.2)
Since: 1.2
Migration capability information
Members:
capability: MigrationCapability
capability enum
state: boolean
capability state bool
Since: 1.2
Enable/Disable the following migration capabilities (like xbzrle)
Arguments:
capabilities: array of MigrationCapabilityStatus
json array of capability modifications to make
Since: 1.2
Example:
-> { "execute": "migrate-set-capabilities" , "arguments": { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
Returns information about the current migration capabilities status
Returns:
MigrationCapabilitiesStatus
Since: 1.2
Example:
-> { "execute": "query-migrate-capabilities" } <- { "return": [ {"state": false, "capability": "xbzrle"}, {"state": false, "capability": "rdma-pin-all"}, {"state": false, "capability": "auto-converge"}, {"state": false, "capability": "zero-blocks"}, {"state": false, "capability": "compress"}, {"state": true, "capability": "events"}, {"state": false, "capability": "postcopy-ram"}, {"state": false, "capability": "x-colo"} ]}
An enumeration of multifd compression methods.
Values:
none
no compression.
zlib
use zlib compression method.
zstd
use zstd compression method.
If: defined(CONFIG_ZSTD)
Since: 5.0
Migration parameters enumeration
Values:
announce-initial
Initial delay (in milliseconds) before sending the first announce (Since 4.0)
announce-max
Maximum delay (in milliseconds) between packets in the announcement (Since 4.0)
announce-rounds
Number of self-announce packets sent after migration (Since 4.0)
announce-step
Increase in delay (in milliseconds) between subsequent packets in the announcement (Since 4.0)
compress-level
Set the compression level to be used in live migration, the compression level is an integer between 0 and 9, where 0 means no compression, 1 means the best compression speed, and 9 means best compression ratio which will consume more CPU.
compress-threads
Set compression thread count to be used in live migration, the compression thread count is an integer between 1 and 255.
compress-wait-thread
Controls behavior when all compression threads are currently busy. If true (default), wait for a free compression thread to become available; otherwise, send the page uncompressed. (Since 3.1)
decompress-threads
Set decompression thread count to be used in live migration, the decompression thread count is an integer between 1 and 255. Usually, decompression is at least 4 times as fast as compression, so set the decompress-threads to the number about 1/4 of compress-threads is adequate.
throttle-trigger-threshold
The ratio of bytes_dirty_period and bytes_xfer_period to trigger throttling. It is expressed as percentage. The default value is 50. (Since 5.0)
cpu-throttle-initial
Initial percentage of time guest cpus are throttled when migration auto-converge is activated. The default value is 20. (Since 2.7)
cpu-throttle-increment
throttle percentage increase each time auto-converge detects that migration is not making progress. The default value is 10. (Since 2.7)
cpu-throttle-tailslow
Make CPU throttling slower at tail stage
At the tail stage of throttling, the Guest is very
sensitive to CPU percentage while the cpu-throttle
-increment is excessive usually at tail stage.
If this parameter is true, we will compute the ideal
CPU percentage used by the Guest, which may exactly make
the dirty rate match the dirty rate threshold. Then we
will choose a smaller throttle increment between the
one specified by cpu-throttle-increment
and the one
generated by ideal CPU percentage.
Therefore, it is compatible to traditional throttling,
meanwhile the throttle increment won’t be excessive
at tail stage.
The default value is false. (Since 5.1)
tls-creds
ID of the ’tls-creds’ object that provides credentials for establishing a TLS connection over the migration data channel. On the outgoing side of the migration, the credentials must be for a ’client’ endpoint, while for the incoming side the credentials must be for a ’server’ endpoint. Setting this will enable TLS for all migrations. The default is unset, resulting in unsecured migration at the QEMU level. (Since 2.7)
tls-hostname
hostname of the target host for the migration. This is required when using x509 based TLS credentials and the migration URI does not already include a hostname. For example if using fd: or exec: based migration, the hostname must be provided so that the server’s x509 certificate identity can be validated. (Since 2.7)
tls-authz
ID of the ’authz’ object subclass that provides access control checking of the TLS x509 certificate distinguished name. This object is only resolved at time of use, so can be deleted and recreated on the fly while the migration server is active. If missing, it will default to denying access (Since 4.0)
max-bandwidth
to set maximum speed for migration. maximum speed in bytes per second. (Since 2.8)
downtime-limit
set maximum tolerated downtime for migration. maximum downtime in milliseconds (Since 2.8)
x-checkpoint-delay
The delay time (in ms) between two COLO checkpoints in periodic mode. (Since 2.8)
block-incremental
Affects how much storage is migrated when the block migration capability is enabled. When false, the entire storage backing chain is migrated into a flattened image at the destination; when true, only the active qcow2 layer is migrated and the destination must already have access to the same backing chain as was used on the source. (since 2.10)
multifd-channels
Number of channels used to migrate data in parallel. This is the same number that the number of sockets used for migration. The default value is 2 (since 4.0)
xbzrle-cache-size
cache size to be used by XBZRLE migration. It needs to be a multiple of the target page size and a power of 2 (Since 2.11)
max-postcopy-bandwidth
Background transfer bandwidth during postcopy. Defaults to 0 (unlimited). In bytes per second. (Since 3.0)
max-cpu-throttle
maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
multifd-compression
Which compression method to use. Defaults to none. (Since 5.0)
multifd-zlib-level
Set the compression level to be used in live migration, the compression level is an integer between 0 and 9, where 0 means no compression, 1 means the best compression speed, and 9 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
multifd-zstd-level
Set the compression level to be used in live migration, the compression level is an integer between 0 and 20, where 0 means no compression, 1 means the best compression speed, and 20 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
Since: 2.4
Members:
announce-initial: int
(optional)Initial delay (in milliseconds) before sending the first announce (Since 4.0)
announce-max: int
(optional)Maximum delay (in milliseconds) between packets in the announcement (Since 4.0)
announce-rounds: int
(optional)Number of self-announce packets sent after migration (Since 4.0)
announce-step: int
(optional)Increase in delay (in milliseconds) between subsequent packets in the announcement (Since 4.0)
compress-level: int
(optional)compression level
compress-threads: int
(optional)compression thread count
compress-wait-thread: boolean
(optional)Controls behavior when all compression threads are currently busy. If true (default), wait for a free compression thread to become available; otherwise, send the page uncompressed. (Since 3.1)
decompress-threads: int
(optional)decompression thread count
throttle-trigger-threshold: int
(optional)The ratio of bytes_dirty_period and bytes_xfer_period to trigger throttling. It is expressed as percentage. The default value is 50. (Since 5.0)
cpu-throttle-initial: int
(optional)Initial percentage of time guest cpus are throttled when migration auto-converge is activated. The default value is 20. (Since 2.7)
cpu-throttle-increment: int
(optional)throttle percentage increase each time auto-converge detects that migration is not making progress. The default value is 10. (Since 2.7)
cpu-throttle-tailslow: boolean
(optional)Make CPU throttling slower at tail stage
At the tail stage of throttling, the Guest is very
sensitive to CPU percentage while the cpu-throttle
-increment is excessive usually at tail stage.
If this parameter is true, we will compute the ideal
CPU percentage used by the Guest, which may exactly make
the dirty rate match the dirty rate threshold. Then we
will choose a smaller throttle increment between the
one specified by cpu-throttle-increment
and the one
generated by ideal CPU percentage.
Therefore, it is compatible to traditional throttling,
meanwhile the throttle increment won’t be excessive
at tail stage.
The default value is false. (Since 5.1)
tls-creds: StrOrNull
(optional)ID of the ’tls-creds’ object that provides credentials for establishing a TLS connection over the migration data channel. On the outgoing side of the migration, the credentials must be for a ’client’ endpoint, while for the incoming side the credentials must be for a ’server’ endpoint. Setting this to a non-empty string enables TLS for all migrations. An empty string means that QEMU will use plain text mode for migration, rather than TLS (Since 2.9) Previously (since 2.7), this was reported by omitting tls-creds instead.
tls-hostname: StrOrNull
(optional)hostname of the target host for the migration. This is required when using x509 based TLS credentials and the migration URI does not already include a hostname. For example if using fd: or exec: based migration, the hostname must be provided so that the server’s x509 certificate identity can be validated. (Since 2.7) An empty string means that QEMU will use the hostname associated with the migration URI, if any. (Since 2.9) Previously (since 2.7), this was reported by omitting tls-hostname instead.
max-bandwidth: int
(optional)to set maximum speed for migration. maximum speed in bytes per second. (Since 2.8)
downtime-limit: int
(optional)set maximum tolerated downtime for migration. maximum downtime in milliseconds (Since 2.8)
x-checkpoint-delay: int
(optional)the delay time between two COLO checkpoints. (Since 2.8)
block-incremental: boolean
(optional)Affects how much storage is migrated when the block migration capability is enabled. When false, the entire storage backing chain is migrated into a flattened image at the destination; when true, only the active qcow2 layer is migrated and the destination must already have access to the same backing chain as was used on the source. (since 2.10)
multifd-channels: int
(optional)Number of channels used to migrate data in parallel. This is the same number that the number of sockets used for migration. The default value is 2 (since 4.0)
xbzrle-cache-size: int
(optional)cache size to be used by XBZRLE migration. It needs to be a multiple of the target page size and a power of 2 (Since 2.11)
max-postcopy-bandwidth: int
(optional)Background transfer bandwidth during postcopy. Defaults to 0 (unlimited). In bytes per second. (Since 3.0)
max-cpu-throttle: int
(optional)maximum cpu throttle percentage. The default value is 99. (Since 3.1)
multifd-compression: MultiFDCompression
(optional)Which compression method to use. Defaults to none. (Since 5.0)
multifd-zlib-level: int
(optional)Set the compression level to be used in live migration, the compression level is an integer between 0 and 9, where 0 means no compression, 1 means the best compression speed, and 9 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
multifd-zstd-level: int
(optional)Set the compression level to be used in live migration, the compression level is an integer between 0 and 20, where 0 means no compression, 1 means the best compression speed, and 20 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
tls-authz: StrOrNull
(optional)Not documented
Since: 2.4
Set various migration parameters.
Arguments: the members of MigrateSetParameters
Since: 2.4
Example:
-> { "execute": "migrate-set-parameters" , "arguments": { "compress-level": 1 } }
The optional members aren’t actually optional.
Members:
announce-initial: int
(optional)Initial delay (in milliseconds) before sending the first announce (Since 4.0)
announce-max: int
(optional)Maximum delay (in milliseconds) between packets in the announcement (Since 4.0)
announce-rounds: int
(optional)Number of self-announce packets sent after migration (Since 4.0)
announce-step: int
(optional)Increase in delay (in milliseconds) between subsequent packets in the announcement (Since 4.0)
compress-level: int
(optional)compression level
compress-threads: int
(optional)compression thread count
compress-wait-thread: boolean
(optional)Controls behavior when all compression threads are currently busy. If true (default), wait for a free compression thread to become available; otherwise, send the page uncompressed. (Since 3.1)
decompress-threads: int
(optional)decompression thread count
throttle-trigger-threshold: int
(optional)The ratio of bytes_dirty_period and bytes_xfer_period to trigger throttling. It is expressed as percentage. The default value is 50. (Since 5.0)
cpu-throttle-initial: int
(optional)Initial percentage of time guest cpus are throttled when migration auto-converge is activated. (Since 2.7)
cpu-throttle-increment: int
(optional)throttle percentage increase each time auto-converge detects that migration is not making progress. (Since 2.7)
cpu-throttle-tailslow: boolean
(optional)Make CPU throttling slower at tail stage
At the tail stage of throttling, the Guest is very
sensitive to CPU percentage while the cpu-throttle
-increment is excessive usually at tail stage.
If this parameter is true, we will compute the ideal
CPU percentage used by the Guest, which may exactly make
the dirty rate match the dirty rate threshold. Then we
will choose a smaller throttle increment between the
one specified by cpu-throttle-increment
and the one
generated by ideal CPU percentage.
Therefore, it is compatible to traditional throttling,
meanwhile the throttle increment won’t be excessive
at tail stage.
The default value is false. (Since 5.1)
tls-creds: string
(optional)ID of the ’tls-creds’ object that provides credentials for establishing a TLS connection over the migration data channel. On the outgoing side of the migration, the credentials must be for a ’client’ endpoint, while for the incoming side the credentials must be for a ’server’ endpoint. An empty string means that QEMU will use plain text mode for migration, rather than TLS (Since 2.7) Note: 2.8 reports this by omitting tls-creds instead.
tls-hostname: string
(optional)hostname of the target host for the migration. This is required when using x509 based TLS credentials and the migration URI does not already include a hostname. For example if using fd: or exec: based migration, the hostname must be provided so that the server’s x509 certificate identity can be validated. (Since 2.7) An empty string means that QEMU will use the hostname associated with the migration URI, if any. (Since 2.9) Note: 2.8 reports this by omitting tls-hostname instead.
tls-authz: string
(optional)ID of the ’authz’ object subclass that provides access control checking of the TLS x509 certificate distinguished name. (Since 4.0)
max-bandwidth: int
(optional)to set maximum speed for migration. maximum speed in bytes per second. (Since 2.8)
downtime-limit: int
(optional)set maximum tolerated downtime for migration. maximum downtime in milliseconds (Since 2.8)
x-checkpoint-delay: int
(optional)the delay time between two COLO checkpoints. (Since 2.8)
block-incremental: boolean
(optional)Affects how much storage is migrated when the block migration capability is enabled. When false, the entire storage backing chain is migrated into a flattened image at the destination; when true, only the active qcow2 layer is migrated and the destination must already have access to the same backing chain as was used on the source. (since 2.10)
multifd-channels: int
(optional)Number of channels used to migrate data in parallel. This is the same number that the number of sockets used for migration. The default value is 2 (since 4.0)
xbzrle-cache-size: int
(optional)cache size to be used by XBZRLE migration. It needs to be a multiple of the target page size and a power of 2 (Since 2.11)
max-postcopy-bandwidth: int
(optional)Background transfer bandwidth during postcopy. Defaults to 0 (unlimited). In bytes per second. (Since 3.0)
max-cpu-throttle: int
(optional)maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
multifd-compression: MultiFDCompression
(optional)Which compression method to use. Defaults to none. (Since 5.0)
multifd-zlib-level: int
(optional)Set the compression level to be used in live migration, the compression level is an integer between 0 and 9, where 0 means no compression, 1 means the best compression speed, and 9 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
multifd-zstd-level: int
(optional)Set the compression level to be used in live migration, the compression level is an integer between 0 and 20, where 0 means no compression, 1 means the best compression speed, and 20 means best compression ratio which will consume more CPU. Defaults to 1. (Since 5.0)
Since: 2.4
Returns information about the current migration parameters
Returns:
MigrationParameters
Since: 2.4
Example:
-> { "execute": "query-migrate-parameters" } <- { "return": { "decompress-threads": 2, "cpu-throttle-increment": 10, "compress-threads": 8, "compress-level": 1, "cpu-throttle-initial": 20, "max-bandwidth": 33554432, "downtime-limit": 300 } }
Set migration information for remote display. This makes the server ask the client to automatically reconnect using the new parameters once migration finished successfully. Only implemented for SPICE.
Arguments:
protocol: string
must be "spice"
hostname: string
migration target hostname
port: int
(optional)spice tcp port for plaintext channels
tls-port: int
(optional)spice tcp port for tls-secured channels
cert-subject: string
(optional)server certificate subject
Since: 0.14.0
Example:
-> { "execute": "client_migrate_info", "arguments": { "protocol": "spice", "hostname": "virt42.lab.kraxel.org", "port": 1234 } } <- { "return": {} }
Followup to a migration command to switch the migration to postcopy mode. The postcopy-ram capability must be set on both source and destination before the original migration command.
Since: 2.5
Example:
-> { "execute": "migrate-start-postcopy" } <- { "return": {} }
Emitted when a migration event happens
Arguments:
status: MigrationStatus
MigrationStatus
describing the current migration status.
Since: 2.4
Example:
<- {"timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 744001}, "event": "MIGRATION", "data": {"status": "completed"} }
Emitted from the source side of a migration at the start of each pass (when it syncs the dirty bitmap)
Arguments:
pass: int
An incrementing count (starting at 1 on the first pass)
Since: 2.6
Example:
{ "timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 239225}, "event": "MIGRATION_PASS", "data": {"pass": 2} }
The message transmission between Primary side and Secondary side.
Values:
checkpoint-ready
Secondary VM (SVM) is ready for checkpointing
checkpoint-request
Primary VM (PVM) tells SVM to prepare for checkpointing
checkpoint-reply
SVM gets PVM’s checkpoint request
vmstate-send
VM’s state will be sent by PVM.
vmstate-size
The total size of VMstate.
vmstate-received
VM’s state has been received by SVM.
vmstate-loaded
VM’s state has been loaded by SVM.
Since: 2.8
The COLO current mode.
Values:
none
COLO is disabled.
primary
COLO node in primary side.
secondary
COLO node in slave side.
Since: 2.8
An enumeration of COLO failover status
Values:
none
no failover has ever happened
require
got failover requirement but not handled
active
in the process of doing failover
completed
finish the process of failover
relaunch
restart the failover process, from ’none’ -> ’completed’ (Since 2.9)
Since: 2.8
Emitted when VM finishes COLO mode due to some errors happening or at the request of users.
Arguments:
mode: COLOMode
report COLO mode when COLO exited.
reason: COLOExitReason
describes the reason for the COLO exit.
Since: 3.1
Example:
<- { "timestamp": {"seconds":<PHONE_NUMBER>, "microseconds": 417172}, "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
The reason for a COLO exit.
Values:
none
failover has never happened. This state does not occur in the COLO_EXIT event, and is only visible in the result of query-colo-status.
request
COLO exit is due to an external request.
error
COLO exit is due to an internal error.
processing
COLO is currently handling a failover (since 4.0).
Since: 3.1
Tell qemu that heartbeat is lost, request it to do takeover procedures. If this command is sent to the PVM, the Primary side will exit COLO mode. If sent to the Secondary, the Secondary side will run failover work, then takes over server operation to become the service VM.
Since: 2.8
Example:
-> { "execute": "x-colo-lost-heartbeat" } <- { "return": {} }
Cancel the current executing migration process.
Returns: nothing on success
Notes: This command succeeds even if there is no migration process running.
Since: 0.14.0
Example:
-> { "execute": "migrate_cancel" } <- { "return": {} }
Continue migration when it’s in a paused state.
Arguments:
state: MigrationStatus
The state the migration is currently expected to be in
Returns: nothing on success
Since: 2.11
Example:
-> { "execute": "migrate-continue" , "arguments": { "state": "pre-switchover" } } <- { "return": {} }
Set maximum tolerated downtime for migration.
Arguments:
value: number
maximum downtime in seconds
Features:
deprecated
This command is deprecated. Use ’migrate-set-parameters’ instead.
Returns: nothing on success
Since: 0.14.0
Example:
-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } } <- { "return": {} }
Set maximum speed for migration.
Arguments:
value: int
maximum speed in bytes per second.
Features:
deprecated
This command is deprecated. Use ’migrate-set-parameters’ instead.
Returns: nothing on success
Since: 0.14.0
Example:
-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } } <- { "return": {} }
Set cache size to be used by XBZRLE migration
Arguments:
value: int
cache size in bytes
Features:
deprecated
This command is deprecated. Use ’migrate-set-parameters’ instead.
The size will be rounded down to the nearest power of 2. The cache size can be modified before and during ongoing migration
Returns: nothing on success
Since: 1.2
Example:
-> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } } <- { "return": {} }
Query migration XBZRLE cache size
Features:
deprecated
This command is deprecated. Use ’query-migrate-parameters’ instead.
Returns: XBZRLE cache size in bytes
Since: 1.2
Example:
-> { "execute": "query-migrate-cache-size" } <- { "return": 67108864 }
Migrates the current running guest to another Virtual Machine.
Arguments:
uri: string
the Uniform Resource Identifier of the destination VM
blk: boolean
(optional)do block migration (full disk copy)
inc: boolean
(optional)incremental disk copy migration
detach: boolean
(optional)this argument exists only for compatibility reasons and is ignored by QEMU
resume: boolean
(optional)resume one paused migration, default "off". (since 3.0)
Returns: nothing on success
Since: 0.14.0
Notes:
Example:
-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } <- { "return": {} }
Start an incoming migration, the qemu must have been started with -incoming defer
Arguments:
uri: string
The Uniform Resource Identifier identifying the source or address to listen on
Returns: nothing on success
Since: 2.3
Notes:
Example:
-> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } } <- { "return": {} }
Save the state of all devices to file. The RAM and the block devices of the VM are not saved by this command.
Arguments:
filename: string
the file to save the state of the devices to as binary data. See xen-save-devices-state.txt for a description of the binary format.
live: boolean
(optional)Optional argument to ask QEMU to treat this command as part of a live migration. Default to true. (since 2.11)
Returns: Nothing on success
Since: 1.1
Example:
-> { "execute": "xen-save-devices-state", "arguments": { "filename": "/tmp/save" } } <- { "return": {} }
Enable or disable replication.
Arguments:
enable: boolean
true to enable, false to disable.
primary: boolean
true for primary or false for secondary.
failover: boolean
(optional)true to do failover, false to stop. but cannot be specified if ’enable’ is true. default value is false.
Returns: nothing.
Example:
-> { "execute": "xen-set-replication", "arguments": {"enable": true, "primary": false} } <- { "return": {} }
Since: 2.9
If: defined(CONFIG_REPLICATION)
The result format for ’query-xen-replication-status’.
Members:
error: boolean
true if an error happened, false if replication is normal.
desc: string
(optional)the human readable error description string, when
error
is ’true’.
Since: 2.9
If: defined(CONFIG_REPLICATION)
Query replication status while the vm is running.
Returns:
A ReplicationResult
object showing the status.
Example:
-> { "execute": "query-xen-replication-status" } <- { "return": { "error": false } }
Since: 2.9
If: defined(CONFIG_REPLICATION)
Xen uses this command to notify replication to trigger a checkpoint.
Returns: nothing.
Example:
-> { "execute": "xen-colo-do-checkpoint" } <- { "return": {} }
Since: 2.9
If: defined(CONFIG_REPLICATION)
The result format for ’query-colo-status’.
Members:
mode: COLOMode
COLO running mode. If COLO is running, this field will return ’primary’ or ’secondary’.
last-mode: COLOMode
COLO last running mode. If COLO is running, this field will return same like mode field, after failover we can use this field to get last colo mode. (since 4.0)
reason: COLOExitReason
describes the reason for the COLO exit.
Since: 3.1
Query COLO status while the vm is running.
Returns:
A COLOStatus
object showing the status.
Example:
-> { "execute": "query-colo-status" } <- { "return": { "mode": "primary", "reason": "request" } }
Since: 3.1
Provide a recovery migration stream URI.
Arguments:
uri: string
the URI to be used for the recovery of migration stream.
Returns: nothing.
Example:
-> { "execute": "migrate-recover", "arguments": { "uri": "tcp:<IP_ADDRESS>:12345" } } <- { "return": {} }
Since: 3.0
Pause a migration. Currently it only supports postcopy.
Returns: nothing.
Example:
-> { "execute": "migrate-pause" } <- { "return": {} }
Since: 3.0
Emitted from source side of a migration when migration state is WAIT_UNPLUG. Device was unplugged by guest operating system. Device resources in QEMU are kept on standby to be able to re-plug it in case of migration failure.
Arguments:
device-id: string
QEMU device id of the unplugged device
Since: 4.2
Example:
{"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
This action can be used to test transaction failure.
Since: 1.6
An enumeration of Transactional completion modes.
Values:
individual
Do not attempt to cancel any other Actions if any Actions fail after the Transaction request succeeds. All Actions that can complete successfully will do so without waiting on others. This is the default.
grouped
If any Action fails after the Transaction succeeds, cancel all Actions. Actions do not complete until all Actions are ready to complete. May be rejected by Actions that do not support this completion mode.
Since: 2.5
A discriminated record of operations that can be performed with
transaction
. Action type
can be:
abort
: since 1.6
block-dirty-bitmap-add
: since 2.5
block-dirty-bitmap-remove
: since 4.2
block-dirty-bitmap-clear
: since 2.5
block-dirty-bitmap-enable
: since 4.0
block-dirty-bitmap-disable
: since 4.0
block-dirty-bitmap-merge
: since 4.0
blockdev-backup
: since 2.3
blockdev-snapshot
: since 2.5
blockdev-snapshot-internal-sync
: since 1.7
blockdev-snapshot-sync
: since 1.1
drive-backup
: since 1.6
Members:
type
One of "abort", "block-dirty-bitmap-add", "block-dirty-bitmap-remove", "block-dirty-bitmap-clear", "block-dirty-bitmap-enable", "block-dirty-bitmap-disable", "block-dirty-bitmap-merge", "blockdev-backup", "blockdev-snapshot", "blockdev-snapshot-internal-sync", "blockdev-snapshot-sync", "drive-backup"
data: Abort
when type
is "abort"data: BlockDirtyBitmapAdd
when type
is "block-dirty-bitmap-add"data: BlockDirtyBitmap
when type
is "block-dirty-bitmap-remove"data: BlockDirtyBitmap
when type
is "block-dirty-bitmap-clear"data: BlockDirtyBitmap
when type