7f3c6f22da
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
694 lines
20 KiB
Plaintext
694 lines
20 KiB
Plaintext
QMP Supported Commands
|
|
----------------------
|
|
|
|
This document describes all commands currently supported by QMP.
|
|
|
|
Most of the time their usage is exactly the same as in the user Monitor, this
|
|
means 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 commands
|
|
usually change the Virtual Machine's state someway, while query commands just
|
|
return information. The sections below are divided accordingly.
|
|
|
|
It's important to observe that all communication examples are formatted in
|
|
a reader-friendly way, so that they're easier to understand. However, in real
|
|
protocol usage, they're emitted as a single line.
|
|
|
|
Also, the following notation is used to denote data flow:
|
|
|
|
-> data issued by the Client
|
|
<- Server data response
|
|
|
|
Please, refer to the QMP specification (docs/qmp-spec.txt) for detailed
|
|
information on the Server command and response formats.
|
|
|
|
NOTE: This document is temporary and will be replaced soon.
|
|
|
|
1. Stability Considerations
|
|
===========================
|
|
|
|
The current QMP command set (described in this file) may be useful for a
|
|
number of use cases, however it's limited and several commands have bad
|
|
defined semantics, specially with regard to command completion.
|
|
|
|
These problems are going to be solved incrementally in the next QEMU releases
|
|
and 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, please
|
|
check the documentation of each used command as soon as a new release of
|
|
QEMU is available
|
|
|
|
2. DO NOT rely on anything which is not explicit documented
|
|
|
|
3. Errors, in special, are not documented. Applications should NOT check
|
|
for specific errors classes or data (it's strongly recommended to only
|
|
check for the "error" key)
|
|
|
|
2. Regular Commands
|
|
===================
|
|
|
|
Server's responses in the examples below are always a success response, please
|
|
refer to the QMP specification for more details on error responses.
|
|
|
|
eject
|
|
-----
|
|
|
|
Eject a removable medium.
|
|
|
|
Arguments:
|
|
|
|
- "force": force ejection (json-bool, optional)
|
|
- "device": block device name (deprecated, use @id instead)
|
|
(json-string, optional)
|
|
- "id": the name or QOM path of the guest device (json-string, optional)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "eject", "arguments": { "id": "ide0-1-0" } }
|
|
<- { "return": {} }
|
|
|
|
Note: The "force" argument defaults to false.
|
|
|
|
device_add
|
|
----------
|
|
|
|
Add a device.
|
|
|
|
Arguments:
|
|
|
|
- "driver": the name of the new device's driver (json-string)
|
|
- "bus": the device's parent bus (device tree path, json-string, optional)
|
|
- "id": the device's ID, must be unique (json-string)
|
|
- device properties
|
|
|
|
Example:
|
|
|
|
-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
|
|
<- { "return": {} }
|
|
|
|
Notes:
|
|
|
|
(1) For detailed information about this command, please refer to the
|
|
'docs/qdev-device-use.txt' file.
|
|
|
|
(2) It's possible to list device properties by running QEMU with the
|
|
"-device DEVICE,\?" command-line argument, where DEVICE is the device's name
|
|
|
|
cpu
|
|
---
|
|
|
|
Set the default CPU.
|
|
|
|
Arguments:
|
|
|
|
- "index": the CPU's index (json-int)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "cpu", "arguments": { "index": 0 } }
|
|
<- { "return": {} }
|
|
|
|
Note: CPUs' indexes are obtained with the 'query-cpus' command.
|
|
|
|
xen-load-devices-state
|
|
----------------------
|
|
|
|
Load the state of all devices from file. The RAM and the block devices
|
|
of the VM are not loaded by this command.
|
|
|
|
Arguments:
|
|
|
|
- "filename": the file to load the state of the devices from as binary
|
|
data. See xen-save-devices-state.txt for a description of the binary
|
|
format.
|
|
|
|
Example:
|
|
|
|
-> { "execute": "xen-load-devices-state",
|
|
"arguments": { "filename": "/tmp/resume" } }
|
|
<- { "return": {} }
|
|
|
|
migrate-set-cache-size
|
|
----------------------
|
|
|
|
Set cache size to be used by XBZRLE migration, the cache size will be rounded
|
|
down to the nearest power of 2
|
|
|
|
Arguments:
|
|
|
|
- "value": cache size in bytes (json-int)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
|
|
<- { "return": {} }
|
|
|
|
x-colo-lost-heartbeat
|
|
--------------------
|
|
|
|
Tell COLO that heartbeat is lost, a failover or takeover is needed.
|
|
|
|
Example:
|
|
|
|
-> { "execute": "x-colo-lost-heartbeat" }
|
|
<- { "return": {} }
|
|
|
|
query-dump
|
|
----------
|
|
|
|
Query background dump status.
|
|
|
|
Arguments: None.
|
|
|
|
Example:
|
|
|
|
-> { "execute": "query-dump" }
|
|
<- { "return": { "status": "active", "completed": 1024000,
|
|
"total": 2048000 } }
|
|
|
|
blockdev-snapshot-internal-sync
|
|
-------------------------------
|
|
|
|
Synchronously take an internal snapshot of a block device when the format of
|
|
image used supports it. If the name is an empty string, or a snapshot with
|
|
name already exists, the operation will fail.
|
|
|
|
Arguments:
|
|
|
|
- "device": the device name or node-name of a root node to snapshot
|
|
(json-string)
|
|
- "name": name of the new snapshot (json-string)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "blockdev-snapshot-internal-sync",
|
|
"arguments": { "device": "ide-hd0",
|
|
"name": "snapshot0" }
|
|
}
|
|
<- { "return": {} }
|
|
|
|
blockdev-snapshot-delete-internal-sync
|
|
--------------------------------------
|
|
|
|
Synchronously delete an internal snapshot of a block device when the format of
|
|
image used supports it. The snapshot is identified by name or id or both. One
|
|
of name or id is required. If the snapshot is not found, the operation will
|
|
fail.
|
|
|
|
Arguments:
|
|
|
|
- "device": the device name or node-name of a root node (json-string)
|
|
- "id": ID of the snapshot (json-string, optional)
|
|
- "name": name of the snapshot (json-string, optional)
|
|
|
|
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
|
|
}
|
|
}
|
|
|
|
blockdev-mirror
|
|
------------
|
|
|
|
Start mirroring a block device's writes to another block device. target
|
|
specifies the target of mirror operation.
|
|
|
|
Arguments:
|
|
|
|
- "job-id": Identifier for the newly-created block job. If omitted,
|
|
the device name will be used. (json-string, optional)
|
|
- "device": The device name or node-name of a root node whose writes should be
|
|
mirrored (json-string)
|
|
- "target": device name to mirror to (json-string)
|
|
- "replaces": the block driver node name to replace when finished
|
|
(json-string, optional)
|
|
- "speed": maximum speed of the streaming job, in bytes per second
|
|
(json-int)
|
|
- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
|
|
- "buf_size": maximum amount of data in flight from source to target, in bytes
|
|
(json-int, default 10M)
|
|
- "sync": what parts of the disk image should be copied to the destination;
|
|
possibilities include "full" for all the disk, "top" for only the sectors
|
|
allocated in the topmost image, or "none" to only replicate new I/O
|
|
(MirrorSyncMode).
|
|
- "on-source-error": the action to take on an error on the source
|
|
(BlockdevOnError, default 'report')
|
|
- "on-target-error": the action to take on an error on the target
|
|
(BlockdevOnError, default 'report')
|
|
|
|
The default value of the granularity is the image cluster size clamped
|
|
between 4096 and 65536, if the image format defines one. If the format
|
|
does not define a cluster size, the default value of the granularity
|
|
is 65536.
|
|
|
|
Example:
|
|
|
|
-> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
|
|
"target": "target0",
|
|
"sync": "full" } }
|
|
<- { "return": {} }
|
|
|
|
qmp_capabilities
|
|
----------------
|
|
|
|
Enable QMP capabilities.
|
|
|
|
Arguments: None.
|
|
|
|
Example:
|
|
|
|
-> { "execute": "qmp_capabilities" }
|
|
<- { "return": {} }
|
|
|
|
Note: This command must be issued before issuing any other command.
|
|
|
|
3. Query Commands
|
|
=================
|
|
|
|
|
|
query-version
|
|
-------------
|
|
|
|
Show QEMU version.
|
|
|
|
Return a json-object with the following information:
|
|
|
|
- "qemu": A json-object containing three integer values:
|
|
- "major": QEMU's major version (json-int)
|
|
- "minor": QEMU's minor version (json-int)
|
|
- "micro": QEMU's micro version (json-int)
|
|
- "package": package's version (json-string)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "query-version" }
|
|
<- {
|
|
"return":{
|
|
"qemu":{
|
|
"major":0,
|
|
"minor":11,
|
|
"micro":5
|
|
},
|
|
"package":""
|
|
}
|
|
}
|
|
|
|
query-commands
|
|
--------------
|
|
|
|
List QMP available commands.
|
|
|
|
Each command is represented by a json-object, the returned value is a json-array
|
|
of all commands.
|
|
|
|
Each json-object contain:
|
|
|
|
- "name": command's name (json-string)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "query-commands" }
|
|
<- {
|
|
"return":[
|
|
{
|
|
"name":"query-balloon"
|
|
},
|
|
{
|
|
"name":"system_powerdown"
|
|
}
|
|
]
|
|
}
|
|
|
|
Note: This example has been shortened as the real response is too long.
|
|
|
|
query-qmp-schema
|
|
----------------
|
|
|
|
Return the QMP wire schema. The returned value is a json-array of
|
|
named schema entities. Entities are commands, events and various
|
|
types. See docs/qapi-code-gen.txt for information on their structure
|
|
and intended use.
|
|
|
|
x-blockdev-remove-medium
|
|
------------------------
|
|
|
|
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.
|
|
|
|
This command is still a work in progress and is considered experimental.
|
|
Stay away from it unless you want to help with its development.
|
|
|
|
Arguments:
|
|
|
|
- "device": block device name (deprecated, use @id instead)
|
|
(json-string, optional)
|
|
- "id": the name or QOM path of the guest device (json-string, optional)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "x-blockdev-remove-medium",
|
|
"arguments": { "id": "ide0-1-0" } }
|
|
|
|
<- { "error": { "class": "GenericError",
|
|
"desc": "Tray of device 'ide0-1-0' is not open" } }
|
|
|
|
-> { "execute": "blockdev-open-tray",
|
|
"arguments": { "id": "ide0-1-0" } }
|
|
|
|
<- { "timestamp": { "seconds": 1418751627,
|
|
"microseconds": 549958 },
|
|
"event": "DEVICE_TRAY_MOVED",
|
|
"data": { "device": "ide1-cd0",
|
|
"id": "ide0-1-0",
|
|
"tray-open": true } }
|
|
|
|
<- { "return": {} }
|
|
|
|
-> { "execute": "x-blockdev-remove-medium",
|
|
"arguments": { "device": "ide0-1-0" } }
|
|
|
|
<- { "return": {} }
|
|
|
|
x-blockdev-insert-medium
|
|
------------------------
|
|
|
|
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.
|
|
|
|
This command is still a work in progress and is considered experimental.
|
|
Stay away from it unless you want to help with its development.
|
|
|
|
Arguments:
|
|
|
|
- "device": block device name (deprecated, use @id instead)
|
|
(json-string, optional)
|
|
- "id": the name or QOM path of the guest device (json-string, optional)
|
|
- "node-name": root node of the BDS tree to insert into the block device
|
|
|
|
Example:
|
|
|
|
-> { "execute": "blockdev-add",
|
|
"arguments": { { "node-name": "node0",
|
|
"driver": "raw",
|
|
"file": { "driver": "file",
|
|
"filename": "fedora.iso" } } }
|
|
|
|
<- { "return": {} }
|
|
|
|
-> { "execute": "x-blockdev-insert-medium",
|
|
"arguments": { "id": "ide0-1-0",
|
|
"node-name": "node0" } }
|
|
|
|
<- { "return": {} }
|
|
|
|
x-blockdev-change
|
|
-----------------
|
|
|
|
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": the id or name of the parent node (json-string)
|
|
- "child": the name of a child under the given parent node (json-string, optional)
|
|
- "node": the name of the node that will be added (json-string, optional)
|
|
|
|
Note: this command is experimental, and not a stable API. It doesn't
|
|
support all kinds of operations, all kinds of children, nor all block
|
|
drivers.
|
|
|
|
Warning: The data in a new quorum child MUST be consistent with that of
|
|
the rest of the array.
|
|
|
|
Example:
|
|
|
|
Add a new node to a quorum
|
|
-> { "execute": "blockdev-add",
|
|
"arguments": { "driver": "raw",
|
|
"node-name": "new_node",
|
|
"file": { "driver": "file",
|
|
"filename": "test.raw" } } }
|
|
<- { "return": {} }
|
|
-> { "execute": "x-blockdev-change",
|
|
"arguments": { "parent": "disk1",
|
|
"node": "new_node" } }
|
|
<- { "return": {} }
|
|
|
|
Delete a quorum's node
|
|
-> { "execute": "x-blockdev-change",
|
|
"arguments": { "parent": "disk1",
|
|
"child": "children.1" } }
|
|
<- { "return": {} }
|
|
|
|
blockdev-change-medium
|
|
----------------------
|
|
|
|
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.
|
|
|
|
Arguments:
|
|
|
|
- "device": block device name (deprecated, use @id instead)
|
|
(json-string, optional)
|
|
- "id": the name or QOM path of the guest device (json-string, optional)
|
|
- "filename": filename of the new image (json-string)
|
|
- "format": format of the new image (json-string, optional)
|
|
- "read-only-mode": new read-only mode (json-string, optional)
|
|
- Possible values: "retain" (default), "read-only", "read-write"
|
|
|
|
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": {} }
|
|
|
|
trace-event-get-state
|
|
---------------------
|
|
|
|
Query the state of events.
|
|
|
|
Arguments:
|
|
|
|
- "name": Event name pattern (json-string).
|
|
- "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
|
|
|
|
An event is returned if:
|
|
- its name matches the "name" pattern, and
|
|
- if "vcpu" is given, the event has the "vcpu" property.
|
|
|
|
Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
|
|
returning their state on the specified vCPU. Special case: if "name" is an exact
|
|
match, "vcpu" is given and the event does not have the "vcpu" property, an error
|
|
is returned.
|
|
|
|
Example:
|
|
|
|
-> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
|
|
<- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
|
|
|
|
trace-event-set-state
|
|
---------------------
|
|
|
|
Set the state of events.
|
|
|
|
Arguments:
|
|
|
|
- "name": Event name pattern (json-string).
|
|
- "enable": Whether to enable or disable the event (json-bool).
|
|
- "ignore-unavailable": Whether to ignore errors for events that cannot be
|
|
changed (json-bool, optional).
|
|
- "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
|
|
|
|
An event's state is modified if:
|
|
- its name matches the "name" pattern, and
|
|
- if "vcpu" is given, the event has the "vcpu" property.
|
|
|
|
Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
|
|
setting their state on the specified vCPU. Special case: if "name" is an exact
|
|
match, "vcpu" is given and the event does not have the "vcpu" property, an error
|
|
is returned.
|
|
|
|
Example:
|
|
|
|
-> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
|
|
<- { "return": {} }
|
|
|
|
block-set-write-threshold
|
|
------------
|
|
|
|
Change the write threshold for a block drive. The threshold is an offset,
|
|
thus must be non-negative. Default is no write threshold.
|
|
Setting the threshold to zero disables it.
|
|
|
|
Arguments:
|
|
|
|
- "node-name": the node name in the block driver state graph (json-string)
|
|
- "write-threshold": the write threshold in bytes (json-int)
|
|
|
|
Example:
|
|
|
|
-> { "execute": "block-set-write-threshold",
|
|
"arguments": { "node-name": "mydev",
|
|
"write-threshold": 17179869184 } }
|
|
<- { "return": {} }
|
|
|
|
Show rocker switch
|
|
------------------
|
|
|
|
Arguments:
|
|
|
|
- "name": switch name
|
|
|
|
Example:
|
|
|
|
-> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
|
|
<- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
|
|
|
|
Show rocker switch ports
|
|
------------------------
|
|
|
|
Arguments:
|
|
|
|
- "name": switch name
|
|
|
|
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}
|
|
]}
|
|
|
|
Show rocker switch OF-DPA flow tables
|
|
-------------------------------------
|
|
|
|
Arguments:
|
|
|
|
- "name": switch name
|
|
- "tbl-id": (optional) flow table ID
|
|
|
|
Example:
|
|
|
|
-> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
|
|
<- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
|
|
"hits": 138,
|
|
"cookie": 0,
|
|
"action": {"goto-tbl": 10},
|
|
"mask": {"in-pport": 4294901760}
|
|
},
|
|
{...more...},
|
|
]}
|
|
|
|
Show rocker OF-DPA group tables
|
|
-------------------------------
|
|
|
|
Arguments:
|
|
|
|
- "name": switch name
|
|
- "type": (optional) group type
|
|
|
|
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}
|
|
]}
|
|
|
|
query-gic-capabilities
|
|
---------------
|
|
|
|
Return a list of GICCapability objects, describing supported GIC
|
|
(Generic Interrupt Controller) versions.
|
|
|
|
Arguments: None
|
|
|
|
Example:
|
|
|
|
-> { "execute": "query-gic-capabilities" }
|
|
<- { "return": [{ "version": 2, "emulated": true, "kernel": false },
|
|
{ "version": 3, "emulated": false, "kernel": true } ] }
|
|
|
|
Show existing/possible CPUs
|
|
---------------------------
|
|
|
|
Arguments: None.
|
|
|
|
Example for pseries machine type started with
|
|
-smp 2,cores=2,maxcpus=4 -cpu POWER8:
|
|
|
|
-> { "execute": "query-hotpluggable-cpus" }
|
|
<- {"return": [
|
|
{ "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
|
|
"vcpus-count": 1 },
|
|
{ "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
|
|
"vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
|
|
]}'
|
|
|
|
Example for pc machine type started with
|
|
-smp 1,maxcpus=2:
|
|
-> { "execute": "query-hotpluggable-cpus" }
|
|
<- {"return": [
|
|
{
|
|
"type": "qemu64-x86_64-cpu", "vcpus-count": 1,
|
|
"props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
|
|
},
|
|
{
|
|
"qom-path": "/machine/unattached/device[0]",
|
|
"type": "qemu64-x86_64-cpu", "vcpus-count": 1,
|
|
"props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
|
|
}
|
|
]}
|