1QEMU-GA-REF(7) QEMU QEMU-GA-REF(7)
2
3
4
6 qemu-ga-ref - QEMU Guest Agent Protocol Reference
7
8 Contents
9 • QEMU Guest Agent Protocol Reference
10
11 • General note concerning the use of guest agent interfaces
12
13 • "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
18 • QEMU guest agent protocol commands and structs
19
20 • guest-sync-delimited (Command)
21
22 • guest-sync (Command)
23
24 • guest-ping (Command)
25
26 • guest-get-time (Command)
27
28 • guest-set-time (Command)
29
30 • GuestAgentCommandInfo (Object)
31
32 • GuestAgentInfo (Object)
33
34 • guest-info (Command)
35
36 • guest-shutdown (Command)
37
38 • guest-file-open (Command)
39
40 • guest-file-close (Command)
41
42 • GuestFileRead (Object)
43
44 • guest-file-read (Command)
45
46 • GuestFileWrite (Object)
47
48 • guest-file-write (Command)
49
50 • GuestFileSeek (Object)
51
52 • QGASeek (Enum)
53
54 • GuestFileWhence (Alternate)
55
56 • guest-file-seek (Command)
57
58 • guest-file-flush (Command)
59
60 • GuestFsfreezeStatus (Enum)
61
62 • guest-fsfreeze-status (Command)
63
64 • guest-fsfreeze-freeze (Command)
65
66 • guest-fsfreeze-freeze-list (Command)
67
68 • guest-fsfreeze-thaw (Command)
69
70 • GuestFilesystemTrimResult (Object)
71
72 • GuestFilesystemTrimResponse (Object)
73
74 • guest-fstrim (Command)
75
76 • guest-suspend-disk (Command)
77
78 • guest-suspend-ram (Command)
79
80 • guest-suspend-hybrid (Command)
81
82 • GuestIpAddressType (Enum)
83
84 • GuestIpAddress (Object)
85
86 • GuestNetworkInterfaceStat (Object)
87
88 • GuestNetworkInterface (Object)
89
90 • guest-network-get-interfaces (Command)
91
92 • GuestLogicalProcessor (Object)
93
94 • guest-get-vcpus (Command)
95
96 • guest-set-vcpus (Command)
97
98 • GuestDiskBusType (Enum)
99
100 • GuestPCIAddress (Object)
101
102 • GuestCCWAddress (Object)
103
104 • GuestDiskAddress (Object)
105
106 • GuestDiskInfo (Object)
107
108 • guest-get-disks (Command)
109
110 • GuestFilesystemInfo (Object)
111
112 • guest-get-fsinfo (Command)
113
114 • guest-set-user-password (Command)
115
116 • GuestMemoryBlock (Object)
117
118 • guest-get-memory-blocks (Command)
119
120 • GuestMemoryBlockResponseType (Enum)
121
122 • GuestMemoryBlockResponse (Object)
123
124 • guest-set-memory-blocks (Command)
125
126 • GuestMemoryBlockInfo (Object)
127
128 • guest-get-memory-block-info (Command)
129
130 • GuestExecStatus (Object)
131
132 • guest-exec-status (Command)
133
134 • GuestExec (Object)
135
136 • guest-exec (Command)
137
138 • GuestHostName (Object)
139
140 • guest-get-host-name (Command)
141
142 • GuestUser (Object)
143
144 • guest-get-users (Command)
145
146 • GuestTimezone (Object)
147
148 • guest-get-timezone (Command)
149
150 • GuestOSInfo (Object)
151
152 • guest-get-osinfo (Command)
153
154 • GuestDeviceType (Enum)
155
156 • GuestDeviceIdPCI (Object)
157
158 • GuestDeviceId (Object)
159
160 • GuestDeviceInfo (Object)
161
162 • guest-get-devices (Command)
163
164 • GuestAuthorizedKeys (Object)
165
166 • guest-ssh-get-authorized-keys (Command)
167
168 • guest-ssh-add-authorized-keys (Command)
169
170 • 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
183 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
189 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
198 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
202 Arguments
203 id: int
204 randomly generated 64-bit integer
205
206 Returns
207 The unique integer id passed in by the client
208
209 Since
210 1.1
211
212 guest-sync (Command)
213 Echo back a unique integer value
214
215 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
222 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
227 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
232 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
236 Arguments
237 id: int
238 randomly generated 64-bit integer
239
240 Returns
241 The unique integer id passed in by the client
242
243 Since
244 0.15.0
245
246 guest-ping (Command)
247 Ping the guest agent, a non-error return implies success
248
249 Since
250 0.15.0
251
252 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
256 Returns
257 Time in nanoseconds.
258
259 Since
260 1.5
261
262 guest-set-time (Command)
263 Set guest time.
264
265 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
270 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
277 Arguments
278 time: int (optional)
279 time of nanoseconds, relative to the Epoch of 1970-01-01 in UTC.
280
281 Returns
282 Nothing on success.
283
284 Since
285 1.5
286
287 GuestAgentCommandInfo (Object)
288 Information about guest agent commands.
289
290 Members
291 name: string
292 name of the command
293
294 enabled: boolean
295 whether command is currently enabled by guest admin
296
297 success-response: boolean
298 whether command returns a response on success (since 1.7)
299
300 Since
301 1.1.0
302
303 GuestAgentInfo (Object)
304 Information about guest agent.
305
306 Members
307 version: string
308 guest agent version
309
310 supported_commands: array of GuestAgentCommandInfo
311 Information about guest agent commands
312
313 Since
314 0.15.0
315
316 guest-info (Command)
317 Get some information about the guest agent.
318
319 Returns
320 GuestAgentInfo
321
322 Since
323 0.15.0
324
325 guest-shutdown (Command)
326 Initiate guest-activated shutdown. Note: this is an asynchronous shut‐
327 down request, with no guarantee of successful shutdown.
328
329 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
337 Since
338 0.15.0
339
340 guest-file-open (Command)
341 Open a file in the guest and retrieve a file handle for it
342
343 Arguments
344 path: string
345 Full path to the file in the guest to open.
346
347 mode: string (optional)
348 open mode, as per fopen(), "r" is the default.
349
350 Returns
351 Guest file handle on success.
352
353 Since
354 0.15.0
355
356 guest-file-close (Command)
357 Close an open file in the guest
358
359 Arguments
360 handle: int
361 filehandle returned by guest-file-open
362
363 Returns
364 Nothing on success.
365
366 Since
367 0.15.0
368
369 GuestFileRead (Object)
370 Result of guest agent file-read operation
371
372 Members
373 count: int
374 number of bytes read (note: count is before base64-encoding is
375 applied)
376
377 buf-b64: string
378 base64-encoded bytes read
379
380 eof: boolean
381 whether EOF was encountered during read operation.
382
383 Since
384 0.15.0
385
386 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
391 Arguments
392 handle: int
393 filehandle returned by guest-file-open
394
395 count: int (optional)
396 maximum number of bytes to read (default is 4KB, maximum is
397 48MB)
398
399 Returns
400 GuestFileRead on success.
401
402 Since
403 0.15.0
404
405 GuestFileWrite (Object)
406 Result of guest agent file-write operation
407
408 Members
409 count: int
410 number of bytes written (note: count is actual bytes written,
411 after base64-decoding of provided buffer)
412
413 eof: boolean
414 whether EOF was encountered during write operation.
415
416 Since
417 0.15.0
418
419 guest-file-write (Command)
420 Write to an open file in the guest.
421
422 Arguments
423 handle: int
424 filehandle returned by guest-file-open
425
426 buf-b64: string
427 base64-encoded string representing data to be written
428
429 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
433 Returns
434 GuestFileWrite on success.
435
436 Since
437 0.15.0
438
439 GuestFileSeek (Object)
440 Result of guest agent file-seek operation
441
442 Members
443 position: int
444 current file position
445
446 eof: boolean
447 whether EOF was encountered during file seek
448
449 Since
450 0.15.0
451
452 QGASeek (Enum)
453 Symbolic names for use in guest-file-seek
454
455 Values
456 set Set to the specified offset (same effect as 'whence':0)
457
458 cur Add offset to the current location (same effect as 'whence':1)
459
460 end Add offset to the end of the file (same effect as 'whence':2)
461
462 Since
463 2.6
464
465 GuestFileWhence (Alternate)
466 Controls the meaning of offset to guest-file-seek.
467
468 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
474 name: QGASeek
475 Symbolic name, and preferred interface
476
477 Since
478 2.6
479
480 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
485 Arguments
486 handle: int
487 filehandle returned by guest-file-open
488
489 offset: int
490 bytes to skip over in the file stream
491
492 whence: GuestFileWhence
493 Symbolic or numeric code for interpreting offset
494
495 Returns
496 GuestFileSeek on success.
497
498 Since
499 0.15.0
500
501 guest-file-flush (Command)
502 Write file changes bufferred in userspace to disk/kernel buffers
503
504 Arguments
505 handle: int
506 filehandle returned by guest-file-open
507
508 Returns
509 Nothing on success.
510
511 Since
512 0.15.0
513
514 GuestFsfreezeStatus (Enum)
515 An enumeration of filesystem freeze states
516
517 Values
518 thawed filesystems thawed/unfrozen
519
520 frozen all non-network guest filesystems frozen
521
522 Since
523 0.15.0
524
525 guest-fsfreeze-status (Command)
526 Get guest fsfreeze state. error state indicates
527
528 Returns
529 GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
530
531 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
535 Since
536 0.15.0
537
538 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
542 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
547 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
553 Since
554 0.15.0
555
556 guest-fsfreeze-freeze-list (Command)
557 Sync and freeze specified guest filesystems. See also guest-fs‐
558 freeze-freeze.
559
560 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
566 Returns
567 Number of file systems currently frozen. On error, all filesystems will
568 be thawed.
569
570 Since
571 2.2
572
573 guest-fsfreeze-thaw (Command)
574 Unfreeze all frozen guest filesystems
575
576 Returns
577 Number of file systems thawed by this call
578
579 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
585 Since
586 0.15.0
587
588 GuestFilesystemTrimResult (Object)
589 Members
590 path: string
591 path that was trimmed
592
593 error: string (optional)
594 an error message when trim failed
595
596 trimmed: int (optional)
597 bytes trimmed for this path
598
599 minimum: int (optional)
600 reported effective minimum for this path
601
602 Since
603 2.4
604
605 GuestFilesystemTrimResponse (Object)
606 Members
607 paths: array of GuestFilesystemTrimResult
608 list of GuestFilesystemTrimResult per path that was trimmed
609
610 Since
611 2.4
612
613 guest-fstrim (Command)
614 Discard (or "trim") blocks which are not in use by the filesystem.
615
616 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
626 Returns
627 A GuestFilesystemTrimResponse which contains the status of all trimmed
628 paths. (since 2.4)
629
630 Since
631 1.2
632
633 guest-suspend-disk (Command)
634 Suspend guest to disk.
635
636 This command attempts to suspend the guest using three strategies, in
637 this order:
638
639 • systemd hibernate
640
641 • pm-utils (via pm-hibernate)
642
643 • manual write into sysfs
644
645 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
651 The following errors may be returned:
652
653 • If suspend to disk is not supported, Unsupported
654
655 Notes
656 It's strongly recommended to issue the guest-sync command before send‐
657 ing commands when the guest resumes
658
659 Since
660 1.1
661
662 guest-suspend-ram (Command)
663 Suspend guest to ram.
664
665 This command attempts to suspend the guest using three strategies, in
666 this order:
667
668 • systemd suspend
669
670 • pm-utils (via pm-suspend)
671
672 • manual write into sysfs
673
674 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
680 This command does NOT return a response on success. There are two op‐
681 tions to check for success:
682
683 1. Wait for the SUSPEND QMP event from QEMU
684
685 2. Issue the query-status QMP command to confirm the VM status is "sus‐
686 pended"
687
688 The following errors may be returned:
689
690 • If suspend to ram is not supported, Unsupported
691
692 Notes
693 It's strongly recommended to issue the guest-sync command before send‐
694 ing commands when the guest resumes
695
696 Since
697 1.1
698
699 guest-suspend-hybrid (Command)
700 Save guest state to disk and suspend to ram.
701
702 This command attempts to suspend the guest by executing, in this order:
703
704 • systemd hybrid-sleep
705
706 • pm-utils (via pm-suspend-hybrid)
707
708 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
714 This command does NOT return a response on success. There are two op‐
715 tions to check for success:
716
717 1. Wait for the SUSPEND QMP event from QEMU
718
719 2. Issue the query-status QMP command to confirm the VM status is "sus‐
720 pended"
721
722 The following errors may be returned:
723
724 • If hybrid suspend is not supported, Unsupported
725
726 Notes
727 It's strongly recommended to issue the guest-sync command before send‐
728 ing commands when the guest resumes
729
730 Since
731 1.1
732
733 GuestIpAddressType (Enum)
734 An enumeration of supported IP address types
735
736 Values
737 ipv4 IP version 4
738
739 ipv6 IP version 6
740
741 Since
742 1.1
743
744 GuestIpAddress (Object)
745 Members
746 ip-address: string
747 IP address
748
749 ip-address-type: GuestIpAddressType
750 Type of ip-address (e.g. ipv4, ipv6)
751
752 prefix: int
753 Network prefix length of ip-address
754
755 Since
756 1.1
757
758 GuestNetworkInterfaceStat (Object)
759 Members
760 rx-bytes: int
761 total bytes received
762
763 rx-packets: int
764 total packets received
765
766 rx-errs: int
767 bad packets received
768
769 rx-dropped: int
770 receiver dropped packets
771
772 tx-bytes: int
773 total bytes transmitted
774
775 tx-packets: int
776 total packets transmitted
777
778 tx-errs: int
779 packet transmit problems
780
781 tx-dropped: int
782 dropped packets transmitted
783
784 Since
785 2.11
786
787 GuestNetworkInterface (Object)
788 Members
789 name: string
790 The name of interface for which info are being delivered
791
792 hardware-address: string (optional)
793 Hardware address of name
794
795 ip-addresses: array of GuestIpAddress (optional)
796 List of addresses assigned to name
797
798 statistics: GuestNetworkInterfaceStat (optional)
799 various statistic counters related to name (since 2.11)
800
801 Since
802 1.1
803
804 guest-network-get-interfaces (Command)
805 Get list of guest IP addresses, MAC addresses and netmasks.
806
807 Returns
808 List of GuestNetworkInfo on success.
809
810 Since
811 1.1
812
813 GuestLogicalProcessor (Object)
814 Members
815 logical-id: int
816 Arbitrary guest-specific unique identifier of the VCPU.
817
818 online: boolean
819 Whether the VCPU is enabled.
820
821 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
826 Since
827 1.5
828
829 guest-get-vcpus (Command)
830 Retrieve the list of the guest's logical processors.
831
832 This is a read-only operation.
833
834 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
838 Since
839 1.5
840
841 guest-set-vcpus (Command)
842 Attempt to reconfigure (currently: enable/disable) logical processors
843 inside the guest.
844
845 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
853 Arguments
854 vcpus: array of GuestLogicalProcessor
855 Not documented
856
857 Returns
858 The length of the initial sublist that has been successfully processed.
859 The guest agent maximizes this value. Possible cases:
860
861 • 0: if the vcpus list was empty on input. Guest state has not been
862 changed. Otherwise,
863
864 • Error: processing the first node of vcpus failed for the reason re‐
865 turned. Guest state has not been changed. Otherwise,
866
867 • < 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
872 • length(vcpus): call successful.
873
874 Since
875 1.5
876
877 GuestDiskBusType (Enum)
878 An enumeration of bus type of disks
879
880 Values
881 ide IDE disks
882
883 fdc floppy disks
884
885 scsi SCSI disks
886
887 virtio virtio disks
888
889 xen Xen disks
890
891 usb USB disks
892
893 uml UML disks
894
895 sata SATA disks
896
897 sd SD cards
898
899 unknown
900 Unknown bus type
901
902 ieee1394
903 Win IEEE 1394 bus type
904
905 ssa Win SSA bus type
906
907 fibre Win fiber channel bus type
908
909 raid Win RAID bus type
910
911 iscsi Win iScsi bus type
912
913 sas Win serial-attaches SCSI bus type
914
915 mmc Win multimedia card (MMC) bus type
916
917 virtual
918 Win virtual bus type
919
920 file-backed-virtual
921 Win file-backed bus type
922
923 Since
924 2.2; 'Unknown' and all entries below since 2.4
925
926 GuestPCIAddress (Object)
927 Members
928 domain: int
929 domain id
930
931 bus: int
932 bus id
933
934 slot: int
935 slot id
936
937 function: int
938 function id
939
940 Since
941 2.2
942
943 GuestCCWAddress (Object)
944 Members
945 cssid: int
946 channel subsystem image id
947
948 ssid: int
949 subchannel set id
950
951 subchno: int
952 subchannel number
953
954 devno: int
955 device number
956
957 Since
958 6.0
959
960 GuestDiskAddress (Object)
961 Members
962 pci-controller: GuestPCIAddress
963 controller's PCI address (fields are set to -1 if invalid)
964
965 bus-type: GuestDiskBusType
966 bus type
967
968 bus: int
969 bus id
970
971 target: int
972 target id
973
974 unit: int
975 unit id
976
977 serial: string (optional)
978 serial number (since: 3.1)
979
980 dev: string (optional)
981 device node (POSIX) or device UNC (Windows) (since: 3.1)
982
983 ccw-address: GuestCCWAddress (optional)
984 CCW address on s390x (since: 6.0)
985
986 Since
987 2.2
988
989 GuestDiskInfo (Object)
990 Members
991 name: string
992 device node (Linux) or device UNC (Windows)
993
994 partition: boolean
995 whether this is a partition or disk
996
997 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
1002 address: GuestDiskAddress (optional)
1003 disk address information (only for non-virtual devices)
1004
1005 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
1010 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
1016 Since
1017 5.2
1018
1019 GuestFilesystemInfo (Object)
1020 Members
1021 name: string
1022 disk name
1023
1024 mountpoint: string
1025 mount point path
1026
1027 type: string
1028 file system type string
1029
1030 used-bytes: int (optional)
1031 file system used bytes (since 3.0)
1032
1033 total-bytes: int (optional)
1034 non-root file system total bytes (since 3.0)
1035
1036 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
1040 Since
1041 2.2
1042
1043 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
1049 Since
1050 2.2
1051
1052 guest-set-user-password (Command)
1053 Arguments
1054 username: string
1055 the user account whose password to change
1056
1057 password: string
1058 the new password entry string, base64 encoded
1059
1060 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
1068 Not all guest operating systems will support use of the crypted flag,
1069 as they may require the clear-text password
1070
1071 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
1075 Returns
1076 Nothing on success.
1077
1078 Since
1079 2.3
1080
1081 GuestMemoryBlock (Object)
1082 Members
1083 phys-index: int
1084 Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
1085
1086 online: boolean
1087 Whether the MEMORY BLOCK is enabled in guest.
1088
1089 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
1095 Since
1096 2.3
1097
1098 guest-get-memory-blocks (Command)
1099 Retrieve the list of the guest's memory blocks.
1100
1101 This is a read-only operation.
1102
1103 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
1107 Since
1108 2.3
1109
1110 GuestMemoryBlockResponseType (Enum)
1111 An enumeration of memory block operation result.
1112
1113 Values
1114 success
1115 the operation of online/offline memory block is successful.
1116
1117 not-found
1118 can't find the corresponding memoryXXX directory in sysfs.
1119
1120 operation-not-supported
1121 for some old kernels, it does not support online or offline mem‐
1122 ory block.
1123
1124 operation-failed
1125 the operation of online/offline memory block fails, because of
1126 some errors happen.
1127
1128 Since
1129 2.3
1130
1131 GuestMemoryBlockResponse (Object)
1132 Members
1133 phys-index: int
1134 same with the 'phys-index' member of GuestMemoryBlock.
1135
1136 response: GuestMemoryBlockResponseType
1137 the result of memory block operation.
1138
1139 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
1144 Since
1145 2.3
1146
1147 guest-set-memory-blocks (Command)
1148 Attempt to reconfigure (currently: enable/disable) state of memory
1149 blocks inside the guest.
1150
1151 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
1159 Arguments
1160 mem-blks: array of GuestMemoryBlock
1161 Not documented
1162
1163 Returns
1164 The operation results, it is a list of GuestMemoryBlockResponse, which
1165 is corresponding to the input list.
1166
1167 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
1170 Since
1171 2.3
1172
1173 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
1180 Since
1181 2.3
1182
1183 guest-get-memory-block-info (Command)
1184 Get information relating to guest memory blocks.
1185
1186 Returns
1187 GuestMemoryBlockInfo
1188
1189 Since
1190 2.3
1191
1192 GuestExecStatus (Object)
1193 Members
1194 exited: boolean
1195 true if process has already terminated.
1196
1197 exitcode: int (optional)
1198 process exit code if it was normally terminated.
1199
1200 signal: int (optional)
1201 signal number (linux) or unhandled exception code (windows) if
1202 the process was abnormally terminated.
1203
1204 out-data: string (optional)
1205 base64-encoded stdout of the process
1206
1207 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
1212 out-truncated: boolean (optional)
1213 true if stdout was not fully captured due to size limitation.
1214
1215 err-truncated: boolean (optional)
1216 true if stderr was not fully captured due to size limitation.
1217
1218 Since
1219 2.5
1220
1221 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
1225 Arguments
1226 pid: int
1227 pid returned from guest-exec
1228
1229 Returns
1230 GuestExecStatus on success.
1231
1232 Since
1233 2.5
1234
1235 GuestExec (Object)
1236 Members
1237 pid: int
1238 pid of child process in guest OS
1239
1240 Since
1241 2.5
1242
1243 guest-exec (Command)
1244 Execute a command in the guest
1245
1246 Arguments
1247 path: string
1248 path or executable name to execute
1249
1250 arg: array of string (optional)
1251 argument list to pass to executable
1252
1253 env: array of string (optional)
1254 environment variables to pass to executable
1255
1256 input-data: string (optional)
1257 data to be passed to process stdin (base64 encoded)
1258
1259 capture-output: boolean (optional)
1260 bool flag to enable capture of stdout/stderr of running process.
1261 defaults to false.
1262
1263 Returns
1264 PID on success.
1265
1266 Since
1267 2.5
1268
1269 GuestHostName (Object)
1270 Members
1271 host-name: string
1272 Fully qualified domain name of the guest OS
1273
1274 Since
1275 2.10
1276
1277 guest-get-host-name (Command)
1278 Return a name for the machine.
1279
1280 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
1284 Returns
1285 the host name of the machine on success
1286
1287 Since
1288 2.10
1289
1290 GuestUser (Object)
1291 Members
1292 user: string
1293 Username
1294
1295 domain: string (optional)
1296 Logon domain (windows only)
1297
1298 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
1303 Since
1304 2.10
1305
1306 guest-get-users (Command)
1307 Retrieves a list of currently active users on the VM.
1308
1309 Returns
1310 A unique list of users.
1311
1312 Since
1313 2.10
1314
1315 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
1321 offset: int
1322 Offset to UTC in seconds, negative numbers for time zones west
1323 of GMT, positive numbers for east
1324
1325 Since
1326 2.10
1327
1328 guest-get-timezone (Command)
1329 Retrieves the timezone information from the guest.
1330
1331 Returns
1332 A GuestTimezone dictionary.
1333
1334 Since
1335 2.10
1336
1337 GuestOSInfo (Object)
1338 Members
1339 kernel-release: string (optional)
1340
1341 • POSIX: release field returned by uname(2)
1342
1343 • Windows: build number of the OS
1344
1345 kernel-version: string (optional)
1346
1347 • POSIX: version field returned by uname(2)
1348
1349 • Windows: version number of the OS
1350
1351 machine: string (optional)
1352
1353 • POSIX: machine field returned by uname(2)
1354
1355 • Windows: one of x86, x86_64, arm, ia64
1356
1357 id: string (optional)
1358
1359 • POSIX: as defined by os-release(5)
1360
1361 • Windows: contains string "mswindows"
1362
1363 name: string (optional)
1364
1365 • POSIX: as defined by os-release(5)
1366
1367 • Windows: contains string "Microsoft Windows"
1368
1369 pretty-name: string (optional)
1370
1371 • POSIX: as defined by os-release(5)
1372
1373 • Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1374
1375 version: string (optional)
1376
1377 • POSIX: as defined by os-release(5)
1378
1379 • Windows: long version string, e.g. "Microsoft Windows Server
1380 2008"
1381
1382 version-id: string (optional)
1383
1384 • POSIX: as defined by os-release(5)
1385
1386 • Windows: short version identifier, e.g. "7" or "20012r2"
1387
1388 variant: string (optional)
1389
1390 • POSIX: as defined by os-release(5)
1391
1392 • Windows: contains string "server" or "client"
1393
1394 variant-id: string (optional)
1395
1396 • POSIX: as defined by os-release(5)
1397
1398 • Windows: contains string "server" or "client"
1399
1400 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
1408 On Windows the values are filled from information gathered from the
1409 system.
1410
1411 Since
1412 2.10
1413
1414 guest-get-osinfo (Command)
1415 Retrieve guest operating system information
1416
1417 Returns
1418 GuestOSInfo
1419
1420 Since
1421 2.10
1422
1423 GuestDeviceType (Enum)
1424 Values
1425 pci Not documented
1426
1427 GuestDeviceIdPCI (Object)
1428 Members
1429 vendor-id: int
1430 vendor ID
1431
1432 device-id: int
1433 device ID
1434
1435 Since
1436 5.2
1437
1438 GuestDeviceId (Object)
1439 Id of the device - pci: PCI ID, since: 5.2
1440
1441 Members
1442 type: GuestDeviceType
1443 Not documented
1444
1445 The members of GuestDeviceIdPCI when type is "pci"
1446
1447 Since
1448 5.2
1449
1450 GuestDeviceInfo (Object)
1451 Members
1452 driver-name: string
1453 name of the associated driver
1454
1455 driver-date: int (optional)
1456 driver release date, in nanoseconds since the epoch
1457
1458 driver-version: string (optional)
1459 driver version
1460
1461 id: GuestDeviceId (optional)
1462 device ID
1463
1464 Since
1465 5.2
1466
1467 guest-get-devices (Command)
1468 Retrieve information about device drivers in Windows guest
1469
1470 Returns
1471 GuestDeviceInfo
1472
1473 Since
1474 5.2
1475
1476 GuestAuthorizedKeys (Object)
1477 Members
1478 keys: array of string
1479 public keys (in OpenSSH/sshd(8) authorized_keys format)
1480
1481 Since
1482 5.2
1483
1484 If
1485 defined(CONFIG_POSIX)
1486
1487 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
1494 Returns
1495 GuestAuthorizedKeys
1496
1497 Since
1498 5.2
1499
1500 If
1501 defined(CONFIG_POSIX)
1502
1503 guest-ssh-add-authorized-keys (Command)
1504 Arguments
1505 username: string
1506 the user account to add the authorized keys
1507
1508 keys: array of string
1509 the public keys to add (in OpenSSH/sshd(8) authorized_keys for‐
1510 mat)
1511
1512 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
1517 Returns
1518 Nothing on success.
1519
1520 Since
1521 5.2
1522
1523 If
1524 defined(CONFIG_POSIX)
1525
1526 guest-ssh-remove-authorized-keys (Command)
1527 Arguments
1528 username: string
1529 the user account to remove the authorized keys
1530
1531 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
1538 Returns
1539 Nothing on success.
1540
1541 Since
1542 5.2
1543
1544 If
1545 defined(CONFIG_POSIX)
1546
1548 2021, The QEMU Project Developers
1549
1550
1551
1552
15536.1.0 Nov 08, 2021 QEMU-GA-REF(7)