![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to qmp-spec.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Qemu by Fabrice Bellard] / qemu / QMP|
Return to qmp-spec.txt CVS log | Up to [Qemu by Fabrice Bellard] / qemu / QMP |
1.1 root 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
1.1.1.2 root 47: ready for capabilities negotiation (for more information refer to section
48: '4. Capabilities Negotiation').
1.1 root 49:
50: The format is:
51:
1.1.1.2 root 52: { "QMP": { "version": json-object, "capabilities": json-array } }
1.1 root 53:
54: Where,
55:
1.1.1.2 root 56: - The "version" member contains the Server's version information (the format
57: is the same of the 'query-version' command)
1.1 root 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:
1.1.1.2 root 158: S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
1.1 root 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:
1.1.1.2 root 185: 4. Capabilities Negotiation
186: ----------------------------
1.1 root 187:
1.1.1.2 root 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:
1.1.1.3 ! root 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.
1.1 root 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:
1.1.1.3 ! root 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:
1.1.1.2 root 233: 6. Downstream extension of QMP
234: ------------------------------
1.1 root 235:
1.1.1.2 root 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.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.