1QEMU-GA-REF.7(7)                                              QEMU-GA-REF.7(7)
2
3
4

NAME

6       qemu-ga-ref - QEMU Guest Agent Protocol Reference
7

DESCRIPTION

9       General note concerning the use of guest agent interfaces:
10
11       "unsupported" is a higher-level error than the errors that individual
12       commands might document. The caller should always be prepared to
13       receive QERR_UNSUPPORTED, even if the given command doesn't specify it,
14       or doesn't document any failure mode at all.
15
16       guest-sync-delimited  (Command) Echo back a unique integer value, and
17       prepend to response a leading sentinel byte (0xFF) the client can check
18       scan for.
19
20       This is used by clients talking to the guest agent over the wire to
21       ensure the stream is in sync and doesn't contain stale data from
22       previous client. It must be issued upon initial connection, and after
23       any client-side timeouts (including timeouts on receiving a response to
24       this command).
25
26       After issuing this request, all guest agent responses should be ignored
27       until the response containing the unique integer value the client
28       passed in is returned. Receival of the 0xFF sentinel byte must be
29       handled as an indication that the client's lexer/tokenizer/parser state
30       should be flushed/reset in preparation for reliably receiving the
31       subsequent response. As an optimization, clients may opt to ignore all
32       data until a sentinel value is receiving to avoid unnecessary
33       processing of stale data.
34
35       Similarly, clients should also precede this request with a 0xFF byte to
36       make sure the guest agent flushes any partially read JSON data from a
37       previous client connection.
38
39       Arguments:
40
41       "id: int"
42           randomly generated 64-bit integer
43
44       Returns: The unique integer id passed in by the client
45
46       Since: 1.1
47
48       guest-sync  (Command) Echo back a unique integer value
49
50       This is used by clients talking to the guest agent over the wire to
51       ensure the stream is in sync and doesn't contain stale data from
52       previous client. All guest agent responses should be ignored until the
53       provided unique integer value is returned, and it is up to the client
54       to handle stale whole or partially-delivered JSON text in such a way
55       that this response can be obtained.
56
57       In cases where a partial stale response was previously received by the
58       client, this cannot always be done reliably.  One particular scenario
59       being if qemu-ga responses are fed character-by-character into a JSON
60       parser. In these situations, using guest-sync-delimited may be optimal.
61
62       For clients that fetch responses line by line and convert them to JSON
63       objects, guest-sync should be sufficient, but note that in cases where
64       the channel is dirty some attempts at parsing the response may result
65       in a parser error.
66
67       Such clients should also precede this command with a 0xFF byte to make
68       sure the guest agent flushes any partially read JSON data from a
69       previous session.
70
71       Arguments:
72
73       "id: int"
74           randomly generated 64-bit integer
75
76       Returns: The unique integer id passed in by the client
77
78       Since: 0.15.0
79
80       guest-ping  (Command) Ping the guest agent, a non-error return implies
81       success
82
83       Since: 0.15.0
84
85       guest-get-time  (Command) Get the information about guest's System Time
86       relative to the Epoch of 1970-01-01 in UTC.
87
88       Returns: Time in nanoseconds.
89
90       Since: 1.5
91
92       guest-set-time  (Command) Set guest time.
93
94       When a guest is paused or migrated to a file then loaded from that
95       file, the guest OS has no idea that there was a big gap in the time.
96       Depending on how long the gap was, NTP might not be able to
97       resynchronize the guest.
98
99       This command tries to set guest's System Time to the given value, then
100       sets the Hardware Clock (RTC) to the current System Time. This will
101       make it easier for a guest to resynchronize without waiting for NTP. If
102       no "time" is specified, then the time to set is read from RTC. However,
103       this may not be supported on all platforms (i.e. Windows).  If that's
104       the case users are advised to always pass a value.
105
106       Arguments:
107
108       "time: int" (optional)
109           time of nanoseconds, relative to the Epoch of 1970-01-01 in UTC.
110
111       Returns: Nothing on success.
112
113       Since: 1.5
114
115       GuestAgentCommandInfo (Object)
116
117       Information about guest agent commands.
118
119       Members:
120
121       "name: string"
122           name of the command
123
124       "enabled: boolean"
125           whether command is currently enabled by guest admin
126
127       "success-response: boolean"
128           whether command returns a response on success (since 1.7)
129
130       Since: 1.1.0
131
132       GuestAgentInfo (Object)
133
134       Information about guest agent.
135
136       Members:
137
138       "version: string"
139           guest agent version
140
141       "supported_commands: array of GuestAgentCommandInfo"
142           Information about guest agent commands
143
144       Since: 0.15.0
145
146       guest-info  (Command) Get some information about the guest agent.
147
148       Returns: "GuestAgentInfo"
149
150       Since: 0.15.0
151
152       guest-shutdown  (Command) Initiate guest-activated shutdown. Note: this
153       is an asynchronous shutdown request, with no guarantee of successful
154       shutdown.
155
156       Arguments:
157
158       "mode: string" (optional)
159           "halt", "powerdown" (default), or "reboot"
160
161       This command does NOT return a response on success. Success condition
162       is indicated by the VM exiting with a zero exit status or, when running
163       with --no-shutdown, by issuing the query-status QMP command to confirm
164       the VM status is "shutdown".
165
166       Since: 0.15.0
167
168       guest-file-open  (Command) Open a file in the guest and retrieve a file
169       handle for it
170
171       Arguments:
172
173       "path: string"
174           Full path to the file in the guest to open.
175
176       "mode: string" (optional)
177           open mode, as per fopen(), "r" is the default.
178
179       Returns: Guest file handle on success.
180
181       Since: 0.15.0
182
183       guest-file-close  (Command) Close an open file in the guest
184
185       Arguments:
186
187       "handle: int"
188           filehandle returned by guest-file-open
189
190       Returns: Nothing on success.
191
192       Since: 0.15.0
193
194       GuestFileRead (Object)
195
196       Result of guest agent file-read operation
197
198       Members:
199
200       "count: int"
201           number of bytes read (note: count is before base64-encoding is
202           applied)
203
204       "buf-b64: string"
205           base64-encoded bytes read
206
207       "eof: boolean"
208           whether EOF was encountered during read operation.
209
210       Since: 0.15.0
211
212       guest-file-read  (Command) Read from an open file in the guest. Data
213       will be base64-encoded
214
215       Arguments:
216
217       "handle: int"
218           filehandle returned by guest-file-open
219
220       "count: int" (optional)
221           maximum number of bytes to read (default is 4KB)
222
223       Returns: "GuestFileRead" on success.
224
225       Since: 0.15.0
226
227       GuestFileWrite (Object)
228
229       Result of guest agent file-write operation
230
231       Members:
232
233       "count: int"
234           number of bytes written (note: count is actual bytes written, after
235           base64-decoding of provided buffer)
236
237       "eof: boolean"
238           whether EOF was encountered during write operation.
239
240       Since: 0.15.0
241
242       guest-file-write  (Command) Write to an open file in the guest.
243
244       Arguments:
245
246       "handle: int"
247           filehandle returned by guest-file-open
248
249       "buf-b64: string"
250           base64-encoded string representing data to be written
251
252       "count: int" (optional)
253           bytes to write (actual bytes, after base64-decode), default is all
254           content in buf-b64 buffer after base64 decoding
255
256       Returns: "GuestFileWrite" on success.
257
258       Since: 0.15.0
259
260       GuestFileSeek (Object)
261
262       Result of guest agent file-seek operation
263
264       Members:
265
266       "position: int"
267           current file position
268
269       "eof: boolean"
270           whether EOF was encountered during file seek
271
272       Since: 0.15.0
273
274       QGASeek (Enum)
275
276       Symbolic names for use in "guest-file-seek"
277
278       Values:
279
280       "set"
281           Set to the specified offset (same effect as 'whence':0)
282
283       "cur"
284           Add offset to the current location (same effect as 'whence':1)
285
286       "end"
287           Add offset to the end of the file (same effect as 'whence':2)
288
289       Since: 2.6
290
291       GuestFileWhence (Alternate)
292
293       Controls the meaning of offset to "guest-file-seek".
294
295       Members:
296
297       "value: int"
298           Integral value (0 for set, 1 for cur, 2 for end), available for
299           historical reasons, and might differ from the host's or guest's
300           SEEK_* values (since: 0.15)
301
302       "name: QGASeek"
303           Symbolic name, and preferred interface
304
305       Since: 2.6
306
307       guest-file-seek  (Command) Seek to a position in the file, as with
308       fseek(), and return the current file position afterward. Also
309       encapsulates ftell()'s functionality, with offset=0 and whence=1.
310
311       Arguments:
312
313       "handle: int"
314           filehandle returned by guest-file-open
315
316       "offset: int"
317           bytes to skip over in the file stream
318
319       "whence: GuestFileWhence"
320           Symbolic or numeric code for interpreting offset
321
322       Returns: "GuestFileSeek" on success.
323
324       Since: 0.15.0
325
326       guest-file-flush  (Command) Write file changes bufferred in userspace
327       to disk/kernel buffers
328
329       Arguments:
330
331       "handle: int"
332           filehandle returned by guest-file-open
333
334       Returns: Nothing on success.
335
336       Since: 0.15.0
337
338       GuestFsfreezeStatus (Enum)
339
340       An enumeration of filesystem freeze states
341
342       Values:
343
344       "thawed"
345           filesystems thawed/unfrozen
346
347       "frozen"
348           all non-network guest filesystems frozen
349
350       Since: 0.15.0
351
352       guest-fsfreeze-status  (Command) Get guest fsfreeze state. error state
353       indicates
354
355       Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
356       below)
357
358       Note: This may fail to properly report the current state as a result of
359       some other guest processes having issued an fs freeze/thaw.
360
361       Since: 0.15.0
362
363       guest-fsfreeze-freeze  (Command) Sync and freeze all freezable, local
364       guest filesystems. If this command succeeded, you may call
365       "guest-fsfreeze-thaw" later to unfreeze.
366
367       Note: On Windows, the command is implemented with the help of a Volume
368       Shadow-copy Service DLL helper. The frozen state is limited for up to
369       10 seconds by VSS.
370
371       Returns: Number of file systems currently frozen. On error, all
372       filesystems will be thawed. If no filesystems are frozen as a result of
373       this call, then "guest-fsfreeze-status" will remain "thawed" and
374       calling "guest-fsfreeze-thaw" is not necessary.
375
376       Since: 0.15.0
377
378       guest-fsfreeze-freeze-list  (Command) Sync and freeze specified guest
379       filesystems.  See also "guest-fsfreeze-freeze".
380
381       Arguments:
382
383       "mountpoints: array of string" (optional)
384           an array of mountpoints of filesystems to be frozen.  If omitted,
385           every mounted filesystem is frozen.  Invalid mount points are
386           ignored.
387
388       Returns: Number of file systems currently frozen. On error, all
389       filesystems will be thawed.
390
391       Since: 2.2
392
393       guest-fsfreeze-thaw  (Command) Unfreeze all frozen guest filesystems
394
395       Returns: Number of file systems thawed by this call
396
397       Note: if return value does not match the previous call to guest-
398       fsfreeze-freeze, this likely means some freezable filesystems were
399       unfrozen before this call, and that the filesystem state may have
400       changed before issuing this command.
401
402       Since: 0.15.0
403
404       GuestFilesystemTrimResult (Object)
405
406       Members:
407
408       "path: string"
409           path that was trimmed
410
411       "error: string" (optional)
412           an error message when trim failed
413
414       "trimmed: int" (optional)
415           bytes trimmed for this path
416
417       "minimum: int" (optional)
418           reported effective minimum for this path
419
420       Since: 2.4
421
422       GuestFilesystemTrimResponse (Object)
423
424       Members:
425
426       "paths: array of GuestFilesystemTrimResult"
427           list of "GuestFilesystemTrimResult" per path that was trimmed
428
429       Since: 2.4
430
431       guest-fstrim  (Command) Discard (or "trim") blocks which are not in use
432       by the filesystem.
433
434       Arguments:
435
436       "minimum: int" (optional)
437           Minimum contiguous free range to discard, in bytes. Free ranges
438           smaller than this may be ignored (this is a hint and the guest may
439           not respect it).  By increasing this value, the fstrim operation
440           will complete more quickly for filesystems with badly fragmented
441           free space, although not all blocks will be discarded.  The default
442           value is zero, meaning "discard every free block".
443
444       Returns: A "GuestFilesystemTrimResponse" which contains the status of
445       all trimmed paths. (since 2.4)
446
447       Since: 1.2
448
449       guest-suspend-disk  (Command) Suspend guest to disk.
450
451       This command attempts to suspend the guest using three strategies, in
452       this order:
453
454       -   systemd hibernate
455
456       -   pm-utils (via pm-hibernate)
457
458       -   manual write into sysfs
459
460       This command does NOT return a response on success. There is a high
461       chance the command succeeded if the VM exits with a zero exit status
462       or, when running with --no-shutdown, by issuing the query-status QMP
463       command to to confirm the VM status is "shutdown". However, the VM
464       could also exit (or set its status to "shutdown") due to other reasons.
465
466       The following errors may be returned: If suspend to disk is not
467       supported, Unsupported
468
469       Notes: It's strongly recommended to issue the guest-sync command before
470       sending commands when the guest resumes
471
472       Since: 1.1
473
474       guest-suspend-ram  (Command) Suspend guest to ram.
475
476       This command attempts to suspend the guest using three strategies, in
477       this order:
478
479       -   systemd suspend
480
481       -   pm-utils (via pm-suspend)
482
483       -   manual write into sysfs
484
485       IMPORTANT: guest-suspend-ram requires working wakeup support in QEMU.
486       You should check QMP command query-current-machine returns wakeup-
487       suspend-support: true before issuing this command. Failure in doing so
488       can result in a suspended guest that QEMU will not be able to awaken,
489       forcing the user to power cycle the guest to bring it back.
490
491       This command does NOT return a response on success. There are two
492       options to check for success:
493
494       1.  Wait for the SUSPEND QMP event from QEMU
495
496       2.  Issue the query-status QMP command to confirm the VM status is
497           "suspended"
498
499       The following errors may be returned: If suspend to ram is not
500       supported, Unsupported
501
502       Notes: It's strongly recommended to issue the guest-sync command before
503       sending commands when the guest resumes
504
505       Since: 1.1
506
507       guest-suspend-hybrid  (Command) Save guest state to disk and suspend to
508       ram.
509
510       This command attempts to suspend the guest by executing, in this order:
511
512       -   systemd hybrid-sleep
513
514       -   pm-utils (via pm-suspend-hybrid)
515
516       IMPORTANT: guest-suspend-hybrid requires working wakeup support in
517       QEMU. You should check QMP command query-current-machine returns
518       wakeup-suspend-support: true before issuing this command. Failure in
519       doing so can result in a suspended guest that QEMU will not be able to
520       awaken, forcing the user to power cycle the guest to bring it back.
521
522       This command does NOT return a response on success. There are two
523       options to check for success:
524
525       1.  Wait for the SUSPEND QMP event from QEMU
526
527       2.  Issue the query-status QMP command to confirm the VM status is
528           "suspended"
529
530       The following errors may be returned: If hybrid suspend is not
531       supported, Unsupported
532
533       Notes: It's strongly recommended to issue the guest-sync command before
534       sending commands when the guest resumes
535
536       Since: 1.1
537
538       GuestIpAddressType (Enum)
539
540       An enumeration of supported IP address types
541
542       Values:
543
544       "ipv4"
545           IP version 4
546
547       "ipv6"
548           IP version 6
549
550       Since: 1.1
551
552       GuestIpAddress (Object)
553
554       Members:
555
556       "ip-address: string"
557           IP address
558
559       "ip-address-type: GuestIpAddressType"
560           Type of "ip-address" (e.g. ipv4, ipv6)
561
562       "prefix: int"
563           Network prefix length of "ip-address"
564
565       Since: 1.1
566
567       GuestNetworkInterfaceStat (Object)
568
569       Members:
570
571       "rx-bytes: int"
572           total bytes received
573
574       "rx-packets: int"
575           total packets received
576
577       "rx-errs: int"
578           bad packets received
579
580       "rx-dropped: int"
581           receiver dropped packets
582
583       "tx-bytes: int"
584           total bytes transmitted
585
586       "tx-packets: int"
587           total packets transmitted
588
589       "tx-errs: int"
590           packet transmit problems
591
592       "tx-dropped: int"
593           dropped packets transmitted
594
595       Since: 2.11
596
597       GuestNetworkInterface (Object)
598
599       Members:
600
601       "name: string"
602           The name of interface for which info are being delivered
603
604       "hardware-address: string" (optional)
605           Hardware address of "name"
606
607       "ip-addresses: array of GuestIpAddress" (optional)
608           List of addresses assigned to "name"
609
610       "statistics: GuestNetworkInterfaceStat" (optional)
611           various statistic counters related to "name" (since 2.11)
612
613       Since: 1.1
614
615       guest-network-get-interfaces  (Command) Get list of guest IP addresses,
616       MAC addresses and netmasks.
617
618       Returns: List of GuestNetworkInfo on success.
619
620       Since: 1.1
621
622       GuestLogicalProcessor (Object)
623
624       Members:
625
626       "logical-id: int"
627           Arbitrary guest-specific unique identifier of the VCPU.
628
629       "online: boolean"
630           Whether the VCPU is enabled.
631
632       "can-offline: boolean" (optional)
633           Whether offlining the VCPU is possible. This member is always
634           filled in by the guest agent when the structure is returned, and
635           always ignored on input (hence it can be omitted then).
636
637       Since: 1.5
638
639       guest-get-vcpus  (Command) Retrieve the list of the guest's logical
640       processors.
641
642       This is a read-only operation.
643
644       Returns: The list of all VCPUs the guest knows about. Each VCPU is put
645       on the list exactly once, but their order is unspecified.
646
647       Since: 1.5
648
649       guest-set-vcpus  (Command) Attempt to reconfigure (currently:
650       enable/disable) logical processors inside the guest.
651
652       The input list is processed node by node in order. In each node
653       "logical-id" is used to look up the guest VCPU, for which "online"
654       specifies the requested state. The set of distinct "logical-id"'s is
655       only required to be a subset of the guest-supported identifiers.
656       There's no restriction on list length or on repeating the same
657       "logical-id" (with possibly different "online" field).  Preferably the
658       input list should describe a modified subset of "guest-get-vcpus"'
659       return value.
660
661       Arguments:
662
663       "vcpus: array of GuestLogicalProcessor"
664           Not documented
665
666       Returns: The length of the initial sublist that has been successfully
667       processed. The guest agent maximizes this value. Possible cases:
668
669       -   0:              if the "vcpus" list was empty on input. Guest state
670           has not been changed. Otherwise,
671
672       -   Error:          processing the first node of "vcpus" failed for the
673           reason returned. Guest state has not been changed.  Otherwise,
674
675       -   < length("vcpus"): more than zero initial nodes have been
676           processed, but not the entire "vcpus" list. Guest state has changed
677           accordingly. To retrieve the error (assuming it persists), repeat
678           the call with the successfully processed initial sublist removed.
679           Otherwise,
680
681       -   length("vcpus"): call successful.
682
683       Since: 1.5
684
685       GuestDiskBusType (Enum)
686
687       An enumeration of bus type of disks
688
689       Values:
690
691       "ide"
692           IDE disks
693
694       "fdc"
695           floppy disks
696
697       "scsi"
698           SCSI disks
699
700       "virtio"
701           virtio disks
702
703       "xen"
704           Xen disks
705
706       "usb"
707           USB disks
708
709       "uml"
710           UML disks
711
712       "sata"
713           SATA disks
714
715       "sd"
716           SD cards
717
718       "unknown"
719           Unknown bus type
720
721       "ieee1394"
722           Win IEEE 1394 bus type
723
724       "ssa"
725           Win SSA bus type
726
727       "fibre"
728           Win fiber channel bus type
729
730       "raid"
731           Win RAID bus type
732
733       "iscsi"
734           Win iScsi bus type
735
736       "sas"
737           Win serial-attaches SCSI bus type
738
739       "mmc"
740           Win multimedia card (MMC) bus type
741
742       "virtual"
743           Win virtual bus type "file-backed" virtual: Win file-backed bus
744           type
745
746       "file-backed-virtual"
747           Not documented
748
749       Since: 2.2; 'Unknown' and all entries below since 2.4
750
751       GuestPCIAddress (Object)
752
753       Members:
754
755       "domain: int"
756           domain id
757
758       "bus: int"
759           bus id
760
761       "slot: int"
762           slot id
763
764       "function: int"
765           function id
766
767       Since: 2.2
768
769       GuestDiskAddress (Object)
770
771       Members:
772
773       "pci-controller: GuestPCIAddress"
774           controller's PCI address
775
776       "bus-type: GuestDiskBusType"
777           bus type
778
779       "bus: int"
780           bus id
781
782       "target: int"
783           target id
784
785       "unit: int"
786           unit id
787
788       "serial: string" (optional)
789           serial number (since: 3.1)
790
791       "dev: string" (optional)
792           device node (POSIX) or device UNC (Windows) (since: 3.1)
793
794       Since: 2.2
795
796       GuestFilesystemInfo (Object)
797
798       Members:
799
800       "name: string"
801           disk name
802
803       "mountpoint: string"
804           mount point path
805
806       "type: string"
807           file system type string
808
809       "used-bytes: int" (optional)
810           file system used bytes (since 3.0)
811
812       "total-bytes: int" (optional)
813           non-root file system total bytes (since 3.0)
814
815       "disk: array of GuestDiskAddress"
816           an array of disk hardware information that the volume lies on,
817           which may be empty if the disk type is not supported
818
819       Since: 2.2
820
821       guest-get-fsinfo  (Command)
822
823       Returns: The list of filesystems information mounted in the guest.  The
824       returned mountpoints may be specified to "guest-fsfreeze-freeze-list".
825       Network filesystems (such as CIFS and NFS) are not listed.
826
827       Since: 2.2
828
829       guest-set-user-password  (Command)
830
831       Arguments:
832
833       "username: string"
834           the user account whose password to change
835
836       "password: string"
837           the new password entry string, base64 encoded
838
839       "crypted: boolean"
840           true if password is already crypt()d, false if raw
841
842       If the "crypted" flag is true, it is the caller's responsibility to
843       ensure the correct crypt() encryption scheme is used. This command does
844       not attempt to interpret or report on the encryption scheme. Refer to
845       the documentation of the guest operating system in question to
846       determine what is supported.
847
848       Not all guest operating systems will support use of the "crypted" flag,
849       as they may require the clear-text password
850
851       The "password" parameter must always be base64 encoded before
852       transmission, even if already crypt()d, to ensure it is 8-bit safe when
853       passed as JSON.
854
855       Returns: Nothing on success.
856
857       Since: 2.3
858
859       GuestMemoryBlock (Object)
860
861       Members:
862
863       "phys-index: int"
864           Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
865
866       "online: boolean"
867           Whether the MEMORY BLOCK is enabled in guest.
868
869       "can-offline: boolean" (optional)
870           Whether offlining the MEMORY BLOCK is possible.  This member is
871           always filled in by the guest agent when the structure is returned,
872           and always ignored on input (hence it can be omitted then).
873
874       Since: 2.3
875
876       guest-get-memory-blocks  (Command) Retrieve the list of the guest's
877       memory blocks.
878
879       This is a read-only operation.
880
881       Returns: The list of all memory blocks the guest knows about.  Each
882       memory block is put on the list exactly once, but their order is
883       unspecified.
884
885       Since: 2.3
886
887       GuestMemoryBlockResponseType (Enum)
888
889       An enumeration of memory block operation result.
890
891       Values:
892
893       "success"
894           the operation of online/offline memory block is successful.
895
896       "not-found"
897           can't find the corresponding memoryXXX directory in sysfs.
898
899       "operation-not-supported"
900           for some old kernels, it does not support online or offline memory
901           block.
902
903       "operation-failed"
904           the operation of online/offline memory block fails, because of some
905           errors happen.
906
907       Since: 2.3
908
909       GuestMemoryBlockResponse (Object)
910
911       Members:
912
913       "phys-index: int"
914           same with the 'phys-index' member of "GuestMemoryBlock".
915
916       "response: GuestMemoryBlockResponseType"
917           the result of memory block operation.
918
919       "error-code: int" (optional)
920           the error number.  When memory block operation fails, we assign the
921           value of 'errno' to this member, it indicates what goes wrong.
922           When the operation succeeds, it will be omitted.
923
924       Since: 2.3
925
926       guest-set-memory-blocks  (Command) Attempt to reconfigure (currently:
927       enable/disable) state of memory blocks inside the guest.
928
929       The input list is processed node by node in order. In each node
930       "phys-index" is used to look up the guest MEMORY BLOCK, for which
931       "online" specifies the requested state. The set of distinct
932       "phys-index"'s is only required to be a subset of the guest-supported
933       identifiers. There's no restriction on list length or on repeating the
934       same "phys-index" (with possibly different "online" field).  Preferably
935       the input list should describe a modified subset of
936       "guest-get-memory-blocks"' return value.
937
938       Arguments:
939
940       "mem-blks: array of GuestMemoryBlock"
941           Not documented
942
943       Returns: The operation results, it is a list of
944       "GuestMemoryBlockResponse", which is corresponding to the input list.
945
946       Note: it will return NULL if the "mem-blks" list was empty on input, or
947       there is an error, and in this case, guest state will not be changed.
948
949       Since: 2.3
950
951       GuestMemoryBlockInfo (Object)
952
953       Members:
954
955       "size: int"
956           the size (in bytes) of the guest memory blocks, which are the
957           minimal units of memory block online/offline operations (also
958           called Logical Memory Hotplug).
959
960       Since: 2.3
961
962       guest-get-memory-block-info  (Command) Get information relating to
963       guest memory blocks.
964
965       Returns: "GuestMemoryBlockInfo"
966
967       Since: 2.3
968
969       GuestExecStatus (Object)
970
971       Members:
972
973       "exited: boolean"
974           true if process has already terminated.
975
976       "exitcode: int" (optional)
977           process exit code if it was normally terminated.
978
979       "signal: int" (optional)
980           signal number (linux) or unhandled exception code (windows) if the
981           process was abnormally terminated.
982
983       "out-data: string" (optional)
984           base64-encoded stdout of the process
985
986       "err-data: string" (optional)
987           base64-encoded stderr of the process Note: "out-data" and
988           "err-data" are present only if 'capture-output' was specified for
989           'guest-exec'
990
991       "out-truncated: boolean" (optional)
992           true if stdout was not fully captured due to size limitation.
993
994       "err-truncated: boolean" (optional)
995           true if stderr was not fully captured due to size limitation.
996
997       Since: 2.5
998
999       guest-exec-status  (Command) Check status of process associated with
1000       PID retrieved via guest-exec.  Reap the process and associated metadata
1001       if it has exited.
1002
1003       Arguments:
1004
1005       "pid: int"
1006           pid returned from guest-exec
1007
1008       Returns: GuestExecStatus on success.
1009
1010       Since: 2.5
1011
1012       GuestExec (Object)
1013
1014       Members:
1015
1016       "pid: int"
1017           pid of child process in guest OS
1018
1019       Since: 2.5
1020
1021       guest-exec  (Command) Execute a command in the guest
1022
1023       Arguments:
1024
1025       "path: string"
1026           path or executable name to execute
1027
1028       "arg: array of string" (optional)
1029           argument list to pass to executable
1030
1031       "env: array of string" (optional)
1032           environment variables to pass to executable
1033
1034       "input-data: string" (optional)
1035           data to be passed to process stdin (base64 encoded)
1036
1037       "capture-output: boolean" (optional)
1038           bool flag to enable capture of stdout/stderr of running process.
1039           defaults to false.
1040
1041       Returns: PID on success.
1042
1043       Since: 2.5
1044
1045       GuestHostName (Object)
1046
1047       Members:
1048
1049       "host-name: string"
1050           Fully qualified domain name of the guest OS
1051
1052       Since: 2.10
1053
1054       guest-get-host-name  (Command) Return a name for the machine.
1055
1056       The returned name is not necessarily a fully-qualified domain name, or
1057       even present in DNS or some other name service at all. It need not even
1058       be unique on your local network or site, but usually it is.
1059
1060       Returns: the host name of the machine on success
1061
1062       Since: 2.10
1063
1064       GuestUser (Object)
1065
1066       Members:
1067
1068       "user: string"
1069           Username
1070
1071       "domain: string" (optional)
1072           Logon domain (windows only)
1073
1074       "login-time: number"
1075           Time of login of this user on the computer. If multiple instances
1076           of the user are logged in, the earliest login time is reported. The
1077           value is in fractional seconds since epoch time.
1078
1079       Since: 2.10
1080
1081       guest-get-users  (Command) Retrieves a list of currently active users
1082       on the VM.
1083
1084       Returns: A unique list of users.
1085
1086       Since: 2.10
1087
1088       GuestTimezone (Object)
1089
1090       Members:
1091
1092       "zone: string" (optional)
1093           Timezone name. These values may differ depending on guest/OS and
1094           should only be used for informational purposes.
1095
1096       "offset: int"
1097           Offset to UTC in seconds, negative numbers for time zones west of
1098           GMT, positive numbers for east
1099
1100       Since: 2.10
1101
1102       guest-get-timezone  (Command) Retrieves the timezone information from
1103       the guest.
1104
1105       Returns: A GuestTimezone dictionary.
1106
1107       Since: 2.10
1108
1109       GuestOSInfo (Object)
1110
1111       Members:
1112
1113       "kernel-release: string" (optional)
1114           ·   POSIX: release field returned by uname(2)
1115
1116           ·   Windows: build number of the OS
1117
1118       "kernel-version: string" (optional)
1119           ·   POSIX: version field returned by uname(2)
1120
1121           ·   Windows: version number of the OS
1122
1123       "machine: string" (optional)
1124           ·   POSIX: machine field returned by uname(2)
1125
1126           ·   Windows: one of x86, x86_64, arm, ia64
1127
1128       "id: string" (optional)
1129           ·   POSIX: as defined by os-release(5)
1130
1131           ·   Windows: contains string "mswindows"
1132
1133       "name: string" (optional)
1134           ·   POSIX: as defined by os-release(5)
1135
1136           ·   Windows: contains string "Microsoft Windows"
1137
1138       "pretty-name: string" (optional)
1139           ·   POSIX: as defined by os-release(5)
1140
1141           ·   Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1142
1143       "version: string" (optional)
1144           ·   POSIX: as defined by os-release(5)
1145
1146           ·   Windows: long version string, e.g. "Microsoft Windows Server
1147               2008"
1148
1149       "version-id: string" (optional)
1150           ·   POSIX: as defined by os-release(5)
1151
1152           ·   Windows: short version identifier, e.g. "7" or "20012r2"
1153
1154       "variant: string" (optional)
1155           ·   POSIX: as defined by os-release(5)
1156
1157           ·   Windows: contains string "server" or "client"
1158
1159       "variant-id: string" (optional)
1160           ·   POSIX: as defined by os-release(5)
1161
1162           ·   Windows: contains string "server" or "client"
1163
1164       Notes: On POSIX systems the fields "id", "name", "pretty-name",
1165       "version", "version-id", "variant" and "variant-id" follow the
1166       definition specified in os-release(5).  Refer to the manual page for
1167       exact description of the fields. Their values are taken from the os-
1168       release file. If the file is not present in the system, or the values
1169       are not present in the file, the fields are not included.
1170
1171       On Windows the values are filled from information gathered from the
1172       system.
1173
1174       Since: 2.10
1175
1176       guest-get-osinfo  (Command) Retrieve guest operating system information
1177
1178       Returns: "GuestOSInfo"
1179
1180       Since: 2.10
1181
1182
1183
1184                                  2019-11-15                  QEMU-GA-REF.7(7)