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 • GuestExecCaptureOutputMode (Enum)
141 • GuestExecCaptureOutput (Alternate)
143 • guest-exec (Command)
145 • GuestHostName (Object)
147 • guest-get-host-name (Command)
149 • GuestUser (Object)
151 • guest-get-users (Command)
153 • GuestTimezone (Object)
155 • guest-get-timezone (Command)
157 • GuestOSInfo (Object)
159 • guest-get-osinfo (Command)
161 • GuestDeviceType (Enum)
163 • GuestDeviceIdPCI (Object)
165 • GuestDeviceId (Object)
167 • GuestDeviceInfo (Object)
169 • guest-get-devices (Command)
171 • GuestAuthorizedKeys (Object)
173 • guest-ssh-get-authorized-keys (Command)
175 • guest-ssh-add-authorized-keys (Command)
177 • guest-ssh-remove-authorized-keys (Command)
179 • GuestDiskStats (Object)
181 • GuestDiskStatsInfo (Object)
183 • guest-get-diskstats (Command)
185 • GuestCpuStatsType (Enum)
187 • GuestLinuxCpuStats (Object)
189 • GuestCpuStats (Object)
191 • guest-get-cpustats (Command)
193
195 "unsupported" is a higher-level error than the errors that individual
196 commands might document. The caller should always be prepared to re‐
197 ceive QERR_UNSUPPORTED, even if the given command doesn't specify it,
198 or doesn't document any failure mode at all.
199
201 guest-sync-delimited (Command)
202 Echo back a unique integer value, and prepend to response a leading
203 sentinel byte (0xFF) the client can check scan for.
204 This is used by clients talking to the guest agent over the wire to en‐
206 sure the stream is in sync and doesn't contain stale data from previous
207 client. It must be issued upon initial connection, and after any
208 client-side timeouts (including timeouts on receiving a response to
209 this command).
210 After issuing this request, all guest agent responses should be ignored
212 until the response containing the unique integer value the client
213 passed in is returned. Receival of the 0xFF sentinel byte must be han‐
214 dled as an indication that the client's lexer/tokenizer/parser state
215 should be flushed/reset in preparation for reliably receiving the sub‐
216 sequent response. As an optimization, clients may opt to ignore all
217 data until a sentinel value is receiving to avoid unnecessary process‐
218 ing of stale data.
219 Similarly, clients should also precede this request with a 0xFF byte to
221 make sure the guest agent flushes any partially read JSON data from a
222 previous client connection.
223 Arguments
225 id: int
226 randomly generated 64-bit integer
227 Returns
229 The unique integer id passed in by the client
230 Since
232 1.1
233 guest-sync (Command)
235 Echo back a unique integer value
236 This is used by clients talking to the guest agent over the wire to en‐
238 sure the stream is in sync and doesn't contain stale data from previous
239 client. All guest agent responses should be ignored until the provided
240 unique integer value is returned, and it is up to the client to handle
241 stale whole or partially-delivered JSON text in such a way that this
242 response can be obtained.
243 In cases where a partial stale response was previously received by the
245 client, this cannot always be done reliably. One particular scenario
246 being if qemu-ga responses are fed character-by-character into a JSON
247 parser. In these situations, using guest-sync-delimited may be opti‐
248 mal.
249 For clients that fetch responses line by line and convert them to JSON
251 objects, guest-sync should be sufficient, but note that in cases where
252 the channel is dirty some attempts at parsing the response may result
253 in a parser error.
254 Such clients should also precede this command with a 0xFF byte to make
256 sure the guest agent flushes any partially read JSON data from a previ‐
257 ous session.
258 Arguments
260 id: int
261 randomly generated 64-bit integer
262 Returns
264 The unique integer id passed in by the client
265 Since
267 0.15.0
268 guest-ping (Command)
270 Ping the guest agent, a non-error return implies success
271 Since
273 0.15.0
274 guest-get-time (Command)
276 Get the information about guest's System Time relative to the Epoch of
277 1970-01-01 in UTC.
278 Returns
280 Time in nanoseconds.
281 Since
283 1.5
284 guest-set-time (Command)
286 Set guest time.
287 When a guest is paused or migrated to a file then loaded from that
289 file, the guest OS has no idea that there was a big gap in the time.
290 Depending on how long the gap was, NTP might not be able to resynchro‐
291 nize the guest.
292 This command tries to set guest's System Time to the given value, then
294 sets the Hardware Clock (RTC) to the current System Time. This will
295 make it easier for a guest to resynchronize without waiting for NTP. If
296 no time is specified, then the time to set is read from RTC. However,
297 this may not be supported on all platforms (i.e. Windows). If that's
298 the case users are advised to always pass a value.
299 Arguments
301 time: int (optional)
302 time of nanoseconds, relative to the Epoch of 1970-01-01 in UTC.
303 Returns
305 Nothing on success.
306 Since
308 1.5
309 GuestAgentCommandInfo (Object)
311 Information about guest agent commands.
312 Members
314 name: string
315 name of the command
316 enabled: boolean
318 whether command is currently enabled by guest admin
319 success-response: boolean
321 whether command returns a response on success (since 1.7)
322 Since
324 1.1.0
325 GuestAgentInfo (Object)
327 Information about guest agent.
328 Members
330 version: string
331 guest agent version
332 supported_commands: array of GuestAgentCommandInfo
334 Information about guest agent commands
335 Since
337 0.15.0
338 guest-info (Command)
340 Get some information about the guest agent.
341 Returns
343 GuestAgentInfo
344 Since
346 0.15.0
347 guest-shutdown (Command)
349 Initiate guest-activated shutdown. Note: this is an asynchronous shut‐
350 down request, with no guarantee of successful shutdown.
351 Arguments
353 mode: string (optional)
354 "halt", "powerdown" (default), or "reboot"
355 This command does NOT return a response on success. Success condition
356 is indicated by the VM exiting with a zero exit status or, when running
357 with --no-shutdown, by issuing the query-status QMP command to confirm
358 the VM status is "shutdown".
359 Since
361 0.15.0
362 guest-file-open (Command)
364 Open a file in the guest and retrieve a file handle for it
365 Arguments
367 path: string
368 Full path to the file in the guest to open.
369 mode: string (optional)
371 open mode, as per fopen(), "r" is the default.
372 Returns
374 Guest file handle on success.
375 Since
377 0.15.0
378 guest-file-close (Command)
380 Close an open file in the guest
381 Arguments
383 handle: int
384 filehandle returned by guest-file-open
385 Returns
387 Nothing on success.
388 Since
390 0.15.0
391 GuestFileRead (Object)
393 Result of guest agent file-read operation
394 Members
396 count: int
397 number of bytes read (note: count is before base64-encoding is
398 applied)
399 buf-b64: string
401 base64-encoded bytes read
402 eof: boolean
404 whether EOF was encountered during read operation.
405 Since
407 0.15.0
408 guest-file-read (Command)
410 Read from an open file in the guest. Data will be base64-encoded. As
411 this command is just for limited, ad-hoc debugging, such as log file
412 access, the number of bytes to read is limited to 48 MB.
413 Arguments
415 handle: int
416 filehandle returned by guest-file-open
417 count: int (optional)
419 maximum number of bytes to read (default is 4KB, maximum is
420 48MB)
421 Returns
423 GuestFileRead on success.
424 Since
426 0.15.0
427 GuestFileWrite (Object)
429 Result of guest agent file-write operation
430 Members
432 count: int
433 number of bytes written (note: count is actual bytes written,
434 after base64-decoding of provided buffer)
435 eof: boolean
437 whether EOF was encountered during write operation.
438 Since
440 0.15.0
441 guest-file-write (Command)
443 Write to an open file in the guest.
444 Arguments
446 handle: int
447 filehandle returned by guest-file-open
448 buf-b64: string
450 base64-encoded string representing data to be written
451 count: int (optional)
453 bytes to write (actual bytes, after base64-decode), default is
454 all content in buf-b64 buffer after base64 decoding
455 Returns
457 GuestFileWrite on success.
458 Since
460 0.15.0
461 GuestFileSeek (Object)
463 Result of guest agent file-seek operation
464 Members
466 position: int
467 current file position
468 eof: boolean
470 whether EOF was encountered during file seek
471 Since
473 0.15.0
474 QGASeek (Enum)
476 Symbolic names for use in guest-file-seek
477 Values
479 set Set to the specified offset (same effect as 'whence':0)
480 cur Add offset to the current location (same effect as 'whence':1)
482 end Add offset to the end of the file (same effect as 'whence':2)
484 Since
486 2.6
487 GuestFileWhence (Alternate)
489 Controls the meaning of offset to guest-file-seek.
490 Members
492 value: int
493 Integral value (0 for set, 1 for cur, 2 for end), available for
494 historical reasons, and might differ from the host's or guest's
495 SEEK_* values (since: 0.15)
496 name: QGASeek
498 Symbolic name, and preferred interface
499 Since
501 2.6
502 guest-file-seek (Command)
504 Seek to a position in the file, as with fseek(), and return the current
505 file position afterward. Also encapsulates ftell()'s functionality,
506 with offset=0 and whence=1.
507 Arguments
509 handle: int
510 filehandle returned by guest-file-open
511 offset: int
513 bytes to skip over in the file stream
514 whence: GuestFileWhence
516 Symbolic or numeric code for interpreting offset
517 Returns
519 GuestFileSeek on success.
520 Since
522 0.15.0
523 guest-file-flush (Command)
525 Write file changes buffered in userspace to disk/kernel buffers
526 Arguments
528 handle: int
529 filehandle returned by guest-file-open
530 Returns
532 Nothing on success.
533 Since
535 0.15.0
536 GuestFsfreezeStatus (Enum)
538 An enumeration of filesystem freeze states
539 Values
541 thawed filesystems thawed/unfrozen
542 frozen all non-network guest filesystems frozen
544 Since
546 0.15.0
547 guest-fsfreeze-status (Command)
549 Get guest fsfreeze state.
550 Returns
552 GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
553 Note
555 This may fail to properly report the current state as a result of some
556 other guest processes having issued an fs freeze/thaw.
557 Since
559 0.15.0
560 guest-fsfreeze-freeze (Command)
562 Sync and freeze all freezable, local guest filesystems. If this com‐
563 mand succeeded, you may call guest-fsfreeze-thaw later to unfreeze.
564 Note
566 On Windows, the command is implemented with the help of a Volume
567 Shadow-copy Service DLL helper. The frozen state is limited for up to
568 10 seconds by VSS.
569 Returns
571 Number of file systems currently frozen. On error, all filesystems
572 will be thawed. If no filesystems are frozen as a result of this call,
573 then guest-fsfreeze-status will remain "thawed" and calling guest-fs‐
574 freeze-thaw is not necessary.
575 Since
577 0.15.0
578 guest-fsfreeze-freeze-list (Command)
580 Sync and freeze specified guest filesystems. See also guest-fs‐
581 freeze-freeze.
582 Arguments
584 mountpoints: array of string (optional)
585 an array of mountpoints of filesystems to be frozen. If omit‐
586 ted, every mounted filesystem is frozen. Invalid mount points
587 are ignored.
588 Returns
590 Number of file systems currently frozen. On error, all filesystems
591 will be thawed.
592 Since
594 2.2
595 guest-fsfreeze-thaw (Command)
597 Unfreeze all frozen guest filesystems
598 Returns
600 Number of file systems thawed by this call
601 Note
603 if return value does not match the previous call to guest-fs‐
604 freeze-freeze, this likely means some freezable filesystems were un‐
605 frozen before this call, and that the filesystem state may have changed
606 before issuing this command.
607 Since
609 0.15.0
610 GuestFilesystemTrimResult (Object)
612 Members
613 path: string
614 path that was trimmed
615 error: string (optional)
617 an error message when trim failed
618 trimmed: int (optional)
620 bytes trimmed for this path
621 minimum: int (optional)
623 reported effective minimum for this path
624 Since
626 2.4
627 GuestFilesystemTrimResponse (Object)
629 Members
630 paths: array of GuestFilesystemTrimResult
631 list of GuestFilesystemTrimResult per path that was trimmed
632 Since
634 2.4
635 guest-fstrim (Command)
637 Discard (or "trim") blocks which are not in use by the filesystem.
638 Arguments
640 minimum: int (optional)
641 Minimum contiguous free range to discard, in bytes. Free ranges
642 smaller than this may be ignored (this is a hint and the guest
643 may not respect it). By increasing this value, the fstrim oper‐
644 ation will complete more quickly for filesystems with badly
645 fragmented free space, although not all blocks will be dis‐
646 carded. The default value is zero, meaning "discard every free
647 block".
648 Returns
650 A GuestFilesystemTrimResponse which contains the status of all trimmed
651 paths. (since 2.4)
652 Since
654 1.2
655 guest-suspend-disk (Command)
657 Suspend guest to disk.
658 This command attempts to suspend the guest using three strategies, in
660 this order:
661 • systemd hibernate
663 • pm-utils (via pm-hibernate)
665 • manual write into sysfs
667 This command does NOT return a response on success. There is a high
669 chance the command succeeded if the VM exits with a zero exit status
670 or, when running with --no-shutdown, by issuing the query-status QMP
671 command to to confirm the VM status is "shutdown". However, the VM
672 could also exit (or set its status to "shutdown") due to other reasons.
673 The following errors may be returned:
675 • If suspend to disk is not supported, Unsupported
677 Notes
679 It's strongly recommended to issue the guest-sync command before send‐
680 ing commands when the guest resumes
681 Since
683 1.1
684 guest-suspend-ram (Command)
686 Suspend guest to ram.
687 This command attempts to suspend the guest using three strategies, in
689 this order:
690 • systemd hibernate
692 • pm-utils (via pm-hibernate)
694 • manual write into sysfs
696 IMPORTANT: guest-suspend-ram requires working wakeup support in QEMU.
698 You should check QMP command query-current-machine returns wakeup-sus‐
699 pend-support: true before issuing this command. Failure in doing so
700 can result in a suspended guest that QEMU will not be able to awaken,
701 forcing the user to power cycle the guest to bring it back.
702 This command does NOT return a response on success. There are two op‐
704 tions to check for success:
705 1. Wait for the SUSPEND QMP event from QEMU
707 2. Issue the query-status QMP command to confirm the VM status is "sus‐
709 pended"
710 The following errors may be returned:
712 • If suspend to ram is not supported, Unsupported
714 Notes
716 It's strongly recommended to issue the guest-sync command before send‐
717 ing commands when the guest resumes
718 Since
720 1.1
721 guest-suspend-hybrid (Command)
723 Save guest state to disk and suspend to ram.
724 This command attempts to suspend the guest by executing, in this order:
726 • systemd hybrid-sleep
728 • pm-utils (via pm-suspend-hybrid)
730 IMPORTANT: guest-suspend-hybrid requires working wakeup support in
732 QEMU. You should check QMP command query-current-machine returns
733 wakeup-suspend-support: true before issuing this command. Failure in
734 doing so can result in a suspended guest that QEMU will not be able to
735 awaken, forcing the user to power cycle the guest to bring it back.
736 This command does NOT return a response on success. There are two op‐
738 tions to check for success:
739 1. Wait for the SUSPEND QMP event from QEMU
741 2. Issue the query-status QMP command to confirm the VM status is "sus‐
743 pended"
744 The following errors may be returned:
746 • If hybrid suspend is not supported, Unsupported
748 Notes
750 It's strongly recommended to issue the guest-sync command before send‐
751 ing commands when the guest resumes
752 Since
754 1.1
755 GuestIpAddressType (Enum)
757 An enumeration of supported IP address types
758 Values
760 ipv4 IP version 4
761 ipv6 IP version 6
763 Since
765 1.1
766 GuestIpAddress (Object)
768 Members
769 ip-address: string
770 IP address
771 ip-address-type: GuestIpAddressType
773 Type of ip-address (e.g. ipv4, ipv6)
774 prefix: int
776 Network prefix length of ip-address
777 Since
779 1.1
780 GuestNetworkInterfaceStat (Object)
782 Members
783 rx-bytes: int
784 total bytes received
785 rx-packets: int
787 total packets received
788 rx-errs: int
790 bad packets received
791 rx-dropped: int
793 receiver dropped packets
794 tx-bytes: int
796 total bytes transmitted
797 tx-packets: int
799 total packets transmitted
800 tx-errs: int
802 packet transmit problems
803 tx-dropped: int
805 dropped packets transmitted
806 Since
808 2.11
809 GuestNetworkInterface (Object)
811 Members
812 name: string
813 The name of interface for which info are being delivered
814 hardware-address: string (optional)
816 Hardware address of name
817 ip-addresses: array of GuestIpAddress (optional)
819 List of addresses assigned to name
820 statistics: GuestNetworkInterfaceStat (optional)
822 various statistic counters related to name (since 2.11)
823 Since
825 1.1
826 guest-network-get-interfaces (Command)
828 Get list of guest IP addresses, MAC addresses and netmasks.
829 Returns
831 List of GuestNetworkInterface on success.
832 Since
834 1.1
835 GuestLogicalProcessor (Object)
837 Members
838 logical-id: int
839 Arbitrary guest-specific unique identifier of the VCPU.
840 online: boolean
842 Whether the VCPU is enabled.
843 can-offline: boolean (optional)
845 Whether offlining the VCPU is possible. This member is always
846 filled in by the guest agent when the structure is returned, and
847 always ignored on input (hence it can be omitted then).
848 Since
850 1.5
851 guest-get-vcpus (Command)
853 Retrieve the list of the guest's logical processors.
854 This is a read-only operation.
856 Returns
858 The list of all VCPUs the guest knows about. Each VCPU is put on the
859 list exactly once, but their order is unspecified.
860 Since
862 1.5
863 guest-set-vcpus (Command)
865 Attempt to reconfigure (currently: enable/disable) logical processors
866 inside the guest.
867 The input list is processed node by node in order. In each node logi‐
869 cal-id is used to look up the guest VCPU, for which online specifies
870 the requested state. The set of distinct logical-id's is only required
871 to be a subset of the guest-supported identifiers. There's no restric‐
872 tion on list length or on repeating the same logical-id (with possibly
873 different online field). Preferably the input list should describe a
874 modified subset of guest-get-vcpus' return value.
875 Arguments
877 vcpus: array of GuestLogicalProcessor
878 Not documented
879 Returns
881 The length of the initial sublist that has been successfully processed.
882 The guest agent maximizes this value. Possible cases:
883 • 0: if the vcpus list was empty on input. Guest state has not been
885 changed. Otherwise,
886 • Error: processing the first node of vcpus failed for the reason re‐
888 turned. Guest state has not been changed. Otherwise,
889 • < length(vcpus): more than zero initial nodes have been processed,
891 but not the entire vcpus list. Guest state has changed accordingly.
892 To retrieve the error (assuming it persists), repeat the call with
893 the successfully processed initial sublist removed. Otherwise,
894 • length(vcpus): call successful.
896 Since
898 1.5
899 GuestDiskBusType (Enum)
901 An enumeration of bus type of disks
902 Values
904 ide IDE disks
905 fdc floppy disks
907 scsi SCSI disks
909 virtio virtio disks
911 xen Xen disks
913 usb USB disks
915 uml UML disks
917 sata SATA disks
919 sd SD cards
921 unknown
923 Unknown bus type
924 ieee1394
926 Win IEEE 1394 bus type
927 ssa Win SSA bus type
929 fibre Win fiber channel bus type
931 raid Win RAID bus type
933 iscsi Win iScsi bus type
935 sas Win serial-attaches SCSI bus type
937 mmc Win multimedia card (MMC) bus type
939 virtual
941 Win virtual bus type
942 file-backed-virtual
944 Win file-backed bus type
945 nvme NVMe disks (since 7.1)
947 Since
949 2.2; 'Unknown' and all entries below since 2.4
950 GuestPCIAddress (Object)
952 Members
953 domain: int
954 domain id
955 bus: int
957 bus id
958 slot: int
960 slot id
961 function: int
963 function id
964 Since
966 2.2
967 GuestCCWAddress (Object)
969 Members
970 cssid: int
971 channel subsystem image id
972 ssid: int
974 subchannel set id
975 subchno: int
977 subchannel number
978 devno: int
980 device number
981 Since
983 6.0
984 GuestDiskAddress (Object)
986 Members
987 pci-controller: GuestPCIAddress
988 controller's PCI address (fields are set to -1 if invalid)
989 bus-type: GuestDiskBusType
991 bus type
992 bus: int
994 bus id
995 target: int
997 target id
998 unit: int
1000 unit id
1001 serial: string (optional)
1003 serial number (since: 3.1)
1004 dev: string (optional)
1006 device node (POSIX) or device UNC (Windows) (since: 3.1)
1007 ccw-address: GuestCCWAddress (optional)
1009 CCW address on s390x (since: 6.0)
1010 Since
1012 2.2
1013 GuestNVMeSmart (Object)
1015 NVMe smart information, based on NVMe specification, section <SMART /
1016 Health Information (Log Identifier 02h)>
1017 Members
1019 critical-warning: int
1020 Not documented
1021 temperature: int
1023 Not documented
1024 available-spare: int
1026 Not documented
1027 available-spare-threshold: int
1029 Not documented
1030 percentage-used: int
1032 Not documented
1033 data-units-read-lo: int
1035 Not documented
1036 data-units-read-hi: int
1038 Not documented
1039 data-units-written-lo: int
1041 Not documented
1042 data-units-written-hi: int
1044 Not documented
1045 host-read-commands-lo: int
1047 Not documented
1048 host-read-commands-hi: int
1050 Not documented
1051 host-write-commands-lo: int
1053 Not documented
1054 host-write-commands-hi: int
1056 Not documented
1057 controller-busy-time-lo: int
1059 Not documented
1060 controller-busy-time-hi: int
1062 Not documented
1063 power-cycles-lo: int
1065 Not documented
1066 power-cycles-hi: int
1068 Not documented
1069 power-on-hours-lo: int
1071 Not documented
1072 power-on-hours-hi: int
1074 Not documented
1075 unsafe-shutdowns-lo: int
1077 Not documented
1078 unsafe-shutdowns-hi: int
1080 Not documented
1081 media-errors-lo: int
1083 Not documented
1084 media-errors-hi: int
1086 Not documented
1087 number-of-error-log-entries-lo: int
1089 Not documented
1090 number-of-error-log-entries-hi: int
1092 Not documented
1093 Since
1095 7.1
1096 GuestDiskSmart (Object)
1098 Disk type related smart information.
1099 • nvme: NVMe disk smart
1101 Members
1103 type: GuestDiskBusType
1104 Not documented
1105 The members of GuestNVMeSmart when type is "nvme"
1107 Since
1109 7.1
1110 GuestDiskInfo (Object)
1112 Members
1113 name: string
1114 device node (Linux) or device UNC (Windows)
1115 partition: boolean
1117 whether this is a partition or disk
1118 dependencies: array of string (optional)
1120 list of device dependencies; e.g. for LVs of the LVM this will
1121 hold the list of PVs, for LUKS encrypted volume this will con‐
1122 tain the disk where the volume is placed. (Linux)
1123 address: GuestDiskAddress (optional)
1125 disk address information (only for non-virtual devices)
1126 alias: string (optional)
1128 optional alias assigned to the disk, on Linux this is a name as‐
1129 signed by device mapper
1130 smart: GuestDiskSmart (optional)
1132 disk smart information (Since 7.1)
1133 Since
1135 5.2
1136 guest-get-disks (Command)
1138 Returns
1139 The list of disks in the guest. For Windows these are only the physi‐
1140 cal disks. On Linux these are all root block devices of non-zero size
1141 including e.g. removable devices, loop devices, NBD, etc.
1142 Since
1144 5.2
1145 GuestFilesystemInfo (Object)
1147 Members
1148 name: string
1149 disk name
1150 mountpoint: string
1152 mount point path
1153 type: string
1155 file system type string
1156 used-bytes: int (optional)
1158 file system used bytes (since 3.0)
1159 total-bytes: int (optional)
1161 non-root file system total bytes (since 3.0)
1162 disk: array of GuestDiskAddress
1164 an array of disk hardware information that the volume lies on,
1165 which may be empty if the disk type is not supported
1166 Since
1168 2.2
1169 guest-get-fsinfo (Command)
1171 Returns
1172 The list of filesystems information mounted in the guest. The returned
1173 mountpoints may be specified to guest-fsfreeze-freeze-list. Network
1174 filesystems (such as CIFS and NFS) are not listed.
1175 Since
1177 2.2
1178 guest-set-user-password (Command)
1180 Arguments
1181 username: string
1182 the user account whose password to change
1183 password: string
1185 the new password entry string, base64 encoded
1186 crypted: boolean
1188 true if password is already crypt()d, false if raw
1189 If the crypted flag is true, it is the caller's responsibility to en‐
1190 sure the correct crypt() encryption scheme is used. This command does
1191 not attempt to interpret or report on the encryption scheme. Refer to
1192 the documentation of the guest operating system in question to deter‐
1193 mine what is supported.
1194 Not all guest operating systems will support use of the crypted flag,
1196 as they may require the clear-text password
1197 The password parameter must always be base64 encoded before transmis‐
1199 sion, even if already crypt()d, to ensure it is 8-bit safe when passed
1200 as JSON.
1201 Returns
1203 Nothing on success.
1204 Since
1206 2.3
1207 GuestMemoryBlock (Object)
1209 Members
1210 phys-index: int
1211 Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
1212 online: boolean
1214 Whether the MEMORY BLOCK is enabled in guest.
1215 can-offline: boolean (optional)
1217 Whether offlining the MEMORY BLOCK is possible. This member is
1218 always filled in by the guest agent when the structure is re‐
1219 turned, and always ignored on input (hence it can be omitted
1220 then).
1221 Since
1223 2.3
1224 guest-get-memory-blocks (Command)
1226 Retrieve the list of the guest's memory blocks.
1227 This is a read-only operation.
1229 Returns
1231 The list of all memory blocks the guest knows about. Each memory block
1232 is put on the list exactly once, but their order is unspecified.
1233 Since
1235 2.3
1236 GuestMemoryBlockResponseType (Enum)
1238 An enumeration of memory block operation result.
1239 Values
1241 success
1242 the operation of online/offline memory block is successful.
1243 not-found
1245 can't find the corresponding memoryXXX directory in sysfs.
1246 operation-not-supported
1248 for some old kernels, it does not support online or offline mem‐
1249 ory block.
1250 operation-failed
1252 the operation of online/offline memory block fails, because of
1253 some errors happen.
1254 Since
1256 2.3
1257 GuestMemoryBlockResponse (Object)
1259 Members
1260 phys-index: int
1261 same with the 'phys-index' member of GuestMemoryBlock.
1262 response: GuestMemoryBlockResponseType
1264 the result of memory block operation.
1265 error-code: int (optional)
1267 the error number. When memory block operation fails, we assign
1268 the value of 'errno' to this member, it indicates what goes
1269 wrong. When the operation succeeds, it will be omitted.
1270 Since
1272 2.3
1273 guest-set-memory-blocks (Command)
1275 Attempt to reconfigure (currently: enable/disable) state of memory
1276 blocks inside the guest.
1277 The input list is processed node by node in order. In each node
1279 phys-index is used to look up the guest MEMORY BLOCK, for which online
1280 specifies the requested state. The set of distinct phys-index's is
1281 only required to be a subset of the guest-supported identifiers.
1282 There's no restriction on list length or on repeating the same phys-in‐
1283 dex (with possibly different online field). Preferably the input list
1284 should describe a modified subset of guest-get-memory-blocks' return
1285 value.
1286 Arguments
1288 mem-blks: array of GuestMemoryBlock
1289 Not documented
1290 Returns
1292 The operation results, it is a list of GuestMemoryBlockResponse, which
1293 is corresponding to the input list.
1294 Note: it will return NULL if the mem-blks list was empty on input, or
1296 there is an error, and in this case, guest state will not be changed.
1297 Since
1299 2.3
1300 GuestMemoryBlockInfo (Object)
1302 Members
1303 size: int
1304 the size (in bytes) of the guest memory blocks, which are the
1305 minimal units of memory block online/offline operations (also
1306 called Logical Memory Hotplug).
1307 Since
1309 2.3
1310 guest-get-memory-block-info (Command)
1312 Get information relating to guest memory blocks.
1313 Returns
1315 GuestMemoryBlockInfo
1316 Since
1318 2.3
1319 GuestExecStatus (Object)
1321 Members
1322 exited: boolean
1323 true if process has already terminated.
1324 exitcode: int (optional)
1326 process exit code if it was normally terminated.
1327 signal: int (optional)
1329 signal number (linux) or unhandled exception code (windows) if
1330 the process was abnormally terminated.
1331 out-data: string (optional)
1333 base64-encoded stdout of the process
1334 err-data: string (optional)
1336 base64-encoded stderr of the process Note: out-data and err-data
1337 are present only if 'capture-output' was specified for
1338 'guest-exec'
1339 out-truncated: boolean (optional)
1341 true if stdout was not fully captured due to size limitation.
1342 err-truncated: boolean (optional)
1344 true if stderr was not fully captured due to size limitation.
1345 Since
1347 2.5
1348 guest-exec-status (Command)
1350 Check status of process associated with PID retrieved via guest-exec.
1351 Reap the process and associated metadata if it has exited.
1352 Arguments
1354 pid: int
1355 pid returned from guest-exec
1356 Returns
1358 GuestExecStatus on success.
1359 Since
1361 2.5
1362 GuestExec (Object)
1364 Members
1365 pid: int
1366 pid of child process in guest OS
1367 Since
1369 2.5
1370 GuestExecCaptureOutputMode (Enum)
1372 An enumeration of guest-exec capture modes.
1373 Values
1375 none do not capture any output
1376 stdout only capture stdout
1378 stderr only capture stderr
1380 separated
1382 capture both stdout and stderr, but separated into GuestExecSta‐
1383 tus out-data and err-data, respectively
1384 merged (If: not CONFIG_WIN32)
1386 capture both stdout and stderr, but merge together into
1387 out-data. not effective on windows guests.
1388 Since
1390 8.0
1391 GuestExecCaptureOutput (Alternate)
1393 Controls what guest-exec output gets captures.
1394 Members
1396 flag: boolean
1397 captures both stdout and stderr if true. Equivalent to GuestEx‐
1398 ecCaptureOutputMode::all. (since 2.5)
1399 mode: GuestExecCaptureOutputMode
1401 capture mode; preferred interface
1402 Since
1404 8.0
1405 guest-exec (Command)
1407 Execute a command in the guest
1408 Arguments
1410 path: string
1411 path or executable name to execute
1412 arg: array of string (optional)
1414 argument list to pass to executable
1415 env: array of string (optional)
1417 environment variables to pass to executable
1418 input-data: string (optional)
1420 data to be passed to process stdin (base64 encoded)
1421 capture-output: GuestExecCaptureOutput (optional)
1423 bool flag to enable capture of stdout/stderr of running process.
1424 defaults to false.
1425 Returns
1427 PID on success.
1428 Since
1430 2.5
1431 GuestHostName (Object)
1433 Members
1434 host-name: string
1435 Fully qualified domain name of the guest OS
1436 Since
1438 2.10
1439 guest-get-host-name (Command)
1441 Return a name for the machine.
1442 The returned name is not necessarily a fully-qualified domain name, or
1444 even present in DNS or some other name service at all. It need not
1445 even be unique on your local network or site, but usually it is.
1446 Returns
1448 the host name of the machine on success
1449 Since
1451 2.10
1452 GuestUser (Object)
1454 Members
1455 user: string
1456 Username
1457 domain: string (optional)
1459 Logon domain (windows only)
1460 login-time: number
1462 Time of login of this user on the computer. If multiple in‐
1463 stances of the user are logged in, the earliest login time is
1464 reported. The value is in fractional seconds since epoch time.
1465 Since
1467 2.10
1468 guest-get-users (Command)
1470 Retrieves a list of currently active users on the VM.
1471 Returns
1473 A unique list of users.
1474 Since
1476 2.10
1477 GuestTimezone (Object)
1479 Members
1480 zone: string (optional)
1481 Timezone name. These values may differ depending on guest/OS
1482 and should only be used for informational purposes.
1483 offset: int
1485 Offset to UTC in seconds, negative numbers for time zones west
1486 of GMT, positive numbers for east
1487 Since
1489 2.10
1490 guest-get-timezone (Command)
1492 Retrieves the timezone information from the guest.
1493 Returns
1495 A GuestTimezone dictionary.
1496 Since
1498 2.10
1499 GuestOSInfo (Object)
1501 Members
1502 kernel-release: string (optional)
1503 • POSIX: release field returned by uname(2)
1505 • Windows: build number of the OS
1507 kernel-version: string (optional)
1509 • POSIX: version field returned by uname(2)
1511 • Windows: version number of the OS
1513 machine: string (optional)
1515 • POSIX: machine field returned by uname(2)
1517 • Windows: one of x86, x86_64, arm, ia64
1519 id: string (optional)
1521 • POSIX: as defined by os-release(5)
1523 • Windows: contains string "mswindows"
1525 name: string (optional)
1527 • POSIX: as defined by os-release(5)
1529 • Windows: contains string "Microsoft Windows"
1531 pretty-name: string (optional)
1533 • POSIX: as defined by os-release(5)
1535 • Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1537 version: string (optional)
1539 • POSIX: as defined by os-release(5)
1541 • Windows: long version string, e.g. "Microsoft Windows Server
1543 2008"
1544 version-id: string (optional)
1546 • POSIX: as defined by os-release(5)
1548 • Windows: short version identifier, e.g. "7" or "20012r2"
1550 variant: string (optional)
1552 • POSIX: as defined by os-release(5)
1554 • Windows: contains string "server" or "client"
1556 variant-id: string (optional)
1558 • POSIX: as defined by os-release(5)
1560 • Windows: contains string "server" or "client"
1562 Notes
1564 On POSIX systems the fields id, name, pretty-name, version, version-id,
1565 variant and variant-id follow the definition specified in os-re‐
1566 lease(5). Refer to the manual page for exact description of the fields.
1567 Their values are taken from the os-release file. If the file is not
1568 present in the system, or the values are not present in the file, the
1569 fields are not included.
1570 On Windows the values are filled from information gathered from the
1572 system.
1573 Since
1575 2.10
1576 guest-get-osinfo (Command)
1578 Retrieve guest operating system information
1579 Returns
1581 GuestOSInfo
1582 Since
1584 2.10
1585 GuestDeviceType (Enum)
1587 Values
1588 pci Not documented
1589 GuestDeviceIdPCI (Object)
1591 Members
1592 vendor-id: int
1593 vendor ID
1594 device-id: int
1596 device ID
1597 Since
1599 5.2
1600 GuestDeviceId (Object)
1602 Id of the device - pci: PCI ID, since: 5.2
1603 Members
1605 type: GuestDeviceType
1606 Not documented
1607 The members of GuestDeviceIdPCI when type is "pci"
1609 Since
1611 5.2
1612 GuestDeviceInfo (Object)
1614 Members
1615 driver-name: string
1616 name of the associated driver
1617 driver-date: int (optional)
1619 driver release date, in nanoseconds since the epoch
1620 driver-version: string (optional)
1622 driver version
1623 id: GuestDeviceId (optional)
1625 device ID
1626 Since
1628 5.2
1629 guest-get-devices (Command)
1631 Retrieve information about device drivers in Windows guest
1632 Returns
1634 GuestDeviceInfo
1635 Since
1637 5.2
1638 GuestAuthorizedKeys (Object)
1640 Members
1641 keys: array of string
1642 public keys (in OpenSSH/sshd(8) authorized_keys format)
1643 Since
1645 5.2
1646 If
1648 CONFIG_POSIX
1649 guest-ssh-get-authorized-keys (Command)
1651 Arguments
1652 username: string
1653 the user account to add the authorized keys
1654 Return the public keys from user .ssh/authorized_keys on Unix systems
1655 (not implemented for other systems).
1656 Returns
1658 GuestAuthorizedKeys
1659 Since
1661 5.2
1662 If
1664 CONFIG_POSIX
1665 guest-ssh-add-authorized-keys (Command)
1667 Arguments
1668 username: string
1669 the user account to add the authorized keys
1670 keys: array of string
1672 the public keys to add (in OpenSSH/sshd(8) authorized_keys for‐
1673 mat)
1674 reset: boolean (optional)
1676 ignore the existing content, set it with the given keys only
1677 Append public keys to user .ssh/authorized_keys on Unix systems (not
1678 implemented for other systems).
1679 Returns
1681 Nothing on success.
1682 Since
1684 5.2
1685 If
1687 CONFIG_POSIX
1688 guest-ssh-remove-authorized-keys (Command)
1690 Arguments
1691 username: string
1692 the user account to remove the authorized keys
1693 keys: array of string
1695 the public keys to remove (in OpenSSH/sshd(8) authorized_keys
1696 format)
1697 Remove public keys from the user .ssh/authorized_keys on Unix systems
1698 (not implemented for other systems). It's not an error if the key is
1699 already missing.
1700 Returns
1702 Nothing on success.
1703 Since
1705 5.2
1706 If
1708 CONFIG_POSIX
1709 GuestDiskStats (Object)
1711 Members
1712 read-sectors: int (optional)
1713 sectors read
1714 read-ios: int (optional)
1716 reads completed successfully
1717 read-merges: int (optional)
1719 read requests merged
1720 write-sectors: int (optional)
1722 sectors written
1723 write-ios: int (optional)
1725 writes completed
1726 write-merges: int (optional)
1728 write requests merged
1729 discard-sectors: int (optional)
1731 sectors discarded
1732 discard-ios: int (optional)
1734 discards completed successfully
1735 discard-merges: int (optional)
1737 discard requests merged
1738 flush-ios: int (optional)
1740 flush requests completed successfully
1741 read-ticks: int (optional)
1743 time spent reading(ms)
1744 write-ticks: int (optional)
1746 time spent writing(ms)
1747 discard-ticks: int (optional)
1749 time spent discarding(ms)
1750 flush-ticks: int (optional)
1752 time spent flushing(ms)
1753 ios-pgr: int (optional)
1755 number of I/Os currently in flight
1756 total-ticks: int (optional)
1758 time spent doing I/Os (ms)
1759 weight-ticks: int (optional)
1761 weighted time spent doing I/Os since the last update of this
1762 field(ms)
1763 Since
1765 7.1
1766 GuestDiskStatsInfo (Object)
1768 Members
1769 name: string
1770 disk name
1771 major: int
1773 major device number of disk
1774 minor: int
1776 minor device number of disk
1777 stats: GuestDiskStats
1779 Not documented
1780 guest-get-diskstats (Command)
1782 Retrieve information about disk stats.
1783 Returns
1785 List of disk stats of guest.
1786 Since
1788 7.1
1789 GuestCpuStatsType (Enum)
1791 An enumeration of OS type
1792 Values
1794 linux Not documented
1795 Since
1797 7.1
1798 GuestLinuxCpuStats (Object)
1800 CPU statistics of Linux
1801 Members
1803 cpu: int
1804 CPU index in guest OS
1805 user: int
1807 Time spent in user mode
1808 nice: int
1810 Time spent in user mode with low priority (nice)
1811 system: int
1813 Time spent in system mode
1814 idle: int
1816 Time spent in the idle task
1817 iowait: int (optional)
1819 Time waiting for I/O to complete (since Linux 2.5.41)
1820 irq: int (optional)
1822 Time servicing interrupts (since Linux 2.6.0-test4)
1823 softirq: int (optional)
1825 Time servicing softirqs (since Linux 2.6.0-test4)
1826 steal: int (optional)
1828 Stolen time by host (since Linux 2.6.11)
1829 guest: int (optional)
1831 ime spent running a virtual CPU for guest operating systems un‐
1832 der the control of the Linux kernel (since Linux 2.6.24)
1833 guestnice: int (optional)
1835 Time spent running a niced guest (since Linux 2.6.33)
1836 Since
1838 7.1
1839 GuestCpuStats (Object)
1841 Get statistics of each CPU in millisecond.
1842 • linux: Linux style CPU statistics
1844 Members
1846 type: GuestCpuStatsType
1847 Not documented
1848 The members of GuestLinuxCpuStats when type is "linux"
1850 Since
1852 7.1
1853 guest-get-cpustats (Command)
1855 Retrieve information about CPU stats.
1856 Returns
1858 List of CPU stats of guest.
1859 Since
1861 7.1
1862
1864 2023, The QEMU Project Developers
18658.1.3 Nov 28, 2023 QEMU-GA-REF(7)