1QEMU-GA-REF(7) QEMU QEMU-GA-REF(7)
2
6 qemu-ga-ref - QEMU Guest Agent Protocol Reference
7 Contents
9 • QEMU Guest Agent Protocol Reference
10 • General note concerning the use of guest agent interfaces
12 • "unsupported" is a higher-level error than the errors that indi‐
14 vidual commands might document. The caller should always be pre‐
15 pared to receive QERR_UNSUPPORTED, even if the given command
16 doesn't specify it, or doesn't document any failure mode at all.
17 • QEMU guest agent protocol commands and structs
19 • guest-sync-delimited (Command)
21 • guest-sync (Command)
23 • guest-ping (Command)
25 • guest-get-time (Command)
27 • guest-set-time (Command)
29 • GuestAgentCommandInfo (Object)
31 • GuestAgentInfo (Object)
33 • guest-info (Command)
35 • guest-shutdown (Command)
37 • guest-file-open (Command)
39 • guest-file-close (Command)
41 • GuestFileRead (Object)
43 • guest-file-read (Command)
45 • GuestFileWrite (Object)
47 • guest-file-write (Command)
49 • GuestFileSeek (Object)
51 • QGASeek (Enum)
53 • GuestFileWhence (Alternate)
55 • guest-file-seek (Command)
57 • guest-file-flush (Command)
59 • GuestFsfreezeStatus (Enum)
61 • guest-fsfreeze-status (Command)
63 • guest-fsfreeze-freeze (Command)
65 • guest-fsfreeze-freeze-list (Command)
67 • guest-fsfreeze-thaw (Command)
69 • GuestFilesystemTrimResult (Object)
71 • GuestFilesystemTrimResponse (Object)
73 • guest-fstrim (Command)
75 • guest-suspend-disk (Command)
77 • guest-suspend-ram (Command)
79 • guest-suspend-hybrid (Command)
81 • GuestIpAddressType (Enum)
83 • GuestIpAddress (Object)
85 • GuestNetworkInterfaceStat (Object)
87 • GuestNetworkInterface (Object)
89 • guest-network-get-interfaces (Command)
91 • GuestLogicalProcessor (Object)
93 • guest-get-vcpus (Command)
95 • guest-set-vcpus (Command)
97 • GuestDiskBusType (Enum)
99 • GuestPCIAddress (Object)
101 • GuestCCWAddress (Object)
103 • GuestDiskAddress (Object)
105 • GuestNVMeSmart (Object)
107 • GuestDiskSmart (Object)
109 • GuestDiskInfo (Object)
111 • guest-get-disks (Command)
113 • GuestFilesystemInfo (Object)
115 • guest-get-fsinfo (Command)
117 • guest-set-user-password (Command)
119 • GuestMemoryBlock (Object)
121 • guest-get-memory-blocks (Command)
123 • GuestMemoryBlockResponseType (Enum)
125 • GuestMemoryBlockResponse (Object)
127 • guest-set-memory-blocks (Command)
129 • GuestMemoryBlockInfo (Object)
131 • guest-get-memory-block-info (Command)
133 • GuestExecStatus (Object)
135 • guest-exec-status (Command)
137 • GuestExec (Object)
139 • guest-exec (Command)
141 • GuestHostName (Object)
143 • guest-get-host-name (Command)
145 • GuestUser (Object)
147 • guest-get-users (Command)
149 • GuestTimezone (Object)
151 • guest-get-timezone (Command)
153 • GuestOSInfo (Object)
155 • guest-get-osinfo (Command)
157 • GuestDeviceType (Enum)
159 • GuestDeviceIdPCI (Object)
161 • GuestDeviceId (Object)
163 • GuestDeviceInfo (Object)
165 • guest-get-devices (Command)
167 • GuestAuthorizedKeys (Object)
169 • guest-ssh-get-authorized-keys (Command)
171 • guest-ssh-add-authorized-keys (Command)
173 • guest-ssh-remove-authorized-keys (Command)
175 • GuestDiskStats (Object)
177 • GuestDiskStatsInfo (Object)
179 • guest-get-diskstats (Command)
181 • GuestCpuStatsType (Enum)
183 • GuestLinuxCpuStats (Object)
185 • GuestCpuStats (Object)
187 • guest-get-cpustats (Command)
189
191 "unsupported" is a higher-level error than the errors that individual
192 commands might document. The caller should always be prepared to re‐
193 ceive QERR_UNSUPPORTED, even if the given command doesn't specify it,
194 or doesn't document any failure mode at all.
195
197 guest-sync-delimited (Command)
198 Echo back a unique integer value, and prepend to response a leading
199 sentinel byte (0xFF) the client can check scan for.
200 This is used by clients talking to the guest agent over the wire to en‐
202 sure the stream is in sync and doesn't contain stale data from previous
203 client. It must be issued upon initial connection, and after any
204 client-side timeouts (including timeouts on receiving a response to
205 this command).
206 After issuing this request, all guest agent responses should be ignored
208 until the response containing the unique integer value the client
209 passed in is returned. Receival of the 0xFF sentinel byte must be han‐
210 dled as an indication that the client's lexer/tokenizer/parser state
211 should be flushed/reset in preparation for reliably receiving the sub‐
212 sequent response. As an optimization, clients may opt to ignore all
213 data until a sentinel value is receiving to avoid unnecessary process‐
214 ing of stale data.
215 Similarly, clients should also precede this request with a 0xFF byte to
217 make sure the guest agent flushes any partially read JSON data from a
218 previous client connection.
219 Arguments
221 id: int
222 randomly generated 64-bit integer
223 Returns
225 The unique integer id passed in by the client
226 Since
228 1.1
229 guest-sync (Command)
231 Echo back a unique integer value
232 This is used by clients talking to the guest agent over the wire to en‐
234 sure the stream is in sync and doesn't contain stale data from previous
235 client. All guest agent responses should be ignored until the provided
236 unique integer value is returned, and it is up to the client to handle
237 stale whole or partially-delivered JSON text in such a way that this
238 response can be obtained.
239 In cases where a partial stale response was previously received by the
241 client, this cannot always be done reliably. One particular scenario
242 being if qemu-ga responses are fed character-by-character into a JSON
243 parser. In these situations, using guest-sync-delimited may be optimal.
244 For clients that fetch responses line by line and convert them to JSON
246 objects, guest-sync should be sufficient, but note that in cases where
247 the channel is dirty some attempts at parsing the response may result
248 in a parser error.
249 Such clients should also precede this command with a 0xFF byte to make
251 sure the guest agent flushes any partially read JSON data from a previ‐
252 ous session.
253 Arguments
255 id: int
256 randomly generated 64-bit integer
257 Returns
259 The unique integer id passed in by the client
260 Since
262 0.15.0
263 guest-ping (Command)
265 Ping the guest agent, a non-error return implies success
266 Since
268 0.15.0
269 guest-get-time (Command)
271 Get the information about guest's System Time relative to the Epoch of
272 1970-01-01 in UTC.
273 Returns
275 Time in nanoseconds.
276 Since
278 1.5
279 guest-set-time (Command)
281 Set guest time.
282 When a guest is paused or migrated to a file then loaded from that
284 file, the guest OS has no idea that there was a big gap in the time.
285 Depending on how long the gap was, NTP might not be able to resynchro‐
286 nize the guest.
287 This command tries to set guest's System Time to the given value, then
289 sets the Hardware Clock (RTC) to the current System Time. This will
290 make it easier for a guest to resynchronize without waiting for NTP. If
291 no time is specified, then the time to set is read from RTC. However,
292 this may not be supported on all platforms (i.e. Windows). If that's
293 the case users are advised to always pass a value.
294 Arguments
296 time: int (optional)
297 time of nanoseconds, relative to the Epoch of 1970-01-01 in UTC.
298 Returns
300 Nothing on success.
301 Since
303 1.5
304 GuestAgentCommandInfo (Object)
306 Information about guest agent commands.
307 Members
309 name: string
310 name of the command
311 enabled: boolean
313 whether command is currently enabled by guest admin
314 success-response: boolean
316 whether command returns a response on success (since 1.7)
317 Since
319 1.1.0
320 GuestAgentInfo (Object)
322 Information about guest agent.
323 Members
325 version: string
326 guest agent version
327 supported_commands: array of GuestAgentCommandInfo
329 Information about guest agent commands
330 Since
332 0.15.0
333 guest-info (Command)
335 Get some information about the guest agent.
336 Returns
338 GuestAgentInfo
339 Since
341 0.15.0
342 guest-shutdown (Command)
344 Initiate guest-activated shutdown. Note: this is an asynchronous shut‐
345 down request, with no guarantee of successful shutdown.
346 Arguments
348 mode: string (optional)
349 "halt", "powerdown" (default), or "reboot"
350 This command does NOT return a response on success. Success condition
351 is indicated by the VM exiting with a zero exit status or, when running
352 with --no-shutdown, by issuing the query-status QMP command to confirm
353 the VM status is "shutdown".
354 Since
356 0.15.0
357 guest-file-open (Command)
359 Open a file in the guest and retrieve a file handle for it
360 Arguments
362 path: string
363 Full path to the file in the guest to open.
364 mode: string (optional)
366 open mode, as per fopen(), "r" is the default.
367 Returns
369 Guest file handle on success.
370 Since
372 0.15.0
373 guest-file-close (Command)
375 Close an open file in the guest
376 Arguments
378 handle: int
379 filehandle returned by guest-file-open
380 Returns
382 Nothing on success.
383 Since
385 0.15.0
386 GuestFileRead (Object)
388 Result of guest agent file-read operation
389 Members
391 count: int
392 number of bytes read (note: count is before base64-encoding is
393 applied)
394 buf-b64: string
396 base64-encoded bytes read
397 eof: boolean
399 whether EOF was encountered during read operation.
400 Since
402 0.15.0
403 guest-file-read (Command)
405 Read from an open file in the guest. Data will be base64-encoded. As
406 this command is just for limited, ad-hoc debugging, such as log file
407 access, the number of bytes to read is limited to 48 MB.
408 Arguments
410 handle: int
411 filehandle returned by guest-file-open
412 count: int (optional)
414 maximum number of bytes to read (default is 4KB, maximum is
415 48MB)
416 Returns
418 GuestFileRead on success.
419 Since
421 0.15.0
422 GuestFileWrite (Object)
424 Result of guest agent file-write operation
425 Members
427 count: int
428 number of bytes written (note: count is actual bytes written,
429 after base64-decoding of provided buffer)
430 eof: boolean
432 whether EOF was encountered during write operation.
433 Since
435 0.15.0
436 guest-file-write (Command)
438 Write to an open file in the guest.
439 Arguments
441 handle: int
442 filehandle returned by guest-file-open
443 buf-b64: string
445 base64-encoded string representing data to be written
446 count: int (optional)
448 bytes to write (actual bytes, after base64-decode), default is
449 all content in buf-b64 buffer after base64 decoding
450 Returns
452 GuestFileWrite on success.
453 Since
455 0.15.0
456 GuestFileSeek (Object)
458 Result of guest agent file-seek operation
459 Members
461 position: int
462 current file position
463 eof: boolean
465 whether EOF was encountered during file seek
466 Since
468 0.15.0
469 QGASeek (Enum)
471 Symbolic names for use in guest-file-seek
472 Values
474 set Set to the specified offset (same effect as 'whence':0)
475 cur Add offset to the current location (same effect as 'whence':1)
477 end Add offset to the end of the file (same effect as 'whence':2)
479 Since
481 2.6
482 GuestFileWhence (Alternate)
484 Controls the meaning of offset to guest-file-seek.
485 Members
487 value: int
488 Integral value (0 for set, 1 for cur, 2 for end), available for
489 historical reasons, and might differ from the host's or guest's
490 SEEK_* values (since: 0.15)
491 name: QGASeek
493 Symbolic name, and preferred interface
494 Since
496 2.6
497 guest-file-seek (Command)
499 Seek to a position in the file, as with fseek(), and return the current
500 file position afterward. Also encapsulates ftell()'s functionality,
501 with offset=0 and whence=1.
502 Arguments
504 handle: int
505 filehandle returned by guest-file-open
506 offset: int
508 bytes to skip over in the file stream
509 whence: GuestFileWhence
511 Symbolic or numeric code for interpreting offset
512 Returns
514 GuestFileSeek on success.
515 Since
517 0.15.0
518 guest-file-flush (Command)
520 Write file changes buffered in userspace to disk/kernel buffers
521 Arguments
523 handle: int
524 filehandle returned by guest-file-open
525 Returns
527 Nothing on success.
528 Since
530 0.15.0
531 GuestFsfreezeStatus (Enum)
533 An enumeration of filesystem freeze states
534 Values
536 thawed filesystems thawed/unfrozen
537 frozen all non-network guest filesystems frozen
539 Since
541 0.15.0
542 guest-fsfreeze-status (Command)
544 Get guest fsfreeze state. error state indicates
545 Returns
547 GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
548 Note
550 This may fail to properly report the current state as a result of some
551 other guest processes having issued an fs freeze/thaw.
552 Since
554 0.15.0
555 guest-fsfreeze-freeze (Command)
557 Sync and freeze all freezable, local guest filesystems. If this command
558 succeeded, you may call guest-fsfreeze-thaw later to unfreeze.
559 Note
561 On Windows, the command is implemented with the help of a Volume
562 Shadow-copy Service DLL helper. The frozen state is limited for up to
563 10 seconds by VSS.
564 Returns
566 Number of file systems currently frozen. On error, all filesystems will
567 be thawed. If no filesystems are frozen as a result of this call, then
568 guest-fsfreeze-status will remain "thawed" and calling guest-fs‐
569 freeze-thaw is not necessary.
570 Since
572 0.15.0
573 guest-fsfreeze-freeze-list (Command)
575 Sync and freeze specified guest filesystems. See also guest-fs‐
576 freeze-freeze.
577 Arguments
579 mountpoints: array of string (optional)
580 an array of mountpoints of filesystems to be frozen. If omit‐
581 ted, every mounted filesystem is frozen. Invalid mount points
582 are ignored.
583 Returns
585 Number of file systems currently frozen. On error, all filesystems will
586 be thawed.
587 Since
589 2.2
590 guest-fsfreeze-thaw (Command)
592 Unfreeze all frozen guest filesystems
593 Returns
595 Number of file systems thawed by this call
596 Note
598 if return value does not match the previous call to guest-fs‐
599 freeze-freeze, this likely means some freezable filesystems were un‐
600 frozen before this call, and that the filesystem state may have changed
601 before issuing this command.
602 Since
604 0.15.0
605 GuestFilesystemTrimResult (Object)
607 Members
608 path: string
609 path that was trimmed
610 error: string (optional)
612 an error message when trim failed
613 trimmed: int (optional)
615 bytes trimmed for this path
616 minimum: int (optional)
618 reported effective minimum for this path
619 Since
621 2.4
622 GuestFilesystemTrimResponse (Object)
624 Members
625 paths: array of GuestFilesystemTrimResult
626 list of GuestFilesystemTrimResult per path that was trimmed
627 Since
629 2.4
630 guest-fstrim (Command)
632 Discard (or "trim") blocks which are not in use by the filesystem.
633 Arguments
635 minimum: int (optional)
636 Minimum contiguous free range to discard, in bytes. Free ranges
637 smaller than this may be ignored (this is a hint and the guest
638 may not respect it). By increasing this value, the fstrim oper‐
639 ation will complete more quickly for filesystems with badly
640 fragmented free space, although not all blocks will be dis‐
641 carded. The default value is zero, meaning "discard every free
642 block".
643 Returns
645 A GuestFilesystemTrimResponse which contains the status of all trimmed
646 paths. (since 2.4)
647 Since
649 1.2
650 guest-suspend-disk (Command)
652 Suspend guest to disk.
653 This command attempts to suspend the guest using three strategies, in
655 this order:
656 • systemd hibernate
658 • pm-utils (via pm-hibernate)
660 • manual write into sysfs
662 This command does NOT return a response on success. There is a high
664 chance the command succeeded if the VM exits with a zero exit status
665 or, when running with --no-shutdown, by issuing the query-status QMP
666 command to to confirm the VM status is "shutdown". However, the VM
667 could also exit (or set its status to "shutdown") due to other reasons.
668 The following errors may be returned:
670 • If suspend to disk is not supported, Unsupported
672 Notes
674 It's strongly recommended to issue the guest-sync command before send‐
675 ing commands when the guest resumes
676 Since
678 1.1
679 guest-suspend-ram (Command)
681 Suspend guest to ram.
682 This command attempts to suspend the guest using three strategies, in
684 this order:
685 • systemd suspend
687 • pm-utils (via pm-suspend)
689 • manual write into sysfs
691 IMPORTANT: guest-suspend-ram requires working wakeup support in QEMU.
693 You should check QMP command query-current-machine returns wakeup-sus‐
694 pend-support: true before issuing this command. Failure in doing so can
695 result in a suspended guest that QEMU will not be able to awaken, forc‐
696 ing the user to power cycle the guest to bring it back.
697 This command does NOT return a response on success. There are two op‐
699 tions to check for success:
700 1. Wait for the SUSPEND QMP event from QEMU
702 2. Issue the query-status QMP command to confirm the VM status is "sus‐
704 pended"
705 The following errors may be returned:
707 • If suspend to ram is not supported, Unsupported
709 Notes
711 It's strongly recommended to issue the guest-sync command before send‐
712 ing commands when the guest resumes
713 Since
715 1.1
716 guest-suspend-hybrid (Command)
718 Save guest state to disk and suspend to ram.
719 This command attempts to suspend the guest by executing, in this order:
721 • systemd hybrid-sleep
723 • pm-utils (via pm-suspend-hybrid)
725 IMPORTANT: guest-suspend-hybrid requires working wakeup support in
727 QEMU. You should check QMP command query-current-machine returns
728 wakeup-suspend-support: true before issuing this command. Failure in
729 doing so can result in a suspended guest that QEMU will not be able to
730 awaken, forcing the user to power cycle the guest to bring it back.
731 This command does NOT return a response on success. There are two op‐
733 tions to check for success:
734 1. Wait for the SUSPEND QMP event from QEMU
736 2. Issue the query-status QMP command to confirm the VM status is "sus‐
738 pended"
739 The following errors may be returned:
741 • If hybrid suspend is not supported, Unsupported
743 Notes
745 It's strongly recommended to issue the guest-sync command before send‐
746 ing commands when the guest resumes
747 Since
749 1.1
750 GuestIpAddressType (Enum)
752 An enumeration of supported IP address types
753 Values
755 ipv4 IP version 4
756 ipv6 IP version 6
758 Since
760 1.1
761 GuestIpAddress (Object)
763 Members
764 ip-address: string
765 IP address
766 ip-address-type: GuestIpAddressType
768 Type of ip-address (e.g. ipv4, ipv6)
769 prefix: int
771 Network prefix length of ip-address
772 Since
774 1.1
775 GuestNetworkInterfaceStat (Object)
777 Members
778 rx-bytes: int
779 total bytes received
780 rx-packets: int
782 total packets received
783 rx-errs: int
785 bad packets received
786 rx-dropped: int
788 receiver dropped packets
789 tx-bytes: int
791 total bytes transmitted
792 tx-packets: int
794 total packets transmitted
795 tx-errs: int
797 packet transmit problems
798 tx-dropped: int
800 dropped packets transmitted
801 Since
803 2.11
804 GuestNetworkInterface (Object)
806 Members
807 name: string
808 The name of interface for which info are being delivered
809 hardware-address: string (optional)
811 Hardware address of name
812 ip-addresses: array of GuestIpAddress (optional)
814 List of addresses assigned to name
815 statistics: GuestNetworkInterfaceStat (optional)
817 various statistic counters related to name (since 2.11)
818 Since
820 1.1
821 guest-network-get-interfaces (Command)
823 Get list of guest IP addresses, MAC addresses and netmasks.
824 Returns
826 List of GuestNetworkInfo on success.
827 Since
829 1.1
830 GuestLogicalProcessor (Object)
832 Members
833 logical-id: int
834 Arbitrary guest-specific unique identifier of the VCPU.
835 online: boolean
837 Whether the VCPU is enabled.
838 can-offline: boolean (optional)
840 Whether offlining the VCPU is possible. This member is always
841 filled in by the guest agent when the structure is returned, and
842 always ignored on input (hence it can be omitted then).
843 Since
845 1.5
846 guest-get-vcpus (Command)
848 Retrieve the list of the guest's logical processors.
849 This is a read-only operation.
851 Returns
853 The list of all VCPUs the guest knows about. Each VCPU is put on the
854 list exactly once, but their order is unspecified.
855 Since
857 1.5
858 guest-set-vcpus (Command)
860 Attempt to reconfigure (currently: enable/disable) logical processors
861 inside the guest.
862 The input list is processed node by node in order. In each node logi‐
864 cal-id is used to look up the guest VCPU, for which online specifies
865 the requested state. The set of distinct logical-id's is only required
866 to be a subset of the guest-supported identifiers. There's no restric‐
867 tion on list length or on repeating the same logical-id (with possibly
868 different online field). Preferably the input list should describe a
869 modified subset of guest-get-vcpus' return value.
870 Arguments
872 vcpus: array of GuestLogicalProcessor
873 Not documented
874 Returns
876 The length of the initial sublist that has been successfully processed.
877 The guest agent maximizes this value. Possible cases:
878 • 0: if the vcpus list was empty on input. Guest state has not been
880 changed. Otherwise,
881 • Error: processing the first node of vcpus failed for the reason re‐
883 turned. Guest state has not been changed. Otherwise,
884 • < length(vcpus): more than zero initial nodes have been processed,
886 but not the entire vcpus list. Guest state has changed accordingly.
887 To retrieve the error (assuming it persists), repeat the call with
888 the successfully processed initial sublist removed. Otherwise,
889 • length(vcpus): call successful.
891 Since
893 1.5
894 GuestDiskBusType (Enum)
896 An enumeration of bus type of disks
897 Values
899 ide IDE disks
900 fdc floppy disks
902 scsi SCSI disks
904 virtio virtio disks
906 xen Xen disks
908 usb USB disks
910 uml UML disks
912 sata SATA disks
914 sd SD cards
916 unknown
918 Unknown bus type
919 ieee1394
921 Win IEEE 1394 bus type
922 ssa Win SSA bus type
924 fibre Win fiber channel bus type
926 raid Win RAID bus type
928 iscsi Win iScsi bus type
930 sas Win serial-attaches SCSI bus type
932 mmc Win multimedia card (MMC) bus type
934 virtual
936 Win virtual bus type
937 file-backed-virtual
939 Win file-backed bus type
940 nvme NVMe disks (since 7.1)
942 Since
944 2.2; 'Unknown' and all entries below since 2.4
945 GuestPCIAddress (Object)
947 Members
948 domain: int
949 domain id
950 bus: int
952 bus id
953 slot: int
955 slot id
956 function: int
958 function id
959 Since
961 2.2
962 GuestCCWAddress (Object)
964 Members
965 cssid: int
966 channel subsystem image id
967 ssid: int
969 subchannel set id
970 subchno: int
972 subchannel number
973 devno: int
975 device number
976 Since
978 6.0
979 GuestDiskAddress (Object)
981 Members
982 pci-controller: GuestPCIAddress
983 controller's PCI address (fields are set to -1 if invalid)
984 bus-type: GuestDiskBusType
986 bus type
987 bus: int
989 bus id
990 target: int
992 target id
993 unit: int
995 unit id
996 serial: string (optional)
998 serial number (since: 3.1)
999 dev: string (optional)
1001 device node (POSIX) or device UNC (Windows) (since: 3.1)
1002 ccw-address: GuestCCWAddress (optional)
1004 CCW address on s390x (since: 6.0)
1005 Since
1007 2.2
1008 GuestNVMeSmart (Object)
1010 NVMe smart informations, based on NVMe specification, section <SMART /
1011 Health Information (Log Identifier 02h)>
1012 Members
1014 critical-warning: int
1015 Not documented
1016 temperature: int
1018 Not documented
1019 available-spare: int
1021 Not documented
1022 available-spare-threshold: int
1024 Not documented
1025 percentage-used: int
1027 Not documented
1028 data-units-read-lo: int
1030 Not documented
1031 data-units-read-hi: int
1033 Not documented
1034 data-units-written-lo: int
1036 Not documented
1037 data-units-written-hi: int
1039 Not documented
1040 host-read-commands-lo: int
1042 Not documented
1043 host-read-commands-hi: int
1045 Not documented
1046 host-write-commands-lo: int
1048 Not documented
1049 host-write-commands-hi: int
1051 Not documented
1052 controller-busy-time-lo: int
1054 Not documented
1055 controller-busy-time-hi: int
1057 Not documented
1058 power-cycles-lo: int
1060 Not documented
1061 power-cycles-hi: int
1063 Not documented
1064 power-on-hours-lo: int
1066 Not documented
1067 power-on-hours-hi: int
1069 Not documented
1070 unsafe-shutdowns-lo: int
1072 Not documented
1073 unsafe-shutdowns-hi: int
1075 Not documented
1076 media-errors-lo: int
1078 Not documented
1079 media-errors-hi: int
1081 Not documented
1082 number-of-error-log-entries-lo: int
1084 Not documented
1085 number-of-error-log-entries-hi: int
1087 Not documented
1088 Since
1090 7.1
1091 GuestDiskSmart (Object)
1093 Disk type related smart information.
1094 • nvme: NVMe disk smart
1096 Members
1098 type: GuestDiskBusType
1099 Not documented
1100 The members of GuestNVMeSmart when type is "nvme"
1102 Since
1104 7.1
1105 GuestDiskInfo (Object)
1107 Members
1108 name: string
1109 device node (Linux) or device UNC (Windows)
1110 partition: boolean
1112 whether this is a partition or disk
1113 dependencies: array of string (optional)
1115 list of device dependencies; e.g. for LVs of the LVM this will
1116 hold the list of PVs, for LUKS encrypted volume this will con‐
1117 tain the disk where the volume is placed. (Linux)
1118 address: GuestDiskAddress (optional)
1120 disk address information (only for non-virtual devices)
1121 alias: string (optional)
1123 optional alias assigned to the disk, on Linux this is a name as‐
1124 signed by device mapper
1125 smart: GuestDiskSmart (optional)
1127 disk smart information (Since 7.1)
1128 Since
1130 5.2
1131 guest-get-disks (Command)
1133 Returns
1134 The list of disks in the guest. For Windows these are only the physical
1135 disks. On Linux these are all root block devices of non-zero size in‐
1136 cluding e.g. removable devices, loop devices, NBD, etc.
1137 Since
1139 5.2
1140 GuestFilesystemInfo (Object)
1142 Members
1143 name: string
1144 disk name
1145 mountpoint: string
1147 mount point path
1148 type: string
1150 file system type string
1151 used-bytes: int (optional)
1153 file system used bytes (since 3.0)
1154 total-bytes: int (optional)
1156 non-root file system total bytes (since 3.0)
1157 disk: array of GuestDiskAddress
1159 an array of disk hardware information that the volume lies on,
1160 which may be empty if the disk type is not supported
1161 Since
1163 2.2
1164 guest-get-fsinfo (Command)
1166 Returns
1167 The list of filesystems information mounted in the guest. The returned
1168 mountpoints may be specified to guest-fsfreeze-freeze-list. Network
1169 filesystems (such as CIFS and NFS) are not listed.
1170 Since
1172 2.2
1173 guest-set-user-password (Command)
1175 Arguments
1176 username: string
1177 the user account whose password to change
1178 password: string
1180 the new password entry string, base64 encoded
1181 crypted: boolean
1183 true if password is already crypt()d, false if raw
1184 If the crypted flag is true, it is the caller's responsibility to en‐
1185 sure the correct crypt() encryption scheme is used. This command does
1186 not attempt to interpret or report on the encryption scheme. Refer to
1187 the documentation of the guest operating system in question to deter‐
1188 mine what is supported.
1189 Not all guest operating systems will support use of the crypted flag,
1191 as they may require the clear-text password
1192 The password parameter must always be base64 encoded before transmis‐
1194 sion, even if already crypt()d, to ensure it is 8-bit safe when passed
1195 as JSON.
1196 Returns
1198 Nothing on success.
1199 Since
1201 2.3
1202 GuestMemoryBlock (Object)
1204 Members
1205 phys-index: int
1206 Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
1207 online: boolean
1209 Whether the MEMORY BLOCK is enabled in guest.
1210 can-offline: boolean (optional)
1212 Whether offlining the MEMORY BLOCK is possible. This member is
1213 always filled in by the guest agent when the structure is re‐
1214 turned, and always ignored on input (hence it can be omitted
1215 then).
1216 Since
1218 2.3
1219 guest-get-memory-blocks (Command)
1221 Retrieve the list of the guest's memory blocks.
1222 This is a read-only operation.
1224 Returns
1226 The list of all memory blocks the guest knows about. Each memory block
1227 is put on the list exactly once, but their order is unspecified.
1228 Since
1230 2.3
1231 GuestMemoryBlockResponseType (Enum)
1233 An enumeration of memory block operation result.
1234 Values
1236 success
1237 the operation of online/offline memory block is successful.
1238 not-found
1240 can't find the corresponding memoryXXX directory in sysfs.
1241 operation-not-supported
1243 for some old kernels, it does not support online or offline mem‐
1244 ory block.
1245 operation-failed
1247 the operation of online/offline memory block fails, because of
1248 some errors happen.
1249 Since
1251 2.3
1252 GuestMemoryBlockResponse (Object)
1254 Members
1255 phys-index: int
1256 same with the 'phys-index' member of GuestMemoryBlock.
1257 response: GuestMemoryBlockResponseType
1259 the result of memory block operation.
1260 error-code: int (optional)
1262 the error number. When memory block operation fails, we assign
1263 the value of 'errno' to this member, it indicates what goes
1264 wrong. When the operation succeeds, it will be omitted.
1265 Since
1267 2.3
1268 guest-set-memory-blocks (Command)
1270 Attempt to reconfigure (currently: enable/disable) state of memory
1271 blocks inside the guest.
1272 The input list is processed node by node in order. In each node
1274 phys-index is used to look up the guest MEMORY BLOCK, for which online
1275 specifies the requested state. The set of distinct phys-index's is only
1276 required to be a subset of the guest-supported identifiers. There's no
1277 restriction on list length or on repeating the same phys-index (with
1278 possibly different online field). Preferably the input list should de‐
1279 scribe a modified subset of guest-get-memory-blocks' return value.
1280 Arguments
1282 mem-blks: array of GuestMemoryBlock
1283 Not documented
1284 Returns
1286 The operation results, it is a list of GuestMemoryBlockResponse, which
1287 is corresponding to the input list.
1288 Note: it will return NULL if the mem-blks list was empty on input, or
1290 there is an error, and in this case, guest state will not be changed.
1291 Since
1293 2.3
1294 GuestMemoryBlockInfo (Object)
1296 Members
1297 size: int
1298 the size (in bytes) of the guest memory blocks, which are the
1299 minimal units of memory block online/offline operations (also
1300 called Logical Memory Hotplug).
1301 Since
1303 2.3
1304 guest-get-memory-block-info (Command)
1306 Get information relating to guest memory blocks.
1307 Returns
1309 GuestMemoryBlockInfo
1310 Since
1312 2.3
1313 GuestExecStatus (Object)
1315 Members
1316 exited: boolean
1317 true if process has already terminated.
1318 exitcode: int (optional)
1320 process exit code if it was normally terminated.
1321 signal: int (optional)
1323 signal number (linux) or unhandled exception code (windows) if
1324 the process was abnormally terminated.
1325 out-data: string (optional)
1327 base64-encoded stdout of the process
1328 err-data: string (optional)
1330 base64-encoded stderr of the process Note: out-data and err-data
1331 are present only if 'capture-output' was specified for
1332 'guest-exec'
1333 out-truncated: boolean (optional)
1335 true if stdout was not fully captured due to size limitation.
1336 err-truncated: boolean (optional)
1338 true if stderr was not fully captured due to size limitation.
1339 Since
1341 2.5
1342 guest-exec-status (Command)
1344 Check status of process associated with PID retrieved via guest-exec.
1345 Reap the process and associated metadata if it has exited.
1346 Arguments
1348 pid: int
1349 pid returned from guest-exec
1350 Returns
1352 GuestExecStatus on success.
1353 Since
1355 2.5
1356 GuestExec (Object)
1358 Members
1359 pid: int
1360 pid of child process in guest OS
1361 Since
1363 2.5
1364 guest-exec (Command)
1366 Execute a command in the guest
1367 Arguments
1369 path: string
1370 path or executable name to execute
1371 arg: array of string (optional)
1373 argument list to pass to executable
1374 env: array of string (optional)
1376 environment variables to pass to executable
1377 input-data: string (optional)
1379 data to be passed to process stdin (base64 encoded)
1380 capture-output: boolean (optional)
1382 bool flag to enable capture of stdout/stderr of running process.
1383 defaults to false.
1384 Returns
1386 PID on success.
1387 Since
1389 2.5
1390 GuestHostName (Object)
1392 Members
1393 host-name: string
1394 Fully qualified domain name of the guest OS
1395 Since
1397 2.10
1398 guest-get-host-name (Command)
1400 Return a name for the machine.
1401 The returned name is not necessarily a fully-qualified domain name, or
1403 even present in DNS or some other name service at all. It need not even
1404 be unique on your local network or site, but usually it is.
1405 Returns
1407 the host name of the machine on success
1408 Since
1410 2.10
1411 GuestUser (Object)
1413 Members
1414 user: string
1415 Username
1416 domain: string (optional)
1418 Logon domain (windows only)
1419 login-time: number
1421 Time of login of this user on the computer. If multiple in‐
1422 stances of the user are logged in, the earliest login time is
1423 reported. The value is in fractional seconds since epoch time.
1424 Since
1426 2.10
1427 guest-get-users (Command)
1429 Retrieves a list of currently active users on the VM.
1430 Returns
1432 A unique list of users.
1433 Since
1435 2.10
1436 GuestTimezone (Object)
1438 Members
1439 zone: string (optional)
1440 Timezone name. These values may differ depending on guest/OS and
1441 should only be used for informational purposes.
1442 offset: int
1444 Offset to UTC in seconds, negative numbers for time zones west
1445 of GMT, positive numbers for east
1446 Since
1448 2.10
1449 guest-get-timezone (Command)
1451 Retrieves the timezone information from the guest.
1452 Returns
1454 A GuestTimezone dictionary.
1455 Since
1457 2.10
1458 GuestOSInfo (Object)
1460 Members
1461 kernel-release: string (optional)
1462 • POSIX: release field returned by uname(2)
1464 • Windows: build number of the OS
1466 kernel-version: string (optional)
1468 • POSIX: version field returned by uname(2)
1470 • Windows: version number of the OS
1472 machine: string (optional)
1474 • POSIX: machine field returned by uname(2)
1476 • Windows: one of x86, x86_64, arm, ia64
1478 id: string (optional)
1480 • POSIX: as defined by os-release(5)
1482 • Windows: contains string "mswindows"
1484 name: string (optional)
1486 • POSIX: as defined by os-release(5)
1488 • Windows: contains string "Microsoft Windows"
1490 pretty-name: string (optional)
1492 • POSIX: as defined by os-release(5)
1494 • Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1496 version: string (optional)
1498 • POSIX: as defined by os-release(5)
1500 • Windows: long version string, e.g. "Microsoft Windows Server
1502 2008"
1503 version-id: string (optional)
1505 • POSIX: as defined by os-release(5)
1507 • Windows: short version identifier, e.g. "7" or "20012r2"
1509 variant: string (optional)
1511 • POSIX: as defined by os-release(5)
1513 • Windows: contains string "server" or "client"
1515 variant-id: string (optional)
1517 • POSIX: as defined by os-release(5)
1519 • Windows: contains string "server" or "client"
1521 Notes
1523 On POSIX systems the fields id, name, pretty-name, version, version-id,
1524 variant and variant-id follow the definition specified in os-re‐
1525 lease(5). Refer to the manual page for exact description of the
1526 fields. Their values are taken from the os-release file. If the file is
1527 not present in the system, or the values are not present in the file,
1528 the fields are not included.
1529 On Windows the values are filled from information gathered from the
1531 system.
1532 Since
1534 2.10
1535 guest-get-osinfo (Command)
1537 Retrieve guest operating system information
1538 Returns
1540 GuestOSInfo
1541 Since
1543 2.10
1544 GuestDeviceType (Enum)
1546 Values
1547 pci Not documented
1548 GuestDeviceIdPCI (Object)
1550 Members
1551 vendor-id: int
1552 vendor ID
1553 device-id: int
1555 device ID
1556 Since
1558 5.2
1559 GuestDeviceId (Object)
1561 Id of the device - pci: PCI ID, since: 5.2
1562 Members
1564 type: GuestDeviceType
1565 Not documented
1566 The members of GuestDeviceIdPCI when type is "pci"
1568 Since
1570 5.2
1571 GuestDeviceInfo (Object)
1573 Members
1574 driver-name: string
1575 name of the associated driver
1576 driver-date: int (optional)
1578 driver release date, in nanoseconds since the epoch
1579 driver-version: string (optional)
1581 driver version
1582 id: GuestDeviceId (optional)
1584 device ID
1585 Since
1587 5.2
1588 guest-get-devices (Command)
1590 Retrieve information about device drivers in Windows guest
1591 Returns
1593 GuestDeviceInfo
1594 Since
1596 5.2
1597 GuestAuthorizedKeys (Object)
1599 Members
1600 keys: array of string
1601 public keys (in OpenSSH/sshd(8) authorized_keys format)
1602 Since
1604 5.2
1605 If
1607 CONFIG_POSIX
1608 guest-ssh-get-authorized-keys (Command)
1610 Arguments
1611 username: string
1612 the user account to add the authorized keys
1613 Return the public keys from user .ssh/authorized_keys on Unix systems
1614 (not implemented for other systems).
1615 Returns
1617 GuestAuthorizedKeys
1618 Since
1620 5.2
1621 If
1623 CONFIG_POSIX
1624 guest-ssh-add-authorized-keys (Command)
1626 Arguments
1627 username: string
1628 the user account to add the authorized keys
1629 keys: array of string
1631 the public keys to add (in OpenSSH/sshd(8) authorized_keys for‐
1632 mat)
1633 reset: boolean (optional)
1635 ignore the existing content, set it with the given keys only
1636 Append public keys to user .ssh/authorized_keys on Unix systems (not
1637 implemented for other systems).
1638 Returns
1640 Nothing on success.
1641 Since
1643 5.2
1644 If
1646 CONFIG_POSIX
1647 guest-ssh-remove-authorized-keys (Command)
1649 Arguments
1650 username: string
1651 the user account to remove the authorized keys
1652 keys: array of string
1654 the public keys to remove (in OpenSSH/sshd(8) authorized_keys
1655 format)
1656 Remove public keys from the user .ssh/authorized_keys on Unix systems
1657 (not implemented for other systems). It's not an error if the key is
1658 already missing.
1659 Returns
1661 Nothing on success.
1662 Since
1664 5.2
1665 If
1667 CONFIG_POSIX
1668 GuestDiskStats (Object)
1670 Members
1671 read-sectors: int (optional)
1672 sectors read
1673 read-ios: int (optional)
1675 reads completed successfully
1676 read-merges: int (optional)
1678 read requests merged
1679 write-sectors: int (optional)
1681 sectors written
1682 write-ios: int (optional)
1684 writes completed
1685 write-merges: int (optional)
1687 write requests merged
1688 discard-sectors: int (optional)
1690 sectors discarded
1691 discard-ios: int (optional)
1693 discards completed successfully
1694 discard-merges: int (optional)
1696 discard requests merged
1697 flush-ios: int (optional)
1699 flush requests completed successfully
1700 read-ticks: int (optional)
1702 time spent reading(ms)
1703 write-ticks: int (optional)
1705 time spent writing(ms)
1706 discard-ticks: int (optional)
1708 time spent discarding(ms)
1709 flush-ticks: int (optional)
1711 time spent flushing(ms)
1712 ios-pgr: int (optional)
1714 number of I/Os currently in flight
1715 total-ticks: int (optional)
1717 time spent doing I/Os (ms)
1718 weight-ticks: int (optional)
1720 weighted time spent doing I/Os since the last update of this
1721 field(ms)
1722 Since
1724 7.1
1725 GuestDiskStatsInfo (Object)
1727 name disk name
1728 major major device number of disk
1730 minor minor device number of disk
1732 Members
1734 name: string
1735 Not documented
1736 major: int
1738 Not documented
1739 minor: int
1741 Not documented
1742 stats: GuestDiskStats
1744 Not documented
1745 guest-get-diskstats (Command)
1747 Retrieve information about disk stats.
1748 Returns
1750 List of disk stats of guest.
1751 Since
1753 7.1
1754 GuestCpuStatsType (Enum)
1756 An enumeration of OS type
1757 Values
1759 linux Not documented
1760 Since
1762 7.1
1763 GuestLinuxCpuStats (Object)
1765 CPU statistics of Linux
1766 Members
1768 cpu: int
1769 CPU index in guest OS
1770 user: int
1772 Time spent in user mode
1773 nice: int
1775 Time spent in user mode with low priority (nice)
1776 system: int
1778 Time spent in system mode
1779 idle: int
1781 Time spent in the idle task
1782 iowait: int (optional)
1784 Time waiting for I/O to complete (since Linux 2.5.41)
1785 irq: int (optional)
1787 Time servicing interrupts (since Linux 2.6.0-test4)
1788 softirq: int (optional)
1790 Time servicing softirqs (since Linux 2.6.0-test4)
1791 steal: int (optional)
1793 Stolen time by host (since Linux 2.6.11)
1794 guest: int (optional)
1796 ime spent running a virtual CPU for guest operating systems un‐
1797 der the control of the Linux kernel (since Linux 2.6.24)
1798 guestnice: int (optional)
1800 Time spent running a niced guest (since Linux 2.6.33)
1801 Since
1803 7.1
1804 GuestCpuStats (Object)
1806 Get statistics of each CPU in millisecond.
1807 • linux: Linux style CPU statistics
1809 Members
1811 type: GuestCpuStatsType
1812 Not documented
1813 The members of GuestLinuxCpuStats when type is "linux"
1815 Since
1817 7.1
1818 guest-get-cpustats (Command)
1820 Retrieve information about CPU stats.
1821 Returns
1823 List of CPU stats of guest.
1824 Since
1826 7.1
1827
1829 2023, The QEMU Project Developers
18307.2.6 Sep 26, 2023 QEMU-GA-REF(7)