Statistics
| Branch: | Revision:

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