1 # *-*- Mode: Python -*-*
5 # General note concerning the use of guest agent interfaces:
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.
16 # Echo back a unique integer value, and prepend to response a
17 # leading sentinel byte (0xFF) the client can check scan for.
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).
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
32 # sentinel value is receiving to avoid unnecessary processing of
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.
39 # @id: randomly generated 64-bit integer
41 # Returns: The unique integer id passed in by the client
45 { 'command': 'guest-sync-delimited',
46 'data': { 'id': 'int' },
52 # Echo back a unique integer value
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
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.
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.
73 # Such clients should also precede this command
74 # with a 0xFF byte to make sure the guest agent flushes any
75 # partially read JSON data from a previous session.
77 # @id: randomly generated 64-bit integer
79 # Returns: The unique integer id passed in by the client
83 { 'command': 'guest-sync',
84 'data': { 'id': 'int' },
90 # Ping the guest agent, a non-error return implies success
94 { 'command': 'guest-ping' }
99 # Get the information about guest's System Time relative to
100 # the Epoch of 1970-01-01 in UTC.
102 # Returns: Time in nanoseconds.
106 { 'command': 'guest-get-time',
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
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
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
129 # @time: #optional time of nanoseconds, relative to the Epoch
130 # of 1970-01-01 in UTC.
132 # Returns: Nothing on success.
136 { 'command': 'guest-set-time',
137 'data': { '*time': 'int' } }
140 # @GuestAgentCommandInfo:
142 # Information about guest agent commands.
144 # @name: name of the command
146 # @enabled: whether command is currently enabled by guest admin
148 # @success-response: whether command returns a response on success
153 { 'struct': 'GuestAgentCommandInfo',
154 'data': { 'name': 'str', 'enabled': 'bool', 'success-response': 'bool' } }
159 # Information about guest agent.
161 # @version: guest agent version
163 # @supported_commands: Information about guest agent commands
167 { 'struct': 'GuestAgentInfo',
168 'data': { 'version': 'str',
169 'supported_commands': ['GuestAgentCommandInfo'] } }
173 # Get some information about the guest agent.
175 # Returns: @GuestAgentInfo
179 { 'command': 'guest-info',
180 'returns': 'GuestAgentInfo' }
185 # Initiate guest-activated shutdown. Note: this is an asynchronous
186 # shutdown request, with no guarantee of successful shutdown.
188 # @mode: #optional "halt", "powerdown" (default), or "reboot"
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".
197 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
198 'success-response': false }
203 # Open a file in the guest and retrieve a file handle for it
205 # @filepath: Full path to the file in the guest to open.
207 # @mode: #optional open mode, as per fopen(), "r" is the default.
209 # Returns: Guest file handle on success.
213 { 'command': 'guest-file-open',
214 'data': { 'path': 'str', '*mode': 'str' },
220 # Close an open file in the guest
222 # @handle: filehandle returned by guest-file-open
224 # Returns: Nothing on success.
228 { 'command': 'guest-file-close',
229 'data': { 'handle': 'int' } }
234 # Result of guest agent file-read operation
236 # @count: number of bytes read (note: count is *before*
237 # base64-encoding is applied)
239 # @buf-b64: base64-encoded bytes read
241 # @eof: whether EOF was encountered during read operation.
245 { 'struct': 'GuestFileRead',
246 'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
251 # Read from an open file in the guest. Data will be base64-encoded
253 # @handle: filehandle returned by guest-file-open
255 # @count: #optional maximum number of bytes to read (default is 4KB)
257 # Returns: @GuestFileRead on success.
261 { 'command': 'guest-file-read',
262 'data': { 'handle': 'int', '*count': 'int' },
263 'returns': 'GuestFileRead' }
268 # Result of guest agent file-write operation
270 # @count: number of bytes written (note: count is actual bytes
271 # written, after base64-decoding of provided buffer)
273 # @eof: whether EOF was encountered during write operation.
277 { 'struct': 'GuestFileWrite',
278 'data': { 'count': 'int', 'eof': 'bool' } }
283 # Write to an open file in the guest.
285 # @handle: filehandle returned by guest-file-open
287 # @buf-b64: base64-encoded string representing data to be written
289 # @count: #optional bytes to write (actual bytes, after base64-decode),
290 # default is all content in buf-b64 buffer after base64 decoding
292 # Returns: @GuestFileWrite on success.
296 { 'command': 'guest-file-write',
297 'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
298 'returns': 'GuestFileWrite' }
304 # Result of guest agent file-seek operation
306 # @position: current file position
308 # @eof: whether EOF was encountered during file seek
312 { 'struct': 'GuestFileSeek',
313 'data': { 'position': 'int', 'eof': 'bool' } }
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.
322 # @handle: filehandle returned by guest-file-open
324 # @offset: bytes to skip over in the file stream
326 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
328 # Returns: @GuestFileSeek on success.
332 { 'command': 'guest-file-seek',
333 'data': { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
334 'returns': 'GuestFileSeek' }
339 # Write file changes bufferred in userspace to disk/kernel buffers
341 # @handle: filehandle returned by guest-file-open
343 # Returns: Nothing on success.
347 { 'command': 'guest-file-flush',
348 'data': { 'handle': 'int' } }
351 # @GuestFsFreezeStatus
353 # An enumeration of filesystem freeze states
355 # @thawed: filesystems thawed/unfrozen
357 # @frozen: all non-network guest filesystems frozen
361 { 'enum': 'GuestFsfreezeStatus',
362 'data': [ 'thawed', 'frozen' ] }
365 # @guest-fsfreeze-status:
367 # Get guest fsfreeze state. error state indicates
369 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
371 # Note: This may fail to properly report the current state as a result of
372 # some other guest processes having issued an fs freeze/thaw.
376 { 'command': 'guest-fsfreeze-status',
377 'returns': 'GuestFsfreezeStatus' }
380 # @guest-fsfreeze-freeze:
382 # Sync and freeze all freezable, local guest filesystems
384 # Returns: Number of file systems currently frozen. On error, all filesystems
389 { 'command': 'guest-fsfreeze-freeze',
393 # @guest-fsfreeze-freeze-list:
395 # Sync and freeze specified guest filesystems
397 # @mountpoints: #optional an array of mountpoints of filesystems to be frozen.
398 # If omitted, every mounted filesystem is frozen.
400 # Returns: Number of file systems currently frozen. On error, all filesystems
405 { 'command': 'guest-fsfreeze-freeze-list',
406 'data': { '*mountpoints': ['str'] },
410 # @guest-fsfreeze-thaw:
412 # Unfreeze all frozen guest filesystems
414 # Returns: Number of file systems thawed by this call
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
424 { 'command': 'guest-fsfreeze-thaw',
430 # Discard (or "trim") blocks which are not in use by the filesystem.
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".
444 { 'command': 'guest-fstrim',
445 'data': { '*minimum': 'int' } }
448 # @guest-suspend-disk
450 # Suspend guest to disk.
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.
456 # For the best results it's strongly recommended to have the pm-utils
457 # package installed in the guest.
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.
465 # The following errors may be returned:
466 # If suspend to disk is not supported, Unsupported
468 # Notes: It's strongly recommended to issue the guest-sync command before
469 # sending commands when the guest resumes
473 { 'command': 'guest-suspend-disk', 'success-response': false }
478 # Suspend guest to ram.
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.
484 # For the best results it's strongly recommended to have the pm-utils
485 # package installed in the guest.
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.
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
497 # The following errors may be returned:
498 # If suspend to ram is not supported, Unsupported
500 # Notes: It's strongly recommended to issue the guest-sync command before
501 # sending commands when the guest resumes
505 { 'command': 'guest-suspend-ram', 'success-response': false }
508 # @guest-suspend-hybrid
510 # Save guest state to disk and suspend to ram.
512 # This command requires the pm-utils package to be installed in the guest.
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.
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
524 # The following errors may be returned:
525 # If hybrid suspend is not supported, Unsupported
527 # Notes: It's strongly recommended to issue the guest-sync command before
528 # sending commands when the guest resumes
532 { 'command': 'guest-suspend-hybrid', 'success-response': false }
535 # @GuestIpAddressType:
537 # An enumeration of supported IP address types
539 # @ipv4: IP version 4
541 # @ipv6: IP version 6
545 { 'enum': 'GuestIpAddressType',
546 'data': [ 'ipv4', 'ipv6' ] }
551 # @ip-address: IP address
553 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
555 # @prefix: Network prefix length of @ip-address
559 { 'struct': 'GuestIpAddress',
560 'data': {'ip-address': 'str',
561 'ip-address-type': 'GuestIpAddressType',
565 # @GuestNetworkInterface:
567 # @name: The name of interface for which info are being delivered
569 # @hardware-address: Hardware address of @name
571 # @ip-addresses: List of addresses assigned to @name
575 { 'struct': 'GuestNetworkInterface',
576 'data': {'name': 'str',
577 '*hardware-address': 'str',
578 '*ip-addresses': ['GuestIpAddress'] } }
581 # @guest-network-get-interfaces:
583 # Get list of guest IP addresses, MAC addresses
586 # Returns: List of GuestNetworkInfo on success.
590 { 'command': 'guest-network-get-interfaces',
591 'returns': ['GuestNetworkInterface'] }
594 # @GuestLogicalProcessor:
596 # @logical-id: Arbitrary guest-specific unique identifier of the VCPU.
598 # @online: Whether the VCPU is enabled.
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
607 { 'struct': 'GuestLogicalProcessor',
608 'data': {'logical-id': 'int',
610 '*can-offline': 'bool'} }
615 # Retrieve the list of the guest's logical processors.
617 # This is a read-only operation.
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.
624 { 'command': 'guest-get-vcpus',
625 'returns': ['GuestLogicalProcessor'] }
630 # Attempt to reconfigure (currently: enable/disable) logical processors inside
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.
641 # Returns: The length of the initial sublist that has been successfully
642 # processed. The guest agent maximizes this value. Possible cases:
644 # 0: if the @vcpus list was empty on input. Guest state
645 # has not been changed. Otherwise,
647 # Error: processing the first node of @vcpus failed for the
648 # reason returned. Guest state has not been changed.
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.
658 # length(@vcpus): call successful.
662 { 'command': 'guest-set-vcpus',
663 'data': {'vcpus': ['GuestLogicalProcessor'] },
669 # An enumeration of bus type of disks
674 # @virtio: virtio disks
683 { 'enum': 'GuestDiskBusType',
684 'data': [ 'ide', 'fdc', 'scsi', 'virtio', 'xen', 'usb', 'uml', 'sata',
693 # @function: function id
697 { 'struct': 'GuestPCIAddress',
698 'data': {'domain': 'int', 'bus': 'int',
699 'slot': 'int', 'function': 'int'} }
704 # @pci-controller: controller's PCI address
712 { 'struct': 'GuestDiskAddress',
713 'data': {'pci-controller': 'GuestPCIAddress',
714 'bus-type': 'GuestDiskBusType',
715 'bus': 'int', 'target': 'int', 'unit': 'int'} }
718 # @GuestFilesystemInfo
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
728 { 'struct': 'GuestFilesystemInfo',
729 'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str',
730 'disk': ['GuestDiskAddress']} }
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.
742 { 'command': 'guest-get-fsinfo',
743 'returns': ['GuestFilesystemInfo'] }
746 # @guest-set-user-password
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
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.
758 # Note all guest operating systems will support use of the
759 # @crypted flag, as they may require the clear-text password
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.
765 # Returns: Nothing on success.
769 { 'command': 'guest-set-user-password',
770 'data': { 'username': 'str', 'password': 'str', 'crypted': 'bool' } }
774 # @phys-index: Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
776 # @online: Whether the MEMORY BLOCK is enabled in guest.
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).
785 { 'struct': 'GuestMemoryBlock',
786 'data': {'phys-index': 'uint64',
788 '*can-offline': 'bool'} }
791 # @guest-get-memory-blocks:
793 # Retrieve the list of the guest's memory blocks.
795 # This is a read-only operation.
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
803 { 'command': 'guest-get-memory-blocks',
804 'returns': ['GuestMemoryBlock'] }
807 # @GuestMemoryBlockResponseType
809 # An enumeration of memory block operation result.
811 # @success: the operation of online/offline memory block is successful.
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.
820 { 'enum': 'GuestMemoryBlockResponseType',
821 'data': ['success', 'not-found', 'operation-not-supported',
822 'operation-failed'] }
825 # @GuestMemoryBlockResponse:
827 # @phys-index: same with the 'phys-index' member of @GuestMemoryBlock.
829 # @response: the result of memory block operation.
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.
838 { 'struct': 'GuestMemoryBlockResponse',
839 'data': { 'phys-index': 'uint64',
840 'response': 'GuestMemoryBlockResponseType',
841 '*error-code': 'int' }}
844 # @guest-set-memory-blocks:
846 # Attempt to reconfigure (currently: enable/disable) state of memory blocks
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
855 # Preferably the input list should describe a modified subset of
856 # @guest-get-memory-blocks' return value.
858 # Returns: The operation results, it is a list of @GuestMemoryBlockResponse,
859 # which is corresponding to the input list.
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
867 { 'command': 'guest-set-memory-blocks',
868 'data': {'mem-blks': ['GuestMemoryBlock'] },
869 'returns': ['GuestMemoryBlockResponse'] }
871 # @GuestMemoryBlockInfo:
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).
879 { 'struct': 'GuestMemoryBlockInfo',
880 'data': {'size': 'uint64'} }
883 # @guest-get-memory-block-info:
885 # Get information relating to guest memory blocks.
887 # Returns: memory block size in bytes.
888 # Returns: @GuestMemoryBlockInfo
892 { 'command': 'guest-get-memory-block-info',
893 'returns': 'GuestMemoryBlockInfo' }