root / QMP / qmp-spec.txt @ 5307d7d3
History | View | Annotate | Download (6.8 kB)
1 | 94048982 | Luiz Capitulino | QEMU Monitor Protocol Specification - Version 0.1 |
---|---|---|---|
2 | f544d174 | Luiz Capitulino | |
3 | f544d174 | Luiz Capitulino | 1. Introduction |
4 | f544d174 | Luiz Capitulino | =============== |
5 | f544d174 | Luiz Capitulino | |
6 | f544d174 | Luiz Capitulino | This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol |
7 | f544d174 | Luiz Capitulino | which is available for applications to control QEMU at the machine-level. |
8 | f544d174 | Luiz Capitulino | |
9 | f544d174 | Luiz Capitulino | To enable QMP support, QEMU has to be run in "control mode". This is done by |
10 | f544d174 | Luiz Capitulino | starting QEMU with the appropriate command-line options. Please, refer to the |
11 | f544d174 | Luiz Capitulino | QEMU manual page for more information. |
12 | f544d174 | Luiz Capitulino | |
13 | f544d174 | Luiz Capitulino | 2. Protocol Specification |
14 | f544d174 | Luiz Capitulino | ========================= |
15 | f544d174 | Luiz Capitulino | |
16 | f544d174 | Luiz Capitulino | This section details the protocol format. For the purpose of this document |
17 | f544d174 | Luiz Capitulino | "Client" is any application which is communicating with QEMU in control mode, |
18 | f544d174 | Luiz Capitulino | and "Server" is QEMU itself. |
19 | f544d174 | Luiz Capitulino | |
20 | f544d174 | Luiz Capitulino | JSON data structures, when mentioned in this document, are always in the |
21 | f544d174 | Luiz Capitulino | following format: |
22 | f544d174 | Luiz Capitulino | |
23 | f544d174 | Luiz Capitulino | json-DATA-STRUCTURE-NAME |
24 | f544d174 | Luiz Capitulino | |
25 | f544d174 | Luiz Capitulino | Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by |
26 | f544d174 | Luiz Capitulino | the JSON standard: |
27 | f544d174 | Luiz Capitulino | |
28 | f544d174 | Luiz Capitulino | http://www.ietf.org/rfc/rfc4627.txt |
29 | f544d174 | Luiz Capitulino | |
30 | 94048982 | Luiz Capitulino | For convenience, json-object members and json-array elements mentioned in |
31 | 94048982 | Luiz Capitulino | this document will be in a certain order. However, in real protocol usage |
32 | 94048982 | Luiz Capitulino | they can be in ANY order, thus no particular order should be assumed. |
33 | f544d174 | Luiz Capitulino | |
34 | f544d174 | Luiz Capitulino | 2.1 General Definitions |
35 | f544d174 | Luiz Capitulino | ----------------------- |
36 | f544d174 | Luiz Capitulino | |
37 | f544d174 | Luiz Capitulino | 2.1.1 All interactions transmitted by the Server are json-objects, always |
38 | f544d174 | Luiz Capitulino | terminating with CRLF |
39 | f544d174 | Luiz Capitulino | |
40 | f544d174 | Luiz Capitulino | 2.1.2 All json-objects members are mandatory when not specified otherwise |
41 | f544d174 | Luiz Capitulino | |
42 | f544d174 | Luiz Capitulino | 2.2 Server Greeting |
43 | f544d174 | Luiz Capitulino | ------------------- |
44 | f544d174 | Luiz Capitulino | |
45 | f544d174 | Luiz Capitulino | Right when connected the Server will issue a greeting message, which signals |
46 | f544d174 | Luiz Capitulino | that the connection has been successfully established and that the Server is |
47 | 5307d7d3 | Luiz Capitulino | ready for capabilities negotiation (for more information refer to section |
48 | 5307d7d3 | Luiz Capitulino | '4. Capabilities Negotiation'). |
49 | f544d174 | Luiz Capitulino | |
50 | f544d174 | Luiz Capitulino | The format is: |
51 | f544d174 | Luiz Capitulino | |
52 | ca9567e2 | Luiz Capitulino | { "QMP": { "version": json-object, "capabilities": json-array } } |
53 | f544d174 | Luiz Capitulino | |
54 | f544d174 | Luiz Capitulino | Where, |
55 | f544d174 | Luiz Capitulino | |
56 | ca9567e2 | Luiz Capitulino | - The "version" member contains the Server's version information (the format |
57 | ca9567e2 | Luiz Capitulino | is the same of the 'query-version' command) |
58 | f544d174 | Luiz Capitulino | - The "capabilities" member specify the availability of features beyond the |
59 | f544d174 | Luiz Capitulino | baseline specification |
60 | f544d174 | Luiz Capitulino | |
61 | f544d174 | Luiz Capitulino | 2.3 Issuing Commands |
62 | f544d174 | Luiz Capitulino | -------------------- |
63 | f544d174 | Luiz Capitulino | |
64 | f544d174 | Luiz Capitulino | The format for command execution is: |
65 | f544d174 | Luiz Capitulino | |
66 | f544d174 | Luiz Capitulino | { "execute": json-string, "arguments": json-object, "id": json-value } |
67 | f544d174 | Luiz Capitulino | |
68 | f544d174 | Luiz Capitulino | Where, |
69 | f544d174 | Luiz Capitulino | |
70 | f544d174 | Luiz Capitulino | - The "execute" member identifies the command to be executed by the Server |
71 | f544d174 | Luiz Capitulino | - The "arguments" member is used to pass any arguments required for the |
72 | f544d174 | Luiz Capitulino | execution of the command, it is optional when no arguments are required |
73 | f544d174 | Luiz Capitulino | - The "id" member is a transaction identification associated with the |
74 | f544d174 | Luiz Capitulino | command execution, it is optional and will be part of the response if |
75 | f544d174 | Luiz Capitulino | provided |
76 | f544d174 | Luiz Capitulino | |
77 | f544d174 | Luiz Capitulino | 2.4 Commands Responses |
78 | f544d174 | Luiz Capitulino | ---------------------- |
79 | f544d174 | Luiz Capitulino | |
80 | f544d174 | Luiz Capitulino | There are two possible responses which the Server will issue as the result |
81 | f544d174 | Luiz Capitulino | of a command execution: success or error. |
82 | f544d174 | Luiz Capitulino | |
83 | f544d174 | Luiz Capitulino | 2.4.1 success |
84 | f544d174 | Luiz Capitulino | ------------- |
85 | f544d174 | Luiz Capitulino | |
86 | f544d174 | Luiz Capitulino | The success response is issued when the command execution has finished |
87 | f544d174 | Luiz Capitulino | without errors. |
88 | f544d174 | Luiz Capitulino | |
89 | f544d174 | Luiz Capitulino | The format is: |
90 | f544d174 | Luiz Capitulino | |
91 | 94048982 | Luiz Capitulino | { "return": json-object, "id": json-value } |
92 | f544d174 | Luiz Capitulino | |
93 | f544d174 | Luiz Capitulino | Where, |
94 | f544d174 | Luiz Capitulino | |
95 | f544d174 | Luiz Capitulino | - The "return" member contains the command returned data, which is defined |
96 | 94048982 | Luiz Capitulino | in a per-command basis or an empty json-object if the command does not |
97 | 94048982 | Luiz Capitulino | return data |
98 | f544d174 | Luiz Capitulino | - The "id" member contains the transaction identification associated |
99 | f544d174 | Luiz Capitulino | with the command execution (if issued by the Client) |
100 | f544d174 | Luiz Capitulino | |
101 | f544d174 | Luiz Capitulino | 2.4.2 error |
102 | f544d174 | Luiz Capitulino | ----------- |
103 | f544d174 | Luiz Capitulino | |
104 | f544d174 | Luiz Capitulino | The error response is issued when the command execution could not be |
105 | f544d174 | Luiz Capitulino | completed because of an error condition. |
106 | f544d174 | Luiz Capitulino | |
107 | f544d174 | Luiz Capitulino | The format is: |
108 | f544d174 | Luiz Capitulino | |
109 | 94048982 | Luiz Capitulino | { "error": { "class": json-string, "data": json-object, "desc": json-string }, |
110 | 77e595e7 | Markus Armbruster | "id": json-value } |
111 | f544d174 | Luiz Capitulino | |
112 | f544d174 | Luiz Capitulino | Where, |
113 | f544d174 | Luiz Capitulino | |
114 | f544d174 | Luiz Capitulino | - The "class" member contains the error class name (eg. "ServiceUnavailable") |
115 | f544d174 | Luiz Capitulino | - The "data" member contains specific error data and is defined in a |
116 | f544d174 | Luiz Capitulino | per-command basis, it will be an empty json-object if the error has no data |
117 | 94048982 | Luiz Capitulino | - The "desc" member is a human-readable error message. Clients should |
118 | 77e595e7 | Markus Armbruster | not attempt to parse this message. |
119 | f544d174 | Luiz Capitulino | - The "id" member contains the transaction identification associated with |
120 | f544d174 | Luiz Capitulino | the command execution (if issued by the Client) |
121 | f544d174 | Luiz Capitulino | |
122 | f544d174 | Luiz Capitulino | NOTE: Some errors can occur before the Server is able to read the "id" member, |
123 | f544d174 | Luiz Capitulino | in these cases the "id" member will not be part of the error response, even |
124 | f544d174 | Luiz Capitulino | if provided by the client. |
125 | f544d174 | Luiz Capitulino | |
126 | f544d174 | Luiz Capitulino | 2.5 Asynchronous events |
127 | f544d174 | Luiz Capitulino | ----------------------- |
128 | f544d174 | Luiz Capitulino | |
129 | f544d174 | Luiz Capitulino | As a result of state changes, the Server may send messages unilaterally |
130 | f544d174 | Luiz Capitulino | to the Client at any time. They are called 'asynchronous events'. |
131 | f544d174 | Luiz Capitulino | |
132 | f544d174 | Luiz Capitulino | The format is: |
133 | f544d174 | Luiz Capitulino | |
134 | 94048982 | Luiz Capitulino | { "event": json-string, "data": json-object, |
135 | f544d174 | Luiz Capitulino | "timestamp": { "seconds": json-number, "microseconds": json-number } } |
136 | f544d174 | Luiz Capitulino | |
137 | f544d174 | Luiz Capitulino | Where, |
138 | f544d174 | Luiz Capitulino | |
139 | f544d174 | Luiz Capitulino | - The "event" member contains the event's name |
140 | f544d174 | Luiz Capitulino | - The "data" member contains event specific data, which is defined in a |
141 | f544d174 | Luiz Capitulino | per-event basis, it is optional |
142 | 94048982 | Luiz Capitulino | - The "timestamp" member contains the exact time of when the event occurred |
143 | f544d174 | Luiz Capitulino | in the Server. It is a fixed json-object with time in seconds and |
144 | f544d174 | Luiz Capitulino | microseconds |
145 | f544d174 | Luiz Capitulino | |
146 | f544d174 | Luiz Capitulino | For a listing of supported asynchronous events, please, refer to the |
147 | f544d174 | Luiz Capitulino | qmp-events.txt file. |
148 | f544d174 | Luiz Capitulino | |
149 | f544d174 | Luiz Capitulino | 3. QMP Examples |
150 | f544d174 | Luiz Capitulino | =============== |
151 | f544d174 | Luiz Capitulino | |
152 | f544d174 | Luiz Capitulino | This section provides some examples of real QMP usage, in all of them |
153 | f544d174 | Luiz Capitulino | 'C' stands for 'Client' and 'S' stands for 'Server'. |
154 | f544d174 | Luiz Capitulino | |
155 | f544d174 | Luiz Capitulino | 3.1 Server greeting |
156 | f544d174 | Luiz Capitulino | ------------------- |
157 | f544d174 | Luiz Capitulino | |
158 | ca9567e2 | Luiz Capitulino | S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}} |
159 | f544d174 | Luiz Capitulino | |
160 | f544d174 | Luiz Capitulino | 3.2 Simple 'stop' execution |
161 | f544d174 | Luiz Capitulino | --------------------------- |
162 | f544d174 | Luiz Capitulino | |
163 | f544d174 | Luiz Capitulino | C: { "execute": "stop" } |
164 | 94048982 | Luiz Capitulino | S: {"return": {}} |
165 | f544d174 | Luiz Capitulino | |
166 | f544d174 | Luiz Capitulino | 3.3 KVM information |
167 | f544d174 | Luiz Capitulino | ------------------- |
168 | f544d174 | Luiz Capitulino | |
169 | 94048982 | Luiz Capitulino | C: { "execute": "query-kvm", "id": "example" } |
170 | 94048982 | Luiz Capitulino | S: {"return": {"enabled": true, "present": true}, "id": "example"} |
171 | f544d174 | Luiz Capitulino | |
172 | f544d174 | Luiz Capitulino | 3.4 Parsing error |
173 | f544d174 | Luiz Capitulino | ------------------ |
174 | f544d174 | Luiz Capitulino | |
175 | f544d174 | Luiz Capitulino | C: { "execute": } |
176 | 94048982 | Luiz Capitulino | S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data": |
177 | 94048982 | Luiz Capitulino | {}}} |
178 | f544d174 | Luiz Capitulino | |
179 | f544d174 | Luiz Capitulino | 3.5 Powerdown event |
180 | f544d174 | Luiz Capitulino | ------------------- |
181 | f544d174 | Luiz Capitulino | |
182 | f544d174 | Luiz Capitulino | S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event": |
183 | f544d174 | Luiz Capitulino | "POWERDOWN"} |
184 | f544d174 | Luiz Capitulino | |
185 | 5307d7d3 | Luiz Capitulino | 4. Capabilities Negotiation |
186 | 5307d7d3 | Luiz Capitulino | ---------------------------- |
187 | f544d174 | Luiz Capitulino | |
188 | 5307d7d3 | Luiz Capitulino | When a Client successfully establishes a connection, the Server is in |
189 | 5307d7d3 | Luiz Capitulino | Capabilities Negotiation mode. |
190 | f544d174 | Luiz Capitulino | |
191 | 5307d7d3 | Luiz Capitulino | In this mode only the 'qmp_capabilities' command is allowed to run, all |
192 | 5307d7d3 | Luiz Capitulino | other commands will return the CommandNotFound error. Asynchronous messages |
193 | 5307d7d3 | Luiz Capitulino | are not delivered either. |
194 | 5307d7d3 | Luiz Capitulino | |
195 | 5307d7d3 | Luiz Capitulino | Clients should use the 'qmp_capabilities' command to enable capabilities |
196 | 5307d7d3 | Luiz Capitulino | advertised in the Server's greeting (section '2.2 Server Greeting') they |
197 | 5307d7d3 | Luiz Capitulino | support. |
198 | f544d174 | Luiz Capitulino | |
199 | 5307d7d3 | Luiz Capitulino | When the 'qmp_capabilities' command is issued, and if it does not return an |
200 | 5307d7d3 | Luiz Capitulino | error, the Server enters in Command mode where capabilities changes take |
201 | 5307d7d3 | Luiz Capitulino | effect, all commands (except 'qmp_capabilities') are allowed and asynchronous |
202 | 5307d7d3 | Luiz Capitulino | messages are delivered. |
203 | f544d174 | Luiz Capitulino | |
204 | 5307d7d3 | Luiz Capitulino | 5 Compatibility Considerations |
205 | 5307d7d3 | Luiz Capitulino | ------------------------------ |
206 | 94048982 | Luiz Capitulino | |
207 | 5307d7d3 | Luiz Capitulino | All protocol changes or new features which modify the protocol format in an |
208 | 5307d7d3 | Luiz Capitulino | incompatible way are disabled by default and will be advertised by the |
209 | 5307d7d3 | Luiz Capitulino | capabilities array (section '2.2 Server Greeting'). Thus, Clients can check |
210 | 5307d7d3 | Luiz Capitulino | that array and enable the capabilities they support. |
211 | 94048982 | Luiz Capitulino | |
212 | 5307d7d3 | Luiz Capitulino | Additionally, Clients must not assume any particular: |
213 | 5307d7d3 | Luiz Capitulino | |
214 | 5307d7d3 | Luiz Capitulino | - Size of json-objects or length of json-arrays |
215 | 5307d7d3 | Luiz Capitulino | - Order of json-object members or json-array elements |
216 | 5307d7d3 | Luiz Capitulino | - Amount of errors generated by a command, that is, new errors can be added |
217 | 5307d7d3 | Luiz Capitulino | to any existing command in newer versions of the Server |