1 # *-*- Mode: Python -*-*
5 # Echo back a unique integer value, and prepend to response a
6 # leading sentinel byte (0xFF) the client can check scan for.
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).
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
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.
28 # @id: randomly generated 64-bit integer
30 # Returns: The unique integer id passed in by the client
34 { 'command': 'guest-sync-delimited',
35 'data': { 'id': 'int' },
41 # Echo back a unique integer value
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
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.
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.
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.
66 # @id: randomly generated 64-bit integer
68 # Returns: The unique integer id passed in by the client
72 { 'command': 'guest-sync',
73 'data': { 'id': 'int' },
79 # Ping the guest agent, a non-error return implies success
83 { 'command': 'guest-ping' }
88 # Get the information about guest time relative to the Epoch
89 # of 1970-01-01 in UTC.
91 # Returns: Time in nanoseconds.
95 { 'command': 'guest-get-time',
99 # @GuestAgentCommandInfo:
101 # Information about guest agent commands.
103 # @name: name of the command
105 # @enabled: whether command is currently enabled by guest admin
109 { 'type': 'GuestAgentCommandInfo',
110 'data': { 'name': 'str', 'enabled': 'bool' } }
115 # Information about guest agent.
117 # @version: guest agent version
119 # @supported_commands: Information about guest agent commands
123 { 'type': 'GuestAgentInfo',
124 'data': { 'version': 'str',
125 'supported_commands': ['GuestAgentCommandInfo'] } }
129 # Get some information about the guest agent.
131 # Returns: @GuestAgentInfo
135 { 'command': 'guest-info',
136 'returns': 'GuestAgentInfo' }
141 # Initiate guest-activated shutdown. Note: this is an asynchronous
142 # shutdown request, with no guarantee of successful shutdown.
144 # @mode: #optional "halt", "powerdown" (default), or "reboot"
146 # This command does NOT return a response on success. Success condition
147 # is indicated by the VM exiting with a zero exit status or, when
148 # running with --no-shutdown, by issuing the query-status QMP command
149 # to confirm the VM status is "shutdown".
153 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
154 'success-response': 'no' }
159 # Open a file in the guest and retrieve a file handle for it
161 # @filepath: Full path to the file in the guest to open.
163 # @mode: #optional open mode, as per fopen(), "r" is the default.
165 # Returns: Guest file handle on success.
169 { 'command': 'guest-file-open',
170 'data': { 'path': 'str', '*mode': 'str' },
176 # Close an open file in the guest
178 # @handle: filehandle returned by guest-file-open
180 # Returns: Nothing on success.
184 { 'command': 'guest-file-close',
185 'data': { 'handle': 'int' } }
190 # Result of guest agent file-read operation
192 # @count: number of bytes read (note: count is *before*
193 # base64-encoding is applied)
195 # @buf-b64: base64-encoded bytes read
197 # @eof: whether EOF was encountered during read operation.
201 { 'type': 'GuestFileRead',
202 'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
207 # Read from an open file in the guest. Data will be base64-encoded
209 # @handle: filehandle returned by guest-file-open
211 # @count: #optional maximum number of bytes to read (default is 4KB)
213 # Returns: @GuestFileRead on success.
217 { 'command': 'guest-file-read',
218 'data': { 'handle': 'int', '*count': 'int' },
219 'returns': 'GuestFileRead' }
224 # Result of guest agent file-write operation
226 # @count: number of bytes written (note: count is actual bytes
227 # written, after base64-decoding of provided buffer)
229 # @eof: whether EOF was encountered during write operation.
233 { 'type': 'GuestFileWrite',
234 'data': { 'count': 'int', 'eof': 'bool' } }
239 # Write to an open file in the guest.
241 # @handle: filehandle returned by guest-file-open
243 # @buf-b64: base64-encoded string representing data to be written
245 # @count: #optional bytes to write (actual bytes, after base64-decode),
246 # default is all content in buf-b64 buffer after base64 decoding
248 # Returns: @GuestFileWrite on success.
252 { 'command': 'guest-file-write',
253 'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
254 'returns': 'GuestFileWrite' }
260 # Result of guest agent file-seek operation
262 # @position: current file position
264 # @eof: whether EOF was encountered during file seek
268 { 'type': 'GuestFileSeek',
269 'data': { 'position': 'int', 'eof': 'bool' } }
274 # Seek to a position in the file, as with fseek(), and return the
275 # current file position afterward. Also encapsulates ftell()'s
276 # functionality, just Set offset=0, whence=SEEK_CUR.
278 # @handle: filehandle returned by guest-file-open
280 # @offset: bytes to skip over in the file stream
282 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
284 # Returns: @GuestFileSeek on success.
288 { 'command': 'guest-file-seek',
289 'data': { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
290 'returns': 'GuestFileSeek' }
295 # Write file changes bufferred in userspace to disk/kernel buffers
297 # @handle: filehandle returned by guest-file-open
299 # Returns: Nothing on success.
303 { 'command': 'guest-file-flush',
304 'data': { 'handle': 'int' } }
307 # @GuestFsFreezeStatus
309 # An enumeration of filesystem freeze states
311 # @thawed: filesystems thawed/unfrozen
313 # @frozen: all non-network guest filesystems frozen
317 { 'enum': 'GuestFsfreezeStatus',
318 'data': [ 'thawed', 'frozen' ] }
321 # @guest-fsfreeze-status:
323 # Get guest fsfreeze state. error state indicates
325 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
327 # Note: This may fail to properly report the current state as a result of
328 # some other guest processes having issued an fs freeze/thaw.
332 { 'command': 'guest-fsfreeze-status',
333 'returns': 'GuestFsfreezeStatus' }
336 # @guest-fsfreeze-freeze:
338 # Sync and freeze all freezable, local guest filesystems
340 # Returns: Number of file systems currently frozen. On error, all filesystems
345 { 'command': 'guest-fsfreeze-freeze',
349 # @guest-fsfreeze-thaw:
351 # Unfreeze all frozen guest filesystems
353 # Returns: Number of file systems thawed by this call
355 # Note: if return value does not match the previous call to
356 # guest-fsfreeze-freeze, this likely means some freezable
357 # filesystems were unfrozen before this call, and that the
358 # filesystem state may have changed before issuing this
363 { 'command': 'guest-fsfreeze-thaw',
369 # Discard (or "trim") blocks which are not in use by the filesystem.
372 # Minimum contiguous free range to discard, in bytes. Free ranges
373 # smaller than this may be ignored (this is a hint and the guest
374 # may not respect it). By increasing this value, the fstrim
375 # operation will complete more quickly for filesystems with badly
376 # fragmented free space, although not all blocks will be discarded.
377 # The default value is zero, meaning "discard every free block".
383 { 'command': 'guest-fstrim',
384 'data': { '*minimum': 'int' } }
387 # @guest-suspend-disk
389 # Suspend guest to disk.
391 # This command tries to execute the scripts provided by the pm-utils package.
392 # If it's not available, the suspend operation will be performed by manually
393 # writing to a sysfs file.
395 # For the best results it's strongly recommended to have the pm-utils
396 # package installed in the guest.
398 # This command does NOT return a response on success. There is a high chance
399 # the command succeeded if the VM exits with a zero exit status or, when
400 # running with --no-shutdown, by issuing the query-status QMP command to
401 # to confirm the VM status is "shutdown". However, the VM could also exit
402 # (or set its status to "shutdown") due to other reasons.
404 # The following errors may be returned:
405 # If suspend to disk is not supported, Unsupported
407 # Notes: It's strongly recommended to issue the guest-sync command before
408 # sending commands when the guest resumes
412 { 'command': 'guest-suspend-disk', 'success-response': 'no' }
417 # Suspend guest to ram.
419 # This command tries to execute the scripts provided by the pm-utils package.
420 # If it's not available, the suspend operation will be performed by manually
421 # writing to a sysfs file.
423 # For the best results it's strongly recommended to have the pm-utils
424 # package installed in the guest.
426 # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
427 # command. Thus, it's *required* to query QEMU for the presence of the
428 # 'system_wakeup' command before issuing guest-suspend-ram.
430 # This command does NOT return a response on success. There are two options
431 # to check for success:
432 # 1. Wait for the SUSPEND QMP event from QEMU
433 # 2. Issue the query-status QMP command to confirm the VM status is
436 # The following errors may be returned:
437 # If suspend to ram is not supported, Unsupported
439 # Notes: It's strongly recommended to issue the guest-sync command before
440 # sending commands when the guest resumes
444 { 'command': 'guest-suspend-ram', 'success-response': 'no' }
447 # @guest-suspend-hybrid
449 # Save guest state to disk and suspend to ram.
451 # This command requires the pm-utils package to be installed in the guest.
453 # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
454 # command. Thus, it's *required* to query QEMU for the presence of the
455 # 'system_wakeup' command before issuing guest-suspend-hybrid.
457 # This command does NOT return a response on success. There are two options
458 # to check for success:
459 # 1. Wait for the SUSPEND QMP event from QEMU
460 # 2. Issue the query-status QMP command to confirm the VM status is
463 # The following errors may be returned:
464 # If hybrid suspend is not supported, Unsupported
466 # Notes: It's strongly recommended to issue the guest-sync command before
467 # sending commands when the guest resumes
471 { 'command': 'guest-suspend-hybrid', 'success-response': 'no' }
474 # @GuestIpAddressType:
476 # An enumeration of supported IP address types
478 # @ipv4: IP version 4
480 # @ipv6: IP version 6
484 { 'enum': 'GuestIpAddressType',
485 'data': [ 'ipv4', 'ipv6' ] }
490 # @ip-address: IP address
492 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
494 # @prefix: Network prefix length of @ip-address
498 { 'type': 'GuestIpAddress',
499 'data': {'ip-address': 'str',
500 'ip-address-type': 'GuestIpAddressType',
504 # @GuestNetworkInterface:
506 # @name: The name of interface for which info are being delivered
508 # @hardware-address: Hardware address of @name
510 # @ip-addresses: List of addresses assigned to @name
514 { 'type': 'GuestNetworkInterface',
515 'data': {'name': 'str',
516 '*hardware-address': 'str',
517 '*ip-addresses': ['GuestIpAddress'] } }
520 # @guest-network-get-interfaces:
522 # Get list of guest IP addresses, MAC addresses
525 # Returns: List of GuestNetworkInfo on success.
529 { 'command': 'guest-network-get-interfaces',
530 'returns': ['GuestNetworkInterface'] }