1QEMU-GA-REF(7) QEMU QEMU-GA-REF(7)
2
6 qemu-ga-ref - QEMU Guest Agent Protocol Reference
7
9 "unsupported" is a higher-level error than the errors that individual
10 commands might document. The caller should always be prepared to re‐
11 ceive QERR_UNSUPPORTED, even if the given command doesn't specify it,
12 or doesn't document any failure mode at all.
13
15 guest-sync-delimited (Command)
16 Echo back a unique integer value, and prepend to response a leading
17 sentinel byte (0xFF) the client can check scan for.
18 This is used by clients talking to the guest agent over the wire to en‐
20 sure the stream is in sync and doesn't contain stale data from previous
21 client. It must be issued upon initial connection, and after any
22 client-side timeouts (including timeouts on receiving a response to
23 this command).
24 After issuing this request, all guest agent responses should be ignored
26 until the response containing the unique integer value the client
27 passed in is returned. Receival of the 0xFF sentinel byte must be han‐
28 dled as an indication that the client's lexer/tokenizer/parser state
29 should be flushed/reset in preparation for reliably receiving the sub‐
30 sequent response. As an optimization, clients may opt to ignore all
31 data until a sentinel value is receiving to avoid unnecessary process‐
32 ing of stale data.
33 Similarly, clients should also precede this request with a 0xFF byte to
35 make sure the guest agent flushes any partially read JSON data from a
36 previous client connection.
37 Arguments
39 id: int
40 randomly generated 64-bit integer
41 Returns
43 The unique integer id passed in by the client
44 Since
46 1.1
47 guest-sync (Command)
49 Echo back a unique integer value
50 This is used by clients talking to the guest agent over the wire to en‐
52 sure the stream is in sync and doesn't contain stale data from previous
53 client. All guest agent responses should be ignored until the provided
54 unique integer value is returned, and it is up to the client to handle
55 stale whole or partially-delivered JSON text in such a way that this
56 response can be obtained.
57 In cases where a partial stale response was previously received by the
59 client, this cannot always be done reliably. One particular scenario
60 being if qemu-ga responses are fed character-by-character into a JSON
61 parser. In these situations, using guest-sync-delimited may be optimal.
62 For clients that fetch responses line by line and convert them to JSON
64 objects, guest-sync should be sufficient, but note that in cases where
65 the channel is dirty some attempts at parsing the response may result
66 in a parser error.
67 Such clients should also precede this command with a 0xFF byte to make
69 sure the guest agent flushes any partially read JSON data from a previ‐
70 ous session.
71 Arguments
73 id: int
74 randomly generated 64-bit integer
75 Returns
77 The unique integer id passed in by the client
78 Since
80 0.15.0
81 guest-ping (Command)
83 Ping the guest agent, a non-error return implies success
84 Since
86 0.15.0
87 guest-get-time (Command)
89 Get the information about guest's System Time relative to the Epoch of
90 1970-01-01 in UTC.
91 Returns
93 Time in nanoseconds.
94 Since
96 1.5
97 guest-set-time (Command)
99 Set guest time.
100 When a guest is paused or migrated to a file then loaded from that
102 file, the guest OS has no idea that there was a big gap in the time.
103 Depending on how long the gap was, NTP might not be able to resynchro‐
104 nize the guest.
105 This command tries to set guest's System Time to the given value, then
107 sets the Hardware Clock (RTC) to the current System Time. This will
108 make it easier for a guest to resynchronize without waiting for NTP. If
109 no time is specified, then the time to set is read from RTC. However,
110 this may not be supported on all platforms (i.e. Windows). If that's
111 the case users are advised to always pass a value.
112 Arguments
114 time: int (optional)
115 time of nanoseconds, relative to the Epoch of 1970-01-01 in UTC.
116 Returns
118 Nothing on success.
119 Since
121 1.5
122 GuestAgentCommandInfo (Object)
124 Information about guest agent commands.
125 Members
127 name: string
128 name of the command
129 enabled: boolean
131 whether command is currently enabled by guest admin
132 success-response: boolean
134 whether command returns a response on success (since 1.7)
135 Since
137 1.1.0
138 GuestAgentInfo (Object)
140 Information about guest agent.
141 Members
143 version: string
144 guest agent version
145 supported_commands: array of GuestAgentCommandInfo
147 Information about guest agent commands
148 Since
150 0.15.0
151 guest-info (Command)
153 Get some information about the guest agent.
154 Returns
156 GuestAgentInfo
157 Since
159 0.15.0
160 guest-shutdown (Command)
162 Initiate guest-activated shutdown. Note: this is an asynchronous shut‐
163 down request, with no guarantee of successful shutdown.
164 Arguments
166 mode: string (optional)
167 "halt", "powerdown" (default), or "reboot"
168 This command does NOT return a response on success. Success condition
169 is indicated by the VM exiting with a zero exit status or, when running
170 with --no-shutdown, by issuing the query-status QMP command to confirm
171 the VM status is "shutdown".
172 Since
174 0.15.0
175 guest-file-open (Command)
177 Open a file in the guest and retrieve a file handle for it
178 Arguments
180 path: string
181 Full path to the file in the guest to open.
182 mode: string (optional)
184 open mode, as per fopen(), "r" is the default.
185 Returns
187 Guest file handle on success.
188 Since
190 0.15.0
191 guest-file-close (Command)
193 Close an open file in the guest
194 Arguments
196 handle: int
197 filehandle returned by guest-file-open
198 Returns
200 Nothing on success.
201 Since
203 0.15.0
204 GuestFileRead (Object)
206 Result of guest agent file-read operation
207 Members
209 count: int
210 number of bytes read (note: count is before base64-encoding is
211 applied)
212 buf-b64: string
214 base64-encoded bytes read
215 eof: boolean
217 whether EOF was encountered during read operation.
218 Since
220 0.15.0
221 guest-file-read (Command)
223 Read from an open file in the guest. Data will be base64-encoded. As
224 this command is just for limited, ad-hoc debugging, such as log file
225 access, the number of bytes to read is limited to 48 MB.
226 Arguments
228 handle: int
229 filehandle returned by guest-file-open
230 count: int (optional)
232 maximum number of bytes to read (default is 4KB, maximum is
233 48MB)
234 Returns
236 GuestFileRead on success.
237 Since
239 0.15.0
240 GuestFileWrite (Object)
242 Result of guest agent file-write operation
243 Members
245 count: int
246 number of bytes written (note: count is actual bytes written,
247 after base64-decoding of provided buffer)
248 eof: boolean
250 whether EOF was encountered during write operation.
251 Since
253 0.15.0
254 guest-file-write (Command)
256 Write to an open file in the guest.
257 Arguments
259 handle: int
260 filehandle returned by guest-file-open
261 buf-b64: string
263 base64-encoded string representing data to be written
264 count: int (optional)
266 bytes to write (actual bytes, after base64-decode), default is
267 all content in buf-b64 buffer after base64 decoding
268 Returns
270 GuestFileWrite on success.
271 Since
273 0.15.0
274 GuestFileSeek (Object)
276 Result of guest agent file-seek operation
277 Members
279 position: int
280 current file position
281 eof: boolean
283 whether EOF was encountered during file seek
284 Since
286 0.15.0
287 QGASeek (Enum)
289 Symbolic names for use in guest-file-seek
290 Values
292 set Set to the specified offset (same effect as 'whence':0)
293 cur Add offset to the current location (same effect as 'whence':1)
295 end Add offset to the end of the file (same effect as 'whence':2)
297 Since
299 2.6
300 GuestFileWhence (Alternate)
302 Controls the meaning of offset to guest-file-seek.
303 Members
305 value: int
306 Integral value (0 for set, 1 for cur, 2 for end), available for
307 historical reasons, and might differ from the host's or guest's
308 SEEK_* values (since: 0.15)
309 name: QGASeek
311 Symbolic name, and preferred interface
312 Since
314 2.6
315 guest-file-seek (Command)
317 Seek to a position in the file, as with fseek(), and return the current
318 file position afterward. Also encapsulates ftell()'s functionality,
319 with offset=0 and whence=1.
320 Arguments
322 handle: int
323 filehandle returned by guest-file-open
324 offset: int
326 bytes to skip over in the file stream
327 whence: GuestFileWhence
329 Symbolic or numeric code for interpreting offset
330 Returns
332 GuestFileSeek on success.
333 Since
335 0.15.0
336 guest-file-flush (Command)
338 Write file changes bufferred in userspace to disk/kernel buffers
339 Arguments
341 handle: int
342 filehandle returned by guest-file-open
343 Returns
345 Nothing on success.
346 Since
348 0.15.0
349 GuestFsfreezeStatus (Enum)
351 An enumeration of filesystem freeze states
352 Values
354 thawed filesystems thawed/unfrozen
355 frozen all non-network guest filesystems frozen
357 Since
359 0.15.0
360 guest-fsfreeze-status (Command)
362 Get guest fsfreeze state. error state indicates
363 Returns
365 GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
366 Note
368 This may fail to properly report the current state as a result of some
369 other guest processes having issued an fs freeze/thaw.
370 Since
372 0.15.0
373 guest-fsfreeze-freeze (Command)
375 Sync and freeze all freezable, local guest filesystems. If this command
376 succeeded, you may call guest-fsfreeze-thaw later to unfreeze.
377 Note
379 On Windows, the command is implemented with the help of a Volume
380 Shadow-copy Service DLL helper. The frozen state is limited for up to
381 10 seconds by VSS.
382 Returns
384 Number of file systems currently frozen. On error, all filesystems will
385 be thawed. If no filesystems are frozen as a result of this call, then
386 guest-fsfreeze-status will remain "thawed" and calling guest-fs‐
387 freeze-thaw is not necessary.
388 Since
390 0.15.0
391 guest-fsfreeze-freeze-list (Command)
393 Sync and freeze specified guest filesystems. See also guest-fs‐
394 freeze-freeze.
395 Arguments
397 mountpoints: array of string (optional)
398 an array of mountpoints of filesystems to be frozen. If omit‐
399 ted, every mounted filesystem is frozen. Invalid mount points
400 are ignored.
401 Returns
403 Number of file systems currently frozen. On error, all filesystems will
404 be thawed.
405 Since
407 2.2
408 guest-fsfreeze-thaw (Command)
410 Unfreeze all frozen guest filesystems
411 Returns
413 Number of file systems thawed by this call
414 Note
416 if return value does not match the previous call to guest-fs‐
417 freeze-freeze, this likely means some freezable filesystems were un‐
418 frozen before this call, and that the filesystem state may have changed
419 before issuing this command.
420 Since
422 0.15.0
423 GuestFilesystemTrimResult (Object)
425 Members
426 path: string
427 path that was trimmed
428 error: string (optional)
430 an error message when trim failed
431 trimmed: int (optional)
433 bytes trimmed for this path
434 minimum: int (optional)
436 reported effective minimum for this path
437 Since
439 2.4
440 GuestFilesystemTrimResponse (Object)
442 Members
443 paths: array of GuestFilesystemTrimResult
444 list of GuestFilesystemTrimResult per path that was trimmed
445 Since
447 2.4
448 guest-fstrim (Command)
450 Discard (or "trim") blocks which are not in use by the filesystem.
451 Arguments
453 minimum: int (optional)
454 Minimum contiguous free range to discard, in bytes. Free ranges
455 smaller than this may be ignored (this is a hint and the guest
456 may not respect it). By increasing this value, the fstrim oper‐
457 ation will complete more quickly for filesystems with badly
458 fragmented free space, although not all blocks will be dis‐
459 carded. The default value is zero, meaning "discard every free
460 block".
461 Returns
463 A GuestFilesystemTrimResponse which contains the status of all trimmed
464 paths. (since 2.4)
465 Since
467 1.2
468 guest-suspend-disk (Command)
470 Suspend guest to disk.
471 This command attempts to suspend the guest using three strategies, in
473 this order:
474 • systemd hibernate
476 • pm-utils (via pm-hibernate)
478 • manual write into sysfs
480 This command does NOT return a response on success. There is a high
482 chance the command succeeded if the VM exits with a zero exit status
483 or, when running with --no-shutdown, by issuing the query-status QMP
484 command to to confirm the VM status is "shutdown". However, the VM
485 could also exit (or set its status to "shutdown") due to other reasons.
486 The following errors may be returned:
488 • If suspend to disk is not supported, Unsupported
490 Notes
492 It's strongly recommended to issue the guest-sync command before send‐
493 ing commands when the guest resumes
494 Since
496 1.1
497 guest-suspend-ram (Command)
499 Suspend guest to ram.
500 This command attempts to suspend the guest using three strategies, in
502 this order:
503 • systemd suspend
505 • pm-utils (via pm-suspend)
507 • manual write into sysfs
509 IMPORTANT: guest-suspend-ram requires working wakeup support in QEMU.
511 You should check QMP command query-current-machine returns wakeup-sus‐
512 pend-support: true before issuing this command. Failure in doing so can
513 result in a suspended guest that QEMU will not be able to awaken, forc‐
514 ing the user to power cycle the guest to bring it back.
515 This command does NOT return a response on success. There are two op‐
517 tions to check for success:
518 1. Wait for the SUSPEND QMP event from QEMU
520 2. Issue the query-status QMP command to confirm the VM status is "sus‐
522 pended"
523 The following errors may be returned:
525 • If suspend to ram is not supported, Unsupported
527 Notes
529 It's strongly recommended to issue the guest-sync command before send‐
530 ing commands when the guest resumes
531 Since
533 1.1
534 guest-suspend-hybrid (Command)
536 Save guest state to disk and suspend to ram.
537 This command attempts to suspend the guest by executing, in this order:
539 • systemd hybrid-sleep
541 • pm-utils (via pm-suspend-hybrid)
543 IMPORTANT: guest-suspend-hybrid requires working wakeup support in
545 QEMU. You should check QMP command query-current-machine returns
546 wakeup-suspend-support: true before issuing this command. Failure in
547 doing so can result in a suspended guest that QEMU will not be able to
548 awaken, forcing the user to power cycle the guest to bring it back.
549 This command does NOT return a response on success. There are two op‐
551 tions to check for success:
552 1. Wait for the SUSPEND QMP event from QEMU
554 2. Issue the query-status QMP command to confirm the VM status is "sus‐
556 pended"
557 The following errors may be returned:
559 • If hybrid suspend is not supported, Unsupported
561 Notes
563 It's strongly recommended to issue the guest-sync command before send‐
564 ing commands when the guest resumes
565 Since
567 1.1
568 GuestIpAddressType (Enum)
570 An enumeration of supported IP address types
571 Values
573 ipv4 IP version 4
574 ipv6 IP version 6
576 Since
578 1.1
579 GuestIpAddress (Object)
581 Members
582 ip-address: string
583 IP address
584 ip-address-type: GuestIpAddressType
586 Type of ip-address (e.g. ipv4, ipv6)
587 prefix: int
589 Network prefix length of ip-address
590 Since
592 1.1
593 GuestNetworkInterfaceStat (Object)
595 Members
596 rx-bytes: int
597 total bytes received
598 rx-packets: int
600 total packets received
601 rx-errs: int
603 bad packets received
604 rx-dropped: int
606 receiver dropped packets
607 tx-bytes: int
609 total bytes transmitted
610 tx-packets: int
612 total packets transmitted
613 tx-errs: int
615 packet transmit problems
616 tx-dropped: int
618 dropped packets transmitted
619 Since
621 2.11
622 GuestNetworkInterface (Object)
624 Members
625 name: string
626 The name of interface for which info are being delivered
627 hardware-address: string (optional)
629 Hardware address of name
630 ip-addresses: array of GuestIpAddress (optional)
632 List of addresses assigned to name
633 statistics: GuestNetworkInterfaceStat (optional)
635 various statistic counters related to name (since 2.11)
636 Since
638 1.1
639 guest-network-get-interfaces (Command)
641 Get list of guest IP addresses, MAC addresses and netmasks.
642 Returns
644 List of GuestNetworkInfo on success.
645 Since
647 1.1
648 GuestLogicalProcessor (Object)
650 Members
651 logical-id: int
652 Arbitrary guest-specific unique identifier of the VCPU.
653 online: boolean
655 Whether the VCPU is enabled.
656 can-offline: boolean (optional)
658 Whether offlining the VCPU is possible. This member is always
659 filled in by the guest agent when the structure is returned, and
660 always ignored on input (hence it can be omitted then).
661 Since
663 1.5
664 guest-get-vcpus (Command)
666 Retrieve the list of the guest's logical processors.
667 This is a read-only operation.
669 Returns
671 The list of all VCPUs the guest knows about. Each VCPU is put on the
672 list exactly once, but their order is unspecified.
673 Since
675 1.5
676 guest-set-vcpus (Command)
678 Attempt to reconfigure (currently: enable/disable) logical processors
679 inside the guest.
680 The input list is processed node by node in order. In each node logi‐
682 cal-id is used to look up the guest VCPU, for which online specifies
683 the requested state. The set of distinct logical-id's is only required
684 to be a subset of the guest-supported identifiers. There's no restric‐
685 tion on list length or on repeating the same logical-id (with possibly
686 different online field). Preferably the input list should describe a
687 modified subset of guest-get-vcpus' return value.
688 Arguments
690 vcpus: array of GuestLogicalProcessor
691 Not documented
692 Returns
694 The length of the initial sublist that has been successfully processed.
695 The guest agent maximizes this value. Possible cases:
696 • 0: if the vcpus list was empty on input. Guest state has not been
698 changed. Otherwise,
699 • Error: processing the first node of vcpus failed for the reason re‐
701 turned. Guest state has not been changed. Otherwise,
702 • < length(vcpus): more than zero initial nodes have been processed,
704 but not the entire vcpus list. Guest state has changed accordingly.
705 To retrieve the error (assuming it persists), repeat the call with
706 the successfully processed initial sublist removed. Otherwise,
707 • length(vcpus): call successful.
709 Since
711 1.5
712 GuestDiskBusType (Enum)
714 An enumeration of bus type of disks
715 Values
717 ide IDE disks
718 fdc floppy disks
720 scsi SCSI disks
722 virtio virtio disks
724 xen Xen disks
726 usb USB disks
728 uml UML disks
730 sata SATA disks
732 sd SD cards
734 unknown
736 Unknown bus type
737 ieee1394
739 Win IEEE 1394 bus type
740 ssa Win SSA bus type
742 fibre Win fiber channel bus type
744 raid Win RAID bus type
746 iscsi Win iScsi bus type
748 sas Win serial-attaches SCSI bus type
750 mmc Win multimedia card (MMC) bus type
752 virtual
754 Win virtual bus type
755 file-backed-virtual
757 Win file-backed bus type
758 Since
760 2.2; 'Unknown' and all entries below since 2.4
761 GuestPCIAddress (Object)
763 Members
764 domain: int
765 domain id
766 bus: int
768 bus id
769 slot: int
771 slot id
772 function: int
774 function id
775 Since
777 2.2
778 GuestDiskAddress (Object)
780 Members
781 pci-controller: GuestPCIAddress
782 controller's PCI address (fields are set to -1 if invalid)
783 bus-type: GuestDiskBusType
785 bus type
786 bus: int
788 bus id
789 target: int
791 target id
792 unit: int
794 unit id
795 serial: string (optional)
797 serial number (since: 3.1)
798 dev: string (optional)
800 device node (POSIX) or device UNC (Windows) (since: 3.1)
801 Since
803 2.2
804 GuestDiskInfo (Object)
806 Members
807 name: string
808 device node (Linux) or device UNC (Windows)
809 partition: boolean
811 whether this is a partition or disk
812 dependencies: array of string (optional)
814 list of device dependencies; e.g. for LVs of the LVM this will
815 hold the list of PVs, for LUKS encrypted volume this will con‐
816 tain the disk where the volume is placed. (Linux)
817 address: GuestDiskAddress (optional)
819 disk address information (only for non-virtual devices)
820 alias: string (optional)
822 optional alias assigned to the disk, on Linux this is a name as‐
823 signed by device mapper
824 Since 5.2
825 guest-get-disks (Command)
827 Returns
828 The list of disks in the guest. For Windows these are only the physical
829 disks. On Linux these are all root block devices of non-zero size in‐
830 cluding e.g. removable devices, loop devices, NBD, etc.
831 Since
833 5.2
834 GuestFilesystemInfo (Object)
836 Members
837 name: string
838 disk name
839 mountpoint: string
841 mount point path
842 type: string
844 file system type string
845 used-bytes: int (optional)
847 file system used bytes (since 3.0)
848 total-bytes: int (optional)
850 non-root file system total bytes (since 3.0)
851 disk: array of GuestDiskAddress
853 an array of disk hardware information that the volume lies on,
854 which may be empty if the disk type is not supported
855 Since
857 2.2
858 guest-get-fsinfo (Command)
860 Returns
861 The list of filesystems information mounted in the guest. The returned
862 mountpoints may be specified to guest-fsfreeze-freeze-list. Network
863 filesystems (such as CIFS and NFS) are not listed.
864 Since
866 2.2
867 guest-set-user-password (Command)
869 Arguments
870 username: string
871 the user account whose password to change
872 password: string
874 the new password entry string, base64 encoded
875 crypted: boolean
877 true if password is already crypt()d, false if raw
878 If the crypted flag is true, it is the caller's responsibility to en‐
879 sure the correct crypt() encryption scheme is used. This command does
880 not attempt to interpret or report on the encryption scheme. Refer to
881 the documentation of the guest operating system in question to deter‐
882 mine what is supported.
883 Not all guest operating systems will support use of the crypted flag,
885 as they may require the clear-text password
886 The password parameter must always be base64 encoded before transmis‐
888 sion, even if already crypt()d, to ensure it is 8-bit safe when passed
889 as JSON.
890 Returns
892 Nothing on success.
893 Since
895 2.3
896 GuestMemoryBlock (Object)
898 Members
899 phys-index: int
900 Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
901 online: boolean
903 Whether the MEMORY BLOCK is enabled in guest.
904 can-offline: boolean (optional)
906 Whether offlining the MEMORY BLOCK is possible. This member is
907 always filled in by the guest agent when the structure is re‐
908 turned, and always ignored on input (hence it can be omitted
909 then).
910 Since
912 2.3
913 guest-get-memory-blocks (Command)
915 Retrieve the list of the guest's memory blocks.
916 This is a read-only operation.
918 Returns
920 The list of all memory blocks the guest knows about. Each memory block
921 is put on the list exactly once, but their order is unspecified.
922 Since
924 2.3
925 GuestMemoryBlockResponseType (Enum)
927 An enumeration of memory block operation result.
928 Values
930 success
931 the operation of online/offline memory block is successful.
932 not-found
934 can't find the corresponding memoryXXX directory in sysfs.
935 operation-not-supported
937 for some old kernels, it does not support online or offline mem‐
938 ory block.
939 operation-failed
941 the operation of online/offline memory block fails, because of
942 some errors happen.
943 Since
945 2.3
946 GuestMemoryBlockResponse (Object)
948 Members
949 phys-index: int
950 same with the 'phys-index' member of GuestMemoryBlock.
951 response: GuestMemoryBlockResponseType
953 the result of memory block operation.
954 error-code: int (optional)
956 the error number. When memory block operation fails, we assign
957 the value of 'errno' to this member, it indicates what goes
958 wrong. When the operation succeeds, it will be omitted.
959 Since
961 2.3
962 guest-set-memory-blocks (Command)
964 Attempt to reconfigure (currently: enable/disable) state of memory
965 blocks inside the guest.
966 The input list is processed node by node in order. In each node
968 phys-index is used to look up the guest MEMORY BLOCK, for which online
969 specifies the requested state. The set of distinct phys-index's is only
970 required to be a subset of the guest-supported identifiers. There's no
971 restriction on list length or on repeating the same phys-index (with
972 possibly different online field). Preferably the input list should de‐
973 scribe a modified subset of guest-get-memory-blocks' return value.
974 Arguments
976 mem-blks: array of GuestMemoryBlock
977 Not documented
978 Returns
980 The operation results, it is a list of GuestMemoryBlockResponse, which
981 is corresponding to the input list.
982 Note: it will return NULL if the mem-blks list was empty on input, or
984 there is an error, and in this case, guest state will not be changed.
985 Since
987 2.3
988 GuestMemoryBlockInfo (Object)
990 Members
991 size: int
992 the size (in bytes) of the guest memory blocks, which are the
993 minimal units of memory block online/offline operations (also
994 called Logical Memory Hotplug).
995 Since
997 2.3
998 guest-get-memory-block-info (Command)
1000 Get information relating to guest memory blocks.
1001 Returns
1003 GuestMemoryBlockInfo
1004 Since
1006 2.3
1007 GuestExecStatus (Object)
1009 Members
1010 exited: boolean
1011 true if process has already terminated.
1012 exitcode: int (optional)
1014 process exit code if it was normally terminated.
1015 signal: int (optional)
1017 signal number (linux) or unhandled exception code (windows) if
1018 the process was abnormally terminated.
1019 out-data: string (optional)
1021 base64-encoded stdout of the process
1022 err-data: string (optional)
1024 base64-encoded stderr of the process Note: out-data and err-data
1025 are present only if 'capture-output' was specified for
1026 'guest-exec'
1027 out-truncated: boolean (optional)
1029 true if stdout was not fully captured due to size limitation.
1030 err-truncated: boolean (optional)
1032 true if stderr was not fully captured due to size limitation.
1033 Since
1035 2.5
1036 guest-exec-status (Command)
1038 Check status of process associated with PID retrieved via guest-exec.
1039 Reap the process and associated metadata if it has exited.
1040 Arguments
1042 pid: int
1043 pid returned from guest-exec
1044 Returns
1046 GuestExecStatus on success.
1047 Since
1049 2.5
1050 GuestExec (Object)
1052 Members
1053 pid: int
1054 pid of child process in guest OS
1055 Since
1057 2.5
1058 guest-exec (Command)
1060 Execute a command in the guest
1061 Arguments
1063 path: string
1064 path or executable name to execute
1065 arg: array of string (optional)
1067 argument list to pass to executable
1068 env: array of string (optional)
1070 environment variables to pass to executable
1071 input-data: string (optional)
1073 data to be passed to process stdin (base64 encoded)
1074 capture-output: boolean (optional)
1076 bool flag to enable capture of stdout/stderr of running process.
1077 defaults to false.
1078 Returns
1080 PID on success.
1081 Since
1083 2.5
1084 GuestHostName (Object)
1086 Members
1087 host-name: string
1088 Fully qualified domain name of the guest OS
1089 Since
1091 2.10
1092 guest-get-host-name (Command)
1094 Return a name for the machine.
1095 The returned name is not necessarily a fully-qualified domain name, or
1097 even present in DNS or some other name service at all. It need not even
1098 be unique on your local network or site, but usually it is.
1099 Returns
1101 the host name of the machine on success
1102 Since
1104 2.10
1105 GuestUser (Object)
1107 Members
1108 user: string
1109 Username
1110 domain: string (optional)
1112 Logon domain (windows only)
1113 login-time: number
1115 Time of login of this user on the computer. If multiple in‐
1116 stances of the user are logged in, the earliest login time is
1117 reported. The value is in fractional seconds since epoch time.
1118 Since
1120 2.10
1121 guest-get-users (Command)
1123 Retrieves a list of currently active users on the VM.
1124 Returns
1126 A unique list of users.
1127 Since
1129 2.10
1130 GuestTimezone (Object)
1132 Members
1133 zone: string (optional)
1134 Timezone name. These values may differ depending on guest/OS and
1135 should only be used for informational purposes.
1136 offset: int
1138 Offset to UTC in seconds, negative numbers for time zones west
1139 of GMT, positive numbers for east
1140 Since
1142 2.10
1143 guest-get-timezone (Command)
1145 Retrieves the timezone information from the guest.
1146 Returns
1148 A GuestTimezone dictionary.
1149 Since
1151 2.10
1152 GuestOSInfo (Object)
1154 Members
1155 kernel-release: string (optional)
1156 • POSIX: release field returned by uname(2)
1158 • Windows: build number of the OS
1160 kernel-version: string (optional)
1162 • POSIX: version field returned by uname(2)
1164 • Windows: version number of the OS
1166 machine: string (optional)
1168 • POSIX: machine field returned by uname(2)
1170 • Windows: one of x86, x86_64, arm, ia64
1172 id: string (optional)
1174 • POSIX: as defined by os-release(5)
1176 • Windows: contains string "mswindows"
1178 name: string (optional)
1180 • POSIX: as defined by os-release(5)
1182 • Windows: contains string "Microsoft Windows"
1184 pretty-name: string (optional)
1186 • POSIX: as defined by os-release(5)
1188 • Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1190 version: string (optional)
1192 • POSIX: as defined by os-release(5)
1194 • Windows: long version string, e.g. "Microsoft Windows Server
1196 2008"
1197 version-id: string (optional)
1199 • POSIX: as defined by os-release(5)
1201 • Windows: short version identifier, e.g. "7" or "20012r2"
1203 variant: string (optional)
1205 • POSIX: as defined by os-release(5)
1207 • Windows: contains string "server" or "client"
1209 variant-id: string (optional)
1211 • POSIX: as defined by os-release(5)
1213 • Windows: contains string "server" or "client"
1215 Notes
1217 On POSIX systems the fields id, name, pretty-name, version, version-id,
1218 variant and variant-id follow the definition specified in os-re‐
1219 lease(5). Refer to the manual page for exact description of the
1220 fields. Their values are taken from the os-release file. If the file is
1221 not present in the system, or the values are not present in the file,
1222 the fields are not included.
1223 On Windows the values are filled from information gathered from the
1225 system.
1226 Since
1228 2.10
1229 guest-get-osinfo (Command)
1231 Retrieve guest operating system information
1232 Returns
1234 GuestOSInfo
1235 Since
1237 2.10
1238 GuestDeviceType (Enum)
1240 Values
1241 pci Not documented
1242 GuestDeviceIdPCI (Object)
1244 Members
1245 vendor-id: int
1246 vendor ID
1247 device-id: int
1249 device ID
1250 Since
1252 5.2
1253 GuestDeviceId (Object)
1255 Id of the device - pci: PCI ID, since: 5.2
1256 Members
1258 type: GuestDeviceType
1259 Not documented
1260 The members of GuestDeviceIdPCI when type is "pci"
1262 Since
1264 5.2
1265 GuestDeviceInfo (Object)
1267 Members
1268 driver-name: string
1269 name of the associated driver
1270 driver-date: int (optional)
1272 driver release date, in nanoseconds since the epoch
1273 driver-version: string (optional)
1275 driver version
1276 id: GuestDeviceId (optional)
1278 device ID
1279 Since
1281 5.2
1282 guest-get-devices (Command)
1284 Retrieve information about device drivers in Windows guest
1285 Returns
1287 GuestDeviceInfo
1288 Since
1290 5.2
1291 GuestAuthorizedKeys (Object)
1293 Members
1294 keys: array of string
1295 public keys (in OpenSSH/sshd(8) authorized_keys format)
1296 Since
1298 5.2
1299 If
1301 defined(CONFIG_POSIX).SS guest-ssh-get-authorized-keys (Command)
1302 Arguments
1304 username: string
1305 the user account to add the authorized keys
1306 Return the public keys from user .ssh/authorized_keys on Unix systems
1307 (not implemented for other systems).
1308 Returns
1310 GuestAuthorizedKeys
1311 Since
1313 5.2
1314 If
1316 defined(CONFIG_POSIX).SS guest-ssh-add-authorized-keys (Command)
1317 Arguments
1319 username: string
1320 the user account to add the authorized keys
1321 keys: array of string
1323 the public keys to add (in OpenSSH/sshd(8) authorized_keys for‐
1324 mat)
1325 reset: boolean (optional)
1327 ignore the existing content, set it with the given keys only
1328 Append public keys to user .ssh/authorized_keys on Unix systems (not
1329 implemented for other systems).
1330 Returns
1332 Nothing on success.
1333 Since
1335 5.2
1336 If
1338 defined(CONFIG_POSIX).SS guest-ssh-remove-authorized-keys (Command)
1339 Arguments
1341 username: string
1342 the user account to remove the authorized keys
1343 keys: array of string
1345 the public keys to remove (in OpenSSH/sshd(8) authorized_keys
1346 format)
1347 Remove public keys from the user .ssh/authorized_keys on Unix systems
1348 (not implemented for other systems). It's not an error if the key is
1349 already missing.
1350 Returns
1352 Nothing on success.
1353 Since
1355 5.2
1356 If
1358 defined(CONFIG_POSIX).SH COPYRIGHT 2021, The QEMU Project Developers
13595.2.0 May 19, 2021 QEMU-GA-REF(7)