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# @max-connections: The maximum number of connections to allow at the same 24# time, 0 for unlimited. (since 5.2; default: 0) 25# 26# Since: 4.2 27## 28{ 'struct': 'NbdServerOptions', 29 'data': { 'addr': 'SocketAddress', 30 '*tls-creds': 'str', 31 '*tls-authz': 'str', 32 '*max-connections': 'uint32' } } 33 34## 35# @nbd-server-start: 36# 37# Start an NBD server listening on the given host and port. Block 38# devices can then be exported using @nbd-server-add. The NBD 39# server will present them as named exports; for example, another 40# QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME". 41# 42# Keep this type consistent with the NbdServerOptions type. The only intended 43# difference is using SocketAddressLegacy instead of SocketAddress. 44# 45# @addr: Address on which to listen. 46# @tls-creds: ID of the TLS credentials object (since 2.6). 47# @tls-authz: ID of the QAuthZ authorization object used to validate 48# the client's x509 distinguished name. This object is 49# is only resolved at time of use, so can be deleted and 50# recreated on the fly while the NBD server is active. 51# If missing, it will default to denying access (since 4.0). 52# @max-connections: The maximum number of connections to allow at the same 53# time, 0 for unlimited. (since 5.2; default: 0) 54# 55# Returns: error if the server is already running. 56# 57# Since: 1.3.0 58## 59{ 'command': 'nbd-server-start', 60 'data': { 'addr': 'SocketAddressLegacy', 61 '*tls-creds': 'str', 62 '*tls-authz': 'str', 63 '*max-connections': 'uint32' } } 64 65## 66# @BlockExportOptionsNbd: 67# 68# An NBD block export (options shared between nbd-server-add and the NBD branch 69# of block-export-add). 70# 71# @name: Export name. If unspecified, the @device parameter is used as the 72# export name. (Since 2.12) 73# 74# @description: Free-form description of the export, up to 4096 bytes. 75# (Since 5.0) 76# 77# @writable: Whether clients should be able to write to the device via the 78# NBD connection (default false). 79# 80# @bitmap: Also export the dirty bitmap reachable from @device, so the 81# NBD client can use NBD_OPT_SET_META_CONTEXT with 82# "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0) 83# 84# Since: 5.0 85## 86{ 'struct': 'BlockExportOptionsNbd', 87 'data': { '*name': 'str', '*description': 'str', 88 '*writable': 'bool', '*bitmap': 'str' } } 89 90## 91# @NbdServerAddOptions: 92# 93# An NBD block export. 94# 95# @device: The device name or node name of the node to be exported 96# 97# Since: 5.0 98## 99{ 'struct': 'NbdServerAddOptions', 100 'base': 'BlockExportOptionsNbd', 101 'data': { 'device': 'str' } } 102 103## 104# @nbd-server-add: 105# 106# Export a block node to QEMU's embedded NBD server. 107# 108# The export name will be used as the id for the resulting block export. 109# 110# Returns: error if the server is not running, or export with the same name 111# already exists. 112# 113# Since: 1.3.0 114## 115{ 'command': 'nbd-server-add', 116 'data': 'NbdServerAddOptions', 'boxed': true } 117 118## 119# @BlockExportRemoveMode: 120# 121# Mode for removing a block export. 122# 123# @safe: Remove export if there are no existing connections, fail otherwise. 124# 125# @hard: Drop all connections immediately and remove export. 126# 127# Potential additional modes to be added in the future: 128# 129# hide: Just hide export from new clients, leave existing connections as is. 130# Remove export after all clients are disconnected. 131# 132# soft: Hide export from new clients, answer with ESHUTDOWN for all further 133# requests from existing clients. 134# 135# Since: 2.12 136## 137{'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']} 138 139## 140# @nbd-server-remove: 141# 142# Remove NBD export by name. 143# 144# @name: Block export id. 145# 146# @mode: Mode of command operation. See @BlockExportRemoveMode description. 147# Default is 'safe'. 148# 149# Returns: error if 150# - the server is not running 151# - export is not found 152# - mode is 'safe' and there are existing connections 153# 154# Since: 2.12 155## 156{ 'command': 'nbd-server-remove', 157 'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'} } 158 159## 160# @nbd-server-stop: 161# 162# Stop QEMU's embedded NBD server, and unregister all devices previously 163# added via @nbd-server-add. 164# 165# Since: 1.3.0 166## 167{ 'command': 'nbd-server-stop' } 168 169## 170# @BlockExportType: 171# 172# An enumeration of block export types 173# 174# @nbd: NBD export 175# 176# Since: 4.2 177## 178{ 'enum': 'BlockExportType', 179 'data': [ 'nbd' ] } 180 181## 182# @BlockExportOptions: 183# 184# Describes a block export, i.e. how single node should be exported on an 185# external interface. 186# 187# @id: A unique identifier for the block export (across all export types) 188# 189# @node-name: The node name of the block node to be exported (since: 5.2) 190# 191# @writethrough: If true, caches are flushed after every write request to the 192# export before completion is signalled. (since: 5.2; 193# default: false) 194# 195# Since: 4.2 196## 197{ 'union': 'BlockExportOptions', 198 'base': { 'type': 'BlockExportType', 199 'id': 'str', 200 'node-name': 'str', 201 '*writethrough': 'bool' }, 202 'discriminator': 'type', 203 'data': { 204 'nbd': 'BlockExportOptionsNbd' 205 } } 206 207## 208# @block-export-add: 209# 210# Creates a new block export. 211# 212# Since: 5.2 213## 214{ 'command': 'block-export-add', 215 'data': 'BlockExportOptions', 'boxed': true } 216 217## 218# @block-export-del: 219# 220# Request to remove a block export. This drops the user's reference to the 221# export, but the export may still stay around after this command returns until 222# the shutdown of the export has completed. 223# 224# @id: Block export id. 225# 226# @mode: Mode of command operation. See @BlockExportRemoveMode description. 227# Default is 'safe'. 228# 229# Returns: Error if the export is not found or @mode is 'safe' and the export 230# is still in use (e.g. by existing client connections) 231# 232# Since: 5.2 233## 234{ 'command': 'block-export-del', 235 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } } 236 237## 238# @BLOCK_EXPORT_DELETED: 239# 240# Emitted when a block export is removed and its id can be reused. 241# 242# @id: Block export id. 243# 244# Since: 5.2 245## 246{ 'event': 'BLOCK_EXPORT_DELETED', 247 'data': { 'id': 'str' } } 248