docs/interop/qmp-spec: Point to the QEMU QMP reference manual
[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/rfc8259.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 The actual commands are documented in the QEMU QMP reference manual
114 docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
115
116 2.3.1 Out-of-band execution
117 ---------------------------
118
119 The server normally reads, executes and responds to one command after
120 the other.  The client therefore receives command responses in issue
121 order.
122
123 With out-of-band execution enabled via capability negotiation (section
124 4.), the server reads and queues commands as they arrive.  It executes
125 commands from the queue one after the other.  Commands executed
126 out-of-band jump the queue: the command get executed right away,
127 possibly overtaking prior in-band commands.  The client may therefore
128 receive such a command's response before responses from prior in-band
129 commands.
130
131 To be able to match responses back to their commands, the client needs
132 to pass "id" with out-of-band commands.  Passing it with all commands
133 is recommended for clients that accept capability "oob".
134
135 If the client sends in-band commands faster than the server can
136 execute them, the server will stop reading the requests from the QMP
137 channel until the request queue length is reduced to an acceptable
138 range.
139
140 Only a few commands support out-of-band execution.  The ones that do
141 have "allow-oob": true in output of query-qmp-schema.
142
143 2.4 Commands Responses
144 ----------------------
145
146 There are two possible responses which the Server will issue as the result
147 of a command execution: success or error.
148
149 As long as the commands were issued with a proper "id" field, then the
150 same "id" field will be attached in the corresponding response message
151 so that requests and responses can match.  Clients should drop all the
152 responses that have an unknown "id" field.
153
154 2.4.1 success
155 -------------
156
157 The format of a success response is:
158
159 { "return": json-value, "id": json-value }
160
161  Where,
162
163 - The "return" member contains the data returned by the command, which
164   is defined on a per-command basis (usually a json-object or
165   json-array of json-objects, but sometimes a json-number, json-string,
166   or json-array of json-strings); it is an empty json-object if the
167   command does not return data
168 - The "id" member contains the transaction identification associated
169   with the command execution if issued by the Client
170
171 2.4.2 error
172 -----------
173
174 The format of an error response is:
175
176 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
177
178  Where,
179
180 - The "class" member contains the error class name (eg. "GenericError")
181 - The "desc" member is a human-readable error message. Clients should
182   not attempt to parse this message.
183 - The "id" member contains the transaction identification associated with
184   the command execution if issued by the Client
185
186 NOTE: Some errors can occur before the Server is able to read the "id" member,
187 in these cases the "id" member will not be part of the error response, even
188 if provided by the client.
189
190 2.5 Asynchronous events
191 -----------------------
192
193 As a result of state changes, the Server may send messages unilaterally
194 to the Client at any time, when not in the middle of any other
195 response. They are called "asynchronous events".
196
197 The format of asynchronous events is:
198
199 { "event": json-string, "data": json-object,
200   "timestamp": { "seconds": json-number, "microseconds": json-number } }
201
202  Where,
203
204 - The "event" member contains the event's name
205 - The "data" member contains event specific data, which is defined in a
206   per-event basis, it is optional
207 - The "timestamp" member contains the exact time of when the event
208   occurred in the Server. It is a fixed json-object with time in
209   seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
210   there is a failure to retrieve host time, both members of the
211   timestamp will be set to -1.
212
213 The actual asynchronous events are documented in the QEMU QMP
214 reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
215
216 Some events are rate-limited to at most one per second.  If additional
217 "similar" events arrive within one second, all but the last one are
218 dropped, and the last one is delayed.  "Similar" normally means same
219 event type.
220
221 2.6 Forcing the JSON parser into known-good state
222 -------------------------------------------------
223
224 Incomplete or invalid input can leave the server's JSON parser in a
225 state where it can't parse additional commands.  To get it back into
226 known-good state, the client should provoke a lexical error.
227
228 The cleanest way to do that is sending an ASCII control character
229 other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new
230 line).
231
232 Sadly, older versions of QEMU can fail to flag this as an error.  If a
233 client needs to deal with them, it should send a 0xFF byte.
234
235 2.7 QGA Synchronization
236 -----------------------
237
238 When a client connects to QGA over a transport lacking proper
239 connection semantics such as virtio-serial, QGA may have read partial
240 input from a previous client.  The client needs to force QGA's parser
241 into known-good state using the previous section's technique.
242 Moreover, the client may receive output a previous client didn't read.
243 To help with skipping that output, QGA provides the
244 'guest-sync-delimited' command.  Refer to its documentation for
245 details.
246
247
248 3. QMP Examples
249 ===============
250
251 This section provides some examples of real QMP usage, in all of them
252 "C" stands for "Client" and "S" stands for "Server".
253
254 3.1 Server greeting
255 -------------------
256
257 S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3},
258      "package": "v3.0.0"}, "capabilities": ["oob"] } }
259
260 3.2 Capabilities negotiation
261 ----------------------------
262
263 C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
264 S: { "return": {}}
265
266 3.3 Simple 'stop' execution
267 ---------------------------
268
269 C: { "execute": "stop" }
270 S: { "return": {} }
271
272 3.4 KVM information
273 -------------------
274
275 C: { "execute": "query-kvm", "id": "example" }
276 S: { "return": { "enabled": true, "present": true }, "id": "example"}
277
278 3.5 Parsing error
279 ------------------
280
281 C: { "execute": }
282 S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
283
284 3.6 Powerdown event
285 -------------------
286
287 S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
288     "event": "POWERDOWN" }
289
290 3.7 Out-of-band execution
291 -------------------------
292
293 C: { "exec-oob": "migrate-pause", "id": 42 }
294 S: { "id": 42,
295      "error": { "class": "GenericError",
296       "desc": "migrate-pause is currently only supported during postcopy-active state" } }
297
298
299 4. Capabilities Negotiation
300 ===========================
301
302 When a Client successfully establishes a connection, the Server is in
303 Capabilities Negotiation mode.
304
305 In this mode only the qmp_capabilities command is allowed to run, all
306 other commands will return the CommandNotFound error. Asynchronous
307 messages are not delivered either.
308
309 Clients should use the qmp_capabilities command to enable capabilities
310 advertised in the Server's greeting (section '2.2 Server Greeting') they
311 support.
312
313 When the qmp_capabilities command is issued, and if it does not return an
314 error, the Server enters in Command mode where capabilities changes take
315 effect, all commands (except qmp_capabilities) are allowed and asynchronous
316 messages are delivered.
317
318 5 Compatibility Considerations
319 ==============================
320
321 All protocol changes or new features which modify the protocol format in an
322 incompatible way are disabled by default and will be advertised by the
323 capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
324 that array and enable the capabilities they support.
325
326 The QMP Server performs a type check on the arguments to a command.  It
327 generates an error if a value does not have the expected type for its
328 key, or if it does not understand a key that the Client included.  The
329 strictness of the Server catches wrong assumptions of Clients about
330 the Server's schema.  Clients can assume that, when such validation
331 errors occur, they will be reported before the command generated any
332 side effect.
333
334 However, Clients must not assume any particular:
335
336 - Length of json-arrays
337 - Size of json-objects; in particular, future versions of QEMU may add
338   new keys and Clients should be able to ignore them.
339 - Order of json-object members or json-array elements
340 - Amount of errors generated by a command, that is, new errors can be added
341   to any existing command in newer versions of the Server
342
343 Any command or member name beginning with "x-" is deemed experimental,
344 and may be withdrawn or changed in an incompatible manner in a future
345 release.
346
347 Of course, the Server does guarantee to send valid JSON.  But apart from
348 this, a Client should be "conservative in what they send, and liberal in
349 what they accept".
350
351 6. Downstream extension of QMP
352 ==============================
353
354 We recommend that downstream consumers of QEMU do *not* modify QMP.
355 Management tools should be able to support both upstream and downstream
356 versions of QMP without special logic, and downstream extensions are
357 inherently at odds with that.
358
359 However, we recognize that it is sometimes impossible for downstreams to
360 avoid modifying QMP.  Both upstream and downstream need to take care to
361 preserve long-term compatibility and interoperability.
362
363 To help with that, QMP reserves JSON object member names beginning with
364 '__' (double underscore) for downstream use ("downstream names").  This
365 means upstream will never use any downstream names for its commands,
366 arguments, errors, asynchronous events, and so forth.
367
368 Any new names downstream wishes to add must begin with '__'.  To
369 ensure compatibility with other downstreams, it is strongly
370 recommended that you prefix your downstream names with '__RFQDN_' where
371 RFQDN is a valid, reverse fully qualified domain name which you
372 control.  For example, a qemu-kvm specific monitor command would be:
373
374     (qemu) __org.linux-kvm_enable_irqchip
375
376 Downstream must not change the server greeting (section 2.2) other than
377 to offer additional capabilities.  But see below for why even that is
378 discouraged.
379
380 Section '5 Compatibility Considerations' applies to downstream as well
381 as to upstream, obviously.  It follows that downstream must behave
382 exactly like upstream for any input not containing members with
383 downstream names ("downstream members"), except it may add members
384 with downstream names to its output.
385
386 Thus, a client should not be able to distinguish downstream from
387 upstream as long as it doesn't send input with downstream members, and
388 properly ignores any downstream members in the output it receives.
389
390 Advice on downstream modifications:
391
392 1. Introducing new commands is okay.  If you want to extend an existing
393    command, consider introducing a new one with the new behaviour
394    instead.
395
396 2. Introducing new asynchronous messages is okay.  If you want to extend
397    an existing message, consider adding a new one instead.
398
399 3. Introducing new errors for use in new commands is okay.  Adding new
400    errors to existing commands counts as extension, so 1. applies.
401
402 4. New capabilities are strongly discouraged.  Capabilities are for
403    evolving the basic protocol, and multiple diverging basic protocol
404    dialects are most undesirable.