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 # @BlockExportOptionsNbdBase:
  67 #
  68 # An NBD block export (common options shared between nbd-server-add and
  69 # the NBD branch 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 # Since: 5.0
  78 ##
  79 { 'struct': 'BlockExportOptionsNbdBase',
  80   'data': { '*name': 'str', '*description': 'str' } }
  81
  82 ##
  83 # @BlockExportOptionsNbd:
  84 #
  85 # An NBD block export (distinct options used in the NBD branch of
  86 # block-export-add).
  87 #
  88 # @bitmaps: Also export each of the named dirty bitmaps reachable from
  89 #           @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
  90 #           the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
  91 #           each bitmap.
  92 #
  93 # @allocation-depth: Also export the allocation depth map for @device, so
  94 #                    the NBD client can use NBD_OPT_SET_META_CONTEXT with
  95 #                    the metadata context name "qemu:allocation-depth" to
  96 #                    inspect allocation details. (since 5.2)
  97 #
  98 # Since: 5.2
  99 ##
 100 { 'struct': 'BlockExportOptionsNbd',
 101   'base': 'BlockExportOptionsNbdBase',
 102   'data': { '*bitmaps': ['str'], '*allocation-depth': 'bool' } }
 103
 104 ##
 105 # @BlockExportOptionsVhostUserBlk:
 106 #
 107 # A vhost-user-blk block export.
 108 #
 109 # @addr: The vhost-user socket on which to listen. Both 'unix' and 'fd'
 110 #        SocketAddress types are supported. Passed fds must be UNIX domain
 111 #        sockets.
 112 # @logical-block-size: Logical block size in bytes. Defaults to 512 bytes.
 113 # @num-queues: Number of request virtqueues. Must be greater than 0. Defaults
 114 #              to 1.
 115 #
 116 # Since: 5.2
 117 ##
 118 { 'struct': 'BlockExportOptionsVhostUserBlk',
 119   'data': { 'addr': 'SocketAddress',
 120             '*logical-block-size': 'size',
 121             '*num-queues': 'uint16'} }
 122
 123 ##
 124 # @NbdServerAddOptions:
 125 #
 126 # An NBD block export, per legacy nbd-server-add command.
 127 #
 128 # @device: The device name or node name of the node to be exported
 129 #
 130 # @writable: Whether clients should be able to write to the device via the
 131 #            NBD connection (default false).
 132 #
 133 # @bitmap: Also export a single dirty bitmap reachable from @device, so the
 134 #          NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
 135 #          context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
 136 #          (since 4.0).
 137 #
 138 # Since: 5.0
 139 ##
 140 { 'struct': 'NbdServerAddOptions',
 141   'base': 'BlockExportOptionsNbdBase',
 142   'data': { 'device': 'str',
 143             '*writable': 'bool', '*bitmap': 'str' } }
 144
 145 ##
 146 # @nbd-server-add:
 147 #
 148 # Export a block node to QEMU's embedded NBD server.
 149 #
 150 # The export name will be used as the id for the resulting block export.
 151 #
 152 # Features:
 153 # @deprecated: This command is deprecated. Use @block-export-add instead.
 154 #
 155 # Returns: error if the server is not running, or export with the same name
 156 #          already exists.
 157 #
 158 # Since: 1.3.0
 159 ##
 160 { 'command': 'nbd-server-add',
 161   'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'] }
 162
 163 ##
 164 # @BlockExportRemoveMode:
 165 #
 166 # Mode for removing a block export.
 167 #
 168 # @safe: Remove export if there are no existing connections, fail otherwise.
 169 #
 170 # @hard: Drop all connections immediately and remove export.
 171 #
 172 # Potential additional modes to be added in the future:
 173 #
 174 # hide: Just hide export from new clients, leave existing connections as is.
 175 # Remove export after all clients are disconnected.
 176 #
 177 # soft: Hide export from new clients, answer with ESHUTDOWN for all further
 178 # requests from existing clients.
 179 #
 180 # Since: 2.12
 181 ##
 182 {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']}
 183
 184 ##
 185 # @nbd-server-remove:
 186 #
 187 # Remove NBD export by name.
 188 #
 189 # @name: Block export id.
 190 #
 191 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
 192 #        Default is 'safe'.
 193 #
 194 # Features:
 195 # @deprecated: This command is deprecated. Use @block-export-del instead.
 196 #
 197 # Returns: error if
 198 #            - the server is not running
 199 #            - export is not found
 200 #            - mode is 'safe' and there are existing connections
 201 #
 202 # Since: 2.12
 203 ##
 204 { 'command': 'nbd-server-remove',
 205   'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'},
 206   'features': ['deprecated'] }
 207
 208 ##
 209 # @nbd-server-stop:
 210 #
 211 # Stop QEMU's embedded NBD server, and unregister all devices previously
 212 # added via @nbd-server-add.
 213 #
 214 # Since: 1.3.0
 215 ##
 216 { 'command': 'nbd-server-stop' }
 217
 218 ##
 219 # @BlockExportType:
 220 #
 221 # An enumeration of block export types
 222 #
 223 # @nbd: NBD export
 224 # @vhost-user-blk: vhost-user-blk export (since 5.2)
 225 #
 226 # Since: 4.2
 227 ##
 228 { 'enum': 'BlockExportType',
 229   'data': [ 'nbd', 'vhost-user-blk' ] }
 230
 231 ##
 232 # @BlockExportOptions:
 233 #
 234 # Describes a block export, i.e. how single node should be exported on an
 235 # external interface.
 236 #
 237 # @id: A unique identifier for the block export (across all export types)
 238 #
 239 # @node-name: The node name of the block node to be exported (since: 5.2)
 240 #
 241 # @writable: True if clients should be able to write to the export
 242 #            (default false)
 243 #
 244 # @writethrough: If true, caches are flushed after every write request to the
 245 #                export before completion is signalled. (since: 5.2;
 246 #                default: false)
 247 #
 248 # @iothread: The name of the iothread object where the export will run. The
 249 #            default is to use the thread currently associated with the
 250 #            block node. (since: 5.2)
 251 #
 252 # @fixed-iothread: True prevents the block node from being moved to another
 253 #                  thread while the export is active. If true and @iothread is
 254 #                  given, export creation fails if the block node cannot be
 255 #                  moved to the iothread. The default is false. (since: 5.2)
 256 #
 257 # Since: 4.2
 258 ##
 259 { 'union': 'BlockExportOptions',
 260   'base': { 'type': 'BlockExportType',
 261             'id': 'str',
 262             '*fixed-iothread': 'bool',
 263             '*iothread': 'str',
 264             'node-name': 'str',
 265             '*writable': 'bool',
 266             '*writethrough': 'bool' },
 267   'discriminator': 'type',
 268   'data': {
 269       'nbd': 'BlockExportOptionsNbd',
 270       'vhost-user-blk': 'BlockExportOptionsVhostUserBlk'
 271    } }
 272
 273 ##
 274 # @block-export-add:
 275 #
 276 # Creates a new block export.
 277 #
 278 # Since: 5.2
 279 ##
 280 { 'command': 'block-export-add',
 281   'data': 'BlockExportOptions', 'boxed': true }
 282
 283 ##
 284 # @block-export-del:
 285 #
 286 # Request to remove a block export. This drops the user's reference to the
 287 # export, but the export may still stay around after this command returns until
 288 # the shutdown of the export has completed.
 289 #
 290 # @id: Block export id.
 291 #
 292 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
 293 #        Default is 'safe'.
 294 #
 295 # Returns: Error if the export is not found or @mode is 'safe' and the export
 296 #          is still in use (e.g. by existing client connections)
 297 #
 298 # Since: 5.2
 299 ##
 300 { 'command': 'block-export-del',
 301   'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } }
 302
 303 ##
 304 # @BLOCK_EXPORT_DELETED:
 305 #
 306 # Emitted when a block export is removed and its id can be reused.
 307 #
 308 # @id: Block export id.
 309 #
 310 # Since: 5.2
 311 ##
 312 { 'event': 'BLOCK_EXPORT_DELETED',
 313   'data': { 'id': 'str' } }
 314
 315 ##
 316 # @BlockExportInfo:
 317 #
 318 # Information about a single block export.
 319 #
 320 # @id: The unique identifier for the block export
 321 #
 322 # @type: The block export type
 323 #
 324 # @node-name: The node name of the block node that is exported
 325 #
 326 # @shutting-down: True if the export is shutting down (e.g. after a
 327 #                 block-export-del command, but before the shutdown has
 328 #                 completed)
 329 #
 330 # Since:  5.2
 331 ##
 332 { 'struct': 'BlockExportInfo',
 333   'data': { 'id': 'str',
 334             'type': 'BlockExportType',
 335             'node-name': 'str',
 336             'shutting-down': 'bool' } }
 337
 338 ##
 339 # @query-block-exports:
 340 #
 341 # Returns: A list of BlockExportInfo describing all block exports
 342 #
 343 # Since: 5.2
 344 ##
 345 { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] }