diff options
Diffstat (limited to 'qapi/block-export.json')
| -rw-r--r-- | qapi/block-export.json | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/qapi/block-export.json b/qapi/block-export.json new file mode 100644 index 0000000000..b21b8e3f4d --- /dev/null +++ b/qapi/block-export.json @@ -0,0 +1,174 @@ +# -*- Mode: Python -*- +# vim: filetype=python + +## +# == Block device exports +## + +{ 'include': 'sockets.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). +# +# Since: 4.2 +## +{ 'struct': 'NbdServerOptions', + 'data': { 'addr': 'SocketAddress', + '*tls-creds': 'str', + '*tls-authz': 'str'} } + +## +# @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). +# +# Returns: error if the server is already running. +# +# Since: 1.3.0 +## +{ 'command': 'nbd-server-start', + 'data': { 'addr': 'SocketAddressLegacy', + '*tls-creds': 'str', + '*tls-authz': 'str'} } + +## +# @BlockExportNbd: +# +# An NBD block export. +# +# @device: The device name or node name of the node to be exported +# +# @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) +# +# @writable: Whether clients should be able to write to the device via the +# NBD connection (default false). +# +# @bitmap: Also export the dirty bitmap reachable from @device, so the +# NBD client can use NBD_OPT_SET_META_CONTEXT with +# "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0) +# +# Since: 5.0 +## +{ 'struct': 'BlockExportNbd', + 'data': {'device': 'str', '*name': 'str', '*description': 'str', + '*writable': 'bool', '*bitmap': 'str' } } + +## +# @nbd-server-add: +# +# Export a block node to QEMU's embedded NBD server. +# +# Returns: error if the server is not running, or export with the same name +# already exists. +# +# Since: 1.3.0 +## +{ 'command': 'nbd-server-add', + 'data': 'BlockExportNbd', 'boxed': true } + +## +# @NbdServerRemoveMode: +# +# Mode for removing an NBD 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': 'NbdServerRemoveMode', 'data': ['safe', 'hard']} + +## +# @nbd-server-remove: +# +# Remove NBD export by name. +# +# @name: Export name. +# +# @mode: Mode of command operation. See @NbdServerRemoveMode description. +# Default is 'safe'. +# +# 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': 'NbdServerRemoveMode'} } + +## +# @nbd-server-stop: +# +# Stop QEMU's embedded NBD server, and unregister all devices previously +# added via @nbd-server-add. +# +# Since: 1.3.0 +## +{ 'command': 'nbd-server-stop' } + +## +# @BlockExportType: +# +# An enumeration of block export types +# +# @nbd: NBD export +# +# Since: 4.2 +## +{ 'enum': 'BlockExportType', + 'data': [ 'nbd' ] } + +## +# @BlockExport: +# +# Describes a block export, i.e. how single node should be exported on an +# external interface. +# +# Since: 4.2 +## +{ 'union': 'BlockExport', + 'base': { 'type': 'BlockExportType' }, + 'discriminator': 'type', + 'data': { + 'nbd': 'BlockExportNbd' + } } |