| # -*- Mode: Python -*- | |
| # vim: filetype=python | |
| ## | |
| # Block device exports | |
| # ==================== | |
| ## | |
| { 'include': 'sockets.json' } | |
| { 'include': 'block-core.json' } | |
| ## | |
| # @NbdServerOptionsBase: | |
| # | |
| # @handshake-max-seconds: Time limit, in seconds, at which a client | |
| # that has not completed the negotiation handshake will be | |
| # disconnected, or 0 for no limit (since 10.0; default: 10). | |
| # | |
| # @tls-creds: ID of the TLS credentials object (since 2.6). | |
| # | |
| # @tls-authz: ID of the QAuthZ authorization object used to validate | |
| # the client's x509 distinguished name. This object is is only | |
| # resolved at time of use, so can be deleted and recreated on the | |
| # fly while the NBD server is active. If missing, it will default | |
| # to denying access (since 4.0). | |
| # | |
| # @max-connections: The maximum number of connections to allow at the | |
| # same time, 0 for unlimited. Setting this to 1 also stops the | |
| # server from advertising multiple client support (since 5.2; | |
| # default: 100). | |
| ## | |
| { 'struct': 'NbdServerOptionsBase', | |
| 'data': { '*handshake-max-seconds': 'uint32', | |
| '*tls-creds': 'str', | |
| '*tls-authz': 'str', | |
| '*max-connections': 'uint32' } } | |
| ## | |
| # @NbdServerOptions: | |
| # Keep this type consistent with the `NbdServerOptionsLegacy` | |
| # type. The only intended difference is using `SocketAddress` | |
| # instead of `SocketAddressLegacy`. | |
| # | |
| # @addr: Address on which to listen (since 4.2). | |
| ## | |
| { 'struct': 'NbdServerOptions', | |
| 'base': 'NbdServerOptionsBase', | |
| 'data': { 'addr': 'SocketAddress' } } | |
| ## | |
| # @NbdServerOptionsLegacy: | |
| # Keep this type consistent with the `NbdServerOptions` type. The | |
| # only intended difference is using `SocketAddressLegacy` instead | |
| # of `SocketAddress`. | |
| # | |
| # @addr: Address on which to listen (since 1.3). | |
| ## | |
| { 'struct': 'NbdServerOptionsLegacy', | |
| 'base': 'NbdServerOptionsBase', | |
| 'data': { 'addr': 'SocketAddressLegacy' } } | |
| ## | |
| # @nbd-server-start: | |
| # Start an NBD server listening on the given host and port. Block | |
| # devices can then be exported using `nbd-server-add`. The NBD | |
| # server will present them as named exports; for example, another | |
| # QEMU instance could refer to them as | |
| # "nbd:HOST:PORT:exportname=NAME". | |
| # | |
| # Errors: | |
| # - if the server is already running | |
| # | |
| # Since: 1.3 | |
| ## | |
| { 'command': 'nbd-server-start', | |
| 'data': 'NbdServerOptionsLegacy', | |
| 'allow-preconfig': true } | |
| ## | |
| # @BlockExportOptionsNbdBase: | |
| # An NBD block export (common options shared between | |
| # `nbd-server-add` and the NBD branch of `block-export-add`). | |
| # | |
| # @name: Export name. If unspecified, the @device parameter is used | |
| # as the export name. (Since 2.12) | |
| # | |
| # @description: Free-form description of the export, up to 4096 bytes. | |
| # (Since 5.0) | |
| # | |
| # Since: 5.0 | |
| ## | |
| { 'struct': 'BlockExportOptionsNbdBase', | |
| 'data': { '*name': 'str', '*description': 'str' } } | |
| ## | |
| # @BlockExportOptionsNbd: | |
| # An NBD block export (distinct options used in the NBD branch of | |
| # `block-export-add`). | |
| # | |
| # @bitmaps: Also export each of the named dirty bitmaps reachable from | |
| # @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with | |
| # the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect | |
| # each bitmap. Since 7.1 bitmap may be specified by node/name | |
| # pair. | |
| # | |
| # @allocation-depth: Also export the allocation depth map for @device, | |
| # so the NBD client can use NBD_OPT_SET_META_CONTEXT with the | |
| # metadata context name "qemu:allocation-depth" to inspect | |
| # allocation details. (since 5.2) | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'struct': 'BlockExportOptionsNbd', | |
| 'base': 'BlockExportOptionsNbdBase', | |
| 'data': { '*bitmaps': ['BlockDirtyBitmapOrStr'], | |
| '*allocation-depth': 'bool' } } | |
| ## | |
| # @BlockExportOptionsVhostUserBlk: | |
| # A vhost-user-blk block export. | |
| # | |
| # @addr: The vhost-user socket on which to listen. Both 'unix' and | |
| # 'fd' `SocketAddress` types are supported. Passed fds must be | |
| # UNIX domain sockets. | |
| # | |
| # @logical-block-size: Logical block size in bytes. Defaults to 512 | |
| # bytes. | |
| # | |
| # @num-queues: Number of request virtqueues. Must be greater than 0. | |
| # Defaults to 1. | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'struct': 'BlockExportOptionsVhostUserBlk', | |
| 'data': { 'addr': 'SocketAddress', | |
| '*logical-block-size': 'size', | |
| '*num-queues': 'uint16'} } | |
| ## | |
| # @FuseExportAllowOther: | |
| # Possible allow_other modes for FUSE exports. | |
| # | |
| # @off: Do not pass allow_other as a mount option. | |
| # | |
| # @on: Pass allow_other as a mount option. | |
| # | |
| # @auto: Try mounting with allow_other first, and if that fails, retry | |
| # without allow_other. | |
| # | |
| # Since: 6.1 | |
| ## | |
| { 'enum': 'FuseExportAllowOther', | |
| 'data': ['off', 'on', 'auto'] } | |
| ## | |
| # @BlockExportOptionsFuse: | |
| # Options for exporting a block graph node on some (file) | |
| # mountpoint as a raw image. | |
| # | |
| # Multi-threading note: The FUSE export supports multi-threading. | |
| # Currently, requests are distributed across these threads in a | |
| # round-robin fashion, i.e. independently of the CPU core from which a | |
| # request originates. | |
| # | |
| # @mountpoint: Path on which to export the block device via FUSE. | |
| # This must point to an existing regular file. | |
| # | |
| # @growable: Whether writes beyond the EOF should grow the block node | |
| # accordingly. (default: false) | |
| # | |
| # @allow-other: If this is off, only QEMU's user is allowed access to | |
| # this export. That cannot be changed even with chmod or chown. | |
| # Enabling this option will allow other users access to the export | |
| # with the FUSE mount option "allow_other". Note that using | |
| # allow_other as a non-root user requires user_allow_other to be | |
| # enabled in the global fuse.conf configuration file. In auto | |
| # mode (the default), the FUSE export driver will first attempt to | |
| # mount the export with allow_other, and if that fails, try again | |
| # without. (since 6.1; default: auto) | |
| # | |
| # Since: 6.0 | |
| ## | |
| { 'struct': 'BlockExportOptionsFuse', | |
| 'data': { 'mountpoint': 'str', | |
| '*growable': 'bool', | |
| '*allow-other': 'FuseExportAllowOther' }, | |
| 'if': 'CONFIG_FUSE' } | |
| ## | |
| # @BlockExportOptionsVduseBlk: | |
| # A vduse-blk block export. | |
| # | |
| # @name: the name of VDUSE device (must be unique across the host). | |
| # | |
| # @num-queues: the number of virtqueues. Defaults to 1. | |
| # | |
| # @queue-size: the size of virtqueue. Defaults to 256. | |
| # | |
| # @logical-block-size: Logical block size in bytes. Range [512, | |
| # PAGE_SIZE] and must be power of 2. Defaults to 512 bytes. | |
| # | |
| # @serial: the serial number of virtio block device. Defaults to | |
| # empty string. | |
| # | |
| # Since: 7.1 | |
| ## | |
| { 'struct': 'BlockExportOptionsVduseBlk', | |
| 'data': { 'name': 'str', | |
| '*num-queues': 'uint16', | |
| '*queue-size': 'uint16', | |
| '*logical-block-size': 'size', | |
| '*serial': 'str' } } | |
| ## | |
| # @NbdServerAddOptions: | |
| # An NBD block export, per legacy `nbd-server-add` command. | |
| # | |
| # @device: The device name or node name of the node to be exported | |
| # | |
| # @writable: Whether clients should be able to write to the device via | |
| # the NBD connection (default false). | |
| # | |
| # @bitmap: Also export a single dirty bitmap reachable from @device, | |
| # so the NBD client can use NBD_OPT_SET_META_CONTEXT with the | |
| # metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the | |
| # bitmap (since 4.0). | |
| # | |
| # Since: 5.0 | |
| ## | |
| { 'struct': 'NbdServerAddOptions', | |
| 'base': 'BlockExportOptionsNbdBase', | |
| 'data': { 'device': 'str', | |
| '*writable': 'bool', '*bitmap': 'str' } } | |
| ## | |
| # @nbd-server-add: | |
| # Export a block node to QEMU's embedded NBD server. | |
| # | |
| # The export name will be used as the id for the resulting block | |
| # export. | |
| # | |
| # Features: | |
| # | |
| # @deprecated: This command is deprecated. Use `block-export-add` | |
| # instead. | |
| # | |
| # Errors: | |
| # - if the server is not running | |
| # - if an export with the same name already exists | |
| # | |
| # Since: 1.3 | |
| ## | |
| { 'command': 'nbd-server-add', | |
| 'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'], | |
| 'allow-preconfig': true } | |
| ## | |
| # @BlockExportRemoveMode: | |
| # Mode for removing a block export. | |
| # | |
| # @safe: Remove export if there are no existing connections, fail | |
| # otherwise. | |
| # | |
| # @hard: Drop all connections immediately and remove export. | |
| # | |
| # TODO: Potential additional modes to be added in the future: | |
| # | |
| # - hide: Just hide export from new clients, leave existing | |
| # connections as is. Remove export after all clients are | |
| # disconnected. | |
| # | |
| # - soft: Hide export from new clients, answer with ESHUTDOWN for | |
| # all further requests from existing clients. | |
| # | |
| # Since: 2.12 | |
| ## | |
| {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']} | |
| ## | |
| # @nbd-server-remove: | |
| # Remove NBD export by name. | |
| # | |
| # @name: Block export id. | |
| # | |
| # @mode: Mode of command operation. See `BlockExportRemoveMode` | |
| # description. Default is 'safe'. | |
| # | |
| # Features: | |
| # | |
| # @deprecated: This command is deprecated. Use `block-export-del` | |
| # instead. | |
| # | |
| # Errors: | |
| # - if the server is not running | |
| # - if export is not found | |
| # - if mode is 'safe' and there are existing connections | |
| # | |
| # Since: 2.12 | |
| ## | |
| { 'command': 'nbd-server-remove', | |
| 'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'}, | |
| 'features': ['deprecated'], | |
| 'allow-preconfig': true } | |
| ## | |
| # @nbd-server-stop: | |
| # Stop QEMU's embedded NBD server, and unregister all devices | |
| # previously added via `nbd-server-add`. | |
| # | |
| # Since: 1.3 | |
| ## | |
| { 'command': 'nbd-server-stop', | |
| 'allow-preconfig': true } | |
| ## | |
| # @BlockExportType: | |
| # An enumeration of block export types | |
| # | |
| # @nbd: NBD export | |
| # | |
| # @vhost-user-blk: vhost-user-blk export (since 5.2) | |
| # | |
| # @fuse: FUSE export (since: 6.0) | |
| # | |
| # @vduse-blk: vduse-blk export (since 7.1) | |
| # | |
| # Since: 4.2 | |
| ## | |
| { 'enum': 'BlockExportType', | |
| 'data': [ 'nbd', | |
| { 'name': 'vhost-user-blk', | |
| 'if': 'CONFIG_VHOST_USER_BLK_SERVER' }, | |
| { 'name': 'fuse', 'if': 'CONFIG_FUSE' }, | |
| { 'name': 'vduse-blk', 'if': 'CONFIG_VDUSE_BLK_EXPORT' } ] } | |
| ## | |
| # @BlockExportOptions: | |
| # Describes a block export, i.e. how single node should be | |
| # exported on an external interface. | |
| # | |
| # @type: Block export type | |
| # | |
| # @id: A unique identifier for the block export (across all export | |
| # types) | |
| # | |
| # @node-name: The node name of the block node to be exported | |
| # (since: 5.2) | |
| # | |
| # @writable: True if clients should be able to write to the export | |
| # (default false) | |
| # | |
| # @writethrough: If true, caches are flushed after every write request | |
| # to the export before completion is signalled. (since: 5.2; | |
| # default: false) | |
| # | |
| # @iothread: The name(s) of one or more iothread object(s) where the | |
| # export will run. The default is to use the thread currently | |
| # associated with the block node. (since: 5.2; multi-threading | |
| # since 10.1) | |
| # | |
| # @fixed-iothread: True prevents the block node from being moved to | |
| # another thread while the export is active. If true and | |
| # @iothread is given, export creation fails if the block node | |
| # cannot be moved to the iothread. Must not be true when giving | |
| # multiple iothreads for @iothread. The default is false. | |
| # (since: 5.2) | |
| # | |
| # @allow-inactive: If true, the export allows the exported node to be | |
| # inactive. If it is created for an inactive block node, the node | |
| # remains inactive. If the export type doesn't support running on | |
| # an inactive node, an error is returned. If false, inactive | |
| # block nodes are automatically activated before creating the | |
| # export and trying to inactivate them later fails. | |
| # (since: 10.0; default: false) | |
| # | |
| # Since: 4.2 | |
| ## | |
| { 'union': 'BlockExportOptions', | |
| 'base': { 'type': 'BlockExportType', | |
| 'id': 'str', | |
| '*fixed-iothread': 'bool', | |
| '*iothread': 'BlockExportIothreads', | |
| 'node-name': 'str', | |
| '*writable': 'bool', | |
| '*writethrough': 'bool', | |
| '*allow-inactive': 'bool' }, | |
| 'discriminator': 'type', | |
| 'data': { | |
| 'nbd': 'BlockExportOptionsNbd', | |
| 'vhost-user-blk': { 'type': 'BlockExportOptionsVhostUserBlk', | |
| 'if': 'CONFIG_VHOST_USER_BLK_SERVER' }, | |
| 'fuse': { 'type': 'BlockExportOptionsFuse', | |
| 'if': 'CONFIG_FUSE' }, | |
| 'vduse-blk': { 'type': 'BlockExportOptionsVduseBlk', | |
| 'if': 'CONFIG_VDUSE_BLK_EXPORT' } | |
| } } | |
| ## | |
| # @BlockExportIothreads: | |
| # Specify a single or multiple I/O threads in which to run a block | |
| # export's I/O. | |
| # | |
| # @single: Run the export's I/O in the given single I/O thread. | |
| # | |
| # @multi: Use multi-threading across the given set of I/O threads, | |
| # which must not be empty. Note: Passing a single I/O thread via | |
| # this variant is still treated as multi-threading, which is | |
| # different from using the @single variant. In particular, even | |
| # if there only is a single I/O thread in the set, export types | |
| # that do not support multi-threading will generally reject this | |
| # variant, and BlockExportOptions.fixed-iothread is always | |
| # incompatible with it. | |
| # | |
| # Since: 10.1 | |
| ## | |
| { 'alternate': 'BlockExportIothreads', | |
| 'data': { | |
| 'single': 'str', | |
| 'multi': ['str'] } } | |
| ## | |
| # @block-export-add: | |
| # Creates a new block export. | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'command': 'block-export-add', | |
| 'data': 'BlockExportOptions', 'boxed': true, | |
| 'allow-preconfig': true } | |
| ## | |
| # @block-export-del: | |
| # Request to remove a block export. This drops the user's | |
| # reference to the export, but the export may still stay around | |
| # after this command returns until the shutdown of the export has | |
| # completed. | |
| # | |
| # @id: Block export id. | |
| # | |
| # @mode: Mode of command operation. See `BlockExportRemoveMode` | |
| # description. Default is 'safe'. | |
| # | |
| # Errors: | |
| # - if the export is not found | |
| # - if @mode is 'safe' and the export is still in use (e.g. by | |
| # existing client connections) | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'command': 'block-export-del', | |
| 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' }, | |
| 'allow-preconfig': true } | |
| ## | |
| # @BLOCK_EXPORT_DELETED: | |
| # Emitted when a block export is removed and its id can be reused. | |
| # | |
| # @id: Block export id. | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'event': 'BLOCK_EXPORT_DELETED', | |
| 'data': { 'id': 'str' } } | |
| ## | |
| # @BlockExportInfo: | |
| # Information about a single block export. | |
| # | |
| # @id: The unique identifier for the block export | |
| # | |
| # @type: The block export type | |
| # | |
| # @node-name: The node name of the block node that is exported | |
| # | |
| # @shutting-down: True if the export is shutting down (e.g. after a | |
| # `block-export-del` command, but before the shutdown has | |
| # completed) | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'struct': 'BlockExportInfo', | |
| 'data': { 'id': 'str', | |
| 'type': 'BlockExportType', | |
| 'node-name': 'str', | |
| 'shutting-down': 'bool' } } | |
| ## | |
| # @query-block-exports: | |
| # | |
| # Returns: A list describing all block exports | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'], | |
| 'allow-preconfig': true } |