Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging
[qemu.git] / docs / interop / qmp-spec.txt
1                       QEMU Machine Protocol Specification
2
3 0. About This Document
4 ======================
5
6 Copyright (C) 2009-2016 Red Hat, Inc.
7
8 This work is licensed under the terms of the GNU GPL, version 2 or
9 later. See the COPYING file in the top-level directory.
10
11 1. Introduction
12 ===============
13
14 This document specifies the QEMU Machine Protocol (QMP), a JSON-based
15 protocol which is available for applications to operate QEMU at the
16 machine-level.  It is also in use by the QEMU Guest Agent (QGA), which
17 is available for host applications to interact with the guest
18 operating system.
19
20 2. Protocol Specification
21 =========================
22
23 This section details the protocol format. For the purpose of this
24 document, "Server" is either QEMU or the QEMU Guest Agent, and
25 "Client" is any application communicating with it via QMP.
26
27 JSON data structures, when mentioned in this document, are always in the
28 following format:
29
30     json-DATA-STRUCTURE-NAME
31
32 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined
33 by the JSON standard:
34
35 http://www.ietf.org/rfc/rfc7159.txt
36
37 The server expects its input to be encoded in UTF-8, and sends its
38 output encoded in ASCII.
39
40 For convenience, json-object members mentioned in this document will
41 be in a certain order. However, in real protocol usage they can be in
42 ANY order, thus no particular order should be assumed. On the other
43 hand, use of json-array elements presumes that preserving order is
44 important unless specifically documented otherwise.  Repeating a key
45 within a json-object gives unpredictable results.
46
47 Also for convenience, the server will accept an extension of
48 'single-quoted' strings in place of the usual "double-quoted"
49 json-string, and both input forms of strings understand an additional
50 escape sequence of "\'" for a single quote. The server will only use
51 double quoting on output.
52
53 2.1 General Definitions
54 -----------------------
55
56 2.1.1 All interactions transmitted by the Server are json-objects, always
57       terminating with CRLF
58
59 2.1.2 All json-objects members are mandatory when not specified otherwise
60
61 2.2 Server Greeting
62 -------------------
63
64 Right when connected the Server will issue a greeting message, which signals
65 that the connection has been successfully established and that the Server is
66 ready for capabilities negotiation (for more information refer to section
67 '4. Capabilities Negotiation').
68
69 The greeting message format is:
70
71 { "QMP": { "version": json-object, "capabilities": json-array } }
72
73  Where,
74
75 - The "version" member contains the Server's version information (the format
76   is the same of the query-version command)
77 - The "capabilities" member specify the availability of features beyond the
78   baseline specification; the order of elements in this array has no
79   particular significance.
80
81 2.2.1 Capabilities
82 ------------------
83
84 Currently supported capabilities are:
85
86 - "oob": the QMP server supports "out-of-band" (OOB) command
87   execution, as described in section "2.3.1 Out-of-band execution".
88
89 2.3 Issuing Commands
90 --------------------
91
92 The format for command execution is:
93
94 { "execute": json-string, "arguments": json-object, "id": json-value }
95
96 or
97
98 { "exec-oob": json-string, "arguments": json-object, "id": json-value }
99
100  Where,
101
102 - The "execute" or "exec-oob" member identifies the command to be
103   executed by the server.  The latter requests out-of-band execution.
104 - The "arguments" member is used to pass any arguments required for the
105   execution of the command, it is optional when no arguments are
106   required. Each command documents what contents will be considered
107   valid when handling the json-argument
108 - The "id" member is a transaction identification associated with the
109   command execution, it is optional and will be part of the response
110   if provided.  The "id" member can be any json-value.  A json-number
111   incremented for each successive command works fine.
112
113 2.3.1 Out-of-band execution
114 ---------------------------
115
116 The server normally reads, executes and responds to one command after
117 the other.  The client therefore receives command responses in issue
118 order.
119
120 With out-of-band execution enabled via capability negotiation (section
121 4.), the server reads and queues commands as they arrive.  It executes
122 commands from the queue one after the other.  Commands executed
123 out-of-band jump the queue: the command get executed right away,
124 possibly overtaking prior in-band commands.  The client may therefore
125 receive such a command's response before responses from prior in-band
126 commands.
127
128 To be able to match responses back to their commands, the client needs
129 to pass "id" with out-of-band commands.  Passing it with all commands
130 is recommended for clients that accept capability "oob".
131
132 If the client sends in-band commands faster than the server can
133 execute them, the server will eventually drop commands to limit the
134 queue length.  The sever sends event COMMAND_DROPPED then.
135
136 Only a few commands support out-of-band execution.  The ones that do
137 have "allow-oob": true in output of query-qmp-schema.
138
139 2.4 Commands Responses
140 ----------------------
141
142 There are two possible responses which the Server will issue as the result
143 of a command execution: success or error.
144
145 As long as the commands were issued with a proper "id" field, then the
146 same "id" field will be attached in the corresponding response message
147 so that requests and responses can match.  Clients should drop all the
148 responses that have an unknown "id" field.
149
150 2.4.1 success
151 -------------
152
153 The format of a success response is:
154
155 { "return": json-value, "id": json-value }
156
157  Where,
158
159 - The "return" member contains the data returned by the command, which
160   is defined on a per-command basis (usually a json-object or
161   json-array of json-objects, but sometimes a json-number, json-string,
162   or json-array of json-strings); it is an empty json-object if the
163   command does not return data
164 - The "id" member contains the transaction identification associated
165   with the command execution if issued by the Client
166
167 2.4.2 error
168 -----------
169
170 The format of an error response is:
171
172 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
173
174  Where,
175
176 - The "class" member contains the error class name (eg. "GenericError")
177 - The "desc" member is a human-readable error message. Clients should
178   not attempt to parse this message.
179 - The "id" member contains the transaction identification associated with
180   the command execution if issued by the Client
181
182 NOTE: Some errors can occur before the Server is able to read the "id" member,
183 in these cases the "id" member will not be part of the error response, even
184 if provided by the client.
185
186 2.5 Asynchronous events
187 -----------------------
188
189 As a result of state changes, the Server may send messages unilaterally
190 to the Client at any time, when not in the middle of any other
191 response. They are called "asynchronous events".
192
193 The format of asynchronous events is:
194
195 { "event": json-string, "data": json-object,
196   "timestamp": { "seconds": json-number, "microseconds": json-number } }
197
198  Where,
199
200 - The "event" member contains the event's name
201 - The "data" member contains event specific data, which is defined in a
202   per-event basis, it is optional
203 - The "timestamp" member contains the exact time of when the event
204   occurred in the Server. It is a fixed json-object with time in
205   seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
206   there is a failure to retrieve host time, both members of the
207   timestamp will be set to -1.
208
209 For a listing of supported asynchronous events, please, refer to the
210 qmp-events.txt file.
211
212 Some events are rate-limited to at most one per second.  If additional
213 "similar" events arrive within one second, all but the last one are
214 dropped, and the last one is delayed.  "Similar" normally means same
215 event type.  See qmp-events.txt for details.
216
217 2.6 Forcing the JSON parser into known-good state
218 -------------------------------------------------
219
220 Incomplete or invalid input can leave the server's JSON parser in a
221 state where it can't parse additional commands.  To get it back into
222 known-good state, the client should provoke a lexical error.
223
224 The cleanest way to do that is sending an ASCII control character
225 other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new
226 line).
227
228 Sadly, older versions of QEMU can fail to flag this as an error.  If a
229 client needs to deal with them, it should send a 0xFF byte.
230
231 2.7 QGA Synchronization
232 -----------------------
233
234 When a client connects to QGA over a transport lacking proper
235 connection semantics such as virtio-serial, QGA may have read partial
236 input from a previous client.  The client needs to force QGA's parser
237 into known-good state using the previous section's technique.
238 Moreover, the client may receive output a previous client didn't read.
239 To help with skipping that output, QGA provides the
240 'guest-sync-delimited' command.  Refer to its documentation for
241 details.
242
243
244 3. QMP Examples
245 ===============
246
247 This section provides some examples of real QMP usage, in all of them
248 "C" stands for "Client" and "S" stands for "Server".
249
250 3.1 Server greeting
251 -------------------
252
253 S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
254      "package": "v3.0.0"}, "capabilities": ["oob"] } }
255
256 3.2 Capabilities negotiation
257 ----------------------------
258
259 C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
260 S: { "return": {}}
261
262 3.3 Simple 'stop' execution
263 ---------------------------
264
265 C: { "execute": "stop" }
266 S: { "return": {} }
267
268 3.4 KVM information
269 -------------------
270
271 C: { "execute": "query-kvm", "id": "example" }
272 S: { "return": { "enabled": true, "present": true }, "id": "example"}
273
274 3.5 Parsing error
275 ------------------
276
277 C: { "execute": }
278 S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
279
280 3.6 Powerdown event
281 -------------------
282
283 S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
284     "event": "POWERDOWN" }
285
286 3.7 Out-of-band execution
287 -------------------------
288
289 C: { "exec-oob": "migrate-pause", "id": 42 }
290 S: { "id": 42,
291      "error": { "class": "GenericError",
292       "desc": "migrate-pause is currently only supported during postcopy-active state" } }
293
294
295 4. Capabilities Negotiation
296 ===========================
297
298 When a Client successfully establishes a connection, the Server is in
299 Capabilities Negotiation mode.
300
301 In this mode only the qmp_capabilities command is allowed to run, all
302 other commands will return the CommandNotFound error. Asynchronous
303 messages are not delivered either.
304
305 Clients should use the qmp_capabilities command to enable capabilities
306 advertised in the Server's greeting (section '2.2 Server Greeting') they
307 support.
308
309 When the qmp_capabilities command is issued, and if it does not return an
310 error, the Server enters in Command mode where capabilities changes take
311 effect, all commands (except qmp_capabilities) are allowed and asynchronous
312 messages are delivered.
313
314 5 Compatibility Considerations
315 ==============================
316
317 All protocol changes or new features which modify the protocol format in an
318 incompatible way are disabled by default and will be advertised by the
319 capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
320 that array and enable the capabilities they support.
321
322 The QMP Server performs a type check on the arguments to a command.  It
323 generates an error if a value does not have the expected type for its
324 key, or if it does not understand a key that the Client included.  The
325 strictness of the Server catches wrong assumptions of Clients about
326 the Server's schema.  Clients can assume that, when such validation
327 errors occur, they will be reported before the command generated any
328 side effect.
329
330 However, Clients must not assume any particular:
331
332 - Length of json-arrays
333 - Size of json-objects; in particular, future versions of QEMU may add
334   new keys and Clients should be able to ignore them.
335 - Order of json-object members or json-array elements
336 - Amount of errors generated by a command, that is, new errors can be added
337   to any existing command in newer versions of the Server
338
339 Any command or member name beginning with "x-" is deemed experimental,
340 and may be withdrawn or changed in an incompatible manner in a future
341 release.
342
343 Of course, the Server does guarantee to send valid JSON.  But apart from
344 this, a Client should be "conservative in what they send, and liberal in
345 what they accept".
346
347 6. Downstream extension of QMP
348 ==============================
349
350 We recommend that downstream consumers of QEMU do *not* modify QMP.
351 Management tools should be able to support both upstream and downstream
352 versions of QMP without special logic, and downstream extensions are
353 inherently at odds with that.
354
355 However, we recognize that it is sometimes impossible for downstreams to
356 avoid modifying QMP.  Both upstream and downstream need to take care to
357 preserve long-term compatibility and interoperability.
358
359 To help with that, QMP reserves JSON object member names beginning with
360 '__' (double underscore) for downstream use ("downstream names").  This
361 means upstream will never use any downstream names for its commands,
362 arguments, errors, asynchronous events, and so forth.
363
364 Any new names downstream wishes to add must begin with '__'.  To
365 ensure compatibility with other downstreams, it is strongly
366 recommended that you prefix your downstream names with '__RFQDN_' where
367 RFQDN is a valid, reverse fully qualified domain name which you
368 control.  For example, a qemu-kvm specific monitor command would be:
369
370     (qemu) __org.linux-kvm_enable_irqchip
371
372 Downstream must not change the server greeting (section 2.2) other than
373 to offer additional capabilities.  But see below for why even that is
374 discouraged.
375
376 Section '5 Compatibility Considerations' applies to downstream as well
377 as to upstream, obviously.  It follows that downstream must behave
378 exactly like upstream for any input not containing members with
379 downstream names ("downstream members"), except it may add members
380 with downstream names to its output.
381
382 Thus, a client should not be able to distinguish downstream from
383 upstream as long as it doesn't send input with downstream members, and
384 properly ignores any downstream members in the output it receives.
385
386 Advice on downstream modifications:
387
388 1. Introducing new commands is okay.  If you want to extend an existing
389    command, consider introducing a new one with the new behaviour
390    instead.
391
392 2. Introducing new asynchronous messages is okay.  If you want to extend
393    an existing message, consider adding a new one instead.
394
395 3. Introducing new errors for use in new commands is okay.  Adding new
396    errors to existing commands counts as extension, so 1. applies.
397
398 4. New capabilities are strongly discouraged.  Capabilities are for
399    evolving the basic protocol, and multiple diverging basic protocol
400    dialects are most undesirable.