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