qapi/block-export.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3
   4 ##
   5 # == Block device exports
   6 ##
   7
   8 { 'include': 'sockets.json' }
   9
  10 ##
  11 # @NbdServerOptions:
  12 #
  13 # Keep this type consistent with the nbd-server-start arguments. The only
  14 # intended difference is using SocketAddress instead of SocketAddressLegacy.
  15 #
  16 # @addr: Address on which to listen.
  17 # @tls-creds: ID of the TLS credentials object (since 2.6).
  18 # @tls-authz: ID of the QAuthZ authorization object used to validate
  19 #             the client's x509 distinguished name. This object is
  20 #             is only resolved at time of use, so can be deleted and
  21 #             recreated on the fly while the NBD server is active.
  22 #             If missing, it will default to denying access (since 4.0).
  23 # @max-connections: The maximum number of connections to allow at the same
  24 #                   time, 0 for unlimited. (since 5.2; default: 0)
  25 #
  26 # Since: 4.2
  27 ##
  28 { 'struct': 'NbdServerOptions',
  29   'data': { 'addr': 'SocketAddress',
  30             '*tls-creds': 'str',
  31             '*tls-authz': 'str',
  32             '*max-connections': 'uint32' } }
  33
  34 ##
  35 # @nbd-server-start:
  36 #
  37 # Start an NBD server listening on the given host and port.  Block
  38 # devices can then be exported using @nbd-server-add.  The NBD
  39 # server will present them as named exports; for example, another
  40 # QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
  41 #
  42 # Keep this type consistent with the NbdServerOptions type. The only intended
  43 # difference is using SocketAddressLegacy instead of SocketAddress.
  44 #
  45 # @addr: Address on which to listen.
  46 # @tls-creds: ID of the TLS credentials object (since 2.6).
  47 # @tls-authz: ID of the QAuthZ authorization object used to validate
  48 #             the client's x509 distinguished name. This object is
  49 #             is only resolved at time of use, so can be deleted and
  50 #             recreated on the fly while the NBD server is active.
  51 #             If missing, it will default to denying access (since 4.0).
  52 # @max-connections: The maximum number of connections to allow at the same
  53 #                   time, 0 for unlimited. (since 5.2; default: 0)
  54 #
  55 # Returns: error if the server is already running.
  56 #
  57 # Since: 1.3.0
  58 ##
  59 { 'command': 'nbd-server-start',
  60   'data': { 'addr': 'SocketAddressLegacy',
  61             '*tls-creds': 'str',
  62             '*tls-authz': 'str',
  63             '*max-connections': 'uint32' } }
  64
  65 ##
  66 # @BlockExportOptionsNbd:
  67 #
  68 # An NBD block export (options shared between nbd-server-add and the NBD branch
  69 # of block-export-add).
  70 #
  71 # @name: Export name. If unspecified, the @device parameter is used as the
  72 #        export name. (Since 2.12)
  73 #
  74 # @description: Free-form description of the export, up to 4096 bytes.
  75 #               (Since 5.0)
  76 #
  77 # @writable: Whether clients should be able to write to the device via the
  78 #            NBD connection (default false).
  79 #
  80 # @bitmap: Also export the dirty bitmap reachable from @device, so the
  81 #          NBD client can use NBD_OPT_SET_META_CONTEXT with
  82 #          "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0)
  83 #
  84 # Since: 5.0
  85 ##
  86 { 'struct': 'BlockExportOptionsNbd',
  87   'data': { '*name': 'str', '*description': 'str',
  88             '*writable': 'bool', '*bitmap': 'str' } }
  89
  90 ##
  91 # @NbdServerAddOptions:
  92 #
  93 # An NBD block export.
  94 #
  95 # @device: The device name or node name of the node to be exported
  96 #
  97 # Since: 5.0
  98 ##
  99 { 'struct': 'NbdServerAddOptions',
 100   'base': 'BlockExportOptionsNbd',
 101   'data': { 'device': 'str' } }
 102
 103 ##
 104 # @nbd-server-add:
 105 #
 106 # Export a block node to QEMU's embedded NBD server.
 107 #
 108 # The export name will be used as the id for the resulting block export.
 109 #
 110 # Returns: error if the server is not running, or export with the same name
 111 #          already exists.
 112 #
 113 # Since: 1.3.0
 114 ##
 115 { 'command': 'nbd-server-add',
 116   'data': 'NbdServerAddOptions', 'boxed': true }
 117
 118 ##
 119 # @BlockExportRemoveMode:
 120 #
 121 # Mode for removing a block export.
 122 #
 123 # @safe: Remove export if there are no existing connections, fail otherwise.
 124 #
 125 # @hard: Drop all connections immediately and remove export.
 126 #
 127 # Potential additional modes to be added in the future:
 128 #
 129 # hide: Just hide export from new clients, leave existing connections as is.
 130 # Remove export after all clients are disconnected.
 131 #
 132 # soft: Hide export from new clients, answer with ESHUTDOWN for all further
 133 # requests from existing clients.
 134 #
 135 # Since: 2.12
 136 ##
 137 {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']}
 138
 139 ##
 140 # @nbd-server-remove:
 141 #
 142 # Remove NBD export by name.
 143 #
 144 # @name: Block export id.
 145 #
 146 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
 147 #        Default is 'safe'.
 148 #
 149 # Returns: error if
 150 #            - the server is not running
 151 #            - export is not found
 152 #            - mode is 'safe' and there are existing connections
 153 #
 154 # Since: 2.12
 155 ##
 156 { 'command': 'nbd-server-remove',
 157   'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'} }
 158
 159 ##
 160 # @nbd-server-stop:
 161 #
 162 # Stop QEMU's embedded NBD server, and unregister all devices previously
 163 # added via @nbd-server-add.
 164 #
 165 # Since: 1.3.0
 166 ##
 167 { 'command': 'nbd-server-stop' }
 168
 169 ##
 170 # @BlockExportType:
 171 #
 172 # An enumeration of block export types
 173 #
 174 # @nbd: NBD export
 175 #
 176 # Since: 4.2
 177 ##
 178 { 'enum': 'BlockExportType',
 179   'data': [ 'nbd' ] }
 180
 181 ##
 182 # @BlockExportOptions:
 183 #
 184 # Describes a block export, i.e. how single node should be exported on an
 185 # external interface.
 186 #
 187 # @id: A unique identifier for the block export (across all export types)
 188 #
 189 # @node-name: The node name of the block node to be exported (since: 5.2)
 190 #
 191 # @writethrough: If true, caches are flushed after every write request to the
 192 #                export before completion is signalled. (since: 5.2;
 193 #                default: false)
 194 #
 195 # Since: 4.2
 196 ##
 197 { 'union': 'BlockExportOptions',
 198   'base': { 'type': 'BlockExportType',
 199             'id': 'str',
 200             'node-name': 'str',
 201             '*writethrough': 'bool' },
 202   'discriminator': 'type',
 203   'data': {
 204       'nbd': 'BlockExportOptionsNbd'
 205    } }
 206
 207 ##
 208 # @block-export-add:
 209 #
 210 # Creates a new block export.
 211 #
 212 # Since: 5.2
 213 ##
 214 { 'command': 'block-export-add',
 215   'data': 'BlockExportOptions', 'boxed': true }
 216
 217 ##
 218 # @block-export-del:
 219 #
 220 # Request to remove a block export. This drops the user's reference to the
 221 # export, but the export may still stay around after this command returns until
 222 # the shutdown of the export has completed.
 223 #
 224 # @id: Block export id.
 225 #
 226 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
 227 #        Default is 'safe'.
 228 #
 229 # Returns: Error if the export is not found or @mode is 'safe' and the export
 230 #          is still in use (e.g. by existing client connections)
 231 #
 232 # Since: 5.2
 233 ##
 234 { 'command': 'block-export-del',
 235   'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } }
 236
 237 ##
 238 # @BLOCK_EXPORT_DELETED:
 239 #
 240 # Emitted when a block export is removed and its id can be reused.
 241 #
 242 # @id: Block export id.
 243 #
 244 # Since: 5.2
 245 ##
 246 { 'event': 'BLOCK_EXPORT_DELETED',
 247   'data': { 'id': 'str' } }
 248
 249 ##
 250 # @BlockExportInfo:
 251 #
 252 # Information about a single block export.
 253 #
 254 # @id: The unique identifier for the block export
 255 #
 256 # @type: The block export type
 257 #
 258 # @node-name: The node name of the block node that is exported
 259 #
 260 # @shutting-down: True if the export is shutting down (e.g. after a
 261 #                 block-export-del command, but before the shutdown has
 262 #                 completed)
 263 #
 264 # Since:  5.2
 265 ##
 266 { 'struct': 'BlockExportInfo',
 267   'data': { 'id': 'str',
 268             'type': 'BlockExportType',
 269             'node-name': 'str',
 270             'shutting-down': 'bool' } }
 271
 272 ##
 273 # @query-block-exports:
 274 #
 275 # Returns: A list of BlockExportInfo describing all block exports
 276 #
 277 # Since: 5.2
 278 ##
 279 { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] }