1# -*- Mode: Python -*- 2# vim: filetype=python 3 4## 5# == Block device exports 6## 7 8{ 'include': 'sockets.json' } 9 10## 11# @NbdServerOptions: 12# 13# Keep this type consistent with the nbd-server-start arguments. The only 14# intended difference is using SocketAddress instead of SocketAddressLegacy. 15# 16# @addr: Address on which to listen. 17# @tls-creds: ID of the TLS credentials object (since 2.6). 18# @tls-authz: ID of the QAuthZ authorization object used to validate 19# the client's x509 distinguished name. This object is 20# is only resolved at time of use, so can be deleted and 21# recreated on the fly while the NBD server is active. 22# If missing, it will default to denying access (since 4.0). 23# 24# Since: 4.2 25## 26{ 'struct': 'NbdServerOptions', 27 'data': { 'addr': 'SocketAddress', 28 '*tls-creds': 'str', 29 '*tls-authz': 'str'} } 30 31## 32# @nbd-server-start: 33# 34# Start an NBD server listening on the given host and port. Block 35# devices can then be exported using @nbd-server-add. The NBD 36# server will present them as named exports; for example, another 37# QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME". 38# 39# Keep this type consistent with the NbdServerOptions type. The only intended 40# difference is using SocketAddressLegacy instead of SocketAddress. 41# 42# @addr: Address on which to listen. 43# @tls-creds: ID of the TLS credentials object (since 2.6). 44# @tls-authz: ID of the QAuthZ authorization object used to validate 45# the client's x509 distinguished name. This object is 46# is only resolved at time of use, so can be deleted and 47# recreated on the fly while the NBD server is active. 48# If missing, it will default to denying access (since 4.0). 49# 50# Returns: error if the server is already running. 51# 52# Since: 1.3.0 53## 54{ 'command': 'nbd-server-start', 55 'data': { 'addr': 'SocketAddressLegacy', 56 '*tls-creds': 'str', 57 '*tls-authz': 'str'} } 58 59## 60# @BlockExportOptionsNbd: 61# 62# An NBD block export. 63# 64# @device: The device name or node name of the node to be exported 65# 66# @name: Export name. If unspecified, the @device parameter is used as the 67# export name. (Since 2.12) 68# 69# @description: Free-form description of the export, up to 4096 bytes. 70# (Since 5.0) 71# 72# @writable: Whether clients should be able to write to the device via the 73# NBD connection (default false). 74# 75# @bitmap: Also export the dirty bitmap reachable from @device, so the 76# NBD client can use NBD_OPT_SET_META_CONTEXT with 77# "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0) 78# 79# Since: 5.0 80## 81{ 'struct': 'BlockExportOptionsNbd', 82 'data': {'device': 'str', '*name': 'str', '*description': 'str', 83 '*writable': 'bool', '*bitmap': 'str' } } 84 85## 86# @nbd-server-add: 87# 88# Export a block node to QEMU's embedded NBD server. 89# 90# Returns: error if the server is not running, or export with the same name 91# already exists. 92# 93# Since: 1.3.0 94## 95{ 'command': 'nbd-server-add', 96 'data': 'BlockExportOptionsNbd', 'boxed': true } 97 98## 99# @NbdServerRemoveMode: 100# 101# Mode for removing an NBD export. 102# 103# @safe: Remove export if there are no existing connections, fail otherwise. 104# 105# @hard: Drop all connections immediately and remove export. 106# 107# Potential additional modes to be added in the future: 108# 109# hide: Just hide export from new clients, leave existing connections as is. 110# Remove export after all clients are disconnected. 111# 112# soft: Hide export from new clients, answer with ESHUTDOWN for all further 113# requests from existing clients. 114# 115# Since: 2.12 116## 117{'enum': 'NbdServerRemoveMode', 'data': ['safe', 'hard']} 118 119## 120# @nbd-server-remove: 121# 122# Remove NBD export by name. 123# 124# @name: Export name. 125# 126# @mode: Mode of command operation. See @NbdServerRemoveMode description. 127# Default is 'safe'. 128# 129# Returns: error if 130# - the server is not running 131# - export is not found 132# - mode is 'safe' and there are existing connections 133# 134# Since: 2.12 135## 136{ 'command': 'nbd-server-remove', 137 'data': {'name': 'str', '*mode': 'NbdServerRemoveMode'} } 138 139## 140# @nbd-server-stop: 141# 142# Stop QEMU's embedded NBD server, and unregister all devices previously 143# added via @nbd-server-add. 144# 145# Since: 1.3.0 146## 147{ 'command': 'nbd-server-stop' } 148 149## 150# @BlockExportType: 151# 152# An enumeration of block export types 153# 154# @nbd: NBD export 155# 156# Since: 4.2 157## 158{ 'enum': 'BlockExportType', 159 'data': [ 'nbd' ] } 160 161## 162# @BlockExportOptions: 163# 164# Describes a block export, i.e. how single node should be exported on an 165# external interface. 166# 167# Since: 4.2 168## 169{ 'union': 'BlockExportOptions', 170 'base': { 'type': 'BlockExportType' }, 171 'discriminator': 'type', 172 'data': { 173 'nbd': 'BlockExportOptionsNbd' 174 } } 175