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=================================== 9QEMU Machine Protocol Specification 10=================================== 11 12The QEMU Machine Protocol (QMP) is a JSON-based 13protocol which is available for applications to operate QEMU at the 14machine-level. It is also in use by the QEMU Guest Agent (QGA), which 15is available for host applications to interact with the guest 16operating system. This page specifies the general format of 17the protocol; details of the commands and data structures can 18be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`. 19 20.. contents:: 21 22Protocol Specification 23====================== 24 25This section details the protocol format. For the purpose of this 26document, "Server" is either QEMU or the QEMU Guest Agent, and 27"Client" is any application communicating with it via QMP. 28 29JSON data structures, when mentioned in this document, are always in the 30following format: 31 32 json-DATA-STRUCTURE-NAME 33 34Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined 35by the `JSON standard <http://www.ietf.org/rfc/rfc8259.txt>`_. 36 37The server expects its input to be encoded in UTF-8, and sends its 38output encoded in ASCII. 39 40For convenience, json-object members mentioned in this document will 41be in a certain order. However, in real protocol usage they can be in 42ANY order, thus no particular order should be assumed. On the other 43hand, use of json-array elements presumes that preserving order is 44important unless specifically documented otherwise. Repeating a key 45within a json-object gives unpredictable results. 46 47Also for convenience, the server will accept an extension of 48``'single-quoted'`` strings in place of the usual ``"double-quoted"`` 49json-string, and both input forms of strings understand an additional 50escape sequence of ``\'`` for a single quote. The server will only use 51double quoting on output. 52 53General Definitions 54------------------- 55 56All interactions transmitted by the Server are json-objects, always 57terminating with CRLF. 58 59All json-objects members are mandatory when not specified otherwise. 60 61Server Greeting 62--------------- 63 64Right when connected the Server will issue a greeting message, which signals 65that the connection has been successfully established and that the Server is 66ready for capabilities negotiation (for more information refer to section 67`Capabilities Negotiation`_). 68 69The greeting message format is: 70 71:: 72 73 { "QMP": { "version": json-object, "capabilities": json-array } } 74 75Where: 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 83Capabilities 84------------ 85 86Currently 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 92Issuing Commands 93---------------- 94 95The format for command execution is: 96 97:: 98 99 { "execute": json-string, "arguments": json-object, "id": json-value } 100 101or 102 103:: 104 105 { "exec-oob": json-string, "arguments": json-object, "id": json-value } 106 107Where: 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 120The actual commands are documented in the :doc:`qemu-qmp-ref`. 121 122Out-of-band execution 123--------------------- 124 125The server normally reads, executes and responds to one command after 126the other. The client therefore receives command responses in issue 127order. 128 129With out-of-band execution enabled via `capabilities negotiation`_, 130the server reads and queues commands as they arrive. It executes 131commands from the queue one after the other. Commands executed 132out-of-band jump the queue: the command get executed right away, 133possibly overtaking prior in-band commands. The client may therefore 134receive such a command's response before responses from prior in-band 135commands. 136 137To be able to match responses back to their commands, the client needs 138to pass ``id`` with out-of-band commands. Passing it with all commands 139is recommended for clients that accept capability ``oob``. 140 141If the client sends in-band commands faster than the server can 142execute them, the server will stop reading requests until the request 143queue length is reduced to an acceptable range. 144 145To ensure commands to be executed out-of-band get read and executed, 146the client should have at most eight in-band commands in flight. 147 148Only a few commands support out-of-band execution. The ones that do 149have ``"allow-oob": true`` in the output of ``query-qmp-schema``. 150 151Commands Responses 152------------------ 153 154There are two possible responses which the Server will issue as the result 155of a command execution: success or error. 156 157As long as the commands were issued with a proper ``id`` field, then the 158same ``id`` field will be attached in the corresponding response message 159so that requests and responses can match. Clients should drop all the 160responses that have an unknown ``id`` field. 161 162Success 163------- 164 165The format of a success response is: 166 167:: 168 169 { "return": json-value, "id": json-value } 170 171Where: 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 181Error 182----- 183 184The format of an error response is: 185 186:: 187 188 { "error": { "class": json-string, "desc": json-string }, "id": json-value } 189 190Where: 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 198NOTE: Some errors can occur before the Server is able to read the ``id`` member; 199in these cases the ``id`` member will not be part of the error response, even 200if provided by the client. 201 202Asynchronous events 203------------------- 204 205As a result of state changes, the Server may send messages unilaterally 206to the Client at any time, when not in the middle of any other 207response. They are called "asynchronous events". 208 209The format of asynchronous events is: 210 211:: 212 213 { "event": json-string, "data": json-object, 214 "timestamp": { "seconds": json-number, "microseconds": json-number } } 215 216Where: 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 227The actual asynchronous events are documented in the :doc:`qemu-qmp-ref`. 228 229Some 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 231dropped, and the last one is delayed. "Similar" normally means same 232event type. 233 234Forcing the JSON parser into known-good state 235--------------------------------------------- 236 237Incomplete or invalid input can leave the server's JSON parser in a 238state where it can't parse additional commands. To get it back into 239known-good state, the client should provoke a lexical error. 240 241The cleanest way to do that is sending an ASCII control character 242other than ``\t`` (horizontal tab), ``\r`` (carriage return), or 243``\n`` (new line). 244 245Sadly, older versions of QEMU can fail to flag this as an error. If a 246client needs to deal with them, it should send a 0xFF byte. 247 248QGA Synchronization 249------------------- 250 251When a client connects to QGA over a transport lacking proper 252connection semantics such as virtio-serial, QGA may have read partial 253input from a previous client. The client needs to force QGA's parser 254into known-good state using the previous section's technique. 255Moreover, the client may receive output a previous client didn't read. 256To help with skipping that output, QGA provides the 257``guest-sync-delimited`` command. Refer to its documentation for 258details. 259 260 261QMP Examples 262============ 263 264This 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 333Capabilities Negotiation 334======================== 335 336When a Client successfully establishes a connection, the Server is in 337Capabilities Negotiation mode. 338 339In this mode only the ``qmp_capabilities`` command is allowed to run; all 340other commands will return the ``CommandNotFound`` error. Asynchronous 341messages are not delivered either. 342 343Clients should use the ``qmp_capabilities`` command to enable capabilities 344advertised in the `Server Greeting`_ which they support. 345 346When the ``qmp_capabilities`` command is issued, and if it does not return an 347error, the Server enters Command mode where capabilities changes take 348effect, all commands (except ``qmp_capabilities``) are allowed and asynchronous 349messages are delivered. 350 351Compatibility Considerations 352============================ 353 354All protocol changes or new features which modify the protocol format in an 355incompatible way are disabled by default and will be advertised by the 356capabilities array (in the `Server Greeting`_). Thus, Clients can check 357that array and enable the capabilities they support. 358 359The QMP Server performs a type check on the arguments to a command. It 360generates an error if a value does not have the expected type for its 361key, or if it does not understand a key that the Client included. The 362strictness of the Server catches wrong assumptions of Clients about 363the Server's schema. Clients can assume that, when such validation 364errors occur, they will be reported before the command generated any 365side effect. 366 367However, 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 376Any command or member name beginning with ``x-`` is deemed experimental, 377and may be withdrawn or changed in an incompatible manner in a future 378release. 379 380Of course, the Server does guarantee to send valid JSON. But apart from 381this, a Client should be "conservative in what they send, and liberal in 382what they accept". 383 384Downstream extension of QMP 385=========================== 386 387We recommend that downstream consumers of QEMU do *not* modify QMP. 388Management tools should be able to support both upstream and downstream 389versions of QMP without special logic, and downstream extensions are 390inherently at odds with that. 391 392However, we recognize that it is sometimes impossible for downstreams to 393avoid modifying QMP. Both upstream and downstream need to take care to 394preserve long-term compatibility and interoperability. 395 396To help with that, QMP reserves JSON object member names beginning with 397``__`` (double underscore) for downstream use ("downstream names"). This 398means upstream will never use any downstream names for its commands, 399arguments, errors, asynchronous events, and so forth. 400 401Any new names downstream wishes to add must begin with ``__``. To 402ensure compatibility with other downstreams, it is strongly 403recommended that you prefix your downstream names with ``__RFQDN_`` where 404RFQDN is a valid, reverse fully qualified domain name which you 405control. For example, a qemu-kvm specific monitor command would be: 406 407:: 408 409 (qemu) __org.linux-kvm_enable_irqchip 410 411Downstream must not change the `server greeting`_ other than 412to offer additional capabilities. But see below for why even that is 413discouraged. 414 415The section `Compatibility Considerations`_ applies to downstream as well 416as to upstream, obviously. It follows that downstream must behave 417exactly like upstream for any input not containing members with 418downstream names ("downstream members"), except it may add members 419with downstream names to its output. 420 421Thus, a client should not be able to distinguish downstream from 422upstream as long as it doesn't send input with downstream members, and 423properly ignores any downstream members in the output it receives. 424 425Advice on downstream modifications: 426 4271. 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 4312. Introducing new asynchronous messages is okay. If you want to extend 432 an existing message, consider adding a new one instead. 433 4343. Introducing new errors for use in new commands is okay. Adding new 435 errors to existing commands counts as extension, so 1. applies. 436 4374. New capabilities are strongly discouraged. Capabilities are for 438 evolving the basic protocol, and multiple diverging basic protocol 439 dialects are most undesirable. 440