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 tries to execute the scripts provided by the pm-utils
452       package.  If it's not available, the suspend operation will be
453       performed by manually writing to a sysfs file.
454
455       For the best results it's strongly recommended to have the pm-utils
456       package installed in the guest.
457
458       This command does NOT return a response on success. There is a high
459       chance the command succeeded if the VM exits with a zero exit status
460       or, when running with --no-shutdown, by issuing the query-status QMP
461       command to to confirm the VM status is "shutdown". However, the VM
462       could also exit (or set its status to "shutdown") due to other reasons.
463
464       The following errors may be returned: If suspend to disk is not
465       supported, Unsupported
466
467       Notes: It's strongly recommended to issue the guest-sync command before
468       sending commands when the guest resumes
469
470       Since: 1.1
471
472       guest-suspend-ram  (Command) Suspend guest to ram.
473
474       This command tries to execute the scripts provided by the pm-utils
475       package.  If it's not available, the suspend operation will be
476       performed by manually writing to a sysfs file.
477
478       For the best results it's strongly recommended to have the pm-utils
479       package installed in the guest.
480
481       IMPORTANT: guest-suspend-ram requires QEMU to support the
482       'system_wakeup' command.  Thus, it's required to query QEMU for the
483       presence of the 'system_wakeup' command before issuing guest-suspend-
484       ram.
485
486       This command does NOT return a response on success. There are two
487       options to check for success:
488
489       1.  Wait for the SUSPEND QMP event from QEMU
490
491       2.  Issue the query-status QMP command to confirm the VM status is
492           "suspended"
493
494       The following errors may be returned: If suspend to ram is not
495       supported, Unsupported
496
497       Notes: It's strongly recommended to issue the guest-sync command before
498       sending commands when the guest resumes
499
500       Since: 1.1
501
502       guest-suspend-hybrid  (Command) Save guest state to disk and suspend to
503       ram.
504
505       This command requires the pm-utils package to be installed in the
506       guest.
507
508       IMPORTANT: guest-suspend-hybrid requires QEMU to support the
509       'system_wakeup' command.  Thus, it's required to query QEMU for the
510       presence of the 'system_wakeup' command before issuing guest-suspend-
511       hybrid.
512
513       This command does NOT return a response on success. There are two
514       options to check for success:
515
516       1.  Wait for the SUSPEND QMP event from QEMU
517
518       2.  Issue the query-status QMP command to confirm the VM status is
519           "suspended"
520
521       The following errors may be returned: If hybrid suspend is not
522       supported, Unsupported
523
524       Notes: It's strongly recommended to issue the guest-sync command before
525       sending commands when the guest resumes
526
527       Since: 1.1
528
529       GuestIpAddressType (Enum)
530
531       An enumeration of supported IP address types
532
533       Values:
534
535       "ipv4"
536           IP version 4
537
538       "ipv6"
539           IP version 6
540
541       Since: 1.1
542
543       GuestIpAddress (Object)
544
545       Members:
546
547       "ip-address: string"
548           IP address
549
550       "ip-address-type: GuestIpAddressType"
551           Type of "ip-address" (e.g. ipv4, ipv6)
552
553       "prefix: int"
554           Network prefix length of "ip-address"
555
556       Since: 1.1
557
558       GuestNetworkInterfaceStat (Object)
559
560       Members:
561
562       "rx-bytes: int"
563           total bytes received
564
565       "rx-packets: int"
566           total packets received
567
568       "rx-errs: int"
569           bad packets received
570
571       "rx-dropped: int"
572           receiver dropped packets
573
574       "tx-bytes: int"
575           total bytes transmitted
576
577       "tx-packets: int"
578           total packets transmitted
579
580       "tx-errs: int"
581           packet transmit problems
582
583       "tx-dropped: int"
584           dropped packets transmitted
585
586       Since: 2.11
587
588       GuestNetworkInterface (Object)
589
590       Members:
591
592       "name: string"
593           The name of interface for which info are being delivered
594
595       "hardware-address: string" (optional)
596           Hardware address of "name"
597
598       "ip-addresses: array of GuestIpAddress" (optional)
599           List of addresses assigned to "name"
600
601       "statistics: GuestNetworkInterfaceStat" (optional)
602           various statistic counters related to "name" (since 2.11)
603
604       Since: 1.1
605
606       guest-network-get-interfaces  (Command) Get list of guest IP addresses,
607       MAC addresses and netmasks.
608
609       Returns: List of GuestNetworkInfo on success.
610
611       Since: 1.1
612
613       GuestLogicalProcessor (Object)
614
615       Members:
616
617       "logical-id: int"
618           Arbitrary guest-specific unique identifier of the VCPU.
619
620       "online: boolean"
621           Whether the VCPU is enabled.
622
623       "can-offline: boolean" (optional)
624           Whether offlining the VCPU is possible. This member is always
625           filled in by the guest agent when the structure is returned, and
626           always ignored on input (hence it can be omitted then).
627
628       Since: 1.5
629
630       guest-get-vcpus  (Command) Retrieve the list of the guest's logical
631       processors.
632
633       This is a read-only operation.
634
635       Returns: The list of all VCPUs the guest knows about. Each VCPU is put
636       on the list exactly once, but their order is unspecified.
637
638       Since: 1.5
639
640       guest-set-vcpus  (Command) Attempt to reconfigure (currently:
641       enable/disable) logical processors inside the guest.
642
643       The input list is processed node by node in order. In each node
644       "logical-id" is used to look up the guest VCPU, for which "online"
645       specifies the requested state. The set of distinct "logical-id"'s is
646       only required to be a subset of the guest-supported identifiers.
647       There's no restriction on list length or on repeating the same
648       "logical-id" (with possibly different "online" field).  Preferably the
649       input list should describe a modified subset of "guest-get-vcpus"'
650       return value.
651
652       Arguments:
653
654       "vcpus: array of GuestLogicalProcessor"
655           Not documented
656
657       Returns: The length of the initial sublist that has been successfully
658       processed. The guest agent maximizes this value. Possible cases:
659
660       -   0:              if the "vcpus" list was empty on input. Guest state
661           has not been changed. Otherwise,
662
663       -   Error:          processing the first node of "vcpus" failed for the
664           reason returned. Guest state has not been changed.  Otherwise,
665
666       -   < length("vcpus"): more than zero initial nodes have been
667           processed, but not the entire "vcpus" list. Guest state has changed
668           accordingly. To retrieve the error (assuming it persists), repeat
669           the call with the successfully processed initial sublist removed.
670           Otherwise,
671
672       -   length("vcpus"): call successful.
673
674       Since: 1.5
675
676       GuestDiskBusType (Enum)
677
678       An enumeration of bus type of disks
679
680       Values:
681
682       "ide"
683           IDE disks
684
685       "fdc"
686           floppy disks
687
688       "scsi"
689           SCSI disks
690
691       "virtio"
692           virtio disks
693
694       "xen"
695           Xen disks
696
697       "usb"
698           USB disks
699
700       "uml"
701           UML disks
702
703       "sata"
704           SATA disks
705
706       "sd"
707           SD cards
708
709       "unknown"
710           Unknown bus type
711
712       "ieee1394"
713           Win IEEE 1394 bus type
714
715       "ssa"
716           Win SSA bus type
717
718       "fibre"
719           Win fiber channel bus type
720
721       "raid"
722           Win RAID bus type
723
724       "iscsi"
725           Win iScsi bus type
726
727       "sas"
728           Win serial-attaches SCSI bus type
729
730       "mmc"
731           Win multimedia card (MMC) bus type
732
733       "virtual"
734           Win virtual bus type "file-backed" virtual: Win file-backed bus
735           type
736
737       "file-backed-virtual"
738           Not documented
739
740       Since: 2.2; 'Unknown' and all entries below since 2.4
741
742       GuestPCIAddress (Object)
743
744       Members:
745
746       "domain: int"
747           domain id
748
749       "bus: int"
750           bus id
751
752       "slot: int"
753           slot id
754
755       "function: int"
756           function id
757
758       Since: 2.2
759
760       GuestDiskAddress (Object)
761
762       Members:
763
764       "pci-controller: GuestPCIAddress"
765           controller's PCI address
766
767       "bus-type: GuestDiskBusType"
768           bus type
769
770       "bus: int"
771           bus id
772
773       "target: int"
774           target id
775
776       "unit: int"
777           unit id
778
779       "serial: string" (optional)
780           serial number (since: 3.1)
781
782       "dev: string" (optional)
783           device node (POSIX) or device UNC (Windows) (since: 3.1)
784
785       Since: 2.2
786
787       GuestFilesystemInfo (Object)
788
789       Members:
790
791       "name: string"
792           disk name
793
794       "mountpoint: string"
795           mount point path
796
797       "type: string"
798           file system type string
799
800       "used-bytes: int" (optional)
801           file system used bytes (since 3.0)
802
803       "total-bytes: int" (optional)
804           non-root file system total bytes (since 3.0)
805
806       "disk: array of GuestDiskAddress"
807           an array of disk hardware information that the volume lies on,
808           which may be empty if the disk type is not supported
809
810       Since: 2.2
811
812       guest-get-fsinfo  (Command)
813
814       Returns: The list of filesystems information mounted in the guest.  The
815       returned mountpoints may be specified to "guest-fsfreeze-freeze-list".
816       Network filesystems (such as CIFS and NFS) are not listed.
817
818       Since: 2.2
819
820       guest-set-user-password  (Command)
821
822       Arguments:
823
824       "username: string"
825           the user account whose password to change
826
827       "password: string"
828           the new password entry string, base64 encoded
829
830       "crypted: boolean"
831           true if password is already crypt()d, false if raw
832
833       If the "crypted" flag is true, it is the caller's responsibility to
834       ensure the correct crypt() encryption scheme is used. This command does
835       not attempt to interpret or report on the encryption scheme. Refer to
836       the documentation of the guest operating system in question to
837       determine what is supported.
838
839       Not all guest operating systems will support use of the "crypted" flag,
840       as they may require the clear-text password
841
842       The "password" parameter must always be base64 encoded before
843       transmission, even if already crypt()d, to ensure it is 8-bit safe when
844       passed as JSON.
845
846       Returns: Nothing on success.
847
848       Since: 2.3
849
850       GuestMemoryBlock (Object)
851
852       Members:
853
854       "phys-index: int"
855           Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
856
857       "online: boolean"
858           Whether the MEMORY BLOCK is enabled in guest.
859
860       "can-offline: boolean" (optional)
861           Whether offlining the MEMORY BLOCK is possible.  This member is
862           always filled in by the guest agent when the structure is returned,
863           and always ignored on input (hence it can be omitted then).
864
865       Since: 2.3
866
867       guest-get-memory-blocks  (Command) Retrieve the list of the guest's
868       memory blocks.
869
870       This is a read-only operation.
871
872       Returns: The list of all memory blocks the guest knows about.  Each
873       memory block is put on the list exactly once, but their order is
874       unspecified.
875
876       Since: 2.3
877
878       GuestMemoryBlockResponseType (Enum)
879
880       An enumeration of memory block operation result.
881
882       Values:
883
884       "success"
885           the operation of online/offline memory block is successful.
886
887       "not-found"
888           can't find the corresponding memoryXXX directory in sysfs.
889
890       "operation-not-supported"
891           for some old kernels, it does not support online or offline memory
892           block.
893
894       "operation-failed"
895           the operation of online/offline memory block fails, because of some
896           errors happen.
897
898       Since: 2.3
899
900       GuestMemoryBlockResponse (Object)
901
902       Members:
903
904       "phys-index: int"
905           same with the 'phys-index' member of "GuestMemoryBlock".
906
907       "response: GuestMemoryBlockResponseType"
908           the result of memory block operation.
909
910       "error-code: int" (optional)
911           the error number.  When memory block operation fails, we assign the
912           value of 'errno' to this member, it indicates what goes wrong.
913           When the operation succeeds, it will be omitted.
914
915       Since: 2.3
916
917       guest-set-memory-blocks  (Command) Attempt to reconfigure (currently:
918       enable/disable) state of memory blocks inside the guest.
919
920       The input list is processed node by node in order. In each node
921       "phys-index" is used to look up the guest MEMORY BLOCK, for which
922       "online" specifies the requested state. The set of distinct
923       "phys-index"'s is only required to be a subset of the guest-supported
924       identifiers. There's no restriction on list length or on repeating the
925       same "phys-index" (with possibly different "online" field).  Preferably
926       the input list should describe a modified subset of
927       "guest-get-memory-blocks"' return value.
928
929       Arguments:
930
931       "mem-blks: array of GuestMemoryBlock"
932           Not documented
933
934       Returns: The operation results, it is a list of
935       "GuestMemoryBlockResponse", which is corresponding to the input list.
936
937       Note: it will return NULL if the "mem-blks" list was empty on input, or
938       there is an error, and in this case, guest state will not be changed.
939
940       Since: 2.3
941
942       GuestMemoryBlockInfo (Object)
943
944       Members:
945
946       "size: int"
947           the size (in bytes) of the guest memory blocks, which are the
948           minimal units of memory block online/offline operations (also
949           called Logical Memory Hotplug).
950
951       Since: 2.3
952
953       guest-get-memory-block-info  (Command) Get information relating to
954       guest memory blocks.
955
956       Returns: "GuestMemoryBlockInfo"
957
958       Since: 2.3
959
960       GuestExecStatus (Object)
961
962       Members:
963
964       "exited: boolean"
965           true if process has already terminated.
966
967       "exitcode: int" (optional)
968           process exit code if it was normally terminated.
969
970       "signal: int" (optional)
971           signal number (linux) or unhandled exception code (windows) if the
972           process was abnormally terminated.
973
974       "out-data: string" (optional)
975           base64-encoded stdout of the process
976
977       "err-data: string" (optional)
978           base64-encoded stderr of the process Note: "out-data" and
979           "err-data" are present only if 'capture-output' was specified for
980           'guest-exec'
981
982       "out-truncated: boolean" (optional)
983           true if stdout was not fully captured due to size limitation.
984
985       "err-truncated: boolean" (optional)
986           true if stderr was not fully captured due to size limitation.
987
988       Since: 2.5
989
990       guest-exec-status  (Command) Check status of process associated with
991       PID retrieved via guest-exec.  Reap the process and associated metadata
992       if it has exited.
993
994       Arguments:
995
996       "pid: int"
997           pid returned from guest-exec
998
999       Returns: GuestExecStatus on success.
1000
1001       Since: 2.5
1002
1003       GuestExec (Object)
1004
1005       Members:
1006
1007       "pid: int"
1008           pid of child process in guest OS
1009
1010       Since: 2.5
1011
1012       guest-exec  (Command) Execute a command in the guest
1013
1014       Arguments:
1015
1016       "path: string"
1017           path or executable name to execute
1018
1019       "arg: array of string" (optional)
1020           argument list to pass to executable
1021
1022       "env: array of string" (optional)
1023           environment variables to pass to executable
1024
1025       "input-data: string" (optional)
1026           data to be passed to process stdin (base64 encoded)
1027
1028       "capture-output: boolean" (optional)
1029           bool flag to enable capture of stdout/stderr of running process.
1030           defaults to false.
1031
1032       Returns: PID on success.
1033
1034       Since: 2.5
1035
1036       GuestHostName (Object)
1037
1038       Members:
1039
1040       "host-name: string"
1041           Fully qualified domain name of the guest OS
1042
1043       Since: 2.10
1044
1045       guest-get-host-name  (Command) Return a name for the machine.
1046
1047       The returned name is not necessarily a fully-qualified domain name, or
1048       even present in DNS or some other name service at all. It need not even
1049       be unique on your local network or site, but usually it is.
1050
1051       Returns: the host name of the machine on success
1052
1053       Since: 2.10
1054
1055       GuestUser (Object)
1056
1057       Members:
1058
1059       "user: string"
1060           Username
1061
1062       "domain: string" (optional)
1063           Logon domain (windows only)
1064
1065       "login-time: number"
1066           Time of login of this user on the computer. If multiple instances
1067           of the user are logged in, the earliest login time is reported. The
1068           value is in fractional seconds since epoch time.
1069
1070       Since: 2.10
1071
1072       guest-get-users  (Command) Retrieves a list of currently active users
1073       on the VM.
1074
1075       Returns: A unique list of users.
1076
1077       Since: 2.10
1078
1079       GuestTimezone (Object)
1080
1081       Members:
1082
1083       "zone: string" (optional)
1084           Timezone name. These values may differ depending on guest/OS and
1085           should only be used for informational purposes.
1086
1087       "offset: int"
1088           Offset to UTC in seconds, negative numbers for time zones west of
1089           GMT, positive numbers for east
1090
1091       Since: 2.10
1092
1093       guest-get-timezone  (Command) Retrieves the timezone information from
1094       the guest.
1095
1096       Returns: A GuestTimezone dictionary.
1097
1098       Since: 2.10
1099
1100       GuestOSInfo (Object)
1101
1102       Members:
1103
1104       "kernel-release: string" (optional)
1105           ·   POSIX: release field returned by uname(2)
1106
1107           ·   Windows: build number of the OS
1108
1109       "kernel-version: string" (optional)
1110           ·   POSIX: version field returned by uname(2)
1111
1112           ·   Windows: version number of the OS
1113
1114       "machine: string" (optional)
1115           ·   POSIX: machine field returned by uname(2)
1116
1117           ·   Windows: one of x86, x86_64, arm, ia64
1118
1119       "id: string" (optional)
1120           ·   POSIX: as defined by os-release(5)
1121
1122           ·   Windows: contains string "mswindows"
1123
1124       "name: string" (optional)
1125           ·   POSIX: as defined by os-release(5)
1126
1127           ·   Windows: contains string "Microsoft Windows"
1128
1129       "pretty-name: string" (optional)
1130           ·   POSIX: as defined by os-release(5)
1131
1132           ·   Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1133
1134       "version: string" (optional)
1135           ·   POSIX: as defined by os-release(5)
1136
1137           ·   Windows: long version string, e.g. "Microsoft Windows Server
1138               2008"
1139
1140       "version-id: string" (optional)
1141           ·   POSIX: as defined by os-release(5)
1142
1143           ·   Windows: short version identifier, e.g. "7" or "20012r2"
1144
1145       "variant: string" (optional)
1146           ·   POSIX: as defined by os-release(5)
1147
1148           ·   Windows: contains string "server" or "client"
1149
1150       "variant-id: string" (optional)
1151           ·   POSIX: as defined by os-release(5)
1152
1153           ·   Windows: contains string "server" or "client"
1154
1155       Notes: On POSIX systems the fields "id", "name", "pretty-name",
1156       "version", "version-id", "variant" and "variant-id" follow the
1157       definition specified in os-release(5).  Refer to the manual page for
1158       exact description of the fields. Their values are taken from the os-
1159       release file. If the file is not present in the system, or the values
1160       are not present in the file, the fields are not included.
1161
1162       On Windows the values are filled from information gathered from the
1163       system.
1164
1165       Since: 2.10
1166
1167       guest-get-osinfo  (Command) Retrieve guest operating system information
1168
1169       Returns: "GuestOSInfo"
1170
1171       Since: 2.10
1172
1173
1174
1175                                  2019-05-14                  QEMU-GA-REF.7(7)