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 • GuestDiskInfo (Object)
107 • guest-get-disks (Command)
109 • GuestFilesystemInfo (Object)
111 • guest-get-fsinfo (Command)
113 • guest-set-user-password (Command)
115 • GuestMemoryBlock (Object)
117 • guest-get-memory-blocks (Command)
119 • GuestMemoryBlockResponseType (Enum)
121 • GuestMemoryBlockResponse (Object)
123 • guest-set-memory-blocks (Command)
125 • GuestMemoryBlockInfo (Object)
127 • guest-get-memory-block-info (Command)
129 • GuestExecStatus (Object)
131 • guest-exec-status (Command)
133 • GuestExec (Object)
135 • guest-exec (Command)
137 • GuestHostName (Object)
139 • guest-get-host-name (Command)
141 • GuestUser (Object)
143 • guest-get-users (Command)
145 • GuestTimezone (Object)
147 • guest-get-timezone (Command)
149 • GuestOSInfo (Object)
151 • guest-get-osinfo (Command)
153 • GuestDeviceType (Enum)
155 • GuestDeviceIdPCI (Object)
157 • GuestDeviceId (Object)
159 • GuestDeviceInfo (Object)
161 • guest-get-devices (Command)
163 • GuestAuthorizedKeys (Object)
165 • guest-ssh-get-authorized-keys (Command)
167 • guest-ssh-add-authorized-keys (Command)
169 • guest-ssh-remove-authorized-keys (Command)
171
173 "unsupported" is a higher-level error than the errors that individual
174 commands might document. The caller should always be prepared to re‐
175 ceive QERR_UNSUPPORTED, even if the given command doesn't specify it,
176 or doesn't document any failure mode at all.
177
179 guest-sync-delimited (Command)
180 Echo back a unique integer value, and prepend to response a leading
181 sentinel byte (0xFF) the client can check scan for.
182 This is used by clients talking to the guest agent over the wire to en‐
184 sure the stream is in sync and doesn't contain stale data from previous
185 client. It must be issued upon initial connection, and after any
186 client-side timeouts (including timeouts on receiving a response to
187 this command).
188 After issuing this request, all guest agent responses should be ignored
190 until the response containing the unique integer value the client
191 passed in is returned. Receival of the 0xFF sentinel byte must be han‐
192 dled as an indication that the client's lexer/tokenizer/parser state
193 should be flushed/reset in preparation for reliably receiving the sub‐
194 sequent response. As an optimization, clients may opt to ignore all
195 data until a sentinel value is receiving to avoid unnecessary process‐
196 ing of stale data.
197 Similarly, clients should also precede this request with a 0xFF byte to
199 make sure the guest agent flushes any partially read JSON data from a
200 previous client connection.
201 Arguments
203 id: int
204 randomly generated 64-bit integer
205 Returns
207 The unique integer id passed in by the client
208 Since
210 1.1
211 guest-sync (Command)
213 Echo back a unique integer value
214 This is used by clients talking to the guest agent over the wire to en‐
216 sure the stream is in sync and doesn't contain stale data from previous
217 client. All guest agent responses should be ignored until the provided
218 unique integer value is returned, and it is up to the client to handle
219 stale whole or partially-delivered JSON text in such a way that this
220 response can be obtained.
221 In cases where a partial stale response was previously received by the
223 client, this cannot always be done reliably. One particular scenario
224 being if qemu-ga responses are fed character-by-character into a JSON
225 parser. In these situations, using guest-sync-delimited may be optimal.
226 For clients that fetch responses line by line and convert them to JSON
228 objects, guest-sync should be sufficient, but note that in cases where
229 the channel is dirty some attempts at parsing the response may result
230 in a parser error.
231 Such clients should also precede this command with a 0xFF byte to make
233 sure the guest agent flushes any partially read JSON data from a previ‐
234 ous session.
235 Arguments
237 id: int
238 randomly generated 64-bit integer
239 Returns
241 The unique integer id passed in by the client
242 Since
244 0.15.0
245 guest-ping (Command)
247 Ping the guest agent, a non-error return implies success
248 Since
250 0.15.0
251 guest-get-time (Command)
253 Get the information about guest's System Time relative to the Epoch of
254 1970-01-01 in UTC.
255 Returns
257 Time in nanoseconds.
258 Since
260 1.5
261 guest-set-time (Command)
263 Set guest time.
264 When a guest is paused or migrated to a file then loaded from that
266 file, the guest OS has no idea that there was a big gap in the time.
267 Depending on how long the gap was, NTP might not be able to resynchro‐
268 nize the guest.
269 This command tries to set guest's System Time to the given value, then
271 sets the Hardware Clock (RTC) to the current System Time. This will
272 make it easier for a guest to resynchronize without waiting for NTP. If
273 no time is specified, then the time to set is read from RTC. However,
274 this may not be supported on all platforms (i.e. Windows). If that's
275 the case users are advised to always pass a value.
276 Arguments
278 time: int (optional)
279 time of nanoseconds, relative to the Epoch of 1970-01-01 in UTC.
280 Returns
282 Nothing on success.
283 Since
285 1.5
286 GuestAgentCommandInfo (Object)
288 Information about guest agent commands.
289 Members
291 name: string
292 name of the command
293 enabled: boolean
295 whether command is currently enabled by guest admin
296 success-response: boolean
298 whether command returns a response on success (since 1.7)
299 Since
301 1.1.0
302 GuestAgentInfo (Object)
304 Information about guest agent.
305 Members
307 version: string
308 guest agent version
309 supported_commands: array of GuestAgentCommandInfo
311 Information about guest agent commands
312 Since
314 0.15.0
315 guest-info (Command)
317 Get some information about the guest agent.
318 Returns
320 GuestAgentInfo
321 Since
323 0.15.0
324 guest-shutdown (Command)
326 Initiate guest-activated shutdown. Note: this is an asynchronous shut‐
327 down request, with no guarantee of successful shutdown.
328 Arguments
330 mode: string (optional)
331 "halt", "powerdown" (default), or "reboot"
332 This command does NOT return a response on success. Success condition
333 is indicated by the VM exiting with a zero exit status or, when running
334 with --no-shutdown, by issuing the query-status QMP command to confirm
335 the VM status is "shutdown".
336 Since
338 0.15.0
339 guest-file-open (Command)
341 Open a file in the guest and retrieve a file handle for it
342 Arguments
344 path: string
345 Full path to the file in the guest to open.
346 mode: string (optional)
348 open mode, as per fopen(), "r" is the default.
349 Returns
351 Guest file handle on success.
352 Since
354 0.15.0
355 guest-file-close (Command)
357 Close an open file in the guest
358 Arguments
360 handle: int
361 filehandle returned by guest-file-open
362 Returns
364 Nothing on success.
365 Since
367 0.15.0
368 GuestFileRead (Object)
370 Result of guest agent file-read operation
371 Members
373 count: int
374 number of bytes read (note: count is before base64-encoding is
375 applied)
376 buf-b64: string
378 base64-encoded bytes read
379 eof: boolean
381 whether EOF was encountered during read operation.
382 Since
384 0.15.0
385 guest-file-read (Command)
387 Read from an open file in the guest. Data will be base64-encoded. As
388 this command is just for limited, ad-hoc debugging, such as log file
389 access, the number of bytes to read is limited to 48 MB.
390 Arguments
392 handle: int
393 filehandle returned by guest-file-open
394 count: int (optional)
396 maximum number of bytes to read (default is 4KB, maximum is
397 48MB)
398 Returns
400 GuestFileRead on success.
401 Since
403 0.15.0
404 GuestFileWrite (Object)
406 Result of guest agent file-write operation
407 Members
409 count: int
410 number of bytes written (note: count is actual bytes written,
411 after base64-decoding of provided buffer)
412 eof: boolean
414 whether EOF was encountered during write operation.
415 Since
417 0.15.0
418 guest-file-write (Command)
420 Write to an open file in the guest.
421 Arguments
423 handle: int
424 filehandle returned by guest-file-open
425 buf-b64: string
427 base64-encoded string representing data to be written
428 count: int (optional)
430 bytes to write (actual bytes, after base64-decode), default is
431 all content in buf-b64 buffer after base64 decoding
432 Returns
434 GuestFileWrite on success.
435 Since
437 0.15.0
438 GuestFileSeek (Object)
440 Result of guest agent file-seek operation
441 Members
443 position: int
444 current file position
445 eof: boolean
447 whether EOF was encountered during file seek
448 Since
450 0.15.0
451 QGASeek (Enum)
453 Symbolic names for use in guest-file-seek
454 Values
456 set Set to the specified offset (same effect as 'whence':0)
457 cur Add offset to the current location (same effect as 'whence':1)
459 end Add offset to the end of the file (same effect as 'whence':2)
461 Since
463 2.6
464 GuestFileWhence (Alternate)
466 Controls the meaning of offset to guest-file-seek.
467 Members
469 value: int
470 Integral value (0 for set, 1 for cur, 2 for end), available for
471 historical reasons, and might differ from the host's or guest's
472 SEEK_* values (since: 0.15)
473 name: QGASeek
475 Symbolic name, and preferred interface
476 Since
478 2.6
479 guest-file-seek (Command)
481 Seek to a position in the file, as with fseek(), and return the current
482 file position afterward. Also encapsulates ftell()'s functionality,
483 with offset=0 and whence=1.
484 Arguments
486 handle: int
487 filehandle returned by guest-file-open
488 offset: int
490 bytes to skip over in the file stream
491 whence: GuestFileWhence
493 Symbolic or numeric code for interpreting offset
494 Returns
496 GuestFileSeek on success.
497 Since
499 0.15.0
500 guest-file-flush (Command)
502 Write file changes bufferred in userspace to disk/kernel buffers
503 Arguments
505 handle: int
506 filehandle returned by guest-file-open
507 Returns
509 Nothing on success.
510 Since
512 0.15.0
513 GuestFsfreezeStatus (Enum)
515 An enumeration of filesystem freeze states
516 Values
518 thawed filesystems thawed/unfrozen
519 frozen all non-network guest filesystems frozen
521 Since
523 0.15.0
524 guest-fsfreeze-status (Command)
526 Get guest fsfreeze state. error state indicates
527 Returns
529 GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
530 Note
532 This may fail to properly report the current state as a result of some
533 other guest processes having issued an fs freeze/thaw.
534 Since
536 0.15.0
537 guest-fsfreeze-freeze (Command)
539 Sync and freeze all freezable, local guest filesystems. If this command
540 succeeded, you may call guest-fsfreeze-thaw later to unfreeze.
541 Note
543 On Windows, the command is implemented with the help of a Volume
544 Shadow-copy Service DLL helper. The frozen state is limited for up to
545 10 seconds by VSS.
546 Returns
548 Number of file systems currently frozen. On error, all filesystems will
549 be thawed. If no filesystems are frozen as a result of this call, then
550 guest-fsfreeze-status will remain "thawed" and calling guest-fs‐
551 freeze-thaw is not necessary.
552 Since
554 0.15.0
555 guest-fsfreeze-freeze-list (Command)
557 Sync and freeze specified guest filesystems. See also guest-fs‐
558 freeze-freeze.
559 Arguments
561 mountpoints: array of string (optional)
562 an array of mountpoints of filesystems to be frozen. If omit‐
563 ted, every mounted filesystem is frozen. Invalid mount points
564 are ignored.
565 Returns
567 Number of file systems currently frozen. On error, all filesystems will
568 be thawed.
569 Since
571 2.2
572 guest-fsfreeze-thaw (Command)
574 Unfreeze all frozen guest filesystems
575 Returns
577 Number of file systems thawed by this call
578 Note
580 if return value does not match the previous call to guest-fs‐
581 freeze-freeze, this likely means some freezable filesystems were un‐
582 frozen before this call, and that the filesystem state may have changed
583 before issuing this command.
584 Since
586 0.15.0
587 GuestFilesystemTrimResult (Object)
589 Members
590 path: string
591 path that was trimmed
592 error: string (optional)
594 an error message when trim failed
595 trimmed: int (optional)
597 bytes trimmed for this path
598 minimum: int (optional)
600 reported effective minimum for this path
601 Since
603 2.4
604 GuestFilesystemTrimResponse (Object)
606 Members
607 paths: array of GuestFilesystemTrimResult
608 list of GuestFilesystemTrimResult per path that was trimmed
609 Since
611 2.4
612 guest-fstrim (Command)
614 Discard (or "trim") blocks which are not in use by the filesystem.
615 Arguments
617 minimum: int (optional)
618 Minimum contiguous free range to discard, in bytes. Free ranges
619 smaller than this may be ignored (this is a hint and the guest
620 may not respect it). By increasing this value, the fstrim oper‐
621 ation will complete more quickly for filesystems with badly
622 fragmented free space, although not all blocks will be dis‐
623 carded. The default value is zero, meaning "discard every free
624 block".
625 Returns
627 A GuestFilesystemTrimResponse which contains the status of all trimmed
628 paths. (since 2.4)
629 Since
631 1.2
632 guest-suspend-disk (Command)
634 Suspend guest to disk.
635 This command attempts to suspend the guest using three strategies, in
637 this order:
638 • systemd hibernate
640 • pm-utils (via pm-hibernate)
642 • manual write into sysfs
644 This command does NOT return a response on success. There is a high
646 chance the command succeeded if the VM exits with a zero exit status
647 or, when running with --no-shutdown, by issuing the query-status QMP
648 command to to confirm the VM status is "shutdown". However, the VM
649 could also exit (or set its status to "shutdown") due to other reasons.
650 The following errors may be returned:
652 • If suspend to disk is not supported, Unsupported
654 Notes
656 It's strongly recommended to issue the guest-sync command before send‐
657 ing commands when the guest resumes
658 Since
660 1.1
661 guest-suspend-ram (Command)
663 Suspend guest to ram.
664 This command attempts to suspend the guest using three strategies, in
666 this order:
667 • systemd suspend
669 • pm-utils (via pm-suspend)
671 • manual write into sysfs
673 IMPORTANT: guest-suspend-ram requires working wakeup support in QEMU.
675 You should check QMP command query-current-machine returns wakeup-sus‐
676 pend-support: true before issuing this command. Failure in doing so can
677 result in a suspended guest that QEMU will not be able to awaken, forc‐
678 ing the user to power cycle the guest to bring it back.
679 This command does NOT return a response on success. There are two op‐
681 tions to check for success:
682 1. Wait for the SUSPEND QMP event from QEMU
684 2. Issue the query-status QMP command to confirm the VM status is "sus‐
686 pended"
687 The following errors may be returned:
689 • If suspend to ram is not supported, Unsupported
691 Notes
693 It's strongly recommended to issue the guest-sync command before send‐
694 ing commands when the guest resumes
695 Since
697 1.1
698 guest-suspend-hybrid (Command)
700 Save guest state to disk and suspend to ram.
701 This command attempts to suspend the guest by executing, in this order:
703 • systemd hybrid-sleep
705 • pm-utils (via pm-suspend-hybrid)
707 IMPORTANT: guest-suspend-hybrid requires working wakeup support in
709 QEMU. You should check QMP command query-current-machine returns
710 wakeup-suspend-support: true before issuing this command. Failure in
711 doing so can result in a suspended guest that QEMU will not be able to
712 awaken, forcing the user to power cycle the guest to bring it back.
713 This command does NOT return a response on success. There are two op‐
715 tions to check for success:
716 1. Wait for the SUSPEND QMP event from QEMU
718 2. Issue the query-status QMP command to confirm the VM status is "sus‐
720 pended"
721 The following errors may be returned:
723 • If hybrid suspend is not supported, Unsupported
725 Notes
727 It's strongly recommended to issue the guest-sync command before send‐
728 ing commands when the guest resumes
729 Since
731 1.1
732 GuestIpAddressType (Enum)
734 An enumeration of supported IP address types
735 Values
737 ipv4 IP version 4
738 ipv6 IP version 6
740 Since
742 1.1
743 GuestIpAddress (Object)
745 Members
746 ip-address: string
747 IP address
748 ip-address-type: GuestIpAddressType
750 Type of ip-address (e.g. ipv4, ipv6)
751 prefix: int
753 Network prefix length of ip-address
754 Since
756 1.1
757 GuestNetworkInterfaceStat (Object)
759 Members
760 rx-bytes: int
761 total bytes received
762 rx-packets: int
764 total packets received
765 rx-errs: int
767 bad packets received
768 rx-dropped: int
770 receiver dropped packets
771 tx-bytes: int
773 total bytes transmitted
774 tx-packets: int
776 total packets transmitted
777 tx-errs: int
779 packet transmit problems
780 tx-dropped: int
782 dropped packets transmitted
783 Since
785 2.11
786 GuestNetworkInterface (Object)
788 Members
789 name: string
790 The name of interface for which info are being delivered
791 hardware-address: string (optional)
793 Hardware address of name
794 ip-addresses: array of GuestIpAddress (optional)
796 List of addresses assigned to name
797 statistics: GuestNetworkInterfaceStat (optional)
799 various statistic counters related to name (since 2.11)
800 Since
802 1.1
803 guest-network-get-interfaces (Command)
805 Get list of guest IP addresses, MAC addresses and netmasks.
806 Returns
808 List of GuestNetworkInfo on success.
809 Since
811 1.1
812 GuestLogicalProcessor (Object)
814 Members
815 logical-id: int
816 Arbitrary guest-specific unique identifier of the VCPU.
817 online: boolean
819 Whether the VCPU is enabled.
820 can-offline: boolean (optional)
822 Whether offlining the VCPU is possible. This member is always
823 filled in by the guest agent when the structure is returned, and
824 always ignored on input (hence it can be omitted then).
825 Since
827 1.5
828 guest-get-vcpus (Command)
830 Retrieve the list of the guest's logical processors.
831 This is a read-only operation.
833 Returns
835 The list of all VCPUs the guest knows about. Each VCPU is put on the
836 list exactly once, but their order is unspecified.
837 Since
839 1.5
840 guest-set-vcpus (Command)
842 Attempt to reconfigure (currently: enable/disable) logical processors
843 inside the guest.
844 The input list is processed node by node in order. In each node logi‐
846 cal-id is used to look up the guest VCPU, for which online specifies
847 the requested state. The set of distinct logical-id's is only required
848 to be a subset of the guest-supported identifiers. There's no restric‐
849 tion on list length or on repeating the same logical-id (with possibly
850 different online field). Preferably the input list should describe a
851 modified subset of guest-get-vcpus' return value.
852 Arguments
854 vcpus: array of GuestLogicalProcessor
855 Not documented
856 Returns
858 The length of the initial sublist that has been successfully processed.
859 The guest agent maximizes this value. Possible cases:
860 • 0: if the vcpus list was empty on input. Guest state has not been
862 changed. Otherwise,
863 • Error: processing the first node of vcpus failed for the reason re‐
865 turned. Guest state has not been changed. Otherwise,
866 • < length(vcpus): more than zero initial nodes have been processed,
868 but not the entire vcpus list. Guest state has changed accordingly.
869 To retrieve the error (assuming it persists), repeat the call with
870 the successfully processed initial sublist removed. Otherwise,
871 • length(vcpus): call successful.
873 Since
875 1.5
876 GuestDiskBusType (Enum)
878 An enumeration of bus type of disks
879 Values
881 ide IDE disks
882 fdc floppy disks
884 scsi SCSI disks
886 virtio virtio disks
888 xen Xen disks
890 usb USB disks
892 uml UML disks
894 sata SATA disks
896 sd SD cards
898 unknown
900 Unknown bus type
901 ieee1394
903 Win IEEE 1394 bus type
904 ssa Win SSA bus type
906 fibre Win fiber channel bus type
908 raid Win RAID bus type
910 iscsi Win iScsi bus type
912 sas Win serial-attaches SCSI bus type
914 mmc Win multimedia card (MMC) bus type
916 virtual
918 Win virtual bus type
919 file-backed-virtual
921 Win file-backed bus type
922 Since
924 2.2; 'Unknown' and all entries below since 2.4
925 GuestPCIAddress (Object)
927 Members
928 domain: int
929 domain id
930 bus: int
932 bus id
933 slot: int
935 slot id
936 function: int
938 function id
939 Since
941 2.2
942 GuestCCWAddress (Object)
944 Members
945 cssid: int
946 channel subsystem image id
947 ssid: int
949 subchannel set id
950 subchno: int
952 subchannel number
953 devno: int
955 device number
956 Since
958 6.0
959 GuestDiskAddress (Object)
961 Members
962 pci-controller: GuestPCIAddress
963 controller's PCI address (fields are set to -1 if invalid)
964 bus-type: GuestDiskBusType
966 bus type
967 bus: int
969 bus id
970 target: int
972 target id
973 unit: int
975 unit id
976 serial: string (optional)
978 serial number (since: 3.1)
979 dev: string (optional)
981 device node (POSIX) or device UNC (Windows) (since: 3.1)
982 ccw-address: GuestCCWAddress (optional)
984 CCW address on s390x (since: 6.0)
985 Since
987 2.2
988 GuestDiskInfo (Object)
990 Members
991 name: string
992 device node (Linux) or device UNC (Windows)
993 partition: boolean
995 whether this is a partition or disk
996 dependencies: array of string (optional)
998 list of device dependencies; e.g. for LVs of the LVM this will
999 hold the list of PVs, for LUKS encrypted volume this will con‐
1000 tain the disk where the volume is placed. (Linux)
1001 address: GuestDiskAddress (optional)
1003 disk address information (only for non-virtual devices)
1004 alias: string (optional)
1006 optional alias assigned to the disk, on Linux this is a name as‐
1007 signed by device mapper
1008 Since 5.2
1009 guest-get-disks (Command)
1011 Returns
1012 The list of disks in the guest. For Windows these are only the physical
1013 disks. On Linux these are all root block devices of non-zero size in‐
1014 cluding e.g. removable devices, loop devices, NBD, etc.
1015 Since
1017 5.2
1018 GuestFilesystemInfo (Object)
1020 Members
1021 name: string
1022 disk name
1023 mountpoint: string
1025 mount point path
1026 type: string
1028 file system type string
1029 used-bytes: int (optional)
1031 file system used bytes (since 3.0)
1032 total-bytes: int (optional)
1034 non-root file system total bytes (since 3.0)
1035 disk: array of GuestDiskAddress
1037 an array of disk hardware information that the volume lies on,
1038 which may be empty if the disk type is not supported
1039 Since
1041 2.2
1042 guest-get-fsinfo (Command)
1044 Returns
1045 The list of filesystems information mounted in the guest. The returned
1046 mountpoints may be specified to guest-fsfreeze-freeze-list. Network
1047 filesystems (such as CIFS and NFS) are not listed.
1048 Since
1050 2.2
1051 guest-set-user-password (Command)
1053 Arguments
1054 username: string
1055 the user account whose password to change
1056 password: string
1058 the new password entry string, base64 encoded
1059 crypted: boolean
1061 true if password is already crypt()d, false if raw
1062 If the crypted flag is true, it is the caller's responsibility to en‐
1063 sure the correct crypt() encryption scheme is used. This command does
1064 not attempt to interpret or report on the encryption scheme. Refer to
1065 the documentation of the guest operating system in question to deter‐
1066 mine what is supported.
1067 Not all guest operating systems will support use of the crypted flag,
1069 as they may require the clear-text password
1070 The password parameter must always be base64 encoded before transmis‐
1072 sion, even if already crypt()d, to ensure it is 8-bit safe when passed
1073 as JSON.
1074 Returns
1076 Nothing on success.
1077 Since
1079 2.3
1080 GuestMemoryBlock (Object)
1082 Members
1083 phys-index: int
1084 Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
1085 online: boolean
1087 Whether the MEMORY BLOCK is enabled in guest.
1088 can-offline: boolean (optional)
1090 Whether offlining the MEMORY BLOCK is possible. This member is
1091 always filled in by the guest agent when the structure is re‐
1092 turned, and always ignored on input (hence it can be omitted
1093 then).
1094 Since
1096 2.3
1097 guest-get-memory-blocks (Command)
1099 Retrieve the list of the guest's memory blocks.
1100 This is a read-only operation.
1102 Returns
1104 The list of all memory blocks the guest knows about. Each memory block
1105 is put on the list exactly once, but their order is unspecified.
1106 Since
1108 2.3
1109 GuestMemoryBlockResponseType (Enum)
1111 An enumeration of memory block operation result.
1112 Values
1114 success
1115 the operation of online/offline memory block is successful.
1116 not-found
1118 can't find the corresponding memoryXXX directory in sysfs.
1119 operation-not-supported
1121 for some old kernels, it does not support online or offline mem‐
1122 ory block.
1123 operation-failed
1125 the operation of online/offline memory block fails, because of
1126 some errors happen.
1127 Since
1129 2.3
1130 GuestMemoryBlockResponse (Object)
1132 Members
1133 phys-index: int
1134 same with the 'phys-index' member of GuestMemoryBlock.
1135 response: GuestMemoryBlockResponseType
1137 the result of memory block operation.
1138 error-code: int (optional)
1140 the error number. When memory block operation fails, we assign
1141 the value of 'errno' to this member, it indicates what goes
1142 wrong. When the operation succeeds, it will be omitted.
1143 Since
1145 2.3
1146 guest-set-memory-blocks (Command)
1148 Attempt to reconfigure (currently: enable/disable) state of memory
1149 blocks inside the guest.
1150 The input list is processed node by node in order. In each node
1152 phys-index is used to look up the guest MEMORY BLOCK, for which online
1153 specifies the requested state. The set of distinct phys-index's is only
1154 required to be a subset of the guest-supported identifiers. There's no
1155 restriction on list length or on repeating the same phys-index (with
1156 possibly different online field). Preferably the input list should de‐
1157 scribe a modified subset of guest-get-memory-blocks' return value.
1158 Arguments
1160 mem-blks: array of GuestMemoryBlock
1161 Not documented
1162 Returns
1164 The operation results, it is a list of GuestMemoryBlockResponse, which
1165 is corresponding to the input list.
1166 Note: it will return NULL if the mem-blks list was empty on input, or
1168 there is an error, and in this case, guest state will not be changed.
1169 Since
1171 2.3
1172 GuestMemoryBlockInfo (Object)
1174 Members
1175 size: int
1176 the size (in bytes) of the guest memory blocks, which are the
1177 minimal units of memory block online/offline operations (also
1178 called Logical Memory Hotplug).
1179 Since
1181 2.3
1182 guest-get-memory-block-info (Command)
1184 Get information relating to guest memory blocks.
1185 Returns
1187 GuestMemoryBlockInfo
1188 Since
1190 2.3
1191 GuestExecStatus (Object)
1193 Members
1194 exited: boolean
1195 true if process has already terminated.
1196 exitcode: int (optional)
1198 process exit code if it was normally terminated.
1199 signal: int (optional)
1201 signal number (linux) or unhandled exception code (windows) if
1202 the process was abnormally terminated.
1203 out-data: string (optional)
1205 base64-encoded stdout of the process
1206 err-data: string (optional)
1208 base64-encoded stderr of the process Note: out-data and err-data
1209 are present only if 'capture-output' was specified for
1210 'guest-exec'
1211 out-truncated: boolean (optional)
1213 true if stdout was not fully captured due to size limitation.
1214 err-truncated: boolean (optional)
1216 true if stderr was not fully captured due to size limitation.
1217 Since
1219 2.5
1220 guest-exec-status (Command)
1222 Check status of process associated with PID retrieved via guest-exec.
1223 Reap the process and associated metadata if it has exited.
1224 Arguments
1226 pid: int
1227 pid returned from guest-exec
1228 Returns
1230 GuestExecStatus on success.
1231 Since
1233 2.5
1234 GuestExec (Object)
1236 Members
1237 pid: int
1238 pid of child process in guest OS
1239 Since
1241 2.5
1242 guest-exec (Command)
1244 Execute a command in the guest
1245 Arguments
1247 path: string
1248 path or executable name to execute
1249 arg: array of string (optional)
1251 argument list to pass to executable
1252 env: array of string (optional)
1254 environment variables to pass to executable
1255 input-data: string (optional)
1257 data to be passed to process stdin (base64 encoded)
1258 capture-output: boolean (optional)
1260 bool flag to enable capture of stdout/stderr of running process.
1261 defaults to false.
1262 Returns
1264 PID on success.
1265 Since
1267 2.5
1268 GuestHostName (Object)
1270 Members
1271 host-name: string
1272 Fully qualified domain name of the guest OS
1273 Since
1275 2.10
1276 guest-get-host-name (Command)
1278 Return a name for the machine.
1279 The returned name is not necessarily a fully-qualified domain name, or
1281 even present in DNS or some other name service at all. It need not even
1282 be unique on your local network or site, but usually it is.
1283 Returns
1285 the host name of the machine on success
1286 Since
1288 2.10
1289 GuestUser (Object)
1291 Members
1292 user: string
1293 Username
1294 domain: string (optional)
1296 Logon domain (windows only)
1297 login-time: number
1299 Time of login of this user on the computer. If multiple in‐
1300 stances of the user are logged in, the earliest login time is
1301 reported. The value is in fractional seconds since epoch time.
1302 Since
1304 2.10
1305 guest-get-users (Command)
1307 Retrieves a list of currently active users on the VM.
1308 Returns
1310 A unique list of users.
1311 Since
1313 2.10
1314 GuestTimezone (Object)
1316 Members
1317 zone: string (optional)
1318 Timezone name. These values may differ depending on guest/OS and
1319 should only be used for informational purposes.
1320 offset: int
1322 Offset to UTC in seconds, negative numbers for time zones west
1323 of GMT, positive numbers for east
1324 Since
1326 2.10
1327 guest-get-timezone (Command)
1329 Retrieves the timezone information from the guest.
1330 Returns
1332 A GuestTimezone dictionary.
1333 Since
1335 2.10
1336 GuestOSInfo (Object)
1338 Members
1339 kernel-release: string (optional)
1340 • POSIX: release field returned by uname(2)
1342 • Windows: build number of the OS
1344 kernel-version: string (optional)
1346 • POSIX: version field returned by uname(2)
1348 • Windows: version number of the OS
1350 machine: string (optional)
1352 • POSIX: machine field returned by uname(2)
1354 • Windows: one of x86, x86_64, arm, ia64
1356 id: string (optional)
1358 • POSIX: as defined by os-release(5)
1360 • Windows: contains string "mswindows"
1362 name: string (optional)
1364 • POSIX: as defined by os-release(5)
1366 • Windows: contains string "Microsoft Windows"
1368 pretty-name: string (optional)
1370 • POSIX: as defined by os-release(5)
1372 • Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1374 version: string (optional)
1376 • POSIX: as defined by os-release(5)
1378 • Windows: long version string, e.g. "Microsoft Windows Server
1380 2008"
1381 version-id: string (optional)
1383 • POSIX: as defined by os-release(5)
1385 • Windows: short version identifier, e.g. "7" or "20012r2"
1387 variant: string (optional)
1389 • POSIX: as defined by os-release(5)
1391 • Windows: contains string "server" or "client"
1393 variant-id: string (optional)
1395 • POSIX: as defined by os-release(5)
1397 • Windows: contains string "server" or "client"
1399 Notes
1401 On POSIX systems the fields id, name, pretty-name, version, version-id,
1402 variant and variant-id follow the definition specified in os-re‐
1403 lease(5). Refer to the manual page for exact description of the
1404 fields. Their values are taken from the os-release file. If the file is
1405 not present in the system, or the values are not present in the file,
1406 the fields are not included.
1407 On Windows the values are filled from information gathered from the
1409 system.
1410 Since
1412 2.10
1413 guest-get-osinfo (Command)
1415 Retrieve guest operating system information
1416 Returns
1418 GuestOSInfo
1419 Since
1421 2.10
1422 GuestDeviceType (Enum)
1424 Values
1425 pci Not documented
1426 GuestDeviceIdPCI (Object)
1428 Members
1429 vendor-id: int
1430 vendor ID
1431 device-id: int
1433 device ID
1434 Since
1436 5.2
1437 GuestDeviceId (Object)
1439 Id of the device - pci: PCI ID, since: 5.2
1440 Members
1442 type: GuestDeviceType
1443 Not documented
1444 The members of GuestDeviceIdPCI when type is "pci"
1446 Since
1448 5.2
1449 GuestDeviceInfo (Object)
1451 Members
1452 driver-name: string
1453 name of the associated driver
1454 driver-date: int (optional)
1456 driver release date, in nanoseconds since the epoch
1457 driver-version: string (optional)
1459 driver version
1460 id: GuestDeviceId (optional)
1462 device ID
1463 Since
1465 5.2
1466 guest-get-devices (Command)
1468 Retrieve information about device drivers in Windows guest
1469 Returns
1471 GuestDeviceInfo
1472 Since
1474 5.2
1475 GuestAuthorizedKeys (Object)
1477 Members
1478 keys: array of string
1479 public keys (in OpenSSH/sshd(8) authorized_keys format)
1480 Since
1482 5.2
1483 If
1485 CONFIG_POSIX
1486 guest-ssh-get-authorized-keys (Command)
1488 Arguments
1489 username: string
1490 the user account to add the authorized keys
1491 Return the public keys from user .ssh/authorized_keys on Unix systems
1492 (not implemented for other systems).
1493 Returns
1495 GuestAuthorizedKeys
1496 Since
1498 5.2
1499 If
1501 CONFIG_POSIX
1502 guest-ssh-add-authorized-keys (Command)
1504 Arguments
1505 username: string
1506 the user account to add the authorized keys
1507 keys: array of string
1509 the public keys to add (in OpenSSH/sshd(8) authorized_keys for‐
1510 mat)
1511 reset: boolean (optional)
1513 ignore the existing content, set it with the given keys only
1514 Append public keys to user .ssh/authorized_keys on Unix systems (not
1515 implemented for other systems).
1516 Returns
1518 Nothing on success.
1519 Since
1521 5.2
1522 If
1524 CONFIG_POSIX
1525 guest-ssh-remove-authorized-keys (Command)
1527 Arguments
1528 username: string
1529 the user account to remove the authorized keys
1530 keys: array of string
1532 the public keys to remove (in OpenSSH/sshd(8) authorized_keys
1533 format)
1534 Remove public keys from the user .ssh/authorized_keys on Unix systems
1535 (not implemented for other systems). It's not an error if the key is
1536 already missing.
1537 Returns
1539 Nothing on success.
1540 Since
1542 5.2
1543 If
1545 CONFIG_POSIX
1546
1548 2023, The QEMU Project Developers
15497.0.0 Jan 19, 2023 QEMU-GA-REF(7)