qapi/block-export.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3
   4 ##
   5 # == Block device exports
   6 ##
   7
   8 { 'include': 'sockets.json' }
   9 { 'include': 'block-core.json' }
  10
  11 ##
  12 # @NbdServerOptions:
  13 #
  14 # Keep this type consistent with the nbd-server-start arguments. The only
  15 # intended difference is using SocketAddress instead of SocketAddressLegacy.
  16 #
  17 # @addr: Address on which to listen.
  18 # @tls-creds: ID of the TLS credentials object (since 2.6).
  19 # @tls-authz: ID of the QAuthZ authorization object used to validate
  20 #             the client's x509 distinguished name. This object is
  21 #             is only resolved at time of use, so can be deleted and
  22 #             recreated on the fly while the NBD server is active.
  23 #             If missing, it will default to denying access (since 4.0).
  24 # @max-connections: The maximum number of connections to allow at the same
  25 #                   time, 0 for unlimited. (since 5.2; default: 0)
  26 #
  27 # Since: 4.2
  28 ##
  29 { 'struct': 'NbdServerOptions',
  30   'data': { 'addr': 'SocketAddress',
  31             '*tls-creds': 'str',
  32             '*tls-authz': 'str',
  33             '*max-connections': 'uint32' } }
  34
  35 ##
  36 # @nbd-server-start:
  37 #
  38 # Start an NBD server listening on the given host and port.  Block
  39 # devices can then be exported using @nbd-server-add.  The NBD
  40 # server will present them as named exports; for example, another
  41 # QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
  42 #
  43 # Keep this type consistent with the NbdServerOptions type. The only intended
  44 # difference is using SocketAddressLegacy instead of SocketAddress.
  45 #
  46 # @addr: Address on which to listen.
  47 # @tls-creds: ID of the TLS credentials object (since 2.6).
  48 # @tls-authz: ID of the QAuthZ authorization object used to validate
  49 #             the client's x509 distinguished name. This object is
  50 #             is only resolved at time of use, so can be deleted and
  51 #             recreated on the fly while the NBD server is active.
  52 #             If missing, it will default to denying access (since 4.0).
  53 # @max-connections: The maximum number of connections to allow at the same
  54 #                   time, 0 for unlimited. (since 5.2; default: 0)
  55 #
  56 # Returns: error if the server is already running.
  57 #
  58 # Since: 1.3
  59 ##
  60 { 'command': 'nbd-server-start',
  61   'data': { 'addr': 'SocketAddressLegacy',
  62             '*tls-creds': 'str',
  63             '*tls-authz': 'str',
  64             '*max-connections': 'uint32' } }
  65
  66 ##
  67 # @BlockExportOptionsNbdBase:
  68 #
  69 # An NBD block export (common options shared between nbd-server-add and
  70 # the NBD branch of block-export-add).
  71 #
  72 # @name: Export name. If unspecified, the @device parameter is used as the
  73 #        export name. (Since 2.12)
  74 #
  75 # @description: Free-form description of the export, up to 4096 bytes.
  76 #               (Since 5.0)
  77 #
  78 # Since: 5.0
  79 ##
  80 { 'struct': 'BlockExportOptionsNbdBase',
  81   'data': { '*name': 'str', '*description': 'str' } }
  82
  83 ##
  84 # @BlockExportOptionsNbd:
  85 #
  86 # An NBD block export (distinct options used in the NBD branch of
  87 # block-export-add).
  88 #
  89 # @bitmaps: Also export each of the named dirty bitmaps reachable from
  90 #           @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
  91 #           the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
  92 #           each bitmap.
  93 #           Since 7.1 bitmap may be specified by node/name pair.
  94 #
  95 # @allocation-depth: Also export the allocation depth map for @device, so
  96 #                    the NBD client can use NBD_OPT_SET_META_CONTEXT with
  97 #                    the metadata context name "qemu:allocation-depth" to
  98 #                    inspect allocation details. (since 5.2)
  99 #
 100 # Since: 5.2
 101 ##
 102 { 'struct': 'BlockExportOptionsNbd',
 103   'base': 'BlockExportOptionsNbdBase',
 104   'data': { '*bitmaps': ['BlockDirtyBitmapOrStr'],
 105             '*allocation-depth': 'bool' } }
 106
 107 ##
 108 # @BlockExportOptionsVhostUserBlk:
 109 #
 110 # A vhost-user-blk block export.
 111 #
 112 # @addr: The vhost-user socket on which to listen. Both 'unix' and 'fd'
 113 #        SocketAddress types are supported. Passed fds must be UNIX domain
 114 #        sockets.
 115 # @logical-block-size: Logical block size in bytes. Defaults to 512 bytes.
 116 # @num-queues: Number of request virtqueues. Must be greater than 0. Defaults
 117 #              to 1.
 118 #
 119 # Since: 5.2
 120 ##
 121 { 'struct': 'BlockExportOptionsVhostUserBlk',
 122   'data': { 'addr': 'SocketAddress',
 123             '*logical-block-size': 'size',
 124             '*num-queues': 'uint16'} }
 125
 126 ##
 127 # @FuseExportAllowOther:
 128 #
 129 # Possible allow_other modes for FUSE exports.
 130 #
 131 # @off: Do not pass allow_other as a mount option.
 132 #
 133 # @on: Pass allow_other as a mount option.
 134 #
 135 # @auto: Try mounting with allow_other first, and if that fails, retry
 136 #        without allow_other.
 137 #
 138 # Since: 6.1
 139 ##
 140 { 'enum': 'FuseExportAllowOther',
 141   'data': ['off', 'on', 'auto'] }
 142
 143 ##
 144 # @BlockExportOptionsFuse:
 145 #
 146 # Options for exporting a block graph node on some (file) mountpoint
 147 # as a raw image.
 148 #
 149 # @mountpoint: Path on which to export the block device via FUSE.
 150 #              This must point to an existing regular file.
 151 #
 152 # @growable: Whether writes beyond the EOF should grow the block node
 153 #            accordingly. (default: false)
 154 #
 155 # @allow-other: If this is off, only qemu's user is allowed access to
 156 #               this export.  That cannot be changed even with chmod or
 157 #               chown.
 158 #               Enabling this option will allow other users access to
 159 #               the export with the FUSE mount option "allow_other".
 160 #               Note that using allow_other as a non-root user requires
 161 #               user_allow_other to be enabled in the global fuse.conf
 162 #               configuration file.
 163 #               In auto mode (the default), the FUSE export driver will
 164 #               first attempt to mount the export with allow_other, and
 165 #               if that fails, try again without.
 166 #               (since 6.1; default: auto)
 167 #
 168 # Since: 6.0
 169 ##
 170 { 'struct': 'BlockExportOptionsFuse',
 171   'data': { 'mountpoint': 'str',
 172             '*growable': 'bool',
 173             '*allow-other': 'FuseExportAllowOther' },
 174   'if': 'CONFIG_FUSE' }
 175
 176 ##
 177 # @NbdServerAddOptions:
 178 #
 179 # An NBD block export, per legacy nbd-server-add command.
 180 #
 181 # @device: The device name or node name of the node to be exported
 182 #
 183 # @writable: Whether clients should be able to write to the device via the
 184 #            NBD connection (default false).
 185 #
 186 # @bitmap: Also export a single dirty bitmap reachable from @device, so the
 187 #          NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
 188 #          context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
 189 #          (since 4.0).
 190 #
 191 # Since: 5.0
 192 ##
 193 { 'struct': 'NbdServerAddOptions',
 194   'base': 'BlockExportOptionsNbdBase',
 195   'data': { 'device': 'str',
 196             '*writable': 'bool', '*bitmap': 'str' } }
 197
 198 ##
 199 # @nbd-server-add:
 200 #
 201 # Export a block node to QEMU's embedded NBD server.
 202 #
 203 # The export name will be used as the id for the resulting block export.
 204 #
 205 # Features:
 206 # @deprecated: This command is deprecated. Use @block-export-add instead.
 207 #
 208 # Returns: error if the server is not running, or export with the same name
 209 #          already exists.
 210 #
 211 # Since: 1.3
 212 ##
 213 { 'command': 'nbd-server-add',
 214   'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'] }
 215
 216 ##
 217 # @BlockExportRemoveMode:
 218 #
 219 # Mode for removing a block export.
 220 #
 221 # @safe: Remove export if there are no existing connections, fail otherwise.
 222 #
 223 # @hard: Drop all connections immediately and remove export.
 224 #
 225 # TODO: Potential additional modes to be added in the future:
 226 #
 227 #       hide: Just hide export from new clients, leave existing connections as is.
 228 #       Remove export after all clients are disconnected.
 229 #
 230 #       soft: Hide export from new clients, answer with ESHUTDOWN for all further
 231 #       requests from existing clients.
 232 #
 233 # Since: 2.12
 234 ##
 235 {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']}
 236
 237 ##
 238 # @nbd-server-remove:
 239 #
 240 # Remove NBD export by name.
 241 #
 242 # @name: Block export id.
 243 #
 244 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
 245 #        Default is 'safe'.
 246 #
 247 # Features:
 248 # @deprecated: This command is deprecated. Use @block-export-del instead.
 249 #
 250 # Returns: error if
 251 #            - the server is not running
 252 #            - export is not found
 253 #            - mode is 'safe' and there are existing connections
 254 #
 255 # Since: 2.12
 256 ##
 257 { 'command': 'nbd-server-remove',
 258   'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'},
 259   'features': ['deprecated'] }
 260
 261 ##
 262 # @nbd-server-stop:
 263 #
 264 # Stop QEMU's embedded NBD server, and unregister all devices previously
 265 # added via @nbd-server-add.
 266 #
 267 # Since: 1.3
 268 ##
 269 { 'command': 'nbd-server-stop' }
 270
 271 ##
 272 # @BlockExportType:
 273 #
 274 # An enumeration of block export types
 275 #
 276 # @nbd: NBD export
 277 # @vhost-user-blk: vhost-user-blk export (since 5.2)
 278 # @fuse: FUSE export (since: 6.0)
 279 #
 280 # Since: 4.2
 281 ##
 282 { 'enum': 'BlockExportType',
 283   'data': [ 'nbd',
 284             { 'name': 'vhost-user-blk',
 285               'if': 'CONFIG_VHOST_USER_BLK_SERVER' },
 286             { 'name': 'fuse', 'if': 'CONFIG_FUSE' } ] }
 287
 288 ##
 289 # @BlockExportOptions:
 290 #
 291 # Describes a block export, i.e. how single node should be exported on an
 292 # external interface.
 293 #
 294 # @id: A unique identifier for the block export (across all export types)
 295 #
 296 # @node-name: The node name of the block node to be exported (since: 5.2)
 297 #
 298 # @writable: True if clients should be able to write to the export
 299 #            (default false)
 300 #
 301 # @writethrough: If true, caches are flushed after every write request to the
 302 #                export before completion is signalled. (since: 5.2;
 303 #                default: false)
 304 #
 305 # @iothread: The name of the iothread object where the export will run. The
 306 #            default is to use the thread currently associated with the
 307 #            block node. (since: 5.2)
 308 #
 309 # @fixed-iothread: True prevents the block node from being moved to another
 310 #                  thread while the export is active. If true and @iothread is
 311 #                  given, export creation fails if the block node cannot be
 312 #                  moved to the iothread. The default is false. (since: 5.2)
 313 #
 314 # Since: 4.2
 315 ##
 316 { 'union': 'BlockExportOptions',
 317   'base': { 'type': 'BlockExportType',
 318             'id': 'str',
 319             '*fixed-iothread': 'bool',
 320             '*iothread': 'str',
 321             'node-name': 'str',
 322             '*writable': 'bool',
 323             '*writethrough': 'bool' },
 324   'discriminator': 'type',
 325   'data': {
 326       'nbd': 'BlockExportOptionsNbd',
 327       'vhost-user-blk': { 'type': 'BlockExportOptionsVhostUserBlk',
 328                           'if': 'CONFIG_VHOST_USER_BLK_SERVER' },
 329       'fuse': { 'type': 'BlockExportOptionsFuse',
 330                 'if': 'CONFIG_FUSE' }
 331    } }
 332
 333 ##
 334 # @block-export-add:
 335 #
 336 # Creates a new block export.
 337 #
 338 # Since: 5.2
 339 ##
 340 { 'command': 'block-export-add',
 341   'data': 'BlockExportOptions', 'boxed': true }
 342
 343 ##
 344 # @block-export-del:
 345 #
 346 # Request to remove a block export. This drops the user's reference to the
 347 # export, but the export may still stay around after this command returns until
 348 # the shutdown of the export has completed.
 349 #
 350 # @id: Block export id.
 351 #
 352 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
 353 #        Default is 'safe'.
 354 #
 355 # Returns: Error if the export is not found or @mode is 'safe' and the export
 356 #          is still in use (e.g. by existing client connections)
 357 #
 358 # Since: 5.2
 359 ##
 360 { 'command': 'block-export-del',
 361   'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } }
 362
 363 ##
 364 # @BLOCK_EXPORT_DELETED:
 365 #
 366 # Emitted when a block export is removed and its id can be reused.
 367 #
 368 # @id: Block export id.
 369 #
 370 # Since: 5.2
 371 ##
 372 { 'event': 'BLOCK_EXPORT_DELETED',
 373   'data': { 'id': 'str' } }
 374
 375 ##
 376 # @BlockExportInfo:
 377 #
 378 # Information about a single block export.
 379 #
 380 # @id: The unique identifier for the block export
 381 #
 382 # @type: The block export type
 383 #
 384 # @node-name: The node name of the block node that is exported
 385 #
 386 # @shutting-down: True if the export is shutting down (e.g. after a
 387 #                 block-export-del command, but before the shutdown has
 388 #                 completed)
 389 #
 390 # Since:  5.2
 391 ##
 392 { 'struct': 'BlockExportInfo',
 393   'data': { 'id': 'str',
 394             'type': 'BlockExportType',
 395             'node-name': 'str',
 396             'shutting-down': 'bool' } }
 397
 398 ##
 399 # @query-block-exports:
 400 #
 401 # Returns: A list of BlockExportInfo describing all block exports
 402 #
 403 # Since: 5.2
 404 ##
 405 { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] }