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