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

NAME

6       qemu-ga-ref - QEMU Guest Agent Protocol Reference
7
8   Contents
9QEMU Guest Agent Protocol Reference
10
11General note concerning the use of guest agent interfaces
12
13"unsupported"  is a higher-level error than the errors that indi‐
14             vidual commands might document. The caller should always be  pre‐
15             pared  to  receive  QERR_UNSUPPORTED,  even  if the given command
16             doesn't specify it, or doesn't document any failure mode at all.
17
18QEMU guest agent protocol commands and structs
19
20guest-sync-delimited (Command)
21
22guest-sync (Command)
23
24guest-ping (Command)
25
26guest-get-time (Command)
27
28guest-set-time (Command)
29
30GuestAgentCommandInfo (Object)
31
32GuestAgentInfo (Object)
33
34guest-info (Command)
35
36guest-shutdown (Command)
37
38guest-file-open (Command)
39
40guest-file-close (Command)
41
42GuestFileRead (Object)
43
44guest-file-read (Command)
45
46GuestFileWrite (Object)
47
48guest-file-write (Command)
49
50GuestFileSeek (Object)
51
52QGASeek (Enum)
53
54GuestFileWhence (Alternate)
55
56guest-file-seek (Command)
57
58guest-file-flush (Command)
59
60GuestFsfreezeStatus (Enum)
61
62guest-fsfreeze-status (Command)
63
64guest-fsfreeze-freeze (Command)
65
66guest-fsfreeze-freeze-list (Command)
67
68guest-fsfreeze-thaw (Command)
69
70GuestFilesystemTrimResult (Object)
71
72GuestFilesystemTrimResponse (Object)
73
74guest-fstrim (Command)
75
76guest-suspend-disk (Command)
77
78guest-suspend-ram (Command)
79
80guest-suspend-hybrid (Command)
81
82GuestIpAddressType (Enum)
83
84GuestIpAddress (Object)
85
86GuestNetworkInterfaceStat (Object)
87
88GuestNetworkInterface (Object)
89
90guest-network-get-interfaces (Command)
91
92GuestLogicalProcessor (Object)
93
94guest-get-vcpus (Command)
95
96guest-set-vcpus (Command)
97
98GuestDiskBusType (Enum)
99
100GuestPCIAddress (Object)
101
102GuestCCWAddress (Object)
103
104GuestDiskAddress (Object)
105
106GuestDiskInfo (Object)
107
108guest-get-disks (Command)
109
110GuestFilesystemInfo (Object)
111
112guest-get-fsinfo (Command)
113
114guest-set-user-password (Command)
115
116GuestMemoryBlock (Object)
117
118guest-get-memory-blocks (Command)
119
120GuestMemoryBlockResponseType (Enum)
121
122GuestMemoryBlockResponse (Object)
123
124guest-set-memory-blocks (Command)
125
126GuestMemoryBlockInfo (Object)
127
128guest-get-memory-block-info (Command)
129
130GuestExecStatus (Object)
131
132guest-exec-status (Command)
133
134GuestExec (Object)
135
136guest-exec (Command)
137
138GuestHostName (Object)
139
140guest-get-host-name (Command)
141
142GuestUser (Object)
143
144guest-get-users (Command)
145
146GuestTimezone (Object)
147
148guest-get-timezone (Command)
149
150GuestOSInfo (Object)
151
152guest-get-osinfo (Command)
153
154GuestDeviceType (Enum)
155
156GuestDeviceIdPCI (Object)
157
158GuestDeviceId (Object)
159
160GuestDeviceInfo (Object)
161
162guest-get-devices (Command)
163
164GuestAuthorizedKeys (Object)
165
166guest-ssh-get-authorized-keys (Command)
167
168guest-ssh-add-authorized-keys (Command)
169
170guest-ssh-remove-authorized-keys (Command)
171

GENERAL NOTE CONCERNING THE USE OF GUEST AGENT INTERFACES

173       "unsupported" is a higher-level error than the errors  that  individual
174       commands  might  document.  The caller should always be prepared to re‐
175       ceive QERR_UNSUPPORTED, even if the given command doesn't  specify  it,
176       or doesn't document any failure mode at all.
177

QEMU GUEST AGENT PROTOCOL COMMANDS AND STRUCTS

179   guest-sync-delimited (Command)
180       Echo  back  a  unique  integer value, and prepend to response a leading
181       sentinel byte (0xFF) the client can check scan for.
182
183       This is used by clients talking to the guest agent over the wire to en‐
184       sure the stream is in sync and doesn't contain stale data from previous
185       client. It must be  issued  upon  initial  connection,  and  after  any
186       client-side  timeouts  (including  timeouts  on receiving a response to
187       this command).
188
189       After issuing this request, all guest agent responses should be ignored
190       until  the  response  containing  the  unique  integer value the client
191       passed in is returned. Receival of the 0xFF sentinel byte must be  han‐
192       dled  as  an  indication that the client's lexer/tokenizer/parser state
193       should be flushed/reset in preparation for reliably receiving the  sub‐
194       sequent  response.  As  an  optimization, clients may opt to ignore all
195       data until a sentinel value is receiving to avoid unnecessary  process‐
196       ing of stale data.
197
198       Similarly, clients should also precede this request with a 0xFF byte to
199       make sure the guest agent flushes any partially read JSON data  from  a
200       previous client connection.
201
202   Arguments
203       id: int
204              randomly generated 64-bit integer
205
206   Returns
207       The unique integer id passed in by the client
208
209   Since
210       1.1
211
212   guest-sync (Command)
213       Echo back a unique integer value
214
215       This is used by clients talking to the guest agent over the wire to en‐
216       sure the stream is in sync and doesn't contain stale data from previous
217       client.  All guest agent responses should be ignored until the provided
218       unique integer value is returned, and it is up to the client to  handle
219       stale  whole  or  partially-delivered JSON text in such a way that this
220       response can be obtained.
221
222       In cases where a partial stale response was previously received by  the
223       client,  this  cannot always be done reliably.  One particular scenario
224       being if qemu-ga responses are fed character-by-character into  a  JSON
225       parser. In these situations, using guest-sync-delimited may be optimal.
226
227       For  clients that fetch responses line by line and convert them to JSON
228       objects, guest-sync should be sufficient, but note that in cases  where
229       the  channel  is dirty some attempts at parsing the response may result
230       in a parser error.
231
232       Such clients should also precede this command with a 0xFF byte to  make
233       sure the guest agent flushes any partially read JSON data from a previ‐
234       ous session.
235
236   Arguments
237       id: int
238              randomly generated 64-bit integer
239
240   Returns
241       The unique integer id passed in by the client
242
243   Since
244       0.15.0
245
246   guest-ping (Command)
247       Ping the guest agent, a non-error return implies success
248
249   Since
250       0.15.0
251
252   guest-get-time (Command)
253       Get the information about guest's System Time relative to the Epoch  of
254       1970-01-01 in UTC.
255
256   Returns
257       Time in nanoseconds.
258
259   Since
260       1.5
261
262   guest-set-time (Command)
263       Set guest time.
264
265       When  a  guest  is  paused  or migrated to a file then loaded from that
266       file, the guest OS has no idea that there was a big gap  in  the  time.
267       Depending  on how long the gap was, NTP might not be able to resynchro‐
268       nize the guest.
269
270       This command tries to set guest's System Time to the given value,  then
271       sets  the  Hardware  Clock  (RTC) to the current System Time. This will
272       make it easier for a guest to resynchronize without waiting for NTP. If
273       no  time  is specified, then the time to set is read from RTC. However,
274       this may not be supported on all platforms (i.e. Windows).   If  that's
275       the case users are advised to always pass a value.
276
277   Arguments
278       time: int (optional)
279              time of nanoseconds, relative to the Epoch of 1970-01-01 in UTC.
280
281   Returns
282       Nothing on success.
283
284   Since
285       1.5
286
287   GuestAgentCommandInfo (Object)
288       Information about guest agent commands.
289
290   Members
291       name: string
292              name of the command
293
294       enabled: boolean
295              whether command is currently enabled by guest admin
296
297       success-response: boolean
298              whether command returns a response on success (since 1.7)
299
300   Since
301       1.1.0
302
303   GuestAgentInfo (Object)
304       Information about guest agent.
305
306   Members
307       version: string
308              guest agent version
309
310       supported_commands: array of GuestAgentCommandInfo
311              Information about guest agent commands
312
313   Since
314       0.15.0
315
316   guest-info (Command)
317       Get some information about the guest agent.
318
319   Returns
320       GuestAgentInfo
321
322   Since
323       0.15.0
324
325   guest-shutdown (Command)
326       Initiate  guest-activated shutdown. Note: this is an asynchronous shut‐
327       down request, with no guarantee of successful shutdown.
328
329   Arguments
330       mode: string (optional)
331              "halt", "powerdown" (default), or "reboot"
332       This command does NOT return a response on success.  Success  condition
333       is indicated by the VM exiting with a zero exit status or, when running
334       with --no-shutdown, by issuing the query-status QMP command to  confirm
335       the VM status is "shutdown".
336
337   Since
338       0.15.0
339
340   guest-file-open (Command)
341       Open a file in the guest and retrieve a file handle for it
342
343   Arguments
344       path: string
345              Full path to the file in the guest to open.
346
347       mode: string (optional)
348              open mode, as per fopen(), "r" is the default.
349
350   Returns
351       Guest file handle on success.
352
353   Since
354       0.15.0
355
356   guest-file-close (Command)
357       Close an open file in the guest
358
359   Arguments
360       handle: int
361              filehandle returned by guest-file-open
362
363   Returns
364       Nothing on success.
365
366   Since
367       0.15.0
368
369   GuestFileRead (Object)
370       Result of guest agent file-read operation
371
372   Members
373       count: int
374              number  of  bytes read (note: count is before base64-encoding is
375              applied)
376
377       buf-b64: string
378              base64-encoded bytes read
379
380       eof: boolean
381              whether EOF was encountered during read operation.
382
383   Since
384       0.15.0
385
386   guest-file-read (Command)
387       Read from an open file in the guest. Data will be  base64-encoded.   As
388       this  command  is  just for limited, ad-hoc debugging, such as log file
389       access, the number of bytes to read is limited to 48 MB.
390
391   Arguments
392       handle: int
393              filehandle returned by guest-file-open
394
395       count: int (optional)
396              maximum number of bytes to read  (default  is  4KB,  maximum  is
397              48MB)
398
399   Returns
400       GuestFileRead on success.
401
402   Since
403       0.15.0
404
405   GuestFileWrite (Object)
406       Result of guest agent file-write operation
407
408   Members
409       count: int
410              number  of  bytes  written (note: count is actual bytes written,
411              after base64-decoding of provided buffer)
412
413       eof: boolean
414              whether EOF was encountered during write operation.
415
416   Since
417       0.15.0
418
419   guest-file-write (Command)
420       Write to an open file in the guest.
421
422   Arguments
423       handle: int
424              filehandle returned by guest-file-open
425
426       buf-b64: string
427              base64-encoded string representing data to be written
428
429       count: int (optional)
430              bytes to write (actual bytes, after base64-decode),  default  is
431              all content in buf-b64 buffer after base64 decoding
432
433   Returns
434       GuestFileWrite on success.
435
436   Since
437       0.15.0
438
439   GuestFileSeek (Object)
440       Result of guest agent file-seek operation
441
442   Members
443       position: int
444              current file position
445
446       eof: boolean
447              whether EOF was encountered during file seek
448
449   Since
450       0.15.0
451
452   QGASeek (Enum)
453       Symbolic names for use in guest-file-seek
454
455   Values
456       set    Set to the specified offset (same effect as 'whence':0)
457
458       cur    Add offset to the current location (same effect as 'whence':1)
459
460       end    Add offset to the end of the file (same effect as 'whence':2)
461
462   Since
463       2.6
464
465   GuestFileWhence (Alternate)
466       Controls the meaning of offset to guest-file-seek.
467
468   Members
469       value: int
470              Integral  value (0 for set, 1 for cur, 2 for end), available for
471              historical reasons, and might differ from the host's or  guest's
472              SEEK_* values (since: 0.15)
473
474       name: QGASeek
475              Symbolic name, and preferred interface
476
477   Since
478       2.6
479
480   guest-file-seek (Command)
481       Seek to a position in the file, as with fseek(), and return the current
482       file position afterward.  Also  encapsulates  ftell()'s  functionality,
483       with offset=0 and whence=1.
484
485   Arguments
486       handle: int
487              filehandle returned by guest-file-open
488
489       offset: int
490              bytes to skip over in the file stream
491
492       whence: GuestFileWhence
493              Symbolic or numeric code for interpreting offset
494
495   Returns
496       GuestFileSeek on success.
497
498   Since
499       0.15.0
500
501   guest-file-flush (Command)
502       Write file changes bufferred in userspace to disk/kernel buffers
503
504   Arguments
505       handle: int
506              filehandle returned by guest-file-open
507
508   Returns
509       Nothing on success.
510
511   Since
512       0.15.0
513
514   GuestFsfreezeStatus (Enum)
515       An enumeration of filesystem freeze states
516
517   Values
518       thawed filesystems thawed/unfrozen
519
520       frozen all non-network guest filesystems frozen
521
522   Since
523       0.15.0
524
525   guest-fsfreeze-status (Command)
526       Get guest fsfreeze state. error state indicates
527
528   Returns
529       GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
530
531   Note
532       This  may fail to properly report the current state as a result of some
533       other guest processes having issued an fs freeze/thaw.
534
535   Since
536       0.15.0
537
538   guest-fsfreeze-freeze (Command)
539       Sync and freeze all freezable, local guest filesystems. If this command
540       succeeded, you may call guest-fsfreeze-thaw later to unfreeze.
541
542   Note
543       On  Windows,  the  command  is  implemented  with  the help of a Volume
544       Shadow-copy Service DLL helper. The frozen state is limited for  up  to
545       10 seconds by VSS.
546
547   Returns
548       Number of file systems currently frozen. On error, all filesystems will
549       be thawed. If no filesystems are frozen as a result of this call,  then
550       guest-fsfreeze-status   will  remain  "thawed"  and  calling  guest-fs‐
551       freeze-thaw is not necessary.
552
553   Since
554       0.15.0
555
556   guest-fsfreeze-freeze-list (Command)
557       Sync and  freeze  specified  guest  filesystems.   See  also  guest-fs‐
558       freeze-freeze.
559
560   Arguments
561       mountpoints: array of string (optional)
562              an  array  of mountpoints of filesystems to be frozen.  If omit‐
563              ted, every mounted filesystem is frozen.  Invalid  mount  points
564              are ignored.
565
566   Returns
567       Number of file systems currently frozen. On error, all filesystems will
568       be thawed.
569
570   Since
571       2.2
572
573   guest-fsfreeze-thaw (Command)
574       Unfreeze all frozen guest filesystems
575
576   Returns
577       Number of file systems thawed by this call
578
579   Note
580       if  return  value  does  not  match  the  previous  call  to  guest-fs‐
581       freeze-freeze,  this  likely  means some freezable filesystems were un‐
582       frozen before this call, and that the filesystem state may have changed
583       before issuing this command.
584
585   Since
586       0.15.0
587
588   GuestFilesystemTrimResult (Object)
589   Members
590       path: string
591              path that was trimmed
592
593       error: string (optional)
594              an error message when trim failed
595
596       trimmed: int (optional)
597              bytes trimmed for this path
598
599       minimum: int (optional)
600              reported effective minimum for this path
601
602   Since
603       2.4
604
605   GuestFilesystemTrimResponse (Object)
606   Members
607       paths: array of GuestFilesystemTrimResult
608              list of GuestFilesystemTrimResult per path that was trimmed
609
610   Since
611       2.4
612
613   guest-fstrim (Command)
614       Discard (or "trim") blocks which are not in use by the filesystem.
615
616   Arguments
617       minimum: int (optional)
618              Minimum  contiguous free range to discard, in bytes. Free ranges
619              smaller than this may be ignored (this is a hint and  the  guest
620              may not respect it).  By increasing this value, the fstrim oper‐
621              ation will complete more  quickly  for  filesystems  with  badly
622              fragmented  free  space,  although  not  all blocks will be dis‐
623              carded.  The default value is zero, meaning "discard every  free
624              block".
625
626   Returns
627       A  GuestFilesystemTrimResponse which contains the status of all trimmed
628       paths. (since 2.4)
629
630   Since
631       1.2
632
633   guest-suspend-disk (Command)
634       Suspend guest to disk.
635
636       This command attempts to suspend the guest using three  strategies,  in
637       this order:
638
639       • systemd hibernate
640
641       • pm-utils (via pm-hibernate)
642
643       • manual write into sysfs
644
645       This  command  does  NOT  return a response on success. There is a high
646       chance the command succeeded if the VM exits with a  zero  exit  status
647       or,  when  running  with --no-shutdown, by issuing the query-status QMP
648       command to to confirm the VM status  is  "shutdown".  However,  the  VM
649       could also exit (or set its status to "shutdown") due to other reasons.
650
651       The following errors may be returned:
652
653       • If suspend to disk is not supported, Unsupported
654
655   Notes
656       It's  strongly recommended to issue the guest-sync command before send‐
657       ing commands when the guest resumes
658
659   Since
660       1.1
661
662   guest-suspend-ram (Command)
663       Suspend guest to ram.
664
665       This command attempts to suspend the guest using three  strategies,  in
666       this order:
667
668       • systemd suspend
669
670       • pm-utils (via pm-suspend)
671
672       • manual write into sysfs
673
674       IMPORTANT:  guest-suspend-ram  requires working wakeup support in QEMU.
675       You should check QMP command query-current-machine returns  wakeup-sus‐
676       pend-support: true before issuing this command. Failure in doing so can
677       result in a suspended guest that QEMU will not be able to awaken, forc‐
678       ing the user to power cycle the guest to bring it back.
679
680       This  command  does NOT return a response on success. There are two op‐
681       tions to check for success:
682
683       1. Wait for the SUSPEND QMP event from QEMU
684
685       2. Issue the query-status QMP command to confirm the VM status is "sus‐
686          pended"
687
688       The following errors may be returned:
689
690       • If suspend to ram is not supported, Unsupported
691
692   Notes
693       It's  strongly recommended to issue the guest-sync command before send‐
694       ing commands when the guest resumes
695
696   Since
697       1.1
698
699   guest-suspend-hybrid (Command)
700       Save guest state to disk and suspend to ram.
701
702       This command attempts to suspend the guest by executing, in this order:
703
704       • systemd hybrid-sleep
705
706       • pm-utils (via pm-suspend-hybrid)
707
708       IMPORTANT: guest-suspend-hybrid  requires  working  wakeup  support  in
709       QEMU.  You  should  check  QMP  command  query-current-machine  returns
710       wakeup-suspend-support: true before issuing this  command.  Failure  in
711       doing  so can result in a suspended guest that QEMU will not be able to
712       awaken, forcing the user to power cycle the guest to bring it back.
713
714       This command does NOT return a response on success. There are  two  op‐
715       tions to check for success:
716
717       1. Wait for the SUSPEND QMP event from QEMU
718
719       2. Issue the query-status QMP command to confirm the VM status is "sus‐
720          pended"
721
722       The following errors may be returned:
723
724       • If hybrid suspend is not supported, Unsupported
725
726   Notes
727       It's strongly recommended to issue the guest-sync command before  send‐
728       ing commands when the guest resumes
729
730   Since
731       1.1
732
733   GuestIpAddressType (Enum)
734       An enumeration of supported IP address types
735
736   Values
737       ipv4   IP version 4
738
739       ipv6   IP version 6
740
741   Since
742       1.1
743
744   GuestIpAddress (Object)
745   Members
746       ip-address: string
747              IP address
748
749       ip-address-type: GuestIpAddressType
750              Type of ip-address (e.g. ipv4, ipv6)
751
752       prefix: int
753              Network prefix length of ip-address
754
755   Since
756       1.1
757
758   GuestNetworkInterfaceStat (Object)
759   Members
760       rx-bytes: int
761              total bytes received
762
763       rx-packets: int
764              total packets received
765
766       rx-errs: int
767              bad packets received
768
769       rx-dropped: int
770              receiver dropped packets
771
772       tx-bytes: int
773              total bytes transmitted
774
775       tx-packets: int
776              total packets transmitted
777
778       tx-errs: int
779              packet transmit problems
780
781       tx-dropped: int
782              dropped packets transmitted
783
784   Since
785       2.11
786
787   GuestNetworkInterface (Object)
788   Members
789       name: string
790              The name of interface for which info are being delivered
791
792       hardware-address: string (optional)
793              Hardware address of name
794
795       ip-addresses: array of GuestIpAddress (optional)
796              List of addresses assigned to name
797
798       statistics: GuestNetworkInterfaceStat (optional)
799              various statistic counters related to name (since 2.11)
800
801   Since
802       1.1
803
804   guest-network-get-interfaces (Command)
805       Get list of guest IP addresses, MAC addresses and netmasks.
806
807   Returns
808       List of GuestNetworkInfo on success.
809
810   Since
811       1.1
812
813   GuestLogicalProcessor (Object)
814   Members
815       logical-id: int
816              Arbitrary guest-specific unique identifier of the VCPU.
817
818       online: boolean
819              Whether the VCPU is enabled.
820
821       can-offline: boolean (optional)
822              Whether  offlining  the  VCPU is possible. This member is always
823              filled in by the guest agent when the structure is returned, and
824              always ignored on input (hence it can be omitted then).
825
826   Since
827       1.5
828
829   guest-get-vcpus (Command)
830       Retrieve the list of the guest's logical processors.
831
832       This is a read-only operation.
833
834   Returns
835       The  list  of  all VCPUs the guest knows about. Each VCPU is put on the
836       list exactly once, but their order is unspecified.
837
838   Since
839       1.5
840
841   guest-set-vcpus (Command)
842       Attempt to reconfigure (currently: enable/disable)  logical  processors
843       inside the guest.
844
845       The  input  list is processed node by node in order. In each node logi‐
846       cal-id is used to look up the guest VCPU, for  which  online  specifies
847       the  requested state. The set of distinct logical-id's is only required
848       to be a subset of the guest-supported identifiers. There's no  restric‐
849       tion  on list length or on repeating the same logical-id (with possibly
850       different online field).  Preferably the input list should  describe  a
851       modified subset of guest-get-vcpus' return value.
852
853   Arguments
854       vcpus: array of GuestLogicalProcessor
855              Not documented
856
857   Returns
858       The length of the initial sublist that has been successfully processed.
859       The guest agent maximizes this value. Possible cases:
860
861       • 0: if the vcpus list was empty on input. Guest  state  has  not  been
862         changed. Otherwise,
863
864       • Error:  processing  the first node of vcpus failed for the reason re‐
865         turned. Guest state has not been changed.  Otherwise,
866
867       • < length(vcpus): more than zero initial nodes  have  been  processed,
868         but  not  the entire vcpus list. Guest state has changed accordingly.
869         To retrieve the error (assuming it persists), repeat  the  call  with
870         the successfully processed initial sublist removed.  Otherwise,
871
872       • length(vcpus): call successful.
873
874   Since
875       1.5
876
877   GuestDiskBusType (Enum)
878       An enumeration of bus type of disks
879
880   Values
881       ide    IDE disks
882
883       fdc    floppy disks
884
885       scsi   SCSI disks
886
887       virtio virtio disks
888
889       xen    Xen disks
890
891       usb    USB disks
892
893       uml    UML disks
894
895       sata   SATA disks
896
897       sd     SD cards
898
899       unknown
900              Unknown bus type
901
902       ieee1394
903              Win IEEE 1394 bus type
904
905       ssa    Win SSA bus type
906
907       fibre  Win fiber channel bus type
908
909       raid   Win RAID bus type
910
911       iscsi  Win iScsi bus type
912
913       sas    Win serial-attaches SCSI bus type
914
915       mmc    Win multimedia card (MMC) bus type
916
917       virtual
918              Win virtual bus type
919
920       file-backed-virtual
921              Win file-backed bus type
922
923   Since
924       2.2; 'Unknown' and all entries below since 2.4
925
926   GuestPCIAddress (Object)
927   Members
928       domain: int
929              domain id
930
931       bus: int
932              bus id
933
934       slot: int
935              slot id
936
937       function: int
938              function id
939
940   Since
941       2.2
942
943   GuestCCWAddress (Object)
944   Members
945       cssid: int
946              channel subsystem image id
947
948       ssid: int
949              subchannel set id
950
951       subchno: int
952              subchannel number
953
954       devno: int
955              device number
956
957   Since
958       6.0
959
960   GuestDiskAddress (Object)
961   Members
962       pci-controller: GuestPCIAddress
963              controller's PCI address (fields are set to -1 if invalid)
964
965       bus-type: GuestDiskBusType
966              bus type
967
968       bus: int
969              bus id
970
971       target: int
972              target id
973
974       unit: int
975              unit id
976
977       serial: string (optional)
978              serial number (since: 3.1)
979
980       dev: string (optional)
981              device node (POSIX) or device UNC (Windows) (since: 3.1)
982
983       ccw-address: GuestCCWAddress (optional)
984              CCW address on s390x (since: 6.0)
985
986   Since
987       2.2
988
989   GuestDiskInfo (Object)
990   Members
991       name: string
992              device node (Linux) or device UNC (Windows)
993
994       partition: boolean
995              whether this is a partition or disk
996
997       dependencies: array of string (optional)
998              list  of  device dependencies; e.g. for LVs of the LVM this will
999              hold the list of PVs, for LUKS encrypted volume this  will  con‐
1000              tain the disk where the volume is placed.     (Linux)
1001
1002       address: GuestDiskAddress (optional)
1003              disk address information (only for non-virtual devices)
1004
1005       alias: string (optional)
1006              optional alias assigned to the disk, on Linux this is a name as‐
1007              signed by device mapper
1008       Since 5.2
1009
1010   guest-get-disks (Command)
1011   Returns
1012       The list of disks in the guest. For Windows these are only the physical
1013       disks.  On  Linux these are all root block devices of non-zero size in‐
1014       cluding e.g. removable devices, loop devices, NBD, etc.
1015
1016   Since
1017       5.2
1018
1019   GuestFilesystemInfo (Object)
1020   Members
1021       name: string
1022              disk name
1023
1024       mountpoint: string
1025              mount point path
1026
1027       type: string
1028              file system type string
1029
1030       used-bytes: int (optional)
1031              file system used bytes (since 3.0)
1032
1033       total-bytes: int (optional)
1034              non-root file system total bytes (since 3.0)
1035
1036       disk: array of GuestDiskAddress
1037              an array of disk hardware information that the volume  lies  on,
1038              which may be empty if the disk type is not supported
1039
1040   Since
1041       2.2
1042
1043   guest-get-fsinfo (Command)
1044   Returns
1045       The list of filesystems information mounted in the guest.  The returned
1046       mountpoints may be specified  to  guest-fsfreeze-freeze-list.   Network
1047       filesystems (such as CIFS and NFS) are not listed.
1048
1049   Since
1050       2.2
1051
1052   guest-set-user-password (Command)
1053   Arguments
1054       username: string
1055              the user account whose password to change
1056
1057       password: string
1058              the new password entry string, base64 encoded
1059
1060       crypted: boolean
1061              true if password is already crypt()d, false if raw
1062       If  the  crypted flag is true, it is the caller's responsibility to en‐
1063       sure the correct crypt() encryption scheme is used. This  command  does
1064       not  attempt  to interpret or report on the encryption scheme. Refer to
1065       the documentation of the guest operating system in question  to  deter‐
1066       mine what is supported.
1067
1068       Not  all  guest operating systems will support use of the crypted flag,
1069       as they may require the clear-text password
1070
1071       The password parameter must always be base64 encoded  before  transmis‐
1072       sion,  even if already crypt()d, to ensure it is 8-bit safe when passed
1073       as JSON.
1074
1075   Returns
1076       Nothing on success.
1077
1078   Since
1079       2.3
1080
1081   GuestMemoryBlock (Object)
1082   Members
1083       phys-index: int
1084              Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
1085
1086       online: boolean
1087              Whether the MEMORY BLOCK is enabled in guest.
1088
1089       can-offline: boolean (optional)
1090              Whether offlining the MEMORY BLOCK is possible.  This member  is
1091              always  filled  in  by the guest agent when the structure is re‐
1092              turned, and always ignored on input (hence  it  can  be  omitted
1093              then).
1094
1095   Since
1096       2.3
1097
1098   guest-get-memory-blocks (Command)
1099       Retrieve the list of the guest's memory blocks.
1100
1101       This is a read-only operation.
1102
1103   Returns
1104       The list of all memory blocks the guest knows about.  Each memory block
1105       is put on the list exactly once, but their order is unspecified.
1106
1107   Since
1108       2.3
1109
1110   GuestMemoryBlockResponseType (Enum)
1111       An enumeration of memory block operation result.
1112
1113   Values
1114       success
1115              the operation of online/offline memory block is successful.
1116
1117       not-found
1118              can't find the corresponding memoryXXX directory in sysfs.
1119
1120       operation-not-supported
1121              for some old kernels, it does not support online or offline mem‐
1122              ory block.
1123
1124       operation-failed
1125              the  operation  of online/offline memory block fails, because of
1126              some errors happen.
1127
1128   Since
1129       2.3
1130
1131   GuestMemoryBlockResponse (Object)
1132   Members
1133       phys-index: int
1134              same with the 'phys-index' member of GuestMemoryBlock.
1135
1136       response: GuestMemoryBlockResponseType
1137              the result of memory block operation.
1138
1139       error-code: int (optional)
1140              the error number.  When memory block operation fails, we  assign
1141              the  value  of  'errno'  to  this member, it indicates what goes
1142              wrong.  When the operation succeeds, it will be omitted.
1143
1144   Since
1145       2.3
1146
1147   guest-set-memory-blocks (Command)
1148       Attempt to reconfigure  (currently:  enable/disable)  state  of  memory
1149       blocks inside the guest.
1150
1151       The  input  list  is  processed  node  by  node  in order. In each node
1152       phys-index is used to look up the guest MEMORY BLOCK, for which  online
1153       specifies the requested state. The set of distinct phys-index's is only
1154       required to be a subset of the guest-supported identifiers. There's  no
1155       restriction  on  list  length or on repeating the same phys-index (with
1156       possibly different online field).  Preferably the input list should de‐
1157       scribe a modified subset of guest-get-memory-blocks' return value.
1158
1159   Arguments
1160       mem-blks: array of GuestMemoryBlock
1161              Not documented
1162
1163   Returns
1164       The  operation results, it is a list of GuestMemoryBlockResponse, which
1165       is corresponding to the input list.
1166
1167       Note: it will return NULL if the mem-blks list was empty on  input,  or
1168       there is an error, and in this case, guest state will not be changed.
1169
1170   Since
1171       2.3
1172
1173   GuestMemoryBlockInfo (Object)
1174   Members
1175       size: int
1176              the  size  (in  bytes) of the guest memory blocks, which are the
1177              minimal units of memory block  online/offline  operations  (also
1178              called Logical Memory Hotplug).
1179
1180   Since
1181       2.3
1182
1183   guest-get-memory-block-info (Command)
1184       Get information relating to guest memory blocks.
1185
1186   Returns
1187       GuestMemoryBlockInfo
1188
1189   Since
1190       2.3
1191
1192   GuestExecStatus (Object)
1193   Members
1194       exited: boolean
1195              true if process has already terminated.
1196
1197       exitcode: int (optional)
1198              process exit code if it was normally terminated.
1199
1200       signal: int (optional)
1201              signal  number  (linux) or unhandled exception code (windows) if
1202              the process was abnormally terminated.
1203
1204       out-data: string (optional)
1205              base64-encoded stdout of the process
1206
1207       err-data: string (optional)
1208              base64-encoded stderr of the process Note: out-data and err-data
1209              are   present   only   if  'capture-output'  was  specified  for
1210              'guest-exec'
1211
1212       out-truncated: boolean (optional)
1213              true if stdout was not fully captured due to size limitation.
1214
1215       err-truncated: boolean (optional)
1216              true if stderr was not fully captured due to size limitation.
1217
1218   Since
1219       2.5
1220
1221   guest-exec-status (Command)
1222       Check status of process associated with PID retrieved  via  guest-exec.
1223       Reap the process and associated metadata if it has exited.
1224
1225   Arguments
1226       pid: int
1227              pid returned from guest-exec
1228
1229   Returns
1230       GuestExecStatus on success.
1231
1232   Since
1233       2.5
1234
1235   GuestExec (Object)
1236   Members
1237       pid: int
1238              pid of child process in guest OS
1239
1240   Since
1241       2.5
1242
1243   guest-exec (Command)
1244       Execute a command in the guest
1245
1246   Arguments
1247       path: string
1248              path or executable name to execute
1249
1250       arg: array of string (optional)
1251              argument list to pass to executable
1252
1253       env: array of string (optional)
1254              environment variables to pass to executable
1255
1256       input-data: string (optional)
1257              data to be passed to process stdin (base64 encoded)
1258
1259       capture-output: boolean (optional)
1260              bool flag to enable capture of stdout/stderr of running process.
1261              defaults to false.
1262
1263   Returns
1264       PID on success.
1265
1266   Since
1267       2.5
1268
1269   GuestHostName (Object)
1270   Members
1271       host-name: string
1272              Fully qualified domain name of the guest OS
1273
1274   Since
1275       2.10
1276
1277   guest-get-host-name (Command)
1278       Return a name for the machine.
1279
1280       The returned name is not necessarily a fully-qualified domain name,  or
1281       even present in DNS or some other name service at all. It need not even
1282       be unique on your local network or site, but usually it is.
1283
1284   Returns
1285       the host name of the machine on success
1286
1287   Since
1288       2.10
1289
1290   GuestUser (Object)
1291   Members
1292       user: string
1293              Username
1294
1295       domain: string (optional)
1296              Logon domain (windows only)
1297
1298       login-time: number
1299              Time of login of this user on  the  computer.  If  multiple  in‐
1300              stances  of  the  user are logged in, the earliest login time is
1301              reported. The value is in fractional seconds since epoch time.
1302
1303   Since
1304       2.10
1305
1306   guest-get-users (Command)
1307       Retrieves a list of currently active users on the VM.
1308
1309   Returns
1310       A unique list of users.
1311
1312   Since
1313       2.10
1314
1315   GuestTimezone (Object)
1316   Members
1317       zone: string (optional)
1318              Timezone name. These values may differ depending on guest/OS and
1319              should only be used for informational purposes.
1320
1321       offset: int
1322              Offset  to  UTC in seconds, negative numbers for time zones west
1323              of GMT, positive numbers for east
1324
1325   Since
1326       2.10
1327
1328   guest-get-timezone (Command)
1329       Retrieves the timezone information from the guest.
1330
1331   Returns
1332       A GuestTimezone dictionary.
1333
1334   Since
1335       2.10
1336
1337   GuestOSInfo (Object)
1338   Members
1339       kernel-release: string (optional)
1340
1341              • POSIX: release field returned by uname(2)
1342
1343              • Windows: build number of the OS
1344
1345       kernel-version: string (optional)
1346
1347              • POSIX: version field returned by uname(2)
1348
1349              • Windows: version number of the OS
1350
1351       machine: string (optional)
1352
1353              • POSIX: machine field returned by uname(2)
1354
1355              • Windows: one of x86, x86_64, arm, ia64
1356
1357       id: string (optional)
1358
1359              • POSIX: as defined by os-release(5)
1360
1361              • Windows: contains string "mswindows"
1362
1363       name: string (optional)
1364
1365              • POSIX: as defined by os-release(5)
1366
1367              • Windows: contains string "Microsoft Windows"
1368
1369       pretty-name: string (optional)
1370
1371              • POSIX: as defined by os-release(5)
1372
1373              • Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1374
1375       version: string (optional)
1376
1377              • POSIX: as defined by os-release(5)
1378
1379              • Windows: long version string, e.g. "Microsoft  Windows  Server
1380                2008"
1381
1382       version-id: string (optional)
1383
1384              • POSIX: as defined by os-release(5)
1385
1386              • Windows: short version identifier, e.g. "7" or "20012r2"
1387
1388       variant: string (optional)
1389
1390              • POSIX: as defined by os-release(5)
1391
1392              • Windows: contains string "server" or "client"
1393
1394       variant-id: string (optional)
1395
1396              • POSIX: as defined by os-release(5)
1397
1398              • Windows: contains string "server" or "client"
1399
1400   Notes
1401       On POSIX systems the fields id, name, pretty-name, version, version-id,
1402       variant and  variant-id  follow  the  definition  specified  in  os-re‐
1403       lease(5).   Refer  to  the  manual  page  for  exact description of the
1404       fields. Their values are taken from the os-release file. If the file is
1405       not  present  in the system, or the values are not present in the file,
1406       the fields are not included.
1407
1408       On Windows the values are filled from  information  gathered  from  the
1409       system.
1410
1411   Since
1412       2.10
1413
1414   guest-get-osinfo (Command)
1415       Retrieve guest operating system information
1416
1417   Returns
1418       GuestOSInfo
1419
1420   Since
1421       2.10
1422
1423   GuestDeviceType (Enum)
1424   Values
1425       pci    Not documented
1426
1427   GuestDeviceIdPCI (Object)
1428   Members
1429       vendor-id: int
1430              vendor ID
1431
1432       device-id: int
1433              device ID
1434
1435   Since
1436       5.2
1437
1438   GuestDeviceId (Object)
1439       Id of the device - pci: PCI ID, since: 5.2
1440
1441   Members
1442       type: GuestDeviceType
1443              Not documented
1444
1445       The members of GuestDeviceIdPCI when type is "pci"
1446
1447   Since
1448       5.2
1449
1450   GuestDeviceInfo (Object)
1451   Members
1452       driver-name: string
1453              name of the associated driver
1454
1455       driver-date: int (optional)
1456              driver release date, in nanoseconds since the epoch
1457
1458       driver-version: string (optional)
1459              driver version
1460
1461       id: GuestDeviceId (optional)
1462              device ID
1463
1464   Since
1465       5.2
1466
1467   guest-get-devices (Command)
1468       Retrieve information about device drivers in Windows guest
1469
1470   Returns
1471       GuestDeviceInfo
1472
1473   Since
1474       5.2
1475
1476   GuestAuthorizedKeys (Object)
1477   Members
1478       keys: array of string
1479              public keys (in OpenSSH/sshd(8) authorized_keys format)
1480
1481   Since
1482       5.2
1483
1484   If
1485       CONFIG_POSIX
1486
1487   guest-ssh-get-authorized-keys (Command)
1488   Arguments
1489       username: string
1490              the user account to add the authorized keys
1491       Return  the  public keys from user .ssh/authorized_keys on Unix systems
1492       (not implemented for other systems).
1493
1494   Returns
1495       GuestAuthorizedKeys
1496
1497   Since
1498       5.2
1499
1500   If
1501       CONFIG_POSIX
1502
1503   guest-ssh-add-authorized-keys (Command)
1504   Arguments
1505       username: string
1506              the user account to add the authorized keys
1507
1508       keys: array of string
1509              the public keys to add (in OpenSSH/sshd(8) authorized_keys  for‐
1510              mat)
1511
1512       reset: boolean (optional)
1513              ignore the existing content, set it with the given keys only
1514       Append  public  keys  to user .ssh/authorized_keys on Unix systems (not
1515       implemented for other systems).
1516
1517   Returns
1518       Nothing on success.
1519
1520   Since
1521       5.2
1522
1523   If
1524       CONFIG_POSIX
1525
1526   guest-ssh-remove-authorized-keys (Command)
1527   Arguments
1528       username: string
1529              the user account to remove the authorized keys
1530
1531       keys: array of string
1532              the public keys to remove  (in  OpenSSH/sshd(8)  authorized_keys
1533              format)
1534       Remove  public  keys from the user .ssh/authorized_keys on Unix systems
1535       (not implemented for other systems). It's not an error if  the  key  is
1536       already missing.
1537
1538   Returns
1539       Nothing on success.
1540
1541   Since
1542       5.2
1543
1544   If
1545       CONFIG_POSIX
1546
1548       2023, The QEMU Project Developers
1549
1550
1551
1552
15537.0.0                            Jan 19, 2023                   QEMU-GA-REF(7)
Impressum