![[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
47: waiting for commands.
48:
49: The format is:
50:
51: { "QMP": { "capabilities": json-array } }
52:
53: Where,
54:
55: - The "capabilities" member specify the availability of features beyond the
56: baseline specification
57:
58: 2.3 Issuing Commands
59: --------------------
60:
61: The format for command execution is:
62:
63: { "execute": json-string, "arguments": json-object, "id": json-value }
64:
65: Where,
66:
67: - The "execute" member identifies the command to be executed by the Server
68: - The "arguments" member is used to pass any arguments required for the
69: execution of the command, it is optional when no arguments are required
70: - The "id" member is a transaction identification associated with the
71: command execution, it is optional and will be part of the response if
72: provided
73:
74: 2.4 Commands Responses
75: ----------------------
76:
77: There are two possible responses which the Server will issue as the result
78: of a command execution: success or error.
79:
80: 2.4.1 success
81: -------------
82:
83: The success response is issued when the command execution has finished
84: without errors.
85:
86: The format is:
87:
88: { "return": json-object, "id": json-value }
89:
90: Where,
91:
92: - The "return" member contains the command returned data, which is defined
93: in a per-command basis or an empty json-object if the command does not
94: return data
95: - The "id" member contains the transaction identification associated
96: with the command execution (if issued by the Client)
97:
98: 2.4.2 error
99: -----------
100:
101: The error response is issued when the command execution could not be
102: completed because of an error condition.
103:
104: The format is:
105:
106: { "error": { "class": json-string, "data": json-object, "desc": json-string },
107: "id": json-value }
108:
109: Where,
110:
111: - The "class" member contains the error class name (eg. "ServiceUnavailable")
112: - The "data" member contains specific error data and is defined in a
113: per-command basis, it will be an empty json-object if the error has no data
114: - The "desc" member is a human-readable error message. Clients should
115: not attempt to parse this message.
116: - The "id" member contains the transaction identification associated with
117: the command execution (if issued by the Client)
118:
119: NOTE: Some errors can occur before the Server is able to read the "id" member,
120: in these cases the "id" member will not be part of the error response, even
121: if provided by the client.
122:
123: 2.5 Asynchronous events
124: -----------------------
125:
126: As a result of state changes, the Server may send messages unilaterally
127: to the Client at any time. They are called 'asynchronous events'.
128:
129: The format is:
130:
131: { "event": json-string, "data": json-object,
132: "timestamp": { "seconds": json-number, "microseconds": json-number } }
133:
134: Where,
135:
136: - The "event" member contains the event's name
137: - The "data" member contains event specific data, which is defined in a
138: per-event basis, it is optional
139: - The "timestamp" member contains the exact time of when the event occurred
140: in the Server. It is a fixed json-object with time in seconds and
141: microseconds
142:
143: For a listing of supported asynchronous events, please, refer to the
144: qmp-events.txt file.
145:
146: 3. QMP Examples
147: ===============
148:
149: This section provides some examples of real QMP usage, in all of them
150: 'C' stands for 'Client' and 'S' stands for 'Server'.
151:
152: 3.1 Server greeting
153: -------------------
154:
155: S: {"QMP": {"capabilities": []}}
156:
157: 3.2 Simple 'stop' execution
158: ---------------------------
159:
160: C: { "execute": "stop" }
161: S: {"return": {}}
162:
163: 3.3 KVM information
164: -------------------
165:
166: C: { "execute": "query-kvm", "id": "example" }
167: S: {"return": {"enabled": true, "present": true}, "id": "example"}
168:
169: 3.4 Parsing error
170: ------------------
171:
172: C: { "execute": }
173: S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":
174: {}}}
175:
176: 3.5 Powerdown event
177: -------------------
178:
179: S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":
180: "POWERDOWN"}
181:
182: 4. Compatibility Considerations
183: --------------------------------
184:
185: In order to achieve maximum compatibility between versions, Clients must not
186: assume any particular:
187:
188: - Size of json-objects or length of json-arrays
189: - Order of json-object members or json-array elements
190: - Amount of errors generated by a command, that is, new errors can be added
191: to any existing command in newer versions of the Server
192:
193: Additionally, Clients should always:
194:
195: - Check the capabilities json-array at connection time
196: - Check the availability of commands with 'query-commands' before issuing them
197:
198: 5. Recommendations to Client implementors
199: -----------------------------------------
200:
201: 5.1 The Server should be always started in pause mode, thus the Client is
202: able to perform any setup procedure without the risk of race conditions
203: and related problems
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.