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