1 QEMU Machine Protocol Specification 2 30. About This Document 4====================== 5 6Copyright (C) 2009-2016 Red Hat, Inc. 7 8This work is licensed under the terms of the GNU GPL, version 2 or 9later. See the COPYING file in the top-level directory. 10 111. Introduction 12=============== 13 14This document specifies the QEMU Machine Protocol (QMP), a JSON-based 15protocol which is available for applications to operate QEMU at the 16machine-level. It is also in use by the QEMU Guest Agent (QGA), which 17is available for host applications to interact with the guest 18operating system. 19 202. Protocol Specification 21========================= 22 23This section details the protocol format. For the purpose of this document 24"Client" is any application which is using QMP to communicate with QEMU and 25"Server" is QEMU itself. 26 27JSON data structures, when mentioned in this document, are always in the 28following format: 29 30 json-DATA-STRUCTURE-NAME 31 32Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined 33by the JSON standard: 34 35http://www.ietf.org/rfc/rfc7159.txt 36 37The protocol is always encoded in UTF-8 except for synchronization 38bytes (documented below); although thanks to json-string escape 39sequences, the server will reply using only the strict ASCII subset. 40 41For convenience, json-object members mentioned in this document will 42be in a certain order. However, in real protocol usage they can be in 43ANY order, thus no particular order should be assumed. On the other 44hand, use of json-array elements presumes that preserving order is 45important unless specifically documented otherwise. Repeating a key 46within a json-object gives unpredictable results. 47 48Also for convenience, the server will accept an extension of 49'single-quoted' strings in place of the usual "double-quoted" 50json-string, and both input forms of strings understand an additional 51escape sequence of "\'" for a single quote. The server will only use 52double quoting on output. 53 542.1 General Definitions 55----------------------- 56 572.1.1 All interactions transmitted by the Server are json-objects, always 58 terminating with CRLF 59 602.1.2 All json-objects members are mandatory when not specified otherwise 61 622.2 Server Greeting 63------------------- 64 65Right when connected the Server will issue a greeting message, which signals 66that the connection has been successfully established and that the Server is 67ready for capabilities negotiation (for more information refer to section 68'4. Capabilities Negotiation'). 69 70The greeting message format is: 71 72{ "QMP": { "version": json-object, "capabilities": json-array } } 73 74 Where, 75 76- The "version" member contains the Server's version information (the format 77 is the same of the query-version command) 78- The "capabilities" member specify the availability of features beyond the 79 baseline specification; the order of elements in this array has no 80 particular significance, so a client must search the entire array 81 when looking for a particular capability 82 832.2.1 Capabilities 84------------------ 85 86As of the date this document was last revised, no server or client 87capability strings have been defined. 88 89 902.3 Issuing Commands 91-------------------- 92 93The format for command execution is: 94 95{ "execute": json-string, "arguments": json-object, "id": json-value } 96 97 Where, 98 99- The "execute" member identifies the command to be executed by the Server 100- The "arguments" member is used to pass any arguments required for the 101 execution of the command, it is optional when no arguments are 102 required. Each command documents what contents will be considered 103 valid when handling the json-argument 104- The "id" member is a transaction identification associated with the 105 command execution, it is optional and will be part of the response if 106 provided. The "id" member can be any json-value, although most 107 clients merely use a json-number incremented for each successive 108 command 109 1102.4 Commands Responses 111---------------------- 112 113There are two possible responses which the Server will issue as the result 114of a command execution: success or error. 115 1162.4.1 success 117------------- 118 119The format of a success response is: 120 121{ "return": json-value, "id": json-value } 122 123 Where, 124 125- The "return" member contains the data returned by the command, which 126 is defined on a per-command basis (usually a json-object or 127 json-array of json-objects, but sometimes a json-number, json-string, 128 or json-array of json-strings); it is an empty json-object if the 129 command does not return data 130- The "id" member contains the transaction identification associated 131 with the command execution if issued by the Client 132 1332.4.2 error 134----------- 135 136The format of an error response is: 137 138{ "error": { "class": json-string, "desc": json-string }, "id": json-value } 139 140 Where, 141 142- The "class" member contains the error class name (eg. "GenericError") 143- The "desc" member is a human-readable error message. Clients should 144 not attempt to parse this message. 145- The "id" member contains the transaction identification associated with 146 the command execution if issued by the Client 147 148NOTE: Some errors can occur before the Server is able to read the "id" member, 149in these cases the "id" member will not be part of the error response, even 150if provided by the client. 151 1522.5 Asynchronous events 153----------------------- 154 155As a result of state changes, the Server may send messages unilaterally 156to the Client at any time, when not in the middle of any other 157response. They are called "asynchronous events". 158 159The format of asynchronous events is: 160 161{ "event": json-string, "data": json-object, 162 "timestamp": { "seconds": json-number, "microseconds": json-number } } 163 164 Where, 165 166- The "event" member contains the event's name 167- The "data" member contains event specific data, which is defined in a 168 per-event basis, it is optional 169- The "timestamp" member contains the exact time of when the event 170 occurred in the Server. It is a fixed json-object with time in 171 seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if 172 there is a failure to retrieve host time, both members of the 173 timestamp will be set to -1. 174 175For a listing of supported asynchronous events, please, refer to the 176qmp-events.txt file. 177 178Some events are rate-limited to at most one per second. If additional 179"similar" events arrive within one second, all but the last one are 180dropped, and the last one is delayed. "Similar" normally means same 181event type. See qmp-events.txt for details. 182 1832.6 QGA Synchronization 184----------------------- 185 186When using QGA, an additional synchronization feature is built into 187the protocol. If the Client sends a raw 0xFF sentinel byte (not valid 188JSON), then the Server will reset its state and discard all pending 189data prior to the sentinel. Conversely, if the Client makes use of 190the 'guest-sync-delimited' command, the Server will send a raw 0xFF 191sentinel byte prior to its response, to aid the Client in discarding 192any data prior to the sentinel. 193 194 1953. QMP Examples 196=============== 197 198This section provides some examples of real QMP usage, in all of them 199"C" stands for "Client" and "S" stands for "Server". 200 2013.1 Server greeting 202------------------- 203 204S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 }, 205 "package": ""}, "capabilities": []}} 206 2073.2 Client QMP negotiation 208-------------------------- 209C: { "execute": "qmp_capabilities" } 210S: { "return": {}} 211 2123.3 Simple 'stop' execution 213--------------------------- 214 215C: { "execute": "stop" } 216S: { "return": {} } 217 2183.4 KVM information 219------------------- 220 221C: { "execute": "query-kvm", "id": "example" } 222S: { "return": { "enabled": true, "present": true }, "id": "example"} 223 2243.5 Parsing error 225------------------ 226 227C: { "execute": } 228S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } } 229 2303.6 Powerdown event 231------------------- 232 233S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 }, 234 "event": "POWERDOWN" } 235 2364. Capabilities Negotiation 237=========================== 238 239When a Client successfully establishes a connection, the Server is in 240Capabilities Negotiation mode. 241 242In this mode only the qmp_capabilities command is allowed to run, all 243other commands will return the CommandNotFound error. Asynchronous 244messages are not delivered either. 245 246Clients should use the qmp_capabilities command to enable capabilities 247advertised in the Server's greeting (section '2.2 Server Greeting') they 248support. 249 250When the qmp_capabilities command is issued, and if it does not return an 251error, the Server enters in Command mode where capabilities changes take 252effect, all commands (except qmp_capabilities) are allowed and asynchronous 253messages are delivered. 254 2555 Compatibility Considerations 256============================== 257 258All protocol changes or new features which modify the protocol format in an 259incompatible way are disabled by default and will be advertised by the 260capabilities array (section '2.2 Server Greeting'). Thus, Clients can check 261that array and enable the capabilities they support. 262 263The QMP Server performs a type check on the arguments to a command. It 264generates an error if a value does not have the expected type for its 265key, or if it does not understand a key that the Client included. The 266strictness of the Server catches wrong assumptions of Clients about 267the Server's schema. Clients can assume that, when such validation 268errors occur, they will be reported before the command generated any 269side effect. 270 271However, Clients must not assume any particular: 272 273- Length of json-arrays 274- Size of json-objects; in particular, future versions of QEMU may add 275 new keys and Clients should be able to ignore them. 276- Order of json-object members or json-array elements 277- Amount of errors generated by a command, that is, new errors can be added 278 to any existing command in newer versions of the Server 279 280Any command or member name beginning with "x-" is deemed experimental, 281and may be withdrawn or changed in an incompatible manner in a future 282release. 283 284Of course, the Server does guarantee to send valid JSON. But apart from 285this, a Client should be "conservative in what they send, and liberal in 286what they accept". 287 2886. Downstream extension of QMP 289============================== 290 291We recommend that downstream consumers of QEMU do *not* modify QMP. 292Management tools should be able to support both upstream and downstream 293versions of QMP without special logic, and downstream extensions are 294inherently at odds with that. 295 296However, we recognize that it is sometimes impossible for downstreams to 297avoid modifying QMP. Both upstream and downstream need to take care to 298preserve long-term compatibility and interoperability. 299 300To help with that, QMP reserves JSON object member names beginning with 301'__' (double underscore) for downstream use ("downstream names"). This 302means upstream will never use any downstream names for its commands, 303arguments, errors, asynchronous events, and so forth. 304 305Any new names downstream wishes to add must begin with '__'. To 306ensure compatibility with other downstreams, it is strongly 307recommended that you prefix your downstream names with '__RFQDN_' where 308RFQDN is a valid, reverse fully qualified domain name which you 309control. For example, a qemu-kvm specific monitor command would be: 310 311 (qemu) __org.linux-kvm_enable_irqchip 312 313Downstream must not change the server greeting (section 2.2) other than 314to offer additional capabilities. But see below for why even that is 315discouraged. 316 317Section '5 Compatibility Considerations' applies to downstream as well 318as to upstream, obviously. It follows that downstream must behave 319exactly like upstream for any input not containing members with 320downstream names ("downstream members"), except it may add members 321with downstream names to its output. 322 323Thus, a client should not be able to distinguish downstream from 324upstream as long as it doesn't send input with downstream members, and 325properly ignores any downstream members in the output it receives. 326 327Advice on downstream modifications: 328 3291. Introducing new commands is okay. If you want to extend an existing 330 command, consider introducing a new one with the new behaviour 331 instead. 332 3332. Introducing new asynchronous messages is okay. If you want to extend 334 an existing message, consider adding a new one instead. 335 3363. Introducing new errors for use in new commands is okay. Adding new 337 errors to existing commands counts as extension, so 1. applies. 338 3394. New capabilities are strongly discouraged. Capabilities are for 340 evolving the basic protocol, and multiple diverging basic protocol 341 dialects are most undesirable. 342