qemu/docs/qmp-spec.txt
<<
>>
Prefs
   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