SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from CentOS 7 qemu-kvm-common-ev-2.9.0-16.el7_4.5.1.x86_64.rpm

QEMU-QMP-REF.7

Section: (7)
Updated: 2017-09-11
Index 

NAME

qemu-qmp-ref - QEMU QMP Reference Manual 

DESCRIPTION

 

Introduction

This document describes all commands currently supported by QMP.

Most of the time their usage is exactly the same as in the user Monitor, thismeans that any other document which also describe commands (the manpage,QEMU's manual, etc) can and should be consulted.

QMP has two types of commands: regular and query commands. Regular commandsusually change the Virtual Machine's state someway, while query commands justreturn information. The sections below are divided accordingly.

It's important to observe that all communication examples are formatted ina reader-friendly way, so that they're easier to understand. However, in realprotocol usage, they're emitted as a single line.

Also, the following notation is used to denote data flow:

Example:

        -> data issued by the Client                <- Server data response

Please, refer to the QMP specification (docs/qmp-spec.txt) fordetailed information on the Server command and response formats. 

Stability Considerations

The current QMP command set (described in this file) may be useful for anumber of use cases, however it's limited and several commands have baddefined semantics, specially with regard to command completion.

These problems are going to be solved incrementally in the next QEMU releasesand we're going to establish a deprecation policy for badly defined commands.

If you're planning to adopt QMP, please observe the following:

1.
The deprecation policy will take effect and be documented soon, pleasecheck the documentation of each used command as soon as a new release ofQEMU is available
2.
DO NOT rely on anything which is not explicit documented
3.
Errors, in special, are not documented. Applications should NOT checkfor specific errors classes or data (it's strongly recommended to onlycheck for the ``error'' key)
 

QAPI common definitions

QapiErrorClass (Enum)

QEMU error classes

Values:

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

Since:1.2

VersionTriple (Object)

A three-part version number.

Members:

major: int
The major version number.
minor: int
The minor version number.
micro: int
The micro version number.

Since:2.4

VersionInfo (Object)

A description of QEMU's version.

Members:

qemu: VersionTriple
The version of QEMU. By current convention, a microversion of 50 signifies a development branch. A micro versiongreater than or equal to 90 signifies a release candidate forthe next minor version. A micro version of less than 50signifies a stable release.
package: string
QEMU will always set this field to an empty string. Downstreamversions of QEMU should set this to a non-empty string. Theexact format depends on the downstream however it highlyrecommended that a unique name is used.

Since:0.14.0

query-version (Command)Returns the current version of QEMU.

Returns:A "VersionInfo" object describing the current version of QEMU.

Since:0.14.0

Example:

        -> { "execute": "query-version" }        <- {              "return":{                 "qemu":{                    "major":0,                    "minor":11,                    "micro":5                 },                 "package":""              }           }

CommandInfo (Object)

Information about a QMP command

Members:

name: string
The command name

Since:0.14.0

query-commands (Command)Return a list of supported QMP commands by this server

Returns:A list of "CommandInfo" for all supported commands

Since:0.14.0

Example:

        -> { "execute": "query-commands" }        <- {             "return":[                {                   "name":"query-balloon"                },                {                   "name":"system_powerdown"                }             ]           }

Note:This example has been shortened as the real response is too long.

OnOffAuto (Enum)

An enumeration of three options: on, off, and auto

Values:

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

Since:2.2

OnOffSplit (Enum)

An enumeration of three values: on, off, and split

Values:

on
Enabled
off
Disabled
split
Mixed

Since:2.6 

QAPI crypto definitions

QCryptoTLSCredsEndpoint (Enum)

The type of network endpoint that will be using the credentials.Most types of credential require different setup / structuresdepending on whether they will be used in a server versus aclient.

Values:

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

Since:2.5

QCryptoSecretFormat (Enum)

The data format that the secret is provided in

Values:

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

Since:2.6

QCryptoHashAlgorithm (Enum)

The supported algorithms for computing content digests

Values:

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

Since:2.6

QCryptoCipherAlgorithm (Enum)

The supported algorithms for content encryption ciphers

Values:

aes-128
AES with 128 bit / 16 byte keys
aes-192
AES with 192 bit / 24 byte keys
aes-256
AES with 256 bit / 32 byte keys
des-rfb
RFB specific variant of single DES. Do not use except in VNC.
3des
3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
cast5-128
Cast5 with 128 bit / 16 byte keys
serpent-128
Serpent with 128 bit / 16 byte keys
serpent-192
Serpent with 192 bit / 24 byte keys
serpent-256
Serpent with 256 bit / 32 byte keys
twofish-128
Twofish with 128 bit / 16 byte keys
twofish-192
Twofish with 192 bit / 24 byte keys
twofish-256
Twofish with 256 bit / 32 byte keys

Since:2.6

QCryptoCipherMode (Enum)

The supported modes for content encryption ciphers

Values:

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

Since:2.6

QCryptoIVGenAlgorithm (Enum)

The supported algorithms for generating initializationvectors for full disk encryption. The 'plain' generatorshould not be used for disks with sector numbers largerthan 2^32, except where compatibility with pre-existingLinux dm-crypt volumes is required.

Values:

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

Since:2.6

QCryptoBlockFormat (Enum)

The supported full disk encryption formats

Values:

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

Since:2.6

QCryptoBlockOptionsBase (Object)

The common options that apply to all full diskencryption formats

Members:

format: QCryptoBlockFormat
the encryption format

Since:2.6

QCryptoBlockOptionsQCow (Object)

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

Members:

key-secret: string (optional)
the ID of a QCryptoSecret object providing thedecryption key. Mandatory except when probing image formetadata only.

Since:2.6

QCryptoBlockOptionsLUKS (Object)

The options that apply to LUKS encryption format

Members:

key-secret: string (optional)
the ID of a QCryptoSecret object providing thedecryption key. Mandatory except when probing image formetadata only.

Since:2.6

QCryptoBlockCreateOptionsLUKS (Object)

The options that apply to LUKS encryption format initialization

Members:

cipher-alg: QCryptoCipherAlgorithm (optional)
the cipher algorithm for data encryptionCurrently defaults to 'aes'.
cipher-mode: QCryptoCipherMode (optional)
the cipher mode for data encryptionCurrently defaults to 'cbc'
ivgen-alg: QCryptoIVGenAlgorithm (optional)
the initialization vector generatorCurrently defaults to 'essiv'
ivgen-hash-alg: QCryptoHashAlgorithm (optional)
the initialization vector generator hashCurrently defaults to 'sha256'
hash-alg: QCryptoHashAlgorithm (optional)
the master key hash algorithmCurrently defaults to 'sha256'
iter-time: int (optional)
number of milliseconds to spend inPBKDF passphrase processing. Currently defaultsto 2000. (since 2.8)
The members of QCryptoBlockOptionsLUKS

Since:2.6

QCryptoBlockOpenOptions (Object)

The options that are available for all encryption formatswhen opening an existing volume

Members:

The members of QCryptoBlockOptionsBase
The members of QCryptoBlockOptionsQCow when format is qcow
The members of QCryptoBlockOptionsLUKS when format is luks

Since:2.6

QCryptoBlockCreateOptions (Object)

The options that are available for all encryption formatswhen initializing a new volume

Members:

The members of QCryptoBlockOptionsBase
The members of QCryptoBlockOptionsQCow when format is qcow
The members of QCryptoBlockCreateOptionsLUKS when format is luks

Since:2.6

QCryptoBlockInfoBase (Object)

The common information that applies to all full diskencryption formats

Members:

format: QCryptoBlockFormat
the encryption format

Since:2.7

QCryptoBlockInfoLUKSSlot (Object)

Information about the LUKS block encryption keyslot options

Members:

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

Since:2.7

QCryptoBlockInfoLUKS (Object)

Information about the LUKS block encryption options

Members:

cipher-alg: QCryptoCipherAlgorithm
the cipher algorithm for data encryption
cipher-mode: QCryptoCipherMode
the cipher mode for data encryption
ivgen-alg: QCryptoIVGenAlgorithm
the initialization vector generator
ivgen-hash-alg: QCryptoHashAlgorithm (optional)
the initialization vector generator hash
hash-alg: QCryptoHashAlgorithm
the master key hash algorithm
payload-offset: int
offset to the payload data in bytes
master-key-iters: int
number of PBKDF2 iterations for key material
uuid: string
unique identifier for the volume
slots: array of QCryptoBlockInfoLUKSSlot
information about each key slot

Since:2.7

QCryptoBlockInfoQCow (Object)

Information about the QCow block encryption options

Since:2.7

QCryptoBlockInfo (Object)

Information about the block encryption options

Members:

The members of QCryptoBlockInfoBase
The members of QCryptoBlockInfoQCow when format is qcow
The members of QCryptoBlockInfoLUKS when format is luks

Since:2.7 

QAPI block definitions

QAPI block core definitions (vm unrelated)

SnapshotInfo (Object)

Members:

id: string
unique snapshot id
name: string
user chosen name
vm-state-size: int
size of the VM state
date-sec: int
UTC date of the snapshot in seconds
date-nsec: int
fractional part in nano seconds to be used with date-sec
vm-clock-sec: int
VM clock relative to boot in seconds
vm-clock-nsec: int
fractional part in nano seconds to be used with vm-clock-sec

Since:1.3

ImageInfoSpecificQCow2 (Object)

Members:

compat: string
compatibility level
lazy-refcounts: boolean (optional)
on or off; only valid for compat >= 1.1
corrupt: boolean (optional)
true if the image has been marked corrupt; only valid forcompat >= 1.1 (since 2.2)
refcount-bits: int
width of a refcount entry in bits (since 2.3)

Since:1.7

ImageInfoSpecificVmdk (Object)

Members:

create-type: string
The create type of VMDK image
cid: int
Content id of image
parent-cid: int
Parent VMDK image's cid
extents: array of ImageInfo
List of extent files

Since:1.7

ImageInfoSpecific (Object)

A discriminated record of image format specific information structures.

Members:

type
One of ``qcow2'', ``vmdk'', ``luks''
data: ImageInfoSpecificQCow2 when type is qcow2
data: ImageInfoSpecificVmdk when type is vmdk
data: QCryptoBlockInfoLUKS when type is luks

Since:1.7

ImageInfo (Object)

Information about a QEMU image file

Members:

filename: string
name of the image file
format: string
format of the image file
virtual-size: int
maximum capacity in bytes of the image
actual-size: int (optional)
actual size on disk in bytes of the image
dirty-flag: boolean (optional)
true if image is not cleanly closed
cluster-size: int (optional)
size of a cluster in bytes
encrypted: boolean (optional)
true if the image is encrypted
compressed: boolean (optional)
true if the image is compressed (Since 1.7)
backing-filename: string (optional)
name of the backing file
full-backing-filename: string (optional)
full path of the backing file
backing-filename-format: string (optional)
the format of the backing file
snapshots: array of SnapshotInfo (optional)
list of VM snapshots
backing-image: ImageInfo (optional)
info of the backing image (since 1.6)
format-specific: ImageInfoSpecific (optional)
structure supplying additional format-specificinformation (since 1.7)

Since:1.3

ImageCheck (Object)

Information about a QEMU image file check

Members:

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

Since:1.4

MapEntry (Object)

Mapping information from a virtual block range to a host file range

Members:

start: int
the start byte of the mapped virtual range
length: int
the number of bytes of the mapped virtual range
data: boolean
whether the mapped range has data
zero: boolean
whether the virtual blocks are zeroed
depth: int
the depth of the mapping
offset: int (optional)
the offset in file that the virtual sectors are mapped to
filename: string (optional)
filename that is referred to by "offset"

Since:2.6

BlockdevCacheInfo (Object)

Cache mode information for a block device

Members:

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

Since:2.3

BlockDeviceInfo (Object)

Information about the backing device for a block device.

Members:

file: string
the filename of the backing device
node-name: string (optional)
the name of the block driver node (Since 2.0)
ro: boolean
true if the backing device was open read-only
drv: string
the name of the block format used to open the backing device. As of0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg','file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device','http', 'https', 'luks', 'nbd', 'parallels', 'qcow','qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat'2.2: 'archipelago' added, 'cow' dropped2.3: 'host_floppy' deprecated2.5: 'host_floppy' dropped2.6: 'luks' added2.8: 'replication' added, 'tftp' dropped2.9: 'archipelago' dropped
backing_file: string (optional)
the name of the backing file (for copy-on-write)
backing_file_depth: int
number of files in the backing file chain (since: 1.2)
encrypted: boolean
true if the backing device is encrypted
encryption_key_missing: boolean
true if the backing device is encrypted but anvalid encryption key is missing
detect_zeroes: BlockdevDetectZeroesOptions
detect and optimize zero writes (Since 2.1)
bps: int
total throughput limit in bytes per second is specified
bps_rd: int
read throughput limit in bytes per second is specified
bps_wr: int
write throughput limit in bytes per second is specified
iops: int
total I/O operations per second is specified
iops_rd: int
read I/O operations per second is specified
iops_wr: int
write I/O operations per second is specified
image: ImageInfo
the info of image used (since: 1.6)
bps_max: int (optional)
total throughput limit during bursts,in bytes (Since 1.7)
bps_rd_max: int (optional)
read throughput limit during bursts,in bytes (Since 1.7)
bps_wr_max: int (optional)
write throughput limit during bursts,in bytes (Since 1.7)
iops_max: int (optional)
total I/O operations per second during bursts,in bytes (Since 1.7)
iops_rd_max: int (optional)
read I/O operations per second during bursts,in bytes (Since 1.7)
iops_wr_max: int (optional)
write I/O operations per second during bursts,in bytes (Since 1.7)
bps_max_length: int (optional)
maximum length of the "bps_max" burstperiod, in seconds. (Since 2.6)
bps_rd_max_length: int (optional)
maximum length of the "bps_rd_max"burst period, in seconds. (Since 2.6)
bps_wr_max_length: int (optional)
maximum length of the "bps_wr_max"burst period, in seconds. (Since 2.6)
iops_max_length: int (optional)
maximum length of the "iops" burstperiod, in seconds. (Since 2.6)
iops_rd_max_length: int (optional)
maximum length of the "iops_rd_max"burst period, in seconds. (Since 2.6)
iops_wr_max_length: int (optional)
maximum length of the "iops_wr_max"burst period, in seconds. (Since 2.6)
iops_size: int (optional)
an I/O size in bytes (Since 1.7)
group: string (optional)
throttle group name (Since 2.4)
cache: BlockdevCacheInfo
the cache mode used for the block device (since: 2.3)
write_threshold: int
configured write threshold for the device.0 if disabled. (Since 2.3)

Since:0.14.0

BlockDeviceIoStatus (Enum)

An enumeration of block device I/O status.

Values:

ok
The last I/O operation has succeeded
failed
The last I/O operation has failed
nospace
The last I/O operation has failed due to a no-space condition

Since:1.0

BlockDeviceMapEntry (Object)

Entry in the metadata map of the device (returned by ``qemu-img map'')

Members:

start: int
Offset in the image of the first byte described by this entry(in bytes)
length: int
Length of the range described by this entry (in bytes)
depth: int
Number of layers (0 = top image, 1 = top image's backing file, etc.)before reaching one for which the range is allocated. The value isin the range 0 to the depth of the image chain - 1.
zero: boolean
the sectors in this range read as zeros
data: boolean
reading the image will actually read data from a file (in particular,if "offset" is present this means that the sectors are not simplypreallocated, but contain actual data in raw format)
offset: int (optional)
if present, the image file stores the data for this range inraw format at the given offset.

Since:1.7

DirtyBitmapStatus (Enum)

An enumeration of possible states that a dirty bitmap can report to the user.

Values:

frozen
The bitmap is currently in-use by a backup operation or block job,and is immutable.
disabled
The bitmap is currently in-use by an internal operation and isread-only. It can still be deleted.
active
The bitmap is actively monitoring for new writes, and can be cleared,deleted, or used for backup operations.

Since:2.4

BlockDirtyInfo (Object)

Block dirty bitmap information.

Members:

name: string (optional)
the name of the dirty bitmap (Since 2.4)
count: int
number of dirty bytes according to the dirty bitmap
granularity: int
granularity of the dirty bitmap in bytes (since 1.4)
status: DirtyBitmapStatus
current status of the dirty bitmap (since 2.4)

Since:1.3

BlockInfo (Object)

Block device information. This structure describes a virtual device andthe backing device associated with it.

Members:

device: string
The device name associated with the virtual device.
type: string
This field is returned only for compatibility reasons, it shouldnot be used (always returns 'unknown')
removable: boolean
True if the device supports removable media.
locked: boolean
True if the guest has locked this device from having its mediaremoved
tray_open: boolean (optional)
True if the device's tray is open(only present if it has a tray)
dirty-bitmaps: array of BlockDirtyInfo (optional)
dirty bitmaps information (only present if thedriver has one or more dirty bitmaps) (Since 2.0)
io-status: BlockDeviceIoStatus (optional)
"BlockDeviceIoStatus". Only present if the devicesupports it and the VM is configured to stop on errors(supported device models: virtio-blk, ide, scsi-disk)
inserted: BlockDeviceInfo (optional)
"BlockDeviceInfo" describing the device if media ispresent

Since:0.14.0

query-block (Command)Get a list of BlockInfo for all virtual block devices.

Returns:a list of "BlockInfo" describing each virtual block device. Filternodes that were created implicitly are skipped over.

Since:0.14.0

Example:

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

BlockDeviceTimedStats (Object)

Statistics of a block device during a given interval of time.

Members:

interval_length: int
Interval used for calculating the statistics,in seconds.
min_rd_latency_ns: int
Minimum latency of read operations in thedefined interval, in nanoseconds.
min_wr_latency_ns: int
Minimum latency of write operations in thedefined interval, in nanoseconds.
min_flush_latency_ns: int
Minimum latency of flush operations in thedefined interval, in nanoseconds.
max_rd_latency_ns: int
Maximum latency of read operations in thedefined interval, in nanoseconds.
max_wr_latency_ns: int
Maximum latency of write operations in thedefined interval, in nanoseconds.
max_flush_latency_ns: int
Maximum latency of flush operations in thedefined interval, in nanoseconds.
avg_rd_latency_ns: int
Average latency of read operations in thedefined interval, in nanoseconds.
avg_wr_latency_ns: int
Average latency of write operations in thedefined interval, in nanoseconds.
avg_flush_latency_ns: int
Average latency of flush operations in thedefined interval, in nanoseconds.
avg_rd_queue_depth: number
Average number of pending read operationsin the defined interval.
avg_wr_queue_depth: number
Average number of pending write operationsin the defined interval.

Since:2.5

BlockDeviceStats (Object)

Statistics of a virtual block device or a block backing device.

Members:

rd_bytes: int
The number of bytes read by the device.
wr_bytes: int
The number of bytes written by the device.
rd_operations: int
The number of read operations performed by the device.
wr_operations: int
The number of write operations performed by the device.
flush_operations: int
The number of cache flush operations performed by thedevice (since 0.15.0)
flush_total_time_ns: int
Total time spend on cache flushes in nano-seconds(since 0.15.0).
wr_total_time_ns: int
Total time spend on writes in nano-seconds (since 0.15.0).
rd_total_time_ns: int
Total_time_spend on reads in nano-seconds (since 0.15.0).
wr_highest_offset: int
The offset after the greatest byte written to thedevice. The intended use of this information is forgrowable sparse files (like qcow2) that are used on topof a physical device.
rd_merged: int
Number of read requests that have been merged into anotherrequest (Since 2.3).
wr_merged: int
Number of write requests that have been merged into anotherrequest (Since 2.3).
idle_time_ns: int (optional)
Time since the last I/O operation, innanoseconds. If the field is absent it means thatthere haven't been any operations yet (Since 2.5).
failed_rd_operations: int
The number of failed read operationsperformed by the device (Since 2.5)
failed_wr_operations: int
The number of failed write operationsperformed by the device (Since 2.5)
failed_flush_operations: int
The number of failed flush operationsperformed by the device (Since 2.5)
invalid_rd_operations: int
The number of invalid read operationsperformed by the device (Since 2.5)
invalid_wr_operations: int
The number of invalid write operationsperformed by the device (Since 2.5)
invalid_flush_operations: int
The number of invalid flush operationsperformed by the device (Since 2.5)
account_invalid: boolean
Whether invalid operations are included in thelast access statistics (Since 2.5)
account_failed: boolean
Whether failed operations are included in thelatency and last access statistics (Since 2.5)
timed_stats: array of BlockDeviceTimedStats
Statistics specific to the set of previously definedintervals of time (Since 2.5)

Since:0.14.0

BlockStats (Object)

Statistics of a virtual block device or a block backing device.

Members:

device: string (optional)
If the stats are for a virtual block device, the namecorresponding to the virtual block device.
node-name: string (optional)
The node name of the device. (Since 2.3)
stats: BlockDeviceStats
A "BlockDeviceStats" for the device.
parent: BlockStats (optional)
This describes the file block device if it has one.Contains recursively the statistics of the underlyingprotocol (e.g. the host file for a qcow2 image). If there isno underlying protocol, this field is omitted
backing: BlockStats (optional)
This describes the backing block device if it has one.(Since 2.0)

Since:0.14.0

query-blockstats (Command)Query the "BlockStats" for all virtual block devices.

Arguments:

query-nodes: boolean (optional)
If true, the command will query all the block nodesthat have a node name, in a list which will include ``parent''information, but not ``backing''.If false or omitted, the behavior is as before - query all thedevice backends, recursively including their ``parent'' and``backing''. Filter nodes that were created implicitly areskipped over in this mode. (Since 2.3)

Returns:A list of "BlockStats" for each virtual block devices.

Since:0.14.0

Example:

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

BlockdevOnError (Enum)

An enumeration of possible behaviors for errors on I/O operations.The exact meaning depends on whether the I/O was initiated by a guestor by a block job

Values:

report
for guest operations, report the error to the guest;for jobs, cancel the job
ignore
ignore the error, only report a QMP event (BLOCK_IO_ERRORor BLOCK_JOB_ERROR)
enospc
same as "stop" on ENOSPC, same as "report" otherwise.
stop
for guest operations, stop the virtual machine;for jobs, pause the job
auto
inherit the error handling policy of the backend (since: 2.7)

Since:1.3

MirrorSyncMode (Enum)

An enumeration of possible behaviors for the initial synchronizationphase of storage mirroring.

Values:

top
copies data in the topmost image to the destination
full
copies data from all images to the destination
none
only copy data written from now on
incremental
only copy data described by the dirty bitmap. Since: 2.4

Since:1.3

BlockJobType (Enum)

Type of a block job.

Values:

commit
block commit job type, see ``block-commit''
stream
block stream job type, see ``block-stream''
mirror
drive mirror job type, see ``drive-mirror''
backup
drive backup job type, see ``drive-backup''

Since:1.7

BlockJobInfo (Object)

Information about a long-running block device operation.

Members:

type: string
the job type ('stream' for image streaming)
device: string
The job identifier. Originally the device name but othervalues are allowed since QEMU 2.7
len: int
the maximum progress value
busy: boolean
false if the job is known to be in a quiescent state, withno pending I/O. Since 1.3.
paused: boolean
whether the job is paused or, if "busy" is true, willpause itself as soon as possible. Since 1.3.
offset: int
the current progress value
speed: int
the rate limit, bytes per second
io-status: BlockDeviceIoStatus
the status of the job (since 1.3)
ready: boolean
true if the job may be completed (since 2.2)

Since:1.1

query-block-jobs (Command)Return information about long-running block device operations.

Returns:a list of "BlockJobInfo" for each active block job

Since:1.1

block_passwd (Command)This command sets the password of a block device that has not been openwith a password and requires one.

The two cases where this can happen are a block device is created throughQEMU's initial command line or a block device is changed through the legacy"change" interface.

In the event that the block device is created through the initial commandline, the VM will start in the stopped state regardless of whether '-S' isused. The intention is for a management tool to query the block devices todetermine which ones are encrypted, set the passwords with this command, andthen start the guest with the "cont" command.

Either "device" or "node-name" must be set but not both.

Arguments:

device: string (optional)
the name of the block backend device to set the password on
node-name: string (optional)
graph node name to set the password on (Since 2.0)
password: string
the password to use for the device

Returns:nothing on successIf "device" is not a valid block device, DeviceNotFoundIf "device" is not encrypted, DeviceNotEncrypted

Notes:Not all block formats support encryption and some that do are notable to validate that a password is correct. Disk corruption mayoccur if an invalid password is specified.

Since:0.14.0

Example:

        -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",                                                       "password": "12345" } }        <- { "return": {} }

block_resize (Command)Resize a block image while a guest is running.

Either "device" or "node-name" must be set but not both.

Arguments:

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

Returns:nothing on successIf "device" is not a valid block device, DeviceNotFound

Since:0.14.0

Example:

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

NewImageMode (Enum)

An enumeration that tells QEMU how to set the backing file path ina new image file.

Values:

existing
QEMU should look for an existing image file.
absolute-paths
QEMU should create a new image with absolute pathsfor the backing file. If there is no backing file available, the newimage will not be backed either.

Since:1.1

BlockdevSnapshotSync (Object)

Either "device" or "node-name" must be set but not both.

Members:

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

BlockdevSnapshot (Object)

Members:

node: string
device or node name that will have a snapshot created.
overlay: string
reference to the existing block device that will becomethe overlay of "node", as part of creating the snapshot.It must not have a current backing file (this can beachieved by passing ``backing'': "" to blockdev-add).

Since:2.5

DriveBackup (Object)

Members:

job-id: string (optional)
identifier for the newly-created block job. Ifomitted, the device name will be used. (Since 2.7)
device: string
the device name or node-name of a root node which should be copied.
target: string
the target of the new image. If the file exists, or if itis a device, the existing file/device will be used as the newdestination. If it does not exist, a new file will be created.
format: string (optional)
the format of the new destination, default is toprobe if "mode" is 'existing', else the format of the source
sync: MirrorSyncMode
what parts of the disk image should be copied to the destination(all the disk, only the sectors allocated in the topmost image, from adirty bitmap, or only new I/O).
mode: NewImageMode (optional)
whether and how QEMU should create a new image, default is'absolute-paths'.
speed: int (optional)
the maximum speed, in bytes per second
bitmap: string (optional)
the name of dirty bitmap if sync is ``incremental''.Must be present if sync is ``incremental'', must NOT be presentotherwise. (Since 2.4)
compress: boolean (optional)
true to compress data, if the target format supports it.(default: false) (since 2.8)
on-source-error: BlockdevOnError (optional)
the action to take on an error on the source,default 'report'. 'stop' and 'enospc' can only be usedif the block device supports io-status (see BlockInfo).
on-target-error: BlockdevOnError (optional)
the action to take on an error on the target,default 'report' (no limitations, since this applies toa different block device than "device").

Note:"on-source-error" and "on-target-error" only affect backgroundI/O. If an error occurs during a guest write request, the device'srerror/werror actions will be used.

Since:1.6

BlockdevBackup (Object)

Members:

job-id: string (optional)
identifier for the newly-created block job. Ifomitted, the device name will be used. (Since 2.7)
device: string
the device name or node-name of a root node which should be copied.
target: string
the device name or node-name of the backup target node.
sync: MirrorSyncMode
what parts of the disk image should be copied to the destination(all the disk, only the sectors allocated in the topmost image, oronly new I/O).
speed: int (optional)
the maximum speed, in bytes per second. The default is 0,for unlimited.
compress: boolean (optional)
true to compress data, if the target format supports it.(default: false) (since 2.8)
on-source-error: BlockdevOnError (optional)
the action to take on an error on the source,default 'report'. 'stop' and 'enospc' can only be usedif the block device supports io-status (see BlockInfo).
on-target-error: BlockdevOnError (optional)
the action to take on an error on the target,default 'report' (no limitations, since this applies toa different block device than "device").

Note:"on-source-error" and "on-target-error" only affect backgroundI/O. If an error occurs during a guest write request, the device'srerror/werror actions will be used.

Since:2.3

blockdev-snapshot-sync (Command)Generates a synchronous snapshot of a block device.

For the arguments, see the documentation of BlockdevSnapshotSync.

Returns:nothing on successIf "device" is not a valid block device, DeviceNotFound

Since:0.14.0

Example:

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

blockdev-snapshot (Command)Generates a snapshot of a block device.

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

For the arguments, see the documentation of BlockdevSnapshot.

Since:2.5

Example:

        -> { "execute": "blockdev-add",             "arguments": { "options": { "driver": "qcow2",                                         "node-name": "node1534",                                         "file": { "driver": "file",                                                   "filename": "hd1.qcow2" },                                         "backing": "" } } }                <- { "return": {} }                -> { "execute": "blockdev-snapshot",             "arguments": { "node": "ide-hd0",                            "overlay": "node1534" } }        <- { "return": {} }

change-backing-file (Command)Change the backing file in the image file metadata. This does notcause QEMU to reopen the image file to reparse the backing filename(it may, however, perform a reopen to change permissions fromr/o -> r/w -> r/o, if needed). The new backing file string is writteninto the image file metadata, and the QEMU internal strings areupdated.

Arguments:

image-node-name: string
The name of the block driver state node of theimage to modify. The ``device'' argument is usedto verify ``image-node-name'' is in the chaindescribed by ``device''.
device: string
The device name or node-name of the root node that ownsimage-node-name.
backing-file: string
The string to write as the backing file. Thisstring is not validated, so care should be takenwhen specifying the string or the image chain maynot be able to be reopened again.

Returns:Nothing on success

If ``device'' does not exist or cannot be determined, DeviceNotFound

Since:2.1

block-commit (Command)Live commit of data from overlay image nodes into backing nodes - i.e.,writes data between 'top' and 'base' into 'base'.

Arguments:

job-id: string (optional)
identifier for the newly-created block job. Ifomitted, the device name will be used. (Since 2.7)
device: string
the device name or node-name of a root node
base: string (optional)
The file name of the backing image to write data into.If not specified, this is the deepest backing image.
top: string (optional)
The file name of the backing image within the image chain,which contains the topmost data to be committed down. Ifnot specified, this is the active layer.
backing-file: string (optional)
The backing file string to write into the overlayimage of 'top'. If 'top' is the active layer,specifying a backing file string is an error. Thisfilename is not validated.

If a pathname string is such that it cannot beresolved by QEMU, that means that subsequent QMP orHMP commands must use node-names for the image inquestion, as filename lookup methods will fail.

If not specified, QEMU will automatically determinethe backing file string to use, or error out ifthere is no obvious choice. Care should be takenwhen specifying the string, to specify a validfilename or protocol.(Since 2.1)

If top == base, that is an error.If top == active, the job will not be completed by itself,user needs to complete the job with the block-job-completecommand after getting the ready event. (Since 2.0)

If the base image is smaller than top, then the base imagewill be resized to be the same size as top. If top issmaller than the base image, the base will not betruncated. If you want the base image size to match thesize of the smaller top, you can safely truncate ityourself once the commit operation successfully completes.

speed: int (optional)
the maximum speed, in bytes per second
filter-node-name: string (optional)
the node name that should be assigned to thefilter driver that the commit job inserts into the graphabove "top". If this option is not given, a node name isautogenerated. (Since: 2.9)

Returns:Nothing on successIf commit or stream is already active on this device, DeviceInUseIf "device" does not exist, DeviceNotFoundIf image commit is not supported by this device, NotSupportedIf "base" or "top" is invalid, a generic error is returnedIf "speed" is invalid, InvalidParameter

Since:1.3

Example:

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