1
QEMU Monitor Protocol Specification - Version 0.1
6
This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
7
which is available for applications to control QEMU at the machine-level.
9
To enable QMP support, QEMU has to be run in "control mode". This is done by
10
starting QEMU with the appropriate command-line options. Please, refer to the
11
QEMU manual page for more information.
13
2. Protocol Specification
14
=========================
16
This section details the protocol format. For the purpose of this document
17
"Client" is any application which is communicating with QEMU in control mode,
18
and "Server" is QEMU itself.
20
JSON data structures, when mentioned in this document, are always in the
23
json-DATA-STRUCTURE-NAME
25
Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
28
http://www.ietf.org/rfc/rfc4627.txt
30
For convenience, json-object members and json-array elements mentioned in
31
this document will be in a certain order. However, in real protocol usage
32
they can be in ANY order, thus no particular order should be assumed.
34
2.1 General Definitions
35
-----------------------
37
2.1.1 All interactions transmitted by the Server are json-objects, always
40
2.1.2 All json-objects members are mandatory when not specified otherwise
45
Right when connected the Server will issue a greeting message, which signals
46
that the connection has been successfully established and that the Server is
47
ready for capabilities negotiation (for more information refer to section
48
'4. Capabilities Negotiation').
52
{ "QMP": { "version": json-object, "capabilities": json-array } }
56
- The "version" member contains the Server's version information (the format
57
is the same of the 'query-version' command)
58
- The "capabilities" member specify the availability of features beyond the
59
baseline specification
64
The format for command execution is:
66
{ "execute": json-string, "arguments": json-object, "id": json-value }
70
- The "execute" member identifies the command to be executed by the Server
71
- The "arguments" member is used to pass any arguments required for the
72
execution of the command, it is optional when no arguments are required
73
- The "id" member is a transaction identification associated with the
74
command execution, it is optional and will be part of the response if
77
2.4 Commands Responses
78
----------------------
80
There are two possible responses which the Server will issue as the result
81
of a command execution: success or error.
86
The success response is issued when the command execution has finished
91
{ "return": json-object, "id": json-value }
95
- The "return" member contains the command returned data, which is defined
96
in a per-command basis or an empty json-object if the command does not
98
- The "id" member contains the transaction identification associated
99
with the command execution (if issued by the Client)
104
The error response is issued when the command execution could not be
105
completed because of an error condition.
109
{ "error": { "class": json-string, "data": json-object, "desc": json-string },
114
- The "class" member contains the error class name (eg. "ServiceUnavailable")
115
- The "data" member contains specific error data and is defined in a
116
per-command basis, it will be an empty json-object if the error has no data
117
- The "desc" member is a human-readable error message. Clients should
118
not attempt to parse this message.
119
- The "id" member contains the transaction identification associated with
120
the command execution (if issued by the Client)
122
NOTE: Some errors can occur before the Server is able to read the "id" member,
123
in these cases the "id" member will not be part of the error response, even
124
if provided by the client.
126
2.5 Asynchronous events
127
-----------------------
129
As a result of state changes, the Server may send messages unilaterally
130
to the Client at any time. They are called 'asynchronous events'.
134
{ "event": json-string, "data": json-object,
135
"timestamp": { "seconds": json-number, "microseconds": json-number } }
139
- The "event" member contains the event's name
140
- The "data" member contains event specific data, which is defined in a
141
per-event basis, it is optional
142
- The "timestamp" member contains the exact time of when the event occurred
143
in the Server. It is a fixed json-object with time in seconds and
146
For a listing of supported asynchronous events, please, refer to the
152
This section provides some examples of real QMP usage, in all of them
153
'C' stands for 'Client' and 'S' stands for 'Server'.
158
S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
160
3.2 Simple 'stop' execution
161
---------------------------
163
C: { "execute": "stop" }
169
C: { "execute": "query-kvm", "id": "example" }
170
S: {"return": {"enabled": true, "present": true}, "id": "example"}
176
S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
182
S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
185
4. Capabilities Negotiation
186
----------------------------
188
When a Client successfully establishes a connection, the Server is in
189
Capabilities Negotiation mode.
191
In this mode only the 'qmp_capabilities' command is allowed to run, all
192
other commands will return the CommandNotFound error. Asynchronous messages
193
are not delivered either.
195
Clients should use the 'qmp_capabilities' command to enable capabilities
196
advertised in the Server's greeting (section '2.2 Server Greeting') they
199
When the 'qmp_capabilities' command is issued, and if it does not return an
200
error, the Server enters in Command mode where capabilities changes take
201
effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
202
messages are delivered.
204
5 Compatibility Considerations
205
------------------------------
207
All protocol changes or new features which modify the protocol format in an
208
incompatible way are disabled by default and will be advertised by the
209
capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
210
that array and enable the capabilities they support.
212
Additionally, Clients must not assume any particular:
214
- Size of json-objects or length of json-arrays
215
- Order of json-object members or json-array elements
216
- Amount of errors generated by a command, that is, new errors can be added
217
to any existing command in newer versions of the Server
219
6. Downstream extension of QMP
220
------------------------------
222
We recommend that downstream consumers of QEMU do *not* modify QMP.
223
Management tools should be able to support both upstream and downstream
224
versions of QMP without special logic, and downstream extensions are
225
inherently at odds with that.
227
However, we recognize that it is sometimes impossible for downstreams to
228
avoid modifying QMP. Both upstream and downstream need to take care to
229
preserve long-term compatibility and interoperability.
231
To help with that, QMP reserves JSON object member names beginning with
232
'__' (double underscore) for downstream use ("downstream names"). This
233
means upstream will never use any downstream names for its commands,
234
arguments, errors, asynchronous events, and so forth.
236
Any new names downstream wishes to add must begin with '__'. To
237
ensure compatibility with other downstreams, it is strongly
238
recommended that you prefix your downstram names with '__RFQDN_' where
239
RFQDN is a valid, reverse fully qualified domain name which you
240
control. For example, a qemu-kvm specific monitor command would be:
242
(qemu) __org.linux-kvm_enable_irqchip
244
Downstream must not change the server greeting (section 2.2) other than
245
to offer additional capabilities. But see below for why even that is
248
Section '5 Compatibility Considerations' applies to downstream as well
249
as to upstream, obviously. It follows that downstream must behave
250
exactly like upstream for any input not containing members with
251
downstream names ("downstream members"), except it may add members
252
with downstream names to its output.
254
Thus, a client should not be able to distinguish downstream from
255
upstream as long as it doesn't send input with downstream members, and
256
properly ignores any downstream members in the output it receives.
258
Advice on downstream modifications:
260
1. Introducing new commands is okay. If you want to extend an existing
261
command, consider introducing a new one with the new behaviour
264
2. Introducing new asynchronous messages is okay. If you want to extend
265
an existing message, consider adding a new one instead.
267
3. Introducing new errors for use in new commands is okay. Adding new
268
errors to existing commands counts as extension, so 1. applies.
270
4. New capabilities are strongly discouraged. Capabilities are for
271
evolving the basic protocol, and multiple diverging basic protocol
272
dialects are most undesirable.
added
removed
QMP/qmp-spec.txt
