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