]>
Commit | Line | Data |
---|---|---|
e3d4d252 MR |
1 | # *-*- Mode: Python -*-* |
2 | ||
9481ecd7 LE |
3 | ## |
4 | # | |
5 | # General note concerning the use of guest agent interfaces: | |
6 | # | |
7 | # "unsupported" is a higher-level error than the errors that individual | |
8 | # commands might document. The caller should always be prepared to receive | |
9 | # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't | |
10 | # document any failure mode at all. | |
11 | # | |
12 | ## | |
13 | ||
3cf0bed8 MR |
14 | ## |
15 | # | |
16 | # Echo back a unique integer value, and prepend to response a | |
17 | # leading sentinel byte (0xFF) the client can check scan for. | |
18 | # | |
19 | # This is used by clients talking to the guest agent over the | |
20 | # wire to ensure the stream is in sync and doesn't contain stale | |
21 | # data from previous client. It must be issued upon initial | |
22 | # connection, and after any client-side timeouts (including | |
23 | # timeouts on receiving a response to this command). | |
24 | # | |
25 | # After issuing this request, all guest agent responses should be | |
26 | # ignored until the response containing the unique integer value | |
27 | # the client passed in is returned. Receival of the 0xFF sentinel | |
28 | # byte must be handled as an indication that the client's | |
29 | # lexer/tokenizer/parser state should be flushed/reset in | |
30 | # preparation for reliably receiving the subsequent response. As | |
31 | # an optimization, clients may opt to ignore all data until a | |
a31f0531 | 32 | # sentinel value is receiving to avoid unnecessary processing of |
3cf0bed8 MR |
33 | # stale data. |
34 | # | |
35 | # Similarly, clients should also precede this *request* | |
36 | # with a 0xFF byte to make sure the guest agent flushes any | |
37 | # partially read JSON data from a previous client connection. | |
38 | # | |
39 | # @id: randomly generated 64-bit integer | |
40 | # | |
41 | # Returns: The unique integer id passed in by the client | |
42 | # | |
43 | # Since: 1.1 | |
44 | # ## | |
01b87f6d | 45 | { 'command': 'guest-sync-delimited', |
3cf0bed8 MR |
46 | 'data': { 'id': 'int' }, |
47 | 'returns': 'int' } | |
48 | ||
e3d4d252 MR |
49 | ## |
50 | # @guest-sync: | |
51 | # | |
52 | # Echo back a unique integer value | |
53 | # | |
54 | # This is used by clients talking to the guest agent over the | |
55 | # wire to ensure the stream is in sync and doesn't contain stale | |
56 | # data from previous client. All guest agent responses should be | |
57 | # ignored until the provided unique integer value is returned, | |
58 | # and it is up to the client to handle stale whole or | |
59 | # partially-delivered JSON text in such a way that this response | |
60 | # can be obtained. | |
61 | # | |
3cf0bed8 MR |
62 | # In cases where a partial stale response was previously |
63 | # received by the client, this cannot always be done reliably. | |
64 | # One particular scenario being if qemu-ga responses are fed | |
65 | # character-by-character into a JSON parser. In these situations, | |
66 | # using guest-sync-delimited may be optimal. | |
67 | # | |
68 | # For clients that fetch responses line by line and convert them | |
69 | # to JSON objects, guest-sync should be sufficient, but note that | |
70 | # in cases where the channel is dirty some attempts at parsing the | |
71 | # response may result in a parser error. | |
72 | # | |
e7d81004 | 73 | # Such clients should also precede this command |
3cf0bed8 | 74 | # with a 0xFF byte to make sure the guest agent flushes any |
e3d4d252 MR |
75 | # partially read JSON data from a previous session. |
76 | # | |
77 | # @id: randomly generated 64-bit integer | |
78 | # | |
79 | # Returns: The unique integer id passed in by the client | |
80 | # | |
81 | # Since: 0.15.0 | |
82 | ## | |
01b87f6d | 83 | { 'command': 'guest-sync', |
e3d4d252 MR |
84 | 'data': { 'id': 'int' }, |
85 | 'returns': 'int' } | |
86 | ||
87 | ## | |
88 | # @guest-ping: | |
89 | # | |
90 | # Ping the guest agent, a non-error return implies success | |
91 | # | |
92 | # Since: 0.15.0 | |
93 | ## | |
94 | { 'command': 'guest-ping' } | |
95 | ||
6912e6a9 LL |
96 | ## |
97 | # @guest-get-time: | |
98 | # | |
1634df56 AK |
99 | # Get the information about guest's System Time relative to |
100 | # the Epoch of 1970-01-01 in UTC. | |
6912e6a9 LL |
101 | # |
102 | # Returns: Time in nanoseconds. | |
103 | # | |
104 | # Since 1.5 | |
105 | ## | |
106 | { 'command': 'guest-get-time', | |
107 | 'returns': 'int' } | |
108 | ||
a1bca57f LL |
109 | ## |
110 | # @guest-set-time: | |
111 | # | |
112 | # Set guest time. | |
113 | # | |
114 | # When a guest is paused or migrated to a file then loaded | |
115 | # from that file, the guest OS has no idea that there | |
116 | # was a big gap in the time. Depending on how long the | |
117 | # gap was, NTP might not be able to resynchronize the | |
118 | # guest. | |
119 | # | |
1634df56 AK |
120 | # This command tries to set guest's System Time to the |
121 | # given value, then sets the Hardware Clock (RTC) to the | |
122 | # current System Time. This will make it easier for a guest | |
123 | # to resynchronize without waiting for NTP. If no @time is | |
ee17cbdc MP |
124 | # specified, then the time to set is read from RTC. However, |
125 | # this may not be supported on all platforms (i.e. Windows). | |
126 | # If that's the case users are advised to always pass a | |
127 | # value. | |
a1bca57f | 128 | # |
2c958923 MP |
129 | # @time: #optional time of nanoseconds, relative to the Epoch |
130 | # of 1970-01-01 in UTC. | |
a1bca57f LL |
131 | # |
132 | # Returns: Nothing on success. | |
133 | # | |
134 | # Since: 1.5 | |
135 | ## | |
136 | { 'command': 'guest-set-time', | |
2c958923 | 137 | 'data': { '*time': 'int' } } |
a1bca57f | 138 | |
e3d4d252 | 139 | ## |
54383726 | 140 | # @GuestAgentCommandInfo: |
e3d4d252 | 141 | # |
54383726 | 142 | # Information about guest agent commands. |
e3d4d252 | 143 | # |
54383726 MR |
144 | # @name: name of the command |
145 | # | |
146 | # @enabled: whether command is currently enabled by guest admin | |
147 | # | |
0106dc4f MW |
148 | # @success-response: whether command returns a response on success |
149 | # (since 1.7) | |
150 | # | |
54383726 | 151 | # Since 1.1.0 |
e3d4d252 | 152 | ## |
bf95c0d5 | 153 | { 'type': 'GuestAgentCommandInfo', |
0106dc4f | 154 | 'data': { 'name': 'str', 'enabled': 'bool', 'success-response': 'bool' } } |
54383726 MR |
155 | |
156 | ## | |
157 | # @GuestAgentInfo | |
158 | # | |
159 | # Information about guest agent. | |
160 | # | |
161 | # @version: guest agent version | |
162 | # | |
163 | # @supported_commands: Information about guest agent commands | |
164 | # | |
165 | # Since 0.15.0 | |
166 | ## | |
bf95c0d5 MR |
167 | { 'type': 'GuestAgentInfo', |
168 | 'data': { 'version': 'str', | |
169 | 'supported_commands': ['GuestAgentCommandInfo'] } } | |
54383726 MR |
170 | ## |
171 | # @guest-info: | |
172 | # | |
173 | # Get some information about the guest agent. | |
174 | # | |
175 | # Returns: @GuestAgentInfo | |
176 | # | |
177 | # Since: 0.15.0 | |
178 | ## | |
e3d4d252 MR |
179 | { 'command': 'guest-info', |
180 | 'returns': 'GuestAgentInfo' } | |
181 | ||
182 | ## | |
183 | # @guest-shutdown: | |
184 | # | |
185 | # Initiate guest-activated shutdown. Note: this is an asynchronous | |
3674838c | 186 | # shutdown request, with no guarantee of successful shutdown. |
e3d4d252 MR |
187 | # |
188 | # @mode: #optional "halt", "powerdown" (default), or "reboot" | |
189 | # | |
89268172 LC |
190 | # This command does NOT return a response on success. Success condition |
191 | # is indicated by the VM exiting with a zero exit status or, when | |
192 | # running with --no-shutdown, by issuing the query-status QMP command | |
193 | # to confirm the VM status is "shutdown". | |
e3d4d252 MR |
194 | # |
195 | # Since: 0.15.0 | |
196 | ## | |
89268172 LC |
197 | { 'command': 'guest-shutdown', 'data': { '*mode': 'str' }, |
198 | 'success-response': 'no' } | |
e3d4d252 MR |
199 | |
200 | ## | |
201 | # @guest-file-open: | |
202 | # | |
203 | # Open a file in the guest and retrieve a file handle for it | |
204 | # | |
205 | # @filepath: Full path to the file in the guest to open. | |
206 | # | |
207 | # @mode: #optional open mode, as per fopen(), "r" is the default. | |
208 | # | |
209 | # Returns: Guest file handle on success. | |
210 | # | |
211 | # Since: 0.15.0 | |
212 | ## | |
213 | { 'command': 'guest-file-open', | |
214 | 'data': { 'path': 'str', '*mode': 'str' }, | |
215 | 'returns': 'int' } | |
216 | ||
217 | ## | |
218 | # @guest-file-close: | |
219 | # | |
220 | # Close an open file in the guest | |
221 | # | |
222 | # @handle: filehandle returned by guest-file-open | |
223 | # | |
224 | # Returns: Nothing on success. | |
225 | # | |
226 | # Since: 0.15.0 | |
227 | ## | |
228 | { 'command': 'guest-file-close', | |
229 | 'data': { 'handle': 'int' } } | |
230 | ||
54383726 MR |
231 | ## |
232 | # @GuestFileRead | |
233 | # | |
234 | # Result of guest agent file-read operation | |
235 | # | |
236 | # @count: number of bytes read (note: count is *before* | |
237 | # base64-encoding is applied) | |
238 | # | |
239 | # @buf-b64: base64-encoded bytes read | |
240 | # | |
241 | # @eof: whether EOF was encountered during read operation. | |
242 | # | |
243 | # Since: 0.15.0 | |
244 | ## | |
245 | { 'type': 'GuestFileRead', | |
246 | 'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } } | |
247 | ||
e3d4d252 MR |
248 | ## |
249 | # @guest-file-read: | |
250 | # | |
251 | # Read from an open file in the guest. Data will be base64-encoded | |
252 | # | |
253 | # @handle: filehandle returned by guest-file-open | |
254 | # | |
255 | # @count: #optional maximum number of bytes to read (default is 4KB) | |
256 | # | |
54383726 | 257 | # Returns: @GuestFileRead on success. |
e3d4d252 MR |
258 | # |
259 | # Since: 0.15.0 | |
260 | ## | |
e3d4d252 MR |
261 | { 'command': 'guest-file-read', |
262 | 'data': { 'handle': 'int', '*count': 'int' }, | |
263 | 'returns': 'GuestFileRead' } | |
264 | ||
54383726 MR |
265 | ## |
266 | # @GuestFileWrite | |
267 | # | |
268 | # Result of guest agent file-write operation | |
269 | # | |
270 | # @count: number of bytes written (note: count is actual bytes | |
271 | # written, after base64-decoding of provided buffer) | |
272 | # | |
273 | # @eof: whether EOF was encountered during write operation. | |
274 | # | |
275 | # Since: 0.15.0 | |
276 | ## | |
277 | { 'type': 'GuestFileWrite', | |
278 | 'data': { 'count': 'int', 'eof': 'bool' } } | |
279 | ||
e3d4d252 MR |
280 | ## |
281 | # @guest-file-write: | |
282 | # | |
283 | # Write to an open file in the guest. | |
284 | # | |
285 | # @handle: filehandle returned by guest-file-open | |
286 | # | |
287 | # @buf-b64: base64-encoded string representing data to be written | |
288 | # | |
289 | # @count: #optional bytes to write (actual bytes, after base64-decode), | |
290 | # default is all content in buf-b64 buffer after base64 decoding | |
291 | # | |
54383726 | 292 | # Returns: @GuestFileWrite on success. |
e3d4d252 MR |
293 | # |
294 | # Since: 0.15.0 | |
295 | ## | |
e3d4d252 MR |
296 | { 'command': 'guest-file-write', |
297 | 'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' }, | |
298 | 'returns': 'GuestFileWrite' } | |
299 | ||
54383726 MR |
300 | |
301 | ## | |
302 | # @GuestFileSeek | |
303 | # | |
304 | # Result of guest agent file-seek operation | |
305 | # | |
306 | # @position: current file position | |
307 | # | |
308 | # @eof: whether EOF was encountered during file seek | |
309 | # | |
310 | # Since: 0.15.0 | |
311 | ## | |
312 | { 'type': 'GuestFileSeek', | |
313 | 'data': { 'position': 'int', 'eof': 'bool' } } | |
314 | ||
e3d4d252 MR |
315 | ## |
316 | # @guest-file-seek: | |
317 | # | |
318 | # Seek to a position in the file, as with fseek(), and return the | |
319 | # current file position afterward. Also encapsulates ftell()'s | |
320 | # functionality, just Set offset=0, whence=SEEK_CUR. | |
321 | # | |
322 | # @handle: filehandle returned by guest-file-open | |
323 | # | |
324 | # @offset: bytes to skip over in the file stream | |
325 | # | |
326 | # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek() | |
327 | # | |
54383726 | 328 | # Returns: @GuestFileSeek on success. |
e3d4d252 MR |
329 | # |
330 | # Since: 0.15.0 | |
331 | ## | |
e3d4d252 MR |
332 | { 'command': 'guest-file-seek', |
333 | 'data': { 'handle': 'int', 'offset': 'int', 'whence': 'int' }, | |
334 | 'returns': 'GuestFileSeek' } | |
335 | ||
336 | ## | |
337 | # @guest-file-flush: | |
338 | # | |
339 | # Write file changes bufferred in userspace to disk/kernel buffers | |
340 | # | |
341 | # @handle: filehandle returned by guest-file-open | |
342 | # | |
343 | # Returns: Nothing on success. | |
344 | # | |
345 | # Since: 0.15.0 | |
346 | ## | |
347 | { 'command': 'guest-file-flush', | |
348 | 'data': { 'handle': 'int' } } | |
349 | ||
350 | ## | |
54383726 | 351 | # @GuestFsFreezeStatus |
e3d4d252 | 352 | # |
6932a69b | 353 | # An enumeration of filesystem freeze states |
e3d4d252 | 354 | # |
54383726 MR |
355 | # @thawed: filesystems thawed/unfrozen |
356 | # | |
357 | # @frozen: all non-network guest filesystems frozen | |
358 | # | |
e3d4d252 MR |
359 | # Since: 0.15.0 |
360 | ## | |
361 | { 'enum': 'GuestFsfreezeStatus', | |
9e8aded4 | 362 | 'data': [ 'thawed', 'frozen' ] } |
54383726 MR |
363 | |
364 | ## | |
365 | # @guest-fsfreeze-status: | |
366 | # | |
367 | # Get guest fsfreeze state. error state indicates | |
368 | # | |
369 | # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below) | |
370 | # | |
9e8aded4 | 371 | # Note: This may fail to properly report the current state as a result of |
f789aa7b | 372 | # some other guest processes having issued an fs freeze/thaw. |
9e8aded4 | 373 | # |
54383726 MR |
374 | # Since: 0.15.0 |
375 | ## | |
e3d4d252 MR |
376 | { 'command': 'guest-fsfreeze-status', |
377 | 'returns': 'GuestFsfreezeStatus' } | |
378 | ||
379 | ## | |
380 | # @guest-fsfreeze-freeze: | |
381 | # | |
9e8aded4 | 382 | # Sync and freeze all freezable, local guest filesystems |
e3d4d252 | 383 | # |
9e8aded4 MR |
384 | # Returns: Number of file systems currently frozen. On error, all filesystems |
385 | # will be thawed. | |
e3d4d252 MR |
386 | # |
387 | # Since: 0.15.0 | |
388 | ## | |
389 | { 'command': 'guest-fsfreeze-freeze', | |
390 | 'returns': 'int' } | |
391 | ||
e99bce20 TS |
392 | ## |
393 | # @guest-fsfreeze-freeze-list: | |
394 | # | |
395 | # Sync and freeze specified guest filesystems | |
396 | # | |
397 | # @mountpoints: #optional an array of mountpoints of filesystems to be frozen. | |
398 | # If omitted, every mounted filesystem is frozen. | |
399 | # | |
400 | # Returns: Number of file systems currently frozen. On error, all filesystems | |
401 | # will be thawed. | |
402 | # | |
403 | # Since: 2.2 | |
404 | ## | |
405 | { 'command': 'guest-fsfreeze-freeze-list', | |
406 | 'data': { '*mountpoints': ['str'] }, | |
407 | 'returns': 'int' } | |
408 | ||
e3d4d252 MR |
409 | ## |
410 | # @guest-fsfreeze-thaw: | |
411 | # | |
9e8aded4 MR |
412 | # Unfreeze all frozen guest filesystems |
413 | # | |
414 | # Returns: Number of file systems thawed by this call | |
e3d4d252 | 415 | # |
9e8aded4 MR |
416 | # Note: if return value does not match the previous call to |
417 | # guest-fsfreeze-freeze, this likely means some freezable | |
418 | # filesystems were unfrozen before this call, and that the | |
419 | # filesystem state may have changed before issuing this | |
420 | # command. | |
e3d4d252 MR |
421 | # |
422 | # Since: 0.15.0 | |
423 | ## | |
424 | { 'command': 'guest-fsfreeze-thaw', | |
425 | 'returns': 'int' } | |
11d0f125 | 426 | |
eab5fd59 PB |
427 | ## |
428 | # @guest-fstrim: | |
429 | # | |
430 | # Discard (or "trim") blocks which are not in use by the filesystem. | |
431 | # | |
432 | # @minimum: | |
433 | # Minimum contiguous free range to discard, in bytes. Free ranges | |
434 | # smaller than this may be ignored (this is a hint and the guest | |
435 | # may not respect it). By increasing this value, the fstrim | |
436 | # operation will complete more quickly for filesystems with badly | |
437 | # fragmented free space, although not all blocks will be discarded. | |
438 | # The default value is zero, meaning "discard every free block". | |
439 | # | |
440 | # Returns: Nothing. | |
441 | # | |
442 | # Since: 1.2 | |
443 | ## | |
444 | { 'command': 'guest-fstrim', | |
445 | 'data': { '*minimum': 'int' } } | |
446 | ||
11d0f125 LC |
447 | ## |
448 | # @guest-suspend-disk | |
449 | # | |
450 | # Suspend guest to disk. | |
451 | # | |
452 | # This command tries to execute the scripts provided by the pm-utils package. | |
453 | # If it's not available, the suspend operation will be performed by manually | |
454 | # writing to a sysfs file. | |
455 | # | |
456 | # For the best results it's strongly recommended to have the pm-utils | |
457 | # package installed in the guest. | |
458 | # | |
c6fcc10a LC |
459 | # This command does NOT return a response on success. There is a high chance |
460 | # the command succeeded if the VM exits with a zero exit status or, when | |
461 | # running with --no-shutdown, by issuing the query-status QMP command to | |
462 | # to confirm the VM status is "shutdown". However, the VM could also exit | |
463 | # (or set its status to "shutdown") due to other reasons. | |
464 | # | |
465 | # The following errors may be returned: | |
11d0f125 LC |
466 | # If suspend to disk is not supported, Unsupported |
467 | # | |
c6fcc10a LC |
468 | # Notes: It's strongly recommended to issue the guest-sync command before |
469 | # sending commands when the guest resumes | |
11d0f125 LC |
470 | # |
471 | # Since: 1.1 | |
472 | ## | |
c6fcc10a | 473 | { 'command': 'guest-suspend-disk', 'success-response': 'no' } |
fbf42210 LC |
474 | |
475 | ## | |
476 | # @guest-suspend-ram | |
477 | # | |
478 | # Suspend guest to ram. | |
479 | # | |
480 | # This command tries to execute the scripts provided by the pm-utils package. | |
481 | # If it's not available, the suspend operation will be performed by manually | |
482 | # writing to a sysfs file. | |
483 | # | |
484 | # For the best results it's strongly recommended to have the pm-utils | |
485 | # package installed in the guest. | |
486 | # | |
487 | # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup' | |
488 | # command. Thus, it's *required* to query QEMU for the presence of the | |
489 | # 'system_wakeup' command before issuing guest-suspend-ram. | |
490 | # | |
432d29db LC |
491 | # This command does NOT return a response on success. There are two options |
492 | # to check for success: | |
493 | # 1. Wait for the SUSPEND QMP event from QEMU | |
494 | # 2. Issue the query-status QMP command to confirm the VM status is | |
495 | # "suspended" | |
496 | # | |
497 | # The following errors may be returned: | |
fbf42210 LC |
498 | # If suspend to ram is not supported, Unsupported |
499 | # | |
432d29db LC |
500 | # Notes: It's strongly recommended to issue the guest-sync command before |
501 | # sending commands when the guest resumes | |
fbf42210 LC |
502 | # |
503 | # Since: 1.1 | |
504 | ## | |
432d29db | 505 | { 'command': 'guest-suspend-ram', 'success-response': 'no' } |
95f4f404 LC |
506 | |
507 | ## | |
508 | # @guest-suspend-hybrid | |
509 | # | |
510 | # Save guest state to disk and suspend to ram. | |
511 | # | |
512 | # This command requires the pm-utils package to be installed in the guest. | |
513 | # | |
514 | # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup' | |
515 | # command. Thus, it's *required* to query QEMU for the presence of the | |
516 | # 'system_wakeup' command before issuing guest-suspend-hybrid. | |
517 | # | |
d9fcd2a1 LC |
518 | # This command does NOT return a response on success. There are two options |
519 | # to check for success: | |
520 | # 1. Wait for the SUSPEND QMP event from QEMU | |
521 | # 2. Issue the query-status QMP command to confirm the VM status is | |
522 | # "suspended" | |
523 | # | |
524 | # The following errors may be returned: | |
95f4f404 LC |
525 | # If hybrid suspend is not supported, Unsupported |
526 | # | |
d9fcd2a1 LC |
527 | # Notes: It's strongly recommended to issue the guest-sync command before |
528 | # sending commands when the guest resumes | |
95f4f404 LC |
529 | # |
530 | # Since: 1.1 | |
531 | ## | |
d9fcd2a1 | 532 | { 'command': 'guest-suspend-hybrid', 'success-response': 'no' } |
3424fc9f MP |
533 | |
534 | ## | |
535 | # @GuestIpAddressType: | |
536 | # | |
537 | # An enumeration of supported IP address types | |
538 | # | |
539 | # @ipv4: IP version 4 | |
540 | # | |
541 | # @ipv6: IP version 6 | |
542 | # | |
543 | # Since: 1.1 | |
544 | ## | |
545 | { 'enum': 'GuestIpAddressType', | |
546 | 'data': [ 'ipv4', 'ipv6' ] } | |
547 | ||
548 | ## | |
549 | # @GuestIpAddress: | |
550 | # | |
551 | # @ip-address: IP address | |
552 | # | |
553 | # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6) | |
554 | # | |
555 | # @prefix: Network prefix length of @ip-address | |
556 | # | |
557 | # Since: 1.1 | |
558 | ## | |
559 | { 'type': 'GuestIpAddress', | |
560 | 'data': {'ip-address': 'str', | |
561 | 'ip-address-type': 'GuestIpAddressType', | |
562 | 'prefix': 'int'} } | |
563 | ||
564 | ## | |
565 | # @GuestNetworkInterface: | |
566 | # | |
567 | # @name: The name of interface for which info are being delivered | |
568 | # | |
569 | # @hardware-address: Hardware address of @name | |
570 | # | |
571 | # @ip-addresses: List of addresses assigned to @name | |
572 | # | |
573 | # Since: 1.1 | |
574 | ## | |
575 | { 'type': 'GuestNetworkInterface', | |
576 | 'data': {'name': 'str', | |
577 | '*hardware-address': 'str', | |
578 | '*ip-addresses': ['GuestIpAddress'] } } | |
579 | ||
580 | ## | |
581 | # @guest-network-get-interfaces: | |
582 | # | |
583 | # Get list of guest IP addresses, MAC addresses | |
584 | # and netmasks. | |
585 | # | |
586 | # Returns: List of GuestNetworkInfo on success. | |
587 | # | |
588 | # Since: 1.1 | |
589 | ## | |
590 | { 'command': 'guest-network-get-interfaces', | |
591 | 'returns': ['GuestNetworkInterface'] } | |
70e133a7 LE |
592 | |
593 | ## | |
594 | # @GuestLogicalProcessor: | |
595 | # | |
596 | # @logical-id: Arbitrary guest-specific unique identifier of the VCPU. | |
597 | # | |
598 | # @online: Whether the VCPU is enabled. | |
599 | # | |
c964c9e0 LE |
600 | # @can-offline: #optional Whether offlining the VCPU is possible. This member |
601 | # is always filled in by the guest agent when the structure is | |
602 | # returned, and always ignored on input (hence it can be omitted | |
603 | # then). | |
70e133a7 LE |
604 | # |
605 | # Since: 1.5 | |
606 | ## | |
607 | { 'type': 'GuestLogicalProcessor', | |
608 | 'data': {'logical-id': 'int', | |
609 | 'online': 'bool', | |
610 | '*can-offline': 'bool'} } | |
611 | ||
612 | ## | |
613 | # @guest-get-vcpus: | |
614 | # | |
615 | # Retrieve the list of the guest's logical processors. | |
616 | # | |
617 | # This is a read-only operation. | |
618 | # | |
619 | # Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the | |
620 | # list exactly once, but their order is unspecified. | |
621 | # | |
622 | # Since: 1.5 | |
623 | ## | |
624 | { 'command': 'guest-get-vcpus', | |
625 | 'returns': ['GuestLogicalProcessor'] } | |
626 | ||
627 | ## | |
628 | # @guest-set-vcpus: | |
629 | # | |
630 | # Attempt to reconfigure (currently: enable/disable) logical processors inside | |
631 | # the guest. | |
632 | # | |
633 | # The input list is processed node by node in order. In each node @logical-id | |
634 | # is used to look up the guest VCPU, for which @online specifies the requested | |
635 | # state. The set of distinct @logical-id's is only required to be a subset of | |
636 | # the guest-supported identifiers. There's no restriction on list length or on | |
637 | # repeating the same @logical-id (with possibly different @online field). | |
638 | # Preferably the input list should describe a modified subset of | |
639 | # @guest-get-vcpus' return value. | |
640 | # | |
641 | # Returns: The length of the initial sublist that has been successfully | |
642 | # processed. The guest agent maximizes this value. Possible cases: | |
643 | # | |
644 | # 0: if the @vcpus list was empty on input. Guest state | |
645 | # has not been changed. Otherwise, | |
646 | # | |
647 | # Error: processing the first node of @vcpus failed for the | |
648 | # reason returned. Guest state has not been changed. | |
649 | # Otherwise, | |
650 | # | |
651 | # < length(@vcpus): more than zero initial nodes have been processed, | |
652 | # but not the entire @vcpus list. Guest state has | |
653 | # changed accordingly. To retrieve the error | |
654 | # (assuming it persists), repeat the call with the | |
655 | # successfully processed initial sublist removed. | |
656 | # Otherwise, | |
657 | # | |
658 | # length(@vcpus): call successful. | |
659 | # | |
660 | # Since: 1.5 | |
661 | ## | |
662 | { 'command': 'guest-set-vcpus', | |
663 | 'data': {'vcpus': ['GuestLogicalProcessor'] }, | |
664 | 'returns': 'int' } | |
46d4c572 TS |
665 | |
666 | ## | |
667 | # @GuestDiskBusType | |
668 | # | |
669 | # An enumeration of bus type of disks | |
670 | # | |
671 | # @ide: IDE disks | |
672 | # @fdc: floppy disks | |
673 | # @scsi: SCSI disks | |
674 | # @virtio: virtio disks | |
675 | # @xen: Xen disks | |
676 | # @usb: USB disks | |
677 | # @uml: UML disks | |
678 | # @sata: SATA disks | |
679 | # @sd: SD cards | |
680 | # | |
681 | # Since: 2.2 | |
682 | ## | |
683 | { 'enum': 'GuestDiskBusType', | |
684 | 'data': [ 'ide', 'fdc', 'scsi', 'virtio', 'xen', 'usb', 'uml', 'sata', | |
685 | 'sd' ] } | |
686 | ||
687 | ## | |
688 | # @GuestPCIAddress: | |
689 | # | |
690 | # @domain: domain id | |
691 | # @bus: bus id | |
692 | # @slot: slot id | |
693 | # @function: function id | |
694 | # | |
695 | # Since: 2.2 | |
696 | ## | |
697 | { 'type': 'GuestPCIAddress', | |
698 | 'data': {'domain': 'int', 'bus': 'int', | |
699 | 'slot': 'int', 'function': 'int'} } | |
700 | ||
701 | ## | |
702 | # @GuestDiskAddress: | |
703 | # | |
704 | # @pci-controller: controller's PCI address | |
705 | # @type: bus type | |
706 | # @bus: bus id | |
707 | # @target: target id | |
708 | # @unit: unit id | |
709 | # | |
710 | # Since: 2.2 | |
711 | ## | |
712 | { 'type': 'GuestDiskAddress', | |
713 | 'data': {'pci-controller': 'GuestPCIAddress', | |
714 | 'bus-type': 'GuestDiskBusType', | |
715 | 'bus': 'int', 'target': 'int', 'unit': 'int'} } | |
716 | ||
717 | ## | |
718 | # @GuestFilesystemInfo | |
719 | # | |
720 | # @name: disk name | |
721 | # @mountpoint: mount point path | |
722 | # @type: file system type string | |
723 | # @disk: an array of disk hardware information that the volume lies on, | |
724 | # which may be empty if the disk type is not supported | |
725 | # | |
726 | # Since: 2.2 | |
727 | ## | |
728 | { 'type': 'GuestFilesystemInfo', | |
729 | 'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str', | |
730 | 'disk': ['GuestDiskAddress']} } | |
731 | ||
732 | ## | |
733 | # @guest-get-fsinfo: | |
734 | # | |
735 | # Returns: The list of filesystems information mounted in the guest. | |
736 | # The returned mountpoints may be specified to | |
737 | # @guest-fsfreeze-freeze-list. | |
738 | # Network filesystems (such as CIFS and NFS) are not listed. | |
739 | # | |
740 | # Since: 2.2 | |
741 | ## | |
742 | { 'command': 'guest-get-fsinfo', | |
743 | 'returns': ['GuestFilesystemInfo'] } | |
215a2771 DB |
744 | |
745 | ## | |
746 | # @guest-set-user-password | |
747 | # | |
748 | # @username: the user account whose password to change | |
749 | # @password: the new password entry string, base64 encoded | |
750 | # @crypted: true if password is already crypt()d, false if raw | |
751 | # | |
752 | # If the @crypted flag is true, it is the caller's responsibility | |
753 | # to ensure the correct crypt() encryption scheme is used. This | |
754 | # command does not attempt to interpret or report on the encryption | |
755 | # scheme. Refer to the documentation of the guest operating system | |
756 | # in question to determine what is supported. | |
757 | # | |
758 | # Note all guest operating systems will support use of the | |
759 | # @crypted flag, as they may require the clear-text password | |
760 | # | |
761 | # The @password parameter must always be base64 encoded before | |
762 | # transmission, even if already crypt()d, to ensure it is 8-bit | |
763 | # safe when passed as JSON. | |
764 | # | |
765 | # Returns: Nothing on success. | |
766 | # | |
767 | # Since 2.3 | |
768 | ## | |
769 | { 'command': 'guest-set-user-password', | |
770 | 'data': { 'username': 'str', 'password': 'str', 'crypted': 'bool' } } | |
a065aaa9 HZ |
771 | |
772 | # @GuestMemoryBlock: | |
773 | # | |
774 | # @phys-index: Arbitrary guest-specific unique identifier of the MEMORY BLOCK. | |
775 | # | |
776 | # @online: Whether the MEMORY BLOCK is enabled in guest. | |
777 | # | |
778 | # @can-offline: #optional Whether offlining the MEMORY BLOCK is possible. | |
779 | # This member is always filled in by the guest agent when the | |
780 | # structure is returned, and always ignored on input (hence it | |
781 | # can be omitted then). | |
782 | # | |
783 | # Since: 2.3 | |
784 | ## | |
785 | { 'type': 'GuestMemoryBlock', | |
786 | 'data': {'phys-index': 'uint64', | |
787 | 'online': 'bool', | |
788 | '*can-offline': 'bool'} } | |
789 | ||
790 | ## | |
791 | # @guest-get-memory-blocks: | |
792 | # | |
793 | # Retrieve the list of the guest's memory blocks. | |
794 | # | |
795 | # This is a read-only operation. | |
796 | # | |
797 | # Returns: The list of all memory blocks the guest knows about. | |
798 | # Each memory block is put on the list exactly once, but their order | |
799 | # is unspecified. | |
800 | # | |
801 | # Since: 2.3 | |
802 | ## | |
803 | { 'command': 'guest-get-memory-blocks', | |
804 | 'returns': ['GuestMemoryBlock'] } | |
805 | ||
806 | ## | |
807 | # @GuestMemoryBlockResponseType | |
808 | # | |
809 | # An enumeration of memory block operation result. | |
810 | # | |
631b22ea | 811 | # @success: the operation of online/offline memory block is successful. |
a065aaa9 HZ |
812 | # @not-found: can't find the corresponding memoryXXX directory in sysfs. |
813 | # @operation-not-supported: for some old kernels, it does not support | |
814 | # online or offline memory block. | |
815 | # @operation-failed: the operation of online/offline memory block fails, | |
816 | # because of some errors happen. | |
817 | # | |
818 | # Since: 2.3 | |
819 | ## | |
820 | { 'enum': 'GuestMemoryBlockResponseType', | |
821 | 'data': ['success', 'not-found', 'operation-not-supported', | |
822 | 'operation-failed'] } | |
823 | ||
824 | ## | |
825 | # @GuestMemoryBlockResponse: | |
826 | # | |
827 | # @phys-index: same with the 'phys-index' member of @GuestMemoryBlock. | |
828 | # | |
829 | # @response: the result of memory block operation. | |
830 | # | |
831 | # @error-code: #optional the error number. | |
832 | # When memory block operation fails, we assign the value of | |
833 | # 'errno' to this member, it indicates what goes wrong. | |
834 | # When the operation succeeds, it will be omitted. | |
835 | # | |
836 | # Since: 2.3 | |
837 | ## | |
838 | { 'type': 'GuestMemoryBlockResponse', | |
839 | 'data': { 'phys-index': 'uint64', | |
840 | 'response': 'GuestMemoryBlockResponseType', | |
841 | '*error-code': 'int' }} | |
842 | ||
843 | ## | |
844 | # @guest-set-memory-blocks: | |
845 | # | |
846 | # Attempt to reconfigure (currently: enable/disable) state of memory blocks | |
847 | # inside the guest. | |
848 | # | |
849 | # The input list is processed node by node in order. In each node @phys-index | |
850 | # is used to look up the guest MEMORY BLOCK, for which @online specifies the | |
851 | # requested state. The set of distinct @phys-index's is only required to be a | |
852 | # subset of the guest-supported identifiers. There's no restriction on list | |
853 | # length or on repeating the same @phys-index (with possibly different @online | |
854 | # field). | |
855 | # Preferably the input list should describe a modified subset of | |
856 | # @guest-get-memory-blocks' return value. | |
857 | # | |
858 | # Returns: The operation results, it is a list of @GuestMemoryBlockResponse, | |
859 | # which is corresponding to the input list. | |
860 | # | |
861 | # Note: it will return NULL if the @mem-blks list was empty on input, | |
862 | # or there is an error, and in this case, guest state will not be | |
863 | # changed. | |
864 | # | |
865 | # Since: 2.3 | |
866 | ## | |
867 | { 'command': 'guest-set-memory-blocks', | |
868 | 'data': {'mem-blks': ['GuestMemoryBlock'] }, | |
869 | 'returns': ['GuestMemoryBlockResponse'] } | |
870 | ||
871 | # @GuestMemoryBlockInfo: | |
872 | # | |
873 | # @size: the size (in bytes) of the guest memory blocks, | |
874 | # which are the minimal units of memory block online/offline | |
875 | # operations (also called Logical Memory Hotplug). | |
876 | # | |
877 | # Since: 2.3 | |
878 | ## | |
879 | { 'type': 'GuestMemoryBlockInfo', | |
880 | 'data': {'size': 'uint64'} } | |
881 | ||
882 | ## | |
883 | # @guest-get-memory-block-info: | |
884 | # | |
885 | # Get information relating to guest memory blocks. | |
886 | # | |
887 | # Returns: memory block size in bytes. | |
888 | # Returns: @GuestMemoryBlockInfo | |
889 | # | |
890 | # Since 2.3 | |
891 | ## | |
892 | { 'command': 'guest-get-memory-block-info', | |
893 | 'returns': 'GuestMemoryBlockInfo' } |