| # -*- Mode: Python -*- | |
| # vim: filetype=python | |
| ## | |
| # == Block device exports | |
| ## | |
| { 'include': 'sockets.json' } | |
| { 'include': 'block-core.json' } | |
| ## | |
| # @NbdServerOptions: | |
| # | |
| # Keep this type consistent with the nbd-server-start arguments. The | |
| # only intended difference is using SocketAddress instead of | |
| # SocketAddressLegacy. | |
| # | |
| # @addr: Address on which to listen. | |
| # | |
| # @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: 0) | |
| # | |
| # Since: 4.2 | |
| ## | |
| { 'struct': 'NbdServerOptions', | |
| 'data': { 'addr': 'SocketAddress', | |
| '*tls-creds': 'str', | |
| '*tls-authz': 'str', | |
| '*max-connections': 'uint32' } } | |
| ## | |
| # @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". | |
| # | |
| # Keep this type consistent with the NbdServerOptions type. The only | |
| # intended difference is using SocketAddressLegacy instead of | |
| # SocketAddress. | |
| # | |
| # @addr: Address on which to listen. | |
| # | |
| # @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: 0). | |
| # | |
| # Returns: error if the server is already running. | |
| # | |
| # Since: 1.3 | |
| ## | |
| { 'command': 'nbd-server-start', | |
| 'data': { 'addr': 'SocketAddressLegacy', | |
| '*tls-creds': 'str', | |
| '*tls-authz': 'str', | |
| '*max-connections': 'uint32' }, | |
| '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. | |
| # | |
| # @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. | |
| # | |
| # Returns: error if the server is not running, or 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. | |
| # | |
| # 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. | |
| # | |
| # Returns: error if | |
| # | |
| # - the server is not running | |
| # - export is not found | |
| # - 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. | |
| # | |
| # @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 of the iothread object where the export will | |
| # run. The default is to use the thread currently associated with | |
| # the block node. (since: 5.2) | |
| # | |
| # @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. The default is false. | |
| # (since: 5.2) | |
| # | |
| # Since: 4.2 | |
| ## | |
| { 'union': 'BlockExportOptions', | |
| 'base': { 'type': 'BlockExportType', | |
| 'id': 'str', | |
| '*fixed-iothread': 'bool', | |
| '*iothread': 'str', | |
| 'node-name': 'str', | |
| '*writable': 'bool', | |
| '*writethrough': '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' } | |
| } } | |
| ## | |
| # @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'. | |
| # | |
| # Returns: Error if the export is not found or @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 of BlockExportInfo describing all block exports | |
| # | |
| # Since: 5.2 | |
| ## | |
| { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'], | |
| 'allow-preconfig': true } |