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