Merge remote-tracking branch 'remotes/bonzini-gitlab/tags/for-upstream' into staging
[qemu.git] / qapi-schema-guest.json
1 # *-*- Mode: Python -*-*
2
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
21 # sentinel value is receiving to avoid unnecessary processing of
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
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 #
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 #
62 # Such clients should also precede this command
63 # with a 0xFF byte to make sure the guest agent flushes any
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 ##
86 # @GuestAgentCommandInfo:
87 #
88 # Information about guest agent commands.
89 #
90 # @name: name of the command
91 #
92 # @enabled: whether command is currently enabled by guest admin
93 #
94 # Since 1.1.0
95 ##
96 { 'type': 'GuestAgentCommandInfo',
97   'data': { 'name': 'str', 'enabled': 'bool' } }
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 ##
110 { 'type': 'GuestAgentInfo',
111   'data': { 'version': 'str',
112             'supported_commands': ['GuestAgentCommandInfo'] } }
113 ##
114 # @guest-info:
115 #
116 # Get some information about the guest agent.
117 #
118 # Returns: @GuestAgentInfo
119 #
120 # Since: 0.15.0
121 ##
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 guarantee of successful shutdown.
130 #
131 # @mode: #optional "halt", "powerdown" (default), or "reboot"
132 #
133 # This command does NOT return a response on success. Success condition
134 # is indicated by the VM exiting with a zero exit status or, when
135 # running with --no-shutdown, by issuing the query-status QMP command
136 # to confirm the VM status is "shutdown".
137 #
138 # Since: 0.15.0
139 ##
140 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
141   'success-response': 'no' }
142
143 ##
144 # @guest-file-open:
145 #
146 # Open a file in the guest and retrieve a file handle for it
147 #
148 # @filepath: Full path to the file in the guest to open.
149 #
150 # @mode: #optional open mode, as per fopen(), "r" is the default.
151 #
152 # Returns: Guest file handle on success.
153 #
154 # Since: 0.15.0
155 ##
156 { 'command': 'guest-file-open',
157   'data':    { 'path': 'str', '*mode': 'str' },
158   'returns': 'int' }
159
160 ##
161 # @guest-file-close:
162 #
163 # Close an open file in the guest
164 #
165 # @handle: filehandle returned by guest-file-open
166 #
167 # Returns: Nothing on success.
168 #
169 # Since: 0.15.0
170 ##
171 { 'command': 'guest-file-close',
172   'data': { 'handle': 'int' } }
173
174 ##
175 # @GuestFileRead
176 #
177 # Result of guest agent file-read operation
178 #
179 # @count: number of bytes read (note: count is *before*
180 #         base64-encoding is applied)
181 #
182 # @buf-b64: base64-encoded bytes read
183 #
184 # @eof: whether EOF was encountered during read operation.
185 #
186 # Since: 0.15.0
187 ##
188 { 'type': 'GuestFileRead',
189   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
190
191 ##
192 # @guest-file-read:
193 #
194 # Read from an open file in the guest. Data will be base64-encoded
195 #
196 # @handle: filehandle returned by guest-file-open
197 #
198 # @count: #optional maximum number of bytes to read (default is 4KB)
199 #
200 # Returns: @GuestFileRead on success.
201 #
202 # Since: 0.15.0
203 ##
204 { 'command': 'guest-file-read',
205   'data':    { 'handle': 'int', '*count': 'int' },
206   'returns': 'GuestFileRead' }
207
208 ##
209 # @GuestFileWrite
210 #
211 # Result of guest agent file-write operation
212 #
213 # @count: number of bytes written (note: count is actual bytes
214 #         written, after base64-decoding of provided buffer)
215 #
216 # @eof: whether EOF was encountered during write operation.
217 #
218 # Since: 0.15.0
219 ##
220 { 'type': 'GuestFileWrite',
221   'data': { 'count': 'int', 'eof': 'bool' } }
222
223 ##
224 # @guest-file-write:
225 #
226 # Write to an open file in the guest.
227 #
228 # @handle: filehandle returned by guest-file-open
229 #
230 # @buf-b64: base64-encoded string representing data to be written
231 #
232 # @count: #optional bytes to write (actual bytes, after base64-decode),
233 #         default is all content in buf-b64 buffer after base64 decoding
234 #
235 # Returns: @GuestFileWrite on success.
236 #
237 # Since: 0.15.0
238 ##
239 { 'command': 'guest-file-write',
240   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
241   'returns': 'GuestFileWrite' }
242
243
244 ##
245 # @GuestFileSeek
246 #
247 # Result of guest agent file-seek operation
248 #
249 # @position: current file position
250 #
251 # @eof: whether EOF was encountered during file seek
252 #
253 # Since: 0.15.0
254 ##
255 { 'type': 'GuestFileSeek',
256   'data': { 'position': 'int', 'eof': 'bool' } }
257
258 ##
259 # @guest-file-seek:
260 #
261 # Seek to a position in the file, as with fseek(), and return the
262 # current file position afterward. Also encapsulates ftell()'s
263 # functionality, just Set offset=0, whence=SEEK_CUR.
264 #
265 # @handle: filehandle returned by guest-file-open
266 #
267 # @offset: bytes to skip over in the file stream
268 #
269 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
270 #
271 # Returns: @GuestFileSeek on success.
272 #
273 # Since: 0.15.0
274 ##
275 { 'command': 'guest-file-seek',
276   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
277   'returns': 'GuestFileSeek' }
278
279 ##
280 # @guest-file-flush:
281 #
282 # Write file changes bufferred in userspace to disk/kernel buffers
283 #
284 # @handle: filehandle returned by guest-file-open
285 #
286 # Returns: Nothing on success.
287 #
288 # Since: 0.15.0
289 ##
290 { 'command': 'guest-file-flush',
291   'data': { 'handle': 'int' } }
292
293 ##
294 # @GuestFsFreezeStatus
295 #
296 # An enumeration of filesystem freeze states
297 #
298 # @thawed: filesystems thawed/unfrozen
299 #
300 # @frozen: all non-network guest filesystems frozen
301 #
302 # Since: 0.15.0
303 ##
304 { 'enum': 'GuestFsfreezeStatus',
305   'data': [ 'thawed', 'frozen' ] }
306
307 ##
308 # @guest-fsfreeze-status:
309 #
310 # Get guest fsfreeze state. error state indicates
311 #
312 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
313 #
314 # Note: This may fail to properly report the current state as a result of
315 # some other guest processes having issued an fs freeze/thaw.
316 #
317 # Since: 0.15.0
318 ##
319 { 'command': 'guest-fsfreeze-status',
320   'returns': 'GuestFsfreezeStatus' }
321
322 ##
323 # @guest-fsfreeze-freeze:
324 #
325 # Sync and freeze all freezable, local guest filesystems
326 #
327 # Returns: Number of file systems currently frozen. On error, all filesystems
328 # will be thawed.
329 #
330 # Since: 0.15.0
331 ##
332 { 'command': 'guest-fsfreeze-freeze',
333   'returns': 'int' }
334
335 ##
336 # @guest-fsfreeze-thaw:
337 #
338 # Unfreeze all frozen guest filesystems
339 #
340 # Returns: Number of file systems thawed by this call
341 #
342 # Note: if return value does not match the previous call to
343 #       guest-fsfreeze-freeze, this likely means some freezable
344 #       filesystems were unfrozen before this call, and that the
345 #       filesystem state may have changed before issuing this
346 #       command.
347 #
348 # Since: 0.15.0
349 ##
350 { 'command': 'guest-fsfreeze-thaw',
351   'returns': 'int' }
352
353 ##
354 # @guest-fstrim:
355 #
356 # Discard (or "trim") blocks which are not in use by the filesystem.
357 #
358 # @minimum:
359 #       Minimum contiguous free range to discard, in bytes. Free ranges
360 #       smaller than this may be ignored (this is a hint and the guest
361 #       may not respect it).  By increasing this value, the fstrim
362 #       operation will complete more quickly for filesystems with badly
363 #       fragmented free space, although not all blocks will be discarded.
364 #       The default value is zero, meaning "discard every free block".
365 #
366 # Returns: Nothing.
367 #
368 # Since: 1.2
369 ##
370 { 'command': 'guest-fstrim',
371   'data': { '*minimum': 'int' } }
372
373 ##
374 # @guest-suspend-disk
375 #
376 # Suspend guest to disk.
377 #
378 # This command tries to execute the scripts provided by the pm-utils package.
379 # If it's not available, the suspend operation will be performed by manually
380 # writing to a sysfs file.
381 #
382 # For the best results it's strongly recommended to have the pm-utils
383 # package installed in the guest.
384 #
385 # This command does NOT return a response on success. There is a high chance
386 # the command succeeded if the VM exits with a zero exit status or, when
387 # running with --no-shutdown, by issuing the query-status QMP command to
388 # to confirm the VM status is "shutdown". However, the VM could also exit
389 # (or set its status to "shutdown") due to other reasons.
390 #
391 # The following errors may be returned:
392 #          If suspend to disk is not supported, Unsupported
393 #
394 # Notes: It's strongly recommended to issue the guest-sync command before
395 #        sending commands when the guest resumes
396 #
397 # Since: 1.1
398 ##
399 { 'command': 'guest-suspend-disk', 'success-response': 'no' }
400
401 ##
402 # @guest-suspend-ram
403 #
404 # Suspend guest to ram.
405 #
406 # This command tries to execute the scripts provided by the pm-utils package.
407 # If it's not available, the suspend operation will be performed by manually
408 # writing to a sysfs file.
409 #
410 # For the best results it's strongly recommended to have the pm-utils
411 # package installed in the guest.
412 #
413 # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
414 # command.  Thus, it's *required* to query QEMU for the presence of the
415 # 'system_wakeup' command before issuing guest-suspend-ram.
416 #
417 # This command does NOT return a response on success. There are two options
418 # to check for success:
419 #   1. Wait for the SUSPEND QMP event from QEMU
420 #   2. Issue the query-status QMP command to confirm the VM status is
421 #      "suspended"
422 #
423 # The following errors may be returned:
424 #          If suspend to ram is not supported, Unsupported
425 #
426 # Notes: It's strongly recommended to issue the guest-sync command before
427 #        sending commands when the guest resumes
428 #
429 # Since: 1.1
430 ##
431 { 'command': 'guest-suspend-ram', 'success-response': 'no' }
432
433 ##
434 # @guest-suspend-hybrid
435 #
436 # Save guest state to disk and suspend to ram.
437 #
438 # This command requires the pm-utils package to be installed in the guest.
439 #
440 # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
441 # command.  Thus, it's *required* to query QEMU for the presence of the
442 # 'system_wakeup' command before issuing guest-suspend-hybrid.
443 #
444 # This command does NOT return a response on success. There are two options
445 # to check for success:
446 #   1. Wait for the SUSPEND QMP event from QEMU
447 #   2. Issue the query-status QMP command to confirm the VM status is
448 #      "suspended"
449 #
450 # The following errors may be returned:
451 #          If hybrid suspend is not supported, Unsupported
452 #
453 # Notes: It's strongly recommended to issue the guest-sync command before
454 #        sending commands when the guest resumes
455 #
456 # Since: 1.1
457 ##
458 { 'command': 'guest-suspend-hybrid', 'success-response': 'no' }
459
460 ##
461 # @GuestIpAddressType:
462 #
463 # An enumeration of supported IP address types
464 #
465 # @ipv4: IP version 4
466 #
467 # @ipv6: IP version 6
468 #
469 # Since: 1.1
470 ##
471 { 'enum': 'GuestIpAddressType',
472   'data': [ 'ipv4', 'ipv6' ] }
473
474 ##
475 # @GuestIpAddress:
476 #
477 # @ip-address: IP address
478 #
479 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
480 #
481 # @prefix: Network prefix length of @ip-address
482 #
483 # Since: 1.1
484 ##
485 { 'type': 'GuestIpAddress',
486   'data': {'ip-address': 'str',
487            'ip-address-type': 'GuestIpAddressType',
488            'prefix': 'int'} }
489
490 ##
491 # @GuestNetworkInterface:
492 #
493 # @name: The name of interface for which info are being delivered
494 #
495 # @hardware-address: Hardware address of @name
496 #
497 # @ip-addresses: List of addresses assigned to @name
498 #
499 # Since: 1.1
500 ##
501 { 'type': 'GuestNetworkInterface',
502   'data': {'name': 'str',
503            '*hardware-address': 'str',
504            '*ip-addresses': ['GuestIpAddress'] } }
505
506 ##
507 # @guest-network-get-interfaces:
508 #
509 # Get list of guest IP addresses, MAC addresses
510 # and netmasks.
511 #
512 # Returns: List of GuestNetworkInfo on success.
513 #
514 # Since: 1.1
515 ##
516 { 'command': 'guest-network-get-interfaces',
517   'returns': ['GuestNetworkInterface'] }