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 waiting for commands.
  48
  49 The format is:
  50
  51 { "QMP": { "capabilities": json-array } }
  52
  53  Where,
  54
  55 - The "capabilities" member specify the availability of features beyond the
  56   baseline specification
  57
  58 2.3 Issuing Commands
  59 --------------------
  60
  61 The format for command execution is:
  62
  63 { "execute": json-string, "arguments": json-object, "id": json-value }
  64
  65  Where,
  66
  67 - The "execute" member identifies the command to be executed by the Server
  68 - The "arguments" member is used to pass any arguments required for the
  69   execution of the command, it is optional when no arguments are required
  70 - The "id" member is a transaction identification associated with the
  71   command execution, it is optional and will be part of the response if
  72   provided
  73
  74 2.4 Commands Responses
  75 ----------------------
  76
  77 There are two possible responses which the Server will issue as the result
  78 of a command execution: success or error.
  79
  80 2.4.1 success
  81 -------------
  82
  83 The success response is issued when the command execution has finished
  84 without errors.
  85
  86 The format is:
  87
  88 { "return": json-object, "id": json-value }
  89
  90  Where,
  91
  92 - The "return" member contains the command returned data, which is defined
  93   in a per-command basis or an empty json-object if the command does not
  94   return data
  95 - The "id" member contains the transaction identification associated
  96   with the command execution (if issued by the Client)
  97
  98 2.4.2 error
  99 -----------
 100
 101 The error response is issued when the command execution could not be
 102 completed because of an error condition.
 103
 104 The format is:
 105
 106 { "error": { "class": json-string, "data": json-object, "desc": json-string },
 107   "id": json-value }
 108
 109  Where,
 110
 111 - The "class" member contains the error class name (eg. "ServiceUnavailable")
 112 - The "data" member contains specific error data and is defined in a
 113   per-command basis, it will be an empty json-object if the error has no data
 114 - The "desc" member is a human-readable error message. Clients should
 115   not attempt to parse this message.
 116 - The "id" member contains the transaction identification associated with
 117   the command execution (if issued by the Client)
 118
 119 NOTE: Some errors can occur before the Server is able to read the "id" member,
 120 in these cases the "id" member will not be part of the error response, even
 121 if provided by the client.
 122
 123 2.5 Asynchronous events
 124 -----------------------
 125
 126 As a result of state changes, the Server may send messages unilaterally
 127 to the Client at any time. They are called 'asynchronous events'.
 128
 129 The format is:
 130
 131 { "event": json-string, "data": json-object,
 132   "timestamp": { "seconds": json-number, "microseconds": json-number } }
 133
 134  Where,
 135
 136 - The "event" member contains the event's name
 137 - The "data" member contains event specific data, which is defined in a
 138   per-event basis, it is optional
 139 - The "timestamp" member contains the exact time of when the event occurred
 140   in the Server. It is a fixed json-object with time in seconds and
 141   microseconds
 142
 143 For a listing of supported asynchronous events, please, refer to the
 144 qmp-events.txt file.
 145
 146 3. QMP Examples
 147 ===============
 148
 149 This section provides some examples of real QMP usage, in all of them
 150 'C' stands for 'Client' and 'S' stands for 'Server'.
 151
 152 3.1 Server greeting
 153 -------------------
 154
 155 S: {"QMP": {"capabilities": []}}
 156
 157 3.2 Simple 'stop' execution
 158 ---------------------------
 159
 160 C: { "execute": "stop" }
 161 S: {"return": {}}
 162
 163 3.3 KVM information
 164 -------------------
 165
 166 C: { "execute": "query-kvm", "id": "example" }
 167 S: {"return": {"enabled": true, "present": true}, "id": "example"}
 168
 169 3.4 Parsing error
 170 ------------------
 171
 172 C: { "execute": }
 173 S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
 174 {}}}
 175
 176 3.5 Powerdown event
 177 -------------------
 178
 179 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
 180 "POWERDOWN"}
 181
 182 4. Compatibility Considerations
 183 --------------------------------
 184
 185 In order to achieve maximum compatibility between versions, Clients must not
 186 assume any particular:
 187
 188 - Size of json-objects or length of json-arrays
 189 - Order of json-object members or json-array elements
 190 - Amount of errors generated by a command, that is, new errors can be added
 191   to any existing command in newer versions of the Server
 192
 193 Additionally, Clients should always:
 194
 195 - Check the capabilities json-array at connection time
 196 - Check the availability of commands with 'query-commands' before issuing them
 197
 198 5. Recommendations to Client implementors
 199 -----------------------------------------
 200
 201 5.1 The Server should be always started in pause mode, thus the Client is
 202     able to perform any setup procedure without the risk of race conditions
 203     and related problems