QMP/qmp-spec.txt

   1            QEMU Monitor Protocol Draft 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 This specification is a work in progress and part of it may NOT be available
  14 in QEMU, the 'Current Implementation' section has details regarding what has
  15 already been implemented and known problems.
  16
  17 2. Protocol Specification
  18 =========================
  19
  20 This section details the protocol format. For the purpose of this document
  21 "Client" is any application which is communicating with QEMU in control mode,
  22 and "Server" is QEMU itself.
  23
  24 JSON data structures, when mentioned in this document, are always in the
  25 following format:
  26
  27     json-DATA-STRUCTURE-NAME
  28
  29 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
  30 the JSON standard:
  31
  32 http://www.ietf.org/rfc/rfc4627.txt
  33
  34 For convenience, json-objects mentioned in this document will have its members
  35 in a certain order. However, in real protocol usage json-objects members can
  36 be in ANY order, thus no particular order should be assumed.
  37
  38 2.1 General Definitions
  39 -----------------------
  40
  41 All interactions transmitted by the Server are json-objects that end with CRLF.
  42
  43 All json-objects members are mandatory when not specified otherwise.
  44
  45 2.2 Server Greeting
  46 -------------------
  47
  48 Right when connected the Server will issue a greeting message, which signals
  49 that the connection has been successfully established and that the Server is
  50 waiting for commands.
  51
  52 The format is:
  53
  54 { "QMP": { "capabilities": json-array } }
  55
  56  Where,
  57
  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, "id": json-value, "arguments": json-object }
  67
  68  Where,
  69
  70 - The "execute" member identifies the command to be executed by the Server
  71 - The "id" member is a transaction identification associated with the
  72   command execution, it is optional
  73 - The "arguments" member is used to pass any arguments required for the
  74   execution of the command, it is optional when no arguments are required
  75
  76 For a listing of supported commands and theirs arguments, please, refer to
  77 the qmp-command-set.txt file.
  78
  79 2.4 Commands Execution
  80 ----------------------
  81
  82 TODO: explain parallel execution and the "id" member.
  83
  84 2.5 Commands Responses
  85 ----------------------
  86
  87 There are two possible responses which the Server will issue as the result
  88 of a command completion: success or error.
  89
  90 2.5.1 success
  91 -------------
  92
  93 The success response is issued when the command execution has finished
  94 without errors.
  95
  96 The format is:
  97
  98 { "return": json-value, "id": json-value, "timestamp": json-string }
  99
 100  Where,
 101
 102 - The "return" member contains the command returned data, which is defined
 103   in a per-command basis or json-null if the command does not return data
 104 - The "id" member contains the transaction identification associated
 105   with the command execution (if issued by the Client)
 106 - The "timestamp" member contains the exact time of when the response was
 107   generated by the Server (FIXME: format)
 108
 109 2.5.2 error
 110 -----------
 111
 112 The error response is issued when the command execution could not be
 113 completed because of an error condition.
 114
 115 The format is:
 116
 117 { "error": { "code": json-number, "desc": json-string, "data": json-value } "id": json-value, "timestamp": json-string }
 118
 119  Where,
 120
 121 - The "code" member contains the error code. Its first digit indicates the
 122   error type, as show below:
 123
 124         1 Server
 125         2 Protocol
 126         3 Command Specific
 127
 128 - The "desc" member contains the error description
 129 - The "data" member contains specific error data, it is optional
 130 - The "id" member contains the transaction identification associated with
 131   the command execution (if issued by the Client)
 132 - The "timestamp" member contains the exact time of when the response was
 133   generated by the Server (FIXME: format)
 134
 135 Section '2.7 Server and Protocol errors' contains additional information about
 136 error handling.
 137
 138 2.6 Asynchronous events
 139 -----------------------
 140
 141 As a result of state changes, the Server may send messages unilaterally
 142 to the Client at any time. This is called 'asynchronous events'.
 143
 144 The format is:
 145
 146 { "event": json-string, "timestamp": json-string, "data": json-value }
 147
 148  Where,
 149
 150 - The "event" member contains the event's name
 151 - The "timestamp" member contains the exact time of when the event happend
 152   in the Server (FIXME: format)
 153 - The "data" member contains event specific data, which is defined in a
 154   per-event basis, it is optional
 155
 156 For a listing of supported asynchronous events, please, refer to the
 157 qmp-command-set.txt file.
 158
 159 2.7 Server and Protocol errors
 160 ------------------------------
 161
 162 TODO: describe all possible server and protocol errors.
 163
 164 3. Examples
 165 ============
 166
 167 This section provides some examples of real QMP usage, in all of them
 168 'C' stands for 'Client' and 'S' stands for 'Server'.
 169
 170 3.1 Simple 'stop' execution
 171 ---------------------------
 172
 173 S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
 174 C: { "execute": "stop" }
 175 S: { "return": null, "timestamp": "" }
 176
 177 3.2 KVM information
 178 -------------------
 179
 180 S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
 181 C: { "execute": "info", "id": 1, "arguments": { "item": "kvm" } }
 182 S: { "return": "enabled", "id": 1, "timestamp": "" }
 183
 184 3.3 Error on 'info balloon' execution
 185 -------------------------------------
 186
 187 S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
 188 C: { "execute": "info", "id": "abc", "arguments": { "item": "balloon" } }
 189 S: { "error": { "code": 354, "Ballooning not activated in VM" }, "id": "abc", "timestamp": "" }
 190
 191 3.4 Powerdown event
 192 -------------------
 193
 194 S: { "QEMU": "0.11.50", "QMP": "0.1", "capabilities": [] }
 195 ...
 196 S: { "event": "POWERDOWN", "timestamp": "" }
 197 ...
 198
 199 4. Current Implementation
 200 =========================
 201
 202 The current QMP implementation lacks some of the protocol capabilities
 203 specified in this document.
 204
 205 The most important one is the execution of commands as discussed in the
 206 section '2.3 Issuing Commands'. Currently the Server does not support it.
 207
 208 Protocol input is done by issuing regular ASCII strings, as it is done when
 209 using the humam Monitor protocol.
 210
 211 For example, to query the current balloon information the Client should
 212 issue:
 213
 214 "info balloon\r\n"
 215
 216 Additionally, the following limitations are present:
 217
 218 - The transaction "id" is not supported
 219 - json-strings issued by the Server are not in Unicode format
 220 - All "timestamp" members are always an empty json-string ""
 221 - Error handling is basically not implemented