Commit cf869d5317
"qmp: support out-of-band (oob) execution" added a
general mechanism for command-independent arguments just for an
out-of-band flag:
The "control" key is introduced to store this extra flag. "control"
field is used to store arguments that are shared by all the commands,
rather than command specific arguments. Let "run-oob" be the first.
However, it failed to reject unknown members of "control". For
instance, in QMP command
{"execute": "query-name", "id": 42, "control": {"crap": true}}
"crap" gets silently ignored.
Instead of fixing this, revert the general "control" mechanism
(because YAGNI), and do it the way I initially proposed, with key
"exec-oob". Simpler code, simpler interface.
An out-of-band command
{"execute": "migrate-pause", "id": 42, "control": {"run-oob": true}}
becomes
{"exec-oob": "migrate-pause", "id": 42}
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20180703085358.13941-13-armbru@redhat.com>
[Commit message typo fixed]
387 lines
14 KiB
Plaintext
387 lines
14 KiB
Plaintext
QEMU Machine Protocol Specification
|
|
|
|
0. About This Document
|
|
======================
|
|
|
|
Copyright (C) 2009-2016 Red Hat, Inc.
|
|
|
|
This work is licensed under the terms of the GNU GPL, version 2 or
|
|
later. See the COPYING file in the top-level directory.
|
|
|
|
1. Introduction
|
|
===============
|
|
|
|
This document specifies the QEMU Machine Protocol (QMP), a JSON-based
|
|
protocol which is available for applications to operate QEMU at the
|
|
machine-level. It is also in use by the QEMU Guest Agent (QGA), which
|
|
is available for host applications to interact with the guest
|
|
operating system.
|
|
|
|
2. Protocol Specification
|
|
=========================
|
|
|
|
This section details the protocol format. For the purpose of this document
|
|
"Client" is any application which is using QMP to communicate with QEMU and
|
|
"Server" is QEMU itself.
|
|
|
|
JSON data structures, when mentioned in this document, are always in the
|
|
following format:
|
|
|
|
json-DATA-STRUCTURE-NAME
|
|
|
|
Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
|
|
by the JSON standard:
|
|
|
|
http://www.ietf.org/rfc/rfc7159.txt
|
|
|
|
The protocol is always encoded in UTF-8 except for synchronization
|
|
bytes (documented below); although thanks to json-string escape
|
|
sequences, the server will reply using only the strict ASCII subset.
|
|
|
|
For convenience, json-object members mentioned in this document will
|
|
be in a certain order. However, in real protocol usage they can be in
|
|
ANY order, thus no particular order should be assumed. On the other
|
|
hand, use of json-array elements presumes that preserving order is
|
|
important unless specifically documented otherwise. Repeating a key
|
|
within a json-object gives unpredictable results.
|
|
|
|
Also for convenience, the server will accept an extension of
|
|
'single-quoted' strings in place of the usual "double-quoted"
|
|
json-string, and both input forms of strings understand an additional
|
|
escape sequence of "\'" for a single quote. The server will only use
|
|
double quoting on output.
|
|
|
|
2.1 General Definitions
|
|
-----------------------
|
|
|
|
2.1.1 All interactions transmitted by the Server are json-objects, always
|
|
terminating with CRLF
|
|
|
|
2.1.2 All json-objects members are mandatory when not specified otherwise
|
|
|
|
2.2 Server Greeting
|
|
-------------------
|
|
|
|
Right when connected the Server will issue a greeting message, which signals
|
|
that the connection has been successfully established and that the Server is
|
|
ready for capabilities negotiation (for more information refer to section
|
|
'4. Capabilities Negotiation').
|
|
|
|
The greeting message format is:
|
|
|
|
{ "QMP": { "version": json-object, "capabilities": json-array } }
|
|
|
|
Where,
|
|
|
|
- The "version" member contains the Server's version information (the format
|
|
is the same of the query-version command)
|
|
- The "capabilities" member specify the availability of features beyond the
|
|
baseline specification; the order of elements in this array has no
|
|
particular significance.
|
|
|
|
2.2.1 Capabilities
|
|
------------------
|
|
|
|
Currently supported capabilities are:
|
|
|
|
- "oob": the QMP server supports "out-of-band" (OOB) command
|
|
execution, as described in section "2.3.1 Out-of-band execution".
|
|
|
|
2.3 Issuing Commands
|
|
--------------------
|
|
|
|
The format for command execution is:
|
|
|
|
{ "execute": json-string, "arguments": json-object, "id": json-value }
|
|
|
|
or
|
|
|
|
{ "exec-oob": json-string, "arguments": json-object, "id": json-value }
|
|
|
|
Where,
|
|
|
|
- The "execute" or "exec-oob" member identifies the command to be
|
|
executed by the server. The latter requests out-of-band execution.
|
|
- The "arguments" member is used to pass any arguments required for the
|
|
execution of the command, it is optional when no arguments are
|
|
required. Each command documents what contents will be considered
|
|
valid when handling the json-argument
|
|
- The "id" member is a transaction identification associated with the
|
|
command execution, it is optional and will be part of the response
|
|
if provided. The "id" member can be any json-value. A json-number
|
|
incremented for each successive command works fine.
|
|
|
|
2.3.1 Out-of-band execution
|
|
---------------------------
|
|
|
|
The server normally reads, executes and responds to one command after
|
|
the other. The client therefore receives command responses in issue
|
|
order.
|
|
|
|
With out-of-band execution enabled via capability negotiation (section
|
|
4.), the server reads and queues commands as they arrive. It executes
|
|
commands from the queue one after the other. Commands executed
|
|
out-of-band jump the queue: the command get executed right away,
|
|
possibly overtaking prior in-band commands. The client may therefore
|
|
receive such a command's response before responses from prior in-band
|
|
commands.
|
|
|
|
To be able to match responses back to their commands, the client needs
|
|
to pass "id" with out-of-band commands. Passing it with all commands
|
|
is recommended for clients that accept capability "oob".
|
|
|
|
If the client sends in-band commands faster than the server can
|
|
execute them, the server will eventually drop commands to limit the
|
|
queue length. The sever sends event COMMAND_DROPPED then.
|
|
|
|
Only a few commands support out-of-band execution. The ones that do
|
|
have "allow-oob": true in output of query-qmp-schema.
|
|
|
|
2.4 Commands Responses
|
|
----------------------
|
|
|
|
There are two possible responses which the Server will issue as the result
|
|
of a command execution: success or error.
|
|
|
|
As long as the commands were issued with a proper "id" field, then the
|
|
same "id" field will be attached in the corresponding response message
|
|
so that requests and responses can match. Clients should drop all the
|
|
responses that have an unknown "id" field.
|
|
|
|
2.4.1 success
|
|
-------------
|
|
|
|
The format of a success response is:
|
|
|
|
{ "return": json-value, "id": json-value }
|
|
|
|
Where,
|
|
|
|
- The "return" member contains the data returned by the command, which
|
|
is defined on a per-command basis (usually a json-object or
|
|
json-array of json-objects, but sometimes a json-number, json-string,
|
|
or json-array of json-strings); it is an empty json-object if the
|
|
command does not return data
|
|
- The "id" member contains the transaction identification associated
|
|
with the command execution if issued by the Client
|
|
|
|
2.4.2 error
|
|
-----------
|
|
|
|
The format of an error response is:
|
|
|
|
{ "error": { "class": json-string, "desc": json-string }, "id": json-value }
|
|
|
|
Where,
|
|
|
|
- The "class" member contains the error class name (eg. "GenericError")
|
|
- The "desc" member is a human-readable error message. Clients should
|
|
not attempt to parse this message.
|
|
- The "id" member contains the transaction identification associated with
|
|
the command execution if issued by the Client
|
|
|
|
NOTE: Some errors can occur before the Server is able to read the "id" member,
|
|
in these cases the "id" member will not be part of the error response, even
|
|
if provided by the client.
|
|
|
|
2.5 Asynchronous events
|
|
-----------------------
|
|
|
|
As a result of state changes, the Server may send messages unilaterally
|
|
to the Client at any time, when not in the middle of any other
|
|
response. They are called "asynchronous events".
|
|
|
|
The format of asynchronous events is:
|
|
|
|
{ "event": json-string, "data": json-object,
|
|
"timestamp": { "seconds": json-number, "microseconds": json-number } }
|
|
|
|
Where,
|
|
|
|
- The "event" member contains the event's name
|
|
- The "data" member contains event specific data, which is defined in a
|
|
per-event basis, it is optional
|
|
- The "timestamp" member contains the exact time of when the event
|
|
occurred in the Server. It is a fixed json-object with time in
|
|
seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
|
|
there is a failure to retrieve host time, both members of the
|
|
timestamp will be set to -1.
|
|
|
|
For a listing of supported asynchronous events, please, refer to the
|
|
qmp-events.txt file.
|
|
|
|
Some events are rate-limited to at most one per second. If additional
|
|
"similar" events arrive within one second, all but the last one are
|
|
dropped, and the last one is delayed. "Similar" normally means same
|
|
event type. See qmp-events.txt for details.
|
|
|
|
2.6 QGA Synchronization
|
|
-----------------------
|
|
|
|
When using QGA, an additional synchronization feature is built into
|
|
the protocol. If the Client sends a raw 0xFF sentinel byte (not valid
|
|
JSON), then the Server will reset its state and discard all pending
|
|
data prior to the sentinel. Conversely, if the Client makes use of
|
|
the 'guest-sync-delimited' command, the Server will send a raw 0xFF
|
|
sentinel byte prior to its response, to aid the Client in discarding
|
|
any data prior to the sentinel.
|
|
|
|
|
|
3. QMP Examples
|
|
===============
|
|
|
|
This section provides some examples of real QMP usage, in all of them
|
|
"C" stands for "Client" and "S" stands for "Server".
|
|
|
|
3.1 Server greeting
|
|
-------------------
|
|
|
|
S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
|
|
"package": "v3.0.0"}, "capabilities": ["oob"] } }
|
|
|
|
3.2 Capabilities negotiation
|
|
----------------------------
|
|
|
|
C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
|
|
S: { "return": {}}
|
|
|
|
3.3 Simple 'stop' execution
|
|
---------------------------
|
|
|
|
C: { "execute": "stop" }
|
|
S: { "return": {} }
|
|
|
|
3.4 KVM information
|
|
-------------------
|
|
|
|
C: { "execute": "query-kvm", "id": "example" }
|
|
S: { "return": { "enabled": true, "present": true }, "id": "example"}
|
|
|
|
3.5 Parsing error
|
|
------------------
|
|
|
|
C: { "execute": }
|
|
S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
|
|
|
|
3.6 Powerdown event
|
|
-------------------
|
|
|
|
S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
|
|
"event": "POWERDOWN" }
|
|
|
|
3.7 Out-of-band execution
|
|
-------------------------
|
|
|
|
C: { "exec-oob": "migrate-pause", "id": 42 }
|
|
S: { "id": 42,
|
|
"error": { "class": "GenericError",
|
|
"desc": "migrate-pause is currently only supported during postcopy-active state" } }
|
|
|
|
|
|
4. Capabilities Negotiation
|
|
===========================
|
|
|
|
When a Client successfully establishes a connection, the Server is in
|
|
Capabilities Negotiation mode.
|
|
|
|
In this mode only the qmp_capabilities command is allowed to run, all
|
|
other commands will return the CommandNotFound error. Asynchronous
|
|
messages are not delivered either.
|
|
|
|
Clients should use the qmp_capabilities command to enable capabilities
|
|
advertised in the Server's greeting (section '2.2 Server Greeting') they
|
|
support.
|
|
|
|
When the qmp_capabilities command is issued, and if it does not return an
|
|
error, the Server enters in Command mode where capabilities changes take
|
|
effect, all commands (except qmp_capabilities) are allowed and asynchronous
|
|
messages are delivered.
|
|
|
|
5 Compatibility Considerations
|
|
==============================
|
|
|
|
All protocol changes or new features which modify the protocol format in an
|
|
incompatible way are disabled by default and will be advertised by the
|
|
capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
|
|
that array and enable the capabilities they support.
|
|
|
|
The QMP Server performs a type check on the arguments to a command. It
|
|
generates an error if a value does not have the expected type for its
|
|
key, or if it does not understand a key that the Client included. The
|
|
strictness of the Server catches wrong assumptions of Clients about
|
|
the Server's schema. Clients can assume that, when such validation
|
|
errors occur, they will be reported before the command generated any
|
|
side effect.
|
|
|
|
However, Clients must not assume any particular:
|
|
|
|
- Length of json-arrays
|
|
- Size of json-objects; in particular, future versions of QEMU may add
|
|
new keys and Clients should be able to ignore them.
|
|
- Order of json-object members or json-array elements
|
|
- Amount of errors generated by a command, that is, new errors can be added
|
|
to any existing command in newer versions of the Server
|
|
|
|
Any command or member name beginning with "x-" is deemed experimental,
|
|
and may be withdrawn or changed in an incompatible manner in a future
|
|
release.
|
|
|
|
Of course, the Server does guarantee to send valid JSON. But apart from
|
|
this, a Client should be "conservative in what they send, and liberal in
|
|
what they accept".
|
|
|
|
6. Downstream extension of QMP
|
|
==============================
|
|
|
|
We recommend that downstream consumers of QEMU do *not* modify QMP.
|
|
Management tools should be able to support both upstream and downstream
|
|
versions of QMP without special logic, and downstream extensions are
|
|
inherently at odds with that.
|
|
|
|
However, we recognize that it is sometimes impossible for downstreams to
|
|
avoid modifying QMP. Both upstream and downstream need to take care to
|
|
preserve long-term compatibility and interoperability.
|
|
|
|
To help with that, QMP reserves JSON object member names beginning with
|
|
'__' (double underscore) for downstream use ("downstream names"). This
|
|
means upstream will never use any downstream names for its commands,
|
|
arguments, errors, asynchronous events, and so forth.
|
|
|
|
Any new names downstream wishes to add must begin with '__'. To
|
|
ensure compatibility with other downstreams, it is strongly
|
|
recommended that you prefix your downstream names with '__RFQDN_' where
|
|
RFQDN is a valid, reverse fully qualified domain name which you
|
|
control. For example, a qemu-kvm specific monitor command would be:
|
|
|
|
(qemu) __org.linux-kvm_enable_irqchip
|
|
|
|
Downstream must not change the server greeting (section 2.2) other than
|
|
to offer additional capabilities. But see below for why even that is
|
|
discouraged.
|
|
|
|
Section '5 Compatibility Considerations' applies to downstream as well
|
|
as to upstream, obviously. It follows that downstream must behave
|
|
exactly like upstream for any input not containing members with
|
|
downstream names ("downstream members"), except it may add members
|
|
with downstream names to its output.
|
|
|
|
Thus, a client should not be able to distinguish downstream from
|
|
upstream as long as it doesn't send input with downstream members, and
|
|
properly ignores any downstream members in the output it receives.
|
|
|
|
Advice on downstream modifications:
|
|
|
|
1. Introducing new commands is okay. If you want to extend an existing
|
|
command, consider introducing a new one with the new behaviour
|
|
instead.
|
|
|
|
2. Introducing new asynchronous messages is okay. If you want to extend
|
|
an existing message, consider adding a new one instead.
|
|
|
|
3. Introducing new errors for use in new commands is okay. Adding new
|
|
errors to existing commands counts as extension, so 1. applies.
|
|
|
|
4. New capabilities are strongly discouraged. Capabilities are for
|
|
evolving the basic protocol, and multiple diverging basic protocol
|
|
dialects are most undesirable.
|