QMP/qmp-spec.txt

   1            QEMU Monitor Protocol Specification - Version 0.1
   2
   3 1. Introduction
   4 ===============
   5
   6 This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol
   7 which is available for applications to control QEMU at the machine-level.
   8
   9 To enable QMP support, QEMU has to be run in "control mode". This is done by
  10 starting QEMU with the appropriate command-line options. Please, refer to the
  11 QEMU manual page for more information.
  12
  13 2. Protocol Specification
  14 =========================
  15
  16 This section details the protocol format. For the purpose of this document
  17 "Client" is any application which is communicating with QEMU in control mode,
  18 and "Server" is QEMU itself.
  19
  20 JSON data structures, when mentioned in this document, are always in the
  21 following format:
  22
  23     json-DATA-STRUCTURE-NAME
  24
  25 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
  26 the JSON standard:
  27
  28 http://www.ietf.org/rfc/rfc4627.txt
  29
  30 For convenience, json-object members and json-array elements mentioned in
  31 this document will be in a certain order. However, in real protocol usage
  32 they can be in ANY order, thus no particular order should be assumed.
  33
  34 2.1 General Definitions
  35 -----------------------
  36
  37 2.1.1 All interactions transmitted by the Server are json-objects, always
  38       terminating with CRLF
  39
  40 2.1.2 All json-objects members are mandatory when not specified otherwise
  41
  42 2.2 Server Greeting
  43 -------------------
  44
  45 Right when connected the Server will issue a greeting message, which signals
  46 that the connection has been successfully established and that the Server is
  47 ready for capabilities negotiation (for more information refer to section
  48 '4. Capabilities Negotiation').
  49
  50 The format is:
  51
  52 { "QMP": { "version": json-object, "capabilities": json-array } }
  53
  54  Where,
  55
  56 - The "version" member contains the Server's version information (the format
  57   is the same of the 'query-version' command)
  58 - The "capabilities" member specify the availability of features beyond the
  59   baseline specification
  60
  61 2.3 Issuing Commands
  62 --------------------
  63
  64 The format for command execution is:
  65
  66 { "execute": json-string, "arguments": json-object, "id": json-value }
  67
  68  Where,
  69
  70 - The "execute" member identifies the command to be executed by the Server
  71 - The "arguments" member is used to pass any arguments required for the
  72   execution of the command, it is optional when no arguments are required
  73 - The "id" member is a transaction identification associated with the
  74   command execution, it is optional and will be part of the response if
  75   provided
  76
  77 2.4 Commands Responses
  78 ----------------------
  79
  80 There are two possible responses which the Server will issue as the result
  81 of a command execution: success or error.
  82
  83 2.4.1 success
  84 -------------
  85
  86 The success response is issued when the command execution has finished
  87 without errors.
  88
  89 The format is:
  90
  91 { "return": json-object, "id": json-value }
  92
  93  Where,
  94
  95 - The "return" member contains the command returned data, which is defined
  96   in a per-command basis or an empty json-object if the command does not
  97   return data
  98 - The "id" member contains the transaction identification associated
  99   with the command execution (if issued by the Client)
 100
 101 2.4.2 error
 102 -----------
 103
 104 The error response is issued when the command execution could not be
 105 completed because of an error condition.
 106
 107 The format is:
 108
 109 { "error": { "class": json-string, "data": json-object, "desc": json-string },
 110   "id": json-value }
 111
 112  Where,
 113
 114 - The "class" member contains the error class name (eg. "ServiceUnavailable")
 115 - The "data" member contains specific error data and is defined in a
 116   per-command basis, it will be an empty json-object if the error has no data
 117 - The "desc" member is a human-readable error message. Clients should
 118   not attempt to parse this message.
 119 - The "id" member contains the transaction identification associated with
 120   the command execution (if issued by the Client)
 121
 122 NOTE: Some errors can occur before the Server is able to read the "id" member,
 123 in these cases the "id" member will not be part of the error response, even
 124 if provided by the client.
 125
 126 2.5 Asynchronous events
 127 -----------------------
 128
 129 As a result of state changes, the Server may send messages unilaterally
 130 to the Client at any time. They are called 'asynchronous events'.
 131
 132 The format is:
 133
 134 { "event": json-string, "data": json-object,
 135   "timestamp": { "seconds": json-number, "microseconds": json-number } }
 136
 137  Where,
 138
 139 - The "event" member contains the event's name
 140 - The "data" member contains event specific data, which is defined in a
 141   per-event basis, it is optional
 142 - The "timestamp" member contains the exact time of when the event occurred
 143   in the Server. It is a fixed json-object with time in seconds and
 144   microseconds
 145
 146 For a listing of supported asynchronous events, please, refer to the
 147 qmp-events.txt file.
 148
 149 3. QMP Examples
 150 ===============
 151
 152 This section provides some examples of real QMP usage, in all of them
 153 'C' stands for 'Client' and 'S' stands for 'Server'.
 154
 155 3.1 Server greeting
 156 -------------------
 157
 158 S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
 159
 160 3.2 Simple 'stop' execution
 161 ---------------------------
 162
 163 C: { "execute": "stop" }
 164 S: {"return": {}}
 165
 166 3.3 KVM information
 167 -------------------
 168
 169 C: { "execute": "query-kvm", "id": "example" }
 170 S: {"return": {"enabled": true, "present": true}, "id": "example"}
 171
 172 3.4 Parsing error
 173 ------------------
 174
 175 C: { "execute": }
 176 S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
 177 {}}}
 178
 179 3.5 Powerdown event
 180 -------------------
 181
 182 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 183 "POWERDOWN"}
 184
 185 4. Capabilities Negotiation
 186 ----------------------------
 187
 188 When a Client successfully establishes a connection, the Server is in
 189 Capabilities Negotiation mode.
 190
 191 In this mode only the 'qmp_capabilities' command is allowed to run, all
 192 other commands will return the CommandNotFound error. Asynchronous messages
 193 are not delivered either.
 194
 195 Clients should use the 'qmp_capabilities' command to enable capabilities
 196 advertised in the Server's greeting (section '2.2 Server Greeting') they
 197 support.
 198
 199 When the 'qmp_capabilities' command is issued, and if it does not return an
 200 error, the Server enters in Command mode where capabilities changes take
 201 effect, all commands (except 'qmp_capabilities') are allowed and asynchronous
 202 messages are delivered.
 203
 204 5 Compatibility Considerations
 205 ------------------------------
 206
 207 All protocol changes or new features which modify the protocol format in an
 208 incompatible way are disabled by default and will be advertised by the
 209 capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
 210 that array and enable the capabilities they support.
 211
 212 The QMP Server performs a type check on the arguments to a command.  It
 213 generates an error if a value does not have the expected type for its
 214 key, or if it does not understand a key that the Client included.  The
 215 strictness of the Server catches wrong assumptions of Clients about
 216 the Server's schema.  Clients can assume that, when such validation
 217 errors occur, they will be reported before the command generated any
 218 side effect.
 219
 220 However, Clients must not assume any particular:
 221
 222 - Length of json-arrays
 223 - Size of json-objects; in particular, future versions of QEMU may add
 224   new keys and Clients should be able to ignore them.
 225 - Order of json-object members or json-array elements
 226 - Amount of errors generated by a command, that is, new errors can be added
 227   to any existing command in newer versions of the Server
 228
 229 Of course, the Server does guarantee to send valid JSON.  But apart from
 230 this, a Client should be "conservative in what they send, and liberal in
 231 what they accept".
 232
 233 6. Downstream extension of QMP
 234 ------------------------------
 235
 236 We recommend that downstream consumers of QEMU do *not* modify QMP.
 237 Management tools should be able to support both upstream and downstream
 238 versions of QMP without special logic, and downstream extensions are
 239 inherently at odds with that.
 240
 241 However, we recognize that it is sometimes impossible for downstreams to
 242 avoid modifying QMP.  Both upstream and downstream need to take care to
 243 preserve long-term compatibility and interoperability.
 244
 245 To help with that, QMP reserves JSON object member names beginning with
 246 '__' (double underscore) for downstream use ("downstream names").  This
 247 means upstream will never use any downstream names for its commands,
 248 arguments, errors, asynchronous events, and so forth.
 249
 250 Any new names downstream wishes to add must begin with '__'.  To
 251 ensure compatibility with other downstreams, it is strongly
 252 recommended that you prefix your downstram names with '__RFQDN_' where
 253 RFQDN is a valid, reverse fully qualified domain name which you
 254 control.  For example, a qemu-kvm specific monitor command would be:
 255
 256     (qemu) __org.linux-kvm_enable_irqchip
 257
 258 Downstream must not change the server greeting (section 2.2) other than
 259 to offer additional capabilities.  But see below for why even that is
 260 discouraged.
 261
 262 Section '5 Compatibility Considerations' applies to downstream as well
 263 as to upstream, obviously.  It follows that downstream must behave
 264 exactly like upstream for any input not containing members with
 265 downstream names ("downstream members"), except it may add members
 266 with downstream names to its output.
 267
 268 Thus, a client should not be able to distinguish downstream from
 269 upstream as long as it doesn't send input with downstream members, and
 270 properly ignores any downstream members in the output it receives.
 271
 272 Advice on downstream modifications:
 273
 274 1. Introducing new commands is okay.  If you want to extend an existing
 275    command, consider introducing a new one with the new behaviour
 276    instead.
 277
 278 2. Introducing new asynchronous messages is okay.  If you want to extend
 279    an existing message, consider adding a new one instead.
 280
 281 3. Introducing new errors for use in new commands is okay.  Adding new
 282    errors to existing commands counts as extension, so 1. applies.
 283
 284 4. New capabilities are strongly discouraged.  Capabilities are for
 285    evolving the basic protocol, and multiple diverging basic protocol
 286    dialects are most undesirable.