]>
Commit | Line | Data |
---|---|---|
e3d4d252 MR |
1 | # *-*- Mode: Python -*-* |
2 | ||
3cf0bed8 MR |
3 | ## |
4 | # | |
5 | # Echo back a unique integer value, and prepend to response a | |
6 | # leading sentinel byte (0xFF) the client can check scan for. | |
7 | # | |
8 | # This is used by clients talking to the guest agent over the | |
9 | # wire to ensure the stream is in sync and doesn't contain stale | |
10 | # data from previous client. It must be issued upon initial | |
11 | # connection, and after any client-side timeouts (including | |
12 | # timeouts on receiving a response to this command). | |
13 | # | |
14 | # After issuing this request, all guest agent responses should be | |
15 | # ignored until the response containing the unique integer value | |
16 | # the client passed in is returned. Receival of the 0xFF sentinel | |
17 | # byte must be handled as an indication that the client's | |
18 | # lexer/tokenizer/parser state should be flushed/reset in | |
19 | # preparation for reliably receiving the subsequent response. As | |
20 | # an optimization, clients may opt to ignore all data until a | |
a31f0531 | 21 | # sentinel value is receiving to avoid unnecessary processing of |
3cf0bed8 MR |
22 | # stale data. |
23 | # | |
24 | # Similarly, clients should also precede this *request* | |
25 | # with a 0xFF byte to make sure the guest agent flushes any | |
26 | # partially read JSON data from a previous client connection. | |
27 | # | |
28 | # @id: randomly generated 64-bit integer | |
29 | # | |
30 | # Returns: The unique integer id passed in by the client | |
31 | # | |
32 | # Since: 1.1 | |
33 | # ## | |
34 | { 'command': 'guest-sync-delimited' | |
35 | 'data': { 'id': 'int' }, | |
36 | 'returns': 'int' } | |
37 | ||
e3d4d252 MR |
38 | ## |
39 | # @guest-sync: | |
40 | # | |
41 | # Echo back a unique integer value | |
42 | # | |
43 | # This is used by clients talking to the guest agent over the | |
44 | # wire to ensure the stream is in sync and doesn't contain stale | |
45 | # data from previous client. All guest agent responses should be | |
46 | # ignored until the provided unique integer value is returned, | |
47 | # and it is up to the client to handle stale whole or | |
48 | # partially-delivered JSON text in such a way that this response | |
49 | # can be obtained. | |
50 | # | |
3cf0bed8 MR |
51 | # In cases where a partial stale response was previously |
52 | # received by the client, this cannot always be done reliably. | |
53 | # One particular scenario being if qemu-ga responses are fed | |
54 | # character-by-character into a JSON parser. In these situations, | |
55 | # using guest-sync-delimited may be optimal. | |
56 | # | |
57 | # For clients that fetch responses line by line and convert them | |
58 | # to JSON objects, guest-sync should be sufficient, but note that | |
59 | # in cases where the channel is dirty some attempts at parsing the | |
60 | # response may result in a parser error. | |
61 | # | |
e7d81004 | 62 | # Such clients should also precede this command |
3cf0bed8 | 63 | # with a 0xFF byte to make sure the guest agent flushes any |
e3d4d252 MR |
64 | # partially read JSON data from a previous session. |
65 | # | |
66 | # @id: randomly generated 64-bit integer | |
67 | # | |
68 | # Returns: The unique integer id passed in by the client | |
69 | # | |
70 | # Since: 0.15.0 | |
71 | ## | |
72 | { 'command': 'guest-sync' | |
73 | 'data': { 'id': 'int' }, | |
74 | 'returns': 'int' } | |
75 | ||
76 | ## | |
77 | # @guest-ping: | |
78 | # | |
79 | # Ping the guest agent, a non-error return implies success | |
80 | # | |
81 | # Since: 0.15.0 | |
82 | ## | |
83 | { 'command': 'guest-ping' } | |
84 | ||
85 | ## | |
54383726 | 86 | # @GuestAgentCommandInfo: |
e3d4d252 | 87 | # |
54383726 | 88 | # Information about guest agent commands. |
e3d4d252 | 89 | # |
54383726 MR |
90 | # @name: name of the command |
91 | # | |
92 | # @enabled: whether command is currently enabled by guest admin | |
93 | # | |
94 | # Since 1.1.0 | |
e3d4d252 | 95 | ## |
bf95c0d5 MR |
96 | { 'type': 'GuestAgentCommandInfo', |
97 | 'data': { 'name': 'str', 'enabled': 'bool' } } | |
54383726 MR |
98 | |
99 | ## | |
100 | # @GuestAgentInfo | |
101 | # | |
102 | # Information about guest agent. | |
103 | # | |
104 | # @version: guest agent version | |
105 | # | |
106 | # @supported_commands: Information about guest agent commands | |
107 | # | |
108 | # Since 0.15.0 | |
109 | ## | |
bf95c0d5 MR |
110 | { 'type': 'GuestAgentInfo', |
111 | 'data': { 'version': 'str', | |
112 | 'supported_commands': ['GuestAgentCommandInfo'] } } | |
54383726 MR |
113 | ## |
114 | # @guest-info: | |
115 | # | |
116 | # Get some information about the guest agent. | |
117 | # | |
118 | # Returns: @GuestAgentInfo | |
119 | # | |
120 | # Since: 0.15.0 | |
121 | ## | |
e3d4d252 MR |
122 | { 'command': 'guest-info', |
123 | 'returns': 'GuestAgentInfo' } | |
124 | ||
125 | ## | |
126 | # @guest-shutdown: | |
127 | # | |
128 | # Initiate guest-activated shutdown. Note: this is an asynchronous | |
129 | # shutdown request, with no guaruntee of successful shutdown. Errors | |
130 | # will be logged to guest's syslog. | |
131 | # | |
132 | # @mode: #optional "halt", "powerdown" (default), or "reboot" | |
133 | # | |
89268172 LC |
134 | # This command does NOT return a response on success. Success condition |
135 | # is indicated by the VM exiting with a zero exit status or, when | |
136 | # running with --no-shutdown, by issuing the query-status QMP command | |
137 | # to confirm the VM status is "shutdown". | |
e3d4d252 MR |
138 | # |
139 | # Since: 0.15.0 | |
140 | ## | |
89268172 LC |
141 | { 'command': 'guest-shutdown', 'data': { '*mode': 'str' }, |
142 | 'success-response': 'no' } | |
e3d4d252 MR |
143 | |
144 | ## | |
145 | # @guest-file-open: | |
146 | # | |
147 | # Open a file in the guest and retrieve a file handle for it | |
148 | # | |
149 | # @filepath: Full path to the file in the guest to open. | |
150 | # | |
151 | # @mode: #optional open mode, as per fopen(), "r" is the default. | |
152 | # | |
153 | # Returns: Guest file handle on success. | |
154 | # | |
155 | # Since: 0.15.0 | |
156 | ## | |
157 | { 'command': 'guest-file-open', | |
158 | 'data': { 'path': 'str', '*mode': 'str' }, | |
159 | 'returns': 'int' } | |
160 | ||
161 | ## | |
162 | # @guest-file-close: | |
163 | # | |
164 | # Close an open file in the guest | |
165 | # | |
166 | # @handle: filehandle returned by guest-file-open | |
167 | # | |
168 | # Returns: Nothing on success. | |
169 | # | |
170 | # Since: 0.15.0 | |
171 | ## | |
172 | { 'command': 'guest-file-close', | |
173 | 'data': { 'handle': 'int' } } | |
174 | ||
54383726 MR |
175 | ## |
176 | # @GuestFileRead | |
177 | # | |
178 | # Result of guest agent file-read operation | |
179 | # | |
180 | # @count: number of bytes read (note: count is *before* | |
181 | # base64-encoding is applied) | |
182 | # | |
183 | # @buf-b64: base64-encoded bytes read | |
184 | # | |
185 | # @eof: whether EOF was encountered during read operation. | |
186 | # | |
187 | # Since: 0.15.0 | |
188 | ## | |
189 | { 'type': 'GuestFileRead', | |
190 | 'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } } | |
191 | ||
e3d4d252 MR |
192 | ## |
193 | # @guest-file-read: | |
194 | # | |
195 | # Read from an open file in the guest. Data will be base64-encoded | |
196 | # | |
197 | # @handle: filehandle returned by guest-file-open | |
198 | # | |
199 | # @count: #optional maximum number of bytes to read (default is 4KB) | |
200 | # | |
54383726 | 201 | # Returns: @GuestFileRead on success. |
e3d4d252 MR |
202 | # |
203 | # Since: 0.15.0 | |
204 | ## | |
e3d4d252 MR |
205 | { 'command': 'guest-file-read', |
206 | 'data': { 'handle': 'int', '*count': 'int' }, | |
207 | 'returns': 'GuestFileRead' } | |
208 | ||
54383726 MR |
209 | ## |
210 | # @GuestFileWrite | |
211 | # | |
212 | # Result of guest agent file-write operation | |
213 | # | |
214 | # @count: number of bytes written (note: count is actual bytes | |
215 | # written, after base64-decoding of provided buffer) | |
216 | # | |
217 | # @eof: whether EOF was encountered during write operation. | |
218 | # | |
219 | # Since: 0.15.0 | |
220 | ## | |
221 | { 'type': 'GuestFileWrite', | |
222 | 'data': { 'count': 'int', 'eof': 'bool' } } | |
223 | ||
e3d4d252 MR |
224 | ## |
225 | # @guest-file-write: | |
226 | # | |
227 | # Write to an open file in the guest. | |
228 | # | |
229 | # @handle: filehandle returned by guest-file-open | |
230 | # | |
231 | # @buf-b64: base64-encoded string representing data to be written | |
232 | # | |
233 | # @count: #optional bytes to write (actual bytes, after base64-decode), | |
234 | # default is all content in buf-b64 buffer after base64 decoding | |
235 | # | |
54383726 | 236 | # Returns: @GuestFileWrite on success. |
e3d4d252 MR |
237 | # |
238 | # Since: 0.15.0 | |
239 | ## | |
e3d4d252 MR |
240 | { 'command': 'guest-file-write', |
241 | 'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' }, | |
242 | 'returns': 'GuestFileWrite' } | |
243 | ||
54383726 MR |
244 | |
245 | ## | |
246 | # @GuestFileSeek | |
247 | # | |
248 | # Result of guest agent file-seek operation | |
249 | # | |
250 | # @position: current file position | |
251 | # | |
252 | # @eof: whether EOF was encountered during file seek | |
253 | # | |
254 | # Since: 0.15.0 | |
255 | ## | |
256 | { 'type': 'GuestFileSeek', | |
257 | 'data': { 'position': 'int', 'eof': 'bool' } } | |
258 | ||
e3d4d252 MR |
259 | ## |
260 | # @guest-file-seek: | |
261 | # | |
262 | # Seek to a position in the file, as with fseek(), and return the | |
263 | # current file position afterward. Also encapsulates ftell()'s | |
264 | # functionality, just Set offset=0, whence=SEEK_CUR. | |
265 | # | |
266 | # @handle: filehandle returned by guest-file-open | |
267 | # | |
268 | # @offset: bytes to skip over in the file stream | |
269 | # | |
270 | # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek() | |
271 | # | |
54383726 | 272 | # Returns: @GuestFileSeek on success. |
e3d4d252 MR |
273 | # |
274 | # Since: 0.15.0 | |
275 | ## | |
e3d4d252 MR |
276 | { 'command': 'guest-file-seek', |
277 | 'data': { 'handle': 'int', 'offset': 'int', 'whence': 'int' }, | |
278 | 'returns': 'GuestFileSeek' } | |
279 | ||
280 | ## | |
281 | # @guest-file-flush: | |
282 | # | |
283 | # Write file changes bufferred in userspace to disk/kernel buffers | |
284 | # | |
285 | # @handle: filehandle returned by guest-file-open | |
286 | # | |
287 | # Returns: Nothing on success. | |
288 | # | |
289 | # Since: 0.15.0 | |
290 | ## | |
291 | { 'command': 'guest-file-flush', | |
292 | 'data': { 'handle': 'int' } } | |
293 | ||
294 | ## | |
54383726 | 295 | # @GuestFsFreezeStatus |
e3d4d252 | 296 | # |
54383726 | 297 | # An enumation of filesystem freeze states |
e3d4d252 | 298 | # |
54383726 MR |
299 | # @thawed: filesystems thawed/unfrozen |
300 | # | |
301 | # @frozen: all non-network guest filesystems frozen | |
302 | # | |
e3d4d252 MR |
303 | # Since: 0.15.0 |
304 | ## | |
305 | { 'enum': 'GuestFsfreezeStatus', | |
9e8aded4 | 306 | 'data': [ 'thawed', 'frozen' ] } |
54383726 MR |
307 | |
308 | ## | |
309 | # @guest-fsfreeze-status: | |
310 | # | |
311 | # Get guest fsfreeze state. error state indicates | |
312 | # | |
313 | # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below) | |
314 | # | |
9e8aded4 | 315 | # Note: This may fail to properly report the current state as a result of |
f789aa7b | 316 | # some other guest processes having issued an fs freeze/thaw. |
9e8aded4 | 317 | # |
54383726 MR |
318 | # Since: 0.15.0 |
319 | ## | |
e3d4d252 MR |
320 | { 'command': 'guest-fsfreeze-status', |
321 | 'returns': 'GuestFsfreezeStatus' } | |
322 | ||
323 | ## | |
324 | # @guest-fsfreeze-freeze: | |
325 | # | |
9e8aded4 | 326 | # Sync and freeze all freezable, local guest filesystems |
e3d4d252 | 327 | # |
9e8aded4 MR |
328 | # Returns: Number of file systems currently frozen. On error, all filesystems |
329 | # will be thawed. | |
e3d4d252 MR |
330 | # |
331 | # Since: 0.15.0 | |
332 | ## | |
333 | { 'command': 'guest-fsfreeze-freeze', | |
334 | 'returns': 'int' } | |
335 | ||
336 | ## | |
337 | # @guest-fsfreeze-thaw: | |
338 | # | |
9e8aded4 MR |
339 | # Unfreeze all frozen guest filesystems |
340 | # | |
341 | # Returns: Number of file systems thawed by this call | |
e3d4d252 | 342 | # |
9e8aded4 MR |
343 | # Note: if return value does not match the previous call to |
344 | # guest-fsfreeze-freeze, this likely means some freezable | |
345 | # filesystems were unfrozen before this call, and that the | |
346 | # filesystem state may have changed before issuing this | |
347 | # command. | |
e3d4d252 MR |
348 | # |
349 | # Since: 0.15.0 | |
350 | ## | |
351 | { 'command': 'guest-fsfreeze-thaw', | |
352 | 'returns': 'int' } | |
11d0f125 LC |
353 | |
354 | ## | |
355 | # @guest-suspend-disk | |
356 | # | |
357 | # Suspend guest to disk. | |
358 | # | |
359 | # This command tries to execute the scripts provided by the pm-utils package. | |
360 | # If it's not available, the suspend operation will be performed by manually | |
361 | # writing to a sysfs file. | |
362 | # | |
363 | # For the best results it's strongly recommended to have the pm-utils | |
364 | # package installed in the guest. | |
365 | # | |
c6fcc10a LC |
366 | # This command does NOT return a response on success. There is a high chance |
367 | # the command succeeded if the VM exits with a zero exit status or, when | |
368 | # running with --no-shutdown, by issuing the query-status QMP command to | |
369 | # to confirm the VM status is "shutdown". However, the VM could also exit | |
370 | # (or set its status to "shutdown") due to other reasons. | |
371 | # | |
372 | # The following errors may be returned: | |
11d0f125 LC |
373 | # If suspend to disk is not supported, Unsupported |
374 | # | |
c6fcc10a LC |
375 | # Notes: It's strongly recommended to issue the guest-sync command before |
376 | # sending commands when the guest resumes | |
11d0f125 LC |
377 | # |
378 | # Since: 1.1 | |
379 | ## | |
c6fcc10a | 380 | { 'command': 'guest-suspend-disk', 'success-response': 'no' } |
fbf42210 LC |
381 | |
382 | ## | |
383 | # @guest-suspend-ram | |
384 | # | |
385 | # Suspend guest to ram. | |
386 | # | |
387 | # This command tries to execute the scripts provided by the pm-utils package. | |
388 | # If it's not available, the suspend operation will be performed by manually | |
389 | # writing to a sysfs file. | |
390 | # | |
391 | # For the best results it's strongly recommended to have the pm-utils | |
392 | # package installed in the guest. | |
393 | # | |
394 | # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup' | |
395 | # command. Thus, it's *required* to query QEMU for the presence of the | |
396 | # 'system_wakeup' command before issuing guest-suspend-ram. | |
397 | # | |
432d29db LC |
398 | # This command does NOT return a response on success. There are two options |
399 | # to check for success: | |
400 | # 1. Wait for the SUSPEND QMP event from QEMU | |
401 | # 2. Issue the query-status QMP command to confirm the VM status is | |
402 | # "suspended" | |
403 | # | |
404 | # The following errors may be returned: | |
fbf42210 LC |
405 | # If suspend to ram is not supported, Unsupported |
406 | # | |
432d29db LC |
407 | # Notes: It's strongly recommended to issue the guest-sync command before |
408 | # sending commands when the guest resumes | |
fbf42210 LC |
409 | # |
410 | # Since: 1.1 | |
411 | ## | |
432d29db | 412 | { 'command': 'guest-suspend-ram', 'success-response': 'no' } |
95f4f404 LC |
413 | |
414 | ## | |
415 | # @guest-suspend-hybrid | |
416 | # | |
417 | # Save guest state to disk and suspend to ram. | |
418 | # | |
419 | # This command requires the pm-utils package to be installed in the guest. | |
420 | # | |
421 | # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup' | |
422 | # command. Thus, it's *required* to query QEMU for the presence of the | |
423 | # 'system_wakeup' command before issuing guest-suspend-hybrid. | |
424 | # | |
425 | # Returns: nothing on success | |
426 | # If hybrid suspend is not supported, Unsupported | |
427 | # | |
428 | # Notes: o This is an asynchronous request. There's no guarantee a response | |
429 | # will be sent | |
430 | # o It's strongly recommended to issue the guest-sync command before | |
431 | # sending commands when the guest resumes | |
432 | # | |
433 | # Since: 1.1 | |
434 | ## | |
435 | { 'command': 'guest-suspend-hybrid' } | |
3424fc9f MP |
436 | |
437 | ## | |
438 | # @GuestIpAddressType: | |
439 | # | |
440 | # An enumeration of supported IP address types | |
441 | # | |
442 | # @ipv4: IP version 4 | |
443 | # | |
444 | # @ipv6: IP version 6 | |
445 | # | |
446 | # Since: 1.1 | |
447 | ## | |
448 | { 'enum': 'GuestIpAddressType', | |
449 | 'data': [ 'ipv4', 'ipv6' ] } | |
450 | ||
451 | ## | |
452 | # @GuestIpAddress: | |
453 | # | |
454 | # @ip-address: IP address | |
455 | # | |
456 | # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6) | |
457 | # | |
458 | # @prefix: Network prefix length of @ip-address | |
459 | # | |
460 | # Since: 1.1 | |
461 | ## | |
462 | { 'type': 'GuestIpAddress', | |
463 | 'data': {'ip-address': 'str', | |
464 | 'ip-address-type': 'GuestIpAddressType', | |
465 | 'prefix': 'int'} } | |
466 | ||
467 | ## | |
468 | # @GuestNetworkInterface: | |
469 | # | |
470 | # @name: The name of interface for which info are being delivered | |
471 | # | |
472 | # @hardware-address: Hardware address of @name | |
473 | # | |
474 | # @ip-addresses: List of addresses assigned to @name | |
475 | # | |
476 | # Since: 1.1 | |
477 | ## | |
478 | { 'type': 'GuestNetworkInterface', | |
479 | 'data': {'name': 'str', | |
480 | '*hardware-address': 'str', | |
481 | '*ip-addresses': ['GuestIpAddress'] } } | |
482 | ||
483 | ## | |
484 | # @guest-network-get-interfaces: | |
485 | # | |
486 | # Get list of guest IP addresses, MAC addresses | |
487 | # and netmasks. | |
488 | # | |
489 | # Returns: List of GuestNetworkInfo on success. | |
490 | # | |
491 | # Since: 1.1 | |
492 | ## | |
493 | { 'command': 'guest-network-get-interfaces', | |
494 | 'returns': ['GuestNetworkInterface'] } |