]>
Commit | Line | Data |
---|---|---|
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. |