1 QEMU Monitor Protocol Specification - Version 0.1
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.
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.
13 2. Protocol Specification
14 =========================
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.
20 JSON data structures, when mentioned in this document, are always in the
23 json-DATA-STRUCTURE-NAME
25 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
28 http://www.ietf.org/rfc/rfc4627.txt
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.
34 2.1 General Definitions
35 -----------------------
37 2.1.1 All interactions transmitted by the Server are json-objects, always
40 2.1.2 All json-objects members are mandatory when not specified otherwise
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').
52 { "QMP": { "version": json-object, "capabilities": json-array } }
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
64 The format for command execution is:
66 { "execute": json-string, "arguments": json-object, "id": json-value }
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
77 2.4 Commands Responses
78 ----------------------
80 There are two possible responses which the Server will issue as the result
81 of a command execution: success or error.
86 The success response is issued when the command execution has finished
91 { "return": json-object, "id": json-value }
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
98 - The "id" member contains the transaction identification associated
99 with the command execution (if issued by the Client)
104 The error response is issued when the command execution could not be
105 completed because of an error condition.
109 { "error": { "class": json-string, "data": json-object, "desc": json-string },
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)
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.
126 2.5 Asynchronous events
127 -----------------------
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'.
134 { "event": json-string, "data": json-object,
135 "timestamp": { "seconds": json-number, "microseconds": json-number } }
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
146 For a listing of supported asynchronous events, please, refer to the
152 This section provides some examples of real QMP usage, in all of them
153 'C' stands for 'Client' and 'S' stands for 'Server'.
158 S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
160 3.2 Simple 'stop' execution
161 ---------------------------
163 C: { "execute": "stop" }
169 C: { "execute": "query-kvm", "id": "example" }
170 S: {"return": {"enabled": true, "present": true}, "id": "example"}
176 S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
182 S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
185 4. Capabilities Negotiation
186 ----------------------------
188 When a Client successfully establishes a connection, the Server is in
189 Capabilities Negotiation mode.
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.
195 Clients should use the 'qmp_capabilities' command to enable capabilities
196 advertised in the Server's greeting (section '2.2 Server Greeting') they
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.
204 5 Compatibility Considerations
205 ------------------------------
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.
212 Additionally, Clients must not assume any particular:
214 - Size of json-objects or length of json-arrays
215 - Order of json-object members or json-array elements
216 - Amount of errors generated by a command, that is, new errors can be added
217 to any existing command in newer versions of the Server