Annotation of qemu/qapi-schema-guest.json, revision 1.1.1.2

1.1       root        1: # *-*- Mode: Python -*-*
                      2: 
                      3: ##
1.1.1.2 ! root        4: #
        !             5: # Echo back a unique integer value, and prepend to response a
        !             6: # leading sentinel byte (0xFF) the client can check scan for.
        !             7: #
        !             8: # This is used by clients talking to the guest agent over the
        !             9: # wire to ensure the stream is in sync and doesn't contain stale
        !            10: # data from previous client. It must be issued upon initial
        !            11: # connection, and after any client-side timeouts (including
        !            12: # timeouts on receiving a response to this command).
        !            13: #
        !            14: # After issuing this request, all guest agent responses should be
        !            15: # ignored until the response containing the unique integer value
        !            16: # the client passed in is returned. Receival of the 0xFF sentinel
        !            17: # byte must be handled as an indication that the client's
        !            18: # lexer/tokenizer/parser state should be flushed/reset in
        !            19: # preparation for reliably receiving the subsequent response. As
        !            20: # an optimization, clients may opt to ignore all data until a
        !            21: # sentinel value is receiving to avoid unnecessary processing of
        !            22: # stale data.
        !            23: #
        !            24: # Similarly, clients should also precede this *request*
        !            25: # with a 0xFF byte to make sure the guest agent flushes any
        !            26: # partially read JSON data from a previous client connection.
        !            27: #
        !            28: # @id: randomly generated 64-bit integer
        !            29: #
        !            30: # Returns: The unique integer id passed in by the client
        !            31: #
        !            32: # Since: 1.1
        !            33: # ##
        !            34: { 'command': 'guest-sync-delimited'
        !            35:   'data':    { 'id': 'int' },
        !            36:   'returns': 'int' }
        !            37: 
        !            38: ##
1.1       root       39: # @guest-sync:
                     40: #
                     41: # Echo back a unique integer value
                     42: #
                     43: # This is used by clients talking to the guest agent over the
                     44: # wire to ensure the stream is in sync and doesn't contain stale
                     45: # data from previous client. All guest agent responses should be
                     46: # ignored until the provided unique integer value is returned,
                     47: # and it is up to the client to handle stale whole or
                     48: # partially-delivered JSON text in such a way that this response
                     49: # can be obtained.
                     50: #
1.1.1.2 ! root       51: # In cases where a partial stale response was previously
        !            52: # received by the client, this cannot always be done reliably.
        !            53: # One particular scenario being if qemu-ga responses are fed
        !            54: # character-by-character into a JSON parser. In these situations,
        !            55: # using guest-sync-delimited may be optimal.
        !            56: #
        !            57: # For clients that fetch responses line by line and convert them
        !            58: # to JSON objects, guest-sync should be sufficient, but note that
        !            59: # in cases where the channel is dirty some attempts at parsing the
        !            60: # response may result in a parser error.
        !            61: #
        !            62: # Such clients should also precede this command
        !            63: # with a 0xFF byte to make sure the guest agent flushes any
1.1       root       64: # partially read JSON data from a previous session.
                     65: #
                     66: # @id: randomly generated 64-bit integer
                     67: #
                     68: # Returns: The unique integer id passed in by the client
                     69: #
                     70: # Since: 0.15.0
                     71: ##
                     72: { 'command': 'guest-sync'
                     73:   'data':    { 'id': 'int' },
                     74:   'returns': 'int' }
                     75: 
                     76: ##
                     77: # @guest-ping:
                     78: #
                     79: # Ping the guest agent, a non-error return implies success
                     80: #
                     81: # Since: 0.15.0
                     82: ##
                     83: { 'command': 'guest-ping' }
                     84: 
                     85: ##
1.1.1.2 ! root       86: # @GuestAgentCommandInfo:
        !            87: #
        !            88: # Information about guest agent commands.
        !            89: #
        !            90: # @name: name of the command
        !            91: #
        !            92: # @enabled: whether command is currently enabled by guest admin
        !            93: #
        !            94: # Since 1.1.0
        !            95: ##
        !            96: { 'type': 'GuestAgentCommandInfo',
        !            97:   'data': { 'name': 'str', 'enabled': 'bool' } }
        !            98: 
        !            99: ##
        !           100: # @GuestAgentInfo
        !           101: #
        !           102: # Information about guest agent.
        !           103: #
        !           104: # @version: guest agent version
        !           105: #
        !           106: # @supported_commands: Information about guest agent commands
        !           107: #
        !           108: # Since 0.15.0
        !           109: ##
        !           110: { 'type': 'GuestAgentInfo',
        !           111:   'data': { 'version': 'str',
        !           112:             'supported_commands': ['GuestAgentCommandInfo'] } }
        !           113: ##
1.1       root      114: # @guest-info:
                    115: #
                    116: # Get some information about the guest agent.
                    117: #
1.1.1.2 ! root      118: # Returns: @GuestAgentInfo
        !           119: #
1.1       root      120: # Since: 0.15.0
                    121: ##
                    122: { 'command': 'guest-info',
                    123:   'returns': 'GuestAgentInfo' }
                    124: 
                    125: ##
                    126: # @guest-shutdown:
                    127: #
                    128: # Initiate guest-activated shutdown. Note: this is an asynchronous
1.1.1.2 ! root      129: # shutdown request, with no guarantee of successful shutdown.
1.1       root      130: #
                    131: # @mode: #optional "halt", "powerdown" (default), or "reboot"
                    132: #
1.1.1.2 ! root      133: # This command does NOT return a response on success. Success condition
        !           134: # is indicated by the VM exiting with a zero exit status or, when
        !           135: # running with --no-shutdown, by issuing the query-status QMP command
        !           136: # to confirm the VM status is "shutdown".
1.1       root      137: #
                    138: # Since: 0.15.0
                    139: ##
1.1.1.2 ! root      140: { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
        !           141:   'success-response': 'no' }
1.1       root      142: 
                    143: ##
                    144: # @guest-file-open:
                    145: #
                    146: # Open a file in the guest and retrieve a file handle for it
                    147: #
                    148: # @filepath: Full path to the file in the guest to open.
                    149: #
                    150: # @mode: #optional open mode, as per fopen(), "r" is the default.
                    151: #
                    152: # Returns: Guest file handle on success.
                    153: #
                    154: # Since: 0.15.0
                    155: ##
                    156: { 'command': 'guest-file-open',
                    157:   'data':    { 'path': 'str', '*mode': 'str' },
                    158:   'returns': 'int' }
                    159: 
                    160: ##
                    161: # @guest-file-close:
                    162: #
                    163: # Close an open file in the guest
                    164: #
                    165: # @handle: filehandle returned by guest-file-open
                    166: #
                    167: # Returns: Nothing on success.
                    168: #
                    169: # Since: 0.15.0
                    170: ##
                    171: { 'command': 'guest-file-close',
                    172:   'data': { 'handle': 'int' } }
                    173: 
                    174: ##
1.1.1.2 ! root      175: # @GuestFileRead
        !           176: #
        !           177: # Result of guest agent file-read operation
        !           178: #
        !           179: # @count: number of bytes read (note: count is *before*
        !           180: #         base64-encoding is applied)
        !           181: #
        !           182: # @buf-b64: base64-encoded bytes read
        !           183: #
        !           184: # @eof: whether EOF was encountered during read operation.
        !           185: #
        !           186: # Since: 0.15.0
        !           187: ##
        !           188: { 'type': 'GuestFileRead',
        !           189:   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
        !           190: 
        !           191: ##
1.1       root      192: # @guest-file-read:
                    193: #
                    194: # Read from an open file in the guest. Data will be base64-encoded
                    195: #
                    196: # @handle: filehandle returned by guest-file-open
                    197: #
                    198: # @count: #optional maximum number of bytes to read (default is 4KB)
                    199: #
1.1.1.2 ! root      200: # Returns: @GuestFileRead on success.
1.1       root      201: #
                    202: # Since: 0.15.0
                    203: ##
                    204: { 'command': 'guest-file-read',
                    205:   'data':    { 'handle': 'int', '*count': 'int' },
                    206:   'returns': 'GuestFileRead' }
                    207: 
                    208: ##
1.1.1.2 ! root      209: # @GuestFileWrite
        !           210: #
        !           211: # Result of guest agent file-write operation
        !           212: #
        !           213: # @count: number of bytes written (note: count is actual bytes
        !           214: #         written, after base64-decoding of provided buffer)
        !           215: #
        !           216: # @eof: whether EOF was encountered during write operation.
        !           217: #
        !           218: # Since: 0.15.0
        !           219: ##
        !           220: { 'type': 'GuestFileWrite',
        !           221:   'data': { 'count': 'int', 'eof': 'bool' } }
        !           222: 
        !           223: ##
1.1       root      224: # @guest-file-write:
                    225: #
                    226: # Write to an open file in the guest.
                    227: #
                    228: # @handle: filehandle returned by guest-file-open
                    229: #
                    230: # @buf-b64: base64-encoded string representing data to be written
                    231: #
                    232: # @count: #optional bytes to write (actual bytes, after base64-decode),
                    233: #         default is all content in buf-b64 buffer after base64 decoding
                    234: #
1.1.1.2 ! root      235: # Returns: @GuestFileWrite on success.
1.1       root      236: #
                    237: # Since: 0.15.0
                    238: ##
                    239: { 'command': 'guest-file-write',
                    240:   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
                    241:   'returns': 'GuestFileWrite' }
                    242: 
1.1.1.2 ! root      243: 
        !           244: ##
        !           245: # @GuestFileSeek
        !           246: #
        !           247: # Result of guest agent file-seek operation
        !           248: #
        !           249: # @position: current file position
        !           250: #
        !           251: # @eof: whether EOF was encountered during file seek
        !           252: #
        !           253: # Since: 0.15.0
        !           254: ##
        !           255: { 'type': 'GuestFileSeek',
        !           256:   'data': { 'position': 'int', 'eof': 'bool' } }
        !           257: 
1.1       root      258: ##
                    259: # @guest-file-seek:
                    260: #
                    261: # Seek to a position in the file, as with fseek(), and return the
                    262: # current file position afterward. Also encapsulates ftell()'s
                    263: # functionality, just Set offset=0, whence=SEEK_CUR.
                    264: #
                    265: # @handle: filehandle returned by guest-file-open
                    266: #
                    267: # @offset: bytes to skip over in the file stream
                    268: #
                    269: # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
                    270: #
1.1.1.2 ! root      271: # Returns: @GuestFileSeek on success.
1.1       root      272: #
                    273: # Since: 0.15.0
                    274: ##
                    275: { 'command': 'guest-file-seek',
                    276:   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
                    277:   'returns': 'GuestFileSeek' }
                    278: 
                    279: ##
                    280: # @guest-file-flush:
                    281: #
                    282: # Write file changes bufferred in userspace to disk/kernel buffers
                    283: #
                    284: # @handle: filehandle returned by guest-file-open
                    285: #
                    286: # Returns: Nothing on success.
                    287: #
                    288: # Since: 0.15.0
                    289: ##
                    290: { 'command': 'guest-file-flush',
                    291:   'data': { 'handle': 'int' } }
                    292: 
                    293: ##
1.1.1.2 ! root      294: # @GuestFsFreezeStatus
        !           295: #
        !           296: # An enumation of filesystem freeze states
        !           297: #
        !           298: # @thawed: filesystems thawed/unfrozen
        !           299: #
        !           300: # @frozen: all non-network guest filesystems frozen
        !           301: #
        !           302: # Since: 0.15.0
        !           303: ##
        !           304: { 'enum': 'GuestFsfreezeStatus',
        !           305:   'data': [ 'thawed', 'frozen' ] }
        !           306: 
        !           307: ##
1.1       root      308: # @guest-fsfreeze-status:
                    309: #
1.1.1.2 ! root      310: # Get guest fsfreeze state. error state indicates
1.1       root      311: #
                    312: # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
                    313: #
1.1.1.2 ! root      314: # Note: This may fail to properly report the current state as a result of
        !           315: # some other guest processes having issued an fs freeze/thaw.
        !           316: #
1.1       root      317: # Since: 0.15.0
                    318: ##
                    319: { 'command': 'guest-fsfreeze-status',
                    320:   'returns': 'GuestFsfreezeStatus' }
                    321: 
                    322: ##
                    323: # @guest-fsfreeze-freeze:
                    324: #
1.1.1.2 ! root      325: # Sync and freeze all freezable, local guest filesystems
1.1       root      326: #
1.1.1.2 ! root      327: # Returns: Number of file systems currently frozen. On error, all filesystems
        !           328: # will be thawed.
1.1       root      329: #
                    330: # Since: 0.15.0
                    331: ##
                    332: { 'command': 'guest-fsfreeze-freeze',
                    333:   'returns': 'int' }
                    334: 
                    335: ##
                    336: # @guest-fsfreeze-thaw:
                    337: #
1.1.1.2 ! root      338: # Unfreeze all frozen guest filesystems
        !           339: #
        !           340: # Returns: Number of file systems thawed by this call
1.1       root      341: #
1.1.1.2 ! root      342: # Note: if return value does not match the previous call to
        !           343: #       guest-fsfreeze-freeze, this likely means some freezable
        !           344: #       filesystems were unfrozen before this call, and that the
        !           345: #       filesystem state may have changed before issuing this
        !           346: #       command.
1.1       root      347: #
                    348: # Since: 0.15.0
                    349: ##
                    350: { 'command': 'guest-fsfreeze-thaw',
                    351:   'returns': 'int' }
1.1.1.2 ! root      352: 
        !           353: ##
        !           354: # @guest-suspend-disk
        !           355: #
        !           356: # Suspend guest to disk.
        !           357: #
        !           358: # This command tries to execute the scripts provided by the pm-utils package.
        !           359: # If it's not available, the suspend operation will be performed by manually
        !           360: # writing to a sysfs file.
        !           361: #
        !           362: # For the best results it's strongly recommended to have the pm-utils
        !           363: # package installed in the guest.
        !           364: #
        !           365: # This command does NOT return a response on success. There is a high chance
        !           366: # the command succeeded if the VM exits with a zero exit status or, when
        !           367: # running with --no-shutdown, by issuing the query-status QMP command to
        !           368: # to confirm the VM status is "shutdown". However, the VM could also exit
        !           369: # (or set its status to "shutdown") due to other reasons.
        !           370: #
        !           371: # The following errors may be returned:
        !           372: #          If suspend to disk is not supported, Unsupported
        !           373: #
        !           374: # Notes: It's strongly recommended to issue the guest-sync command before
        !           375: #        sending commands when the guest resumes
        !           376: #
        !           377: # Since: 1.1
        !           378: ##
        !           379: { 'command': 'guest-suspend-disk', 'success-response': 'no' }
        !           380: 
        !           381: ##
        !           382: # @guest-suspend-ram
        !           383: #
        !           384: # Suspend guest to ram.
        !           385: #
        !           386: # This command tries to execute the scripts provided by the pm-utils package.
        !           387: # If it's not available, the suspend operation will be performed by manually
        !           388: # writing to a sysfs file.
        !           389: #
        !           390: # For the best results it's strongly recommended to have the pm-utils
        !           391: # package installed in the guest.
        !           392: #
        !           393: # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
        !           394: # command.  Thus, it's *required* to query QEMU for the presence of the
        !           395: # 'system_wakeup' command before issuing guest-suspend-ram.
        !           396: #
        !           397: # This command does NOT return a response on success. There are two options
        !           398: # to check for success:
        !           399: #   1. Wait for the SUSPEND QMP event from QEMU
        !           400: #   2. Issue the query-status QMP command to confirm the VM status is
        !           401: #      "suspended"
        !           402: #
        !           403: # The following errors may be returned:
        !           404: #          If suspend to ram is not supported, Unsupported
        !           405: #
        !           406: # Notes: It's strongly recommended to issue the guest-sync command before
        !           407: #        sending commands when the guest resumes
        !           408: #
        !           409: # Since: 1.1
        !           410: ##
        !           411: { 'command': 'guest-suspend-ram', 'success-response': 'no' }
        !           412: 
        !           413: ##
        !           414: # @guest-suspend-hybrid
        !           415: #
        !           416: # Save guest state to disk and suspend to ram.
        !           417: #
        !           418: # This command requires the pm-utils package to be installed in the guest.
        !           419: #
        !           420: # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
        !           421: # command.  Thus, it's *required* to query QEMU for the presence of the
        !           422: # 'system_wakeup' command before issuing guest-suspend-hybrid.
        !           423: #
        !           424: # This command does NOT return a response on success. There are two options
        !           425: # to check for success:
        !           426: #   1. Wait for the SUSPEND QMP event from QEMU
        !           427: #   2. Issue the query-status QMP command to confirm the VM status is
        !           428: #      "suspended"
        !           429: #
        !           430: # The following errors may be returned:
        !           431: #          If hybrid suspend is not supported, Unsupported
        !           432: #
        !           433: # Notes: It's strongly recommended to issue the guest-sync command before
        !           434: #        sending commands when the guest resumes
        !           435: #
        !           436: # Since: 1.1
        !           437: ##
        !           438: { 'command': 'guest-suspend-hybrid', 'success-response': 'no' }
        !           439: 
        !           440: ##
        !           441: # @GuestIpAddressType:
        !           442: #
        !           443: # An enumeration of supported IP address types
        !           444: #
        !           445: # @ipv4: IP version 4
        !           446: #
        !           447: # @ipv6: IP version 6
        !           448: #
        !           449: # Since: 1.1
        !           450: ##
        !           451: { 'enum': 'GuestIpAddressType',
        !           452:   'data': [ 'ipv4', 'ipv6' ] }
        !           453: 
        !           454: ##
        !           455: # @GuestIpAddress:
        !           456: #
        !           457: # @ip-address: IP address
        !           458: #
        !           459: # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
        !           460: #
        !           461: # @prefix: Network prefix length of @ip-address
        !           462: #
        !           463: # Since: 1.1
        !           464: ##
        !           465: { 'type': 'GuestIpAddress',
        !           466:   'data': {'ip-address': 'str',
        !           467:            'ip-address-type': 'GuestIpAddressType',
        !           468:            'prefix': 'int'} }
        !           469: 
        !           470: ##
        !           471: # @GuestNetworkInterface:
        !           472: #
        !           473: # @name: The name of interface for which info are being delivered
        !           474: #
        !           475: # @hardware-address: Hardware address of @name
        !           476: #
        !           477: # @ip-addresses: List of addresses assigned to @name
        !           478: #
        !           479: # Since: 1.1
        !           480: ##
        !           481: { 'type': 'GuestNetworkInterface',
        !           482:   'data': {'name': 'str',
        !           483:            '*hardware-address': 'str',
        !           484:            '*ip-addresses': ['GuestIpAddress'] } }
        !           485: 
        !           486: ##
        !           487: # @guest-network-get-interfaces:
        !           488: #
        !           489: # Get list of guest IP addresses, MAC addresses
        !           490: # and netmasks.
        !           491: #
        !           492: # Returns: List of GuestNetworkInfo on success.
        !           493: #
        !           494: # Since: 1.1
        !           495: ##
        !           496: { 'command': 'guest-network-get-interfaces',
        !           497:   'returns': ['GuestNetworkInterface'] }

unix.superglobalmegacorp.com