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# @bitmap: Also export the dirty bitmap reachable from @device, so the 78# NBD client can use NBD_OPT_SET_META_CONTEXT with 79# "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0) 80# 81# Since: 5.0 82## 83{ 'struct': 'BlockExportOptionsNbd', 84 'data': { '*name': 'str', '*description': 'str', 85 '*bitmap': 'str' } } 86 87## 88# @NbdServerAddOptions: 89# 90# An NBD block export. 91# 92# @device: The device name or node name of the node to be exported 93# 94# @writable: Whether clients should be able to write to the device via the 95# NBD connection (default false). 96# 97# Since: 5.0 98## 99{ 'struct': 'NbdServerAddOptions', 100 'base': 'BlockExportOptionsNbd', 101 'data': { 'device': 'str', 102 '*writable': 'bool' } } 103 104## 105# @nbd-server-add: 106# 107# Export a block node to QEMU's embedded NBD server. 108# 109# The export name will be used as the id for the resulting block export. 110# 111# Returns: error if the server is not running, or export with the same name 112# already exists. 113# 114# Since: 1.3.0 115## 116{ 'command': 'nbd-server-add', 117 'data': 'NbdServerAddOptions', 'boxed': true } 118 119## 120# @BlockExportRemoveMode: 121# 122# Mode for removing a block export. 123# 124# @safe: Remove export if there are no existing connections, fail otherwise. 125# 126# @hard: Drop all connections immediately and remove export. 127# 128# Potential additional modes to be added in the future: 129# 130# hide: Just hide export from new clients, leave existing connections as is. 131# Remove export after all clients are disconnected. 132# 133# soft: Hide export from new clients, answer with ESHUTDOWN for all further 134# requests from existing clients. 135# 136# Since: 2.12 137## 138{'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']} 139 140## 141# @nbd-server-remove: 142# 143# Remove NBD export by name. 144# 145# @name: Block export id. 146# 147# @mode: Mode of command operation. See @BlockExportRemoveMode description. 148# Default is 'safe'. 149# 150# Returns: error if 151# - the server is not running 152# - export is not found 153# - mode is 'safe' and there are existing connections 154# 155# Since: 2.12 156## 157{ 'command': 'nbd-server-remove', 158 'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'} } 159 160## 161# @nbd-server-stop: 162# 163# Stop QEMU's embedded NBD server, and unregister all devices previously 164# added via @nbd-server-add. 165# 166# Since: 1.3.0 167## 168{ 'command': 'nbd-server-stop' } 169 170## 171# @BlockExportType: 172# 173# An enumeration of block export types 174# 175# @nbd: NBD export 176# 177# Since: 4.2 178## 179{ 'enum': 'BlockExportType', 180 'data': [ 'nbd' ] } 181 182## 183# @BlockExportOptions: 184# 185# Describes a block export, i.e. how single node should be exported on an 186# external interface. 187# 188# @id: A unique identifier for the block export (across all export types) 189# 190# @node-name: The node name of the block node to be exported (since: 5.2) 191# 192# @writable: True if clients should be able to write to the export 193# (default false) 194# 195# @writethrough: If true, caches are flushed after every write request to the 196# export before completion is signalled. (since: 5.2; 197# default: false) 198# 199# Since: 4.2 200## 201{ 'union': 'BlockExportOptions', 202 'base': { 'type': 'BlockExportType', 203 'id': 'str', 204 'node-name': 'str', 205 '*writable': 'bool', 206 '*writethrough': 'bool' }, 207 'discriminator': 'type', 208 'data': { 209 'nbd': 'BlockExportOptionsNbd' 210 } } 211 212## 213# @block-export-add: 214# 215# Creates a new block export. 216# 217# Since: 5.2 218## 219{ 'command': 'block-export-add', 220 'data': 'BlockExportOptions', 'boxed': true } 221 222## 223# @block-export-del: 224# 225# Request to remove a block export. This drops the user's reference to the 226# export, but the export may still stay around after this command returns until 227# the shutdown of the export has completed. 228# 229# @id: Block export id. 230# 231# @mode: Mode of command operation. See @BlockExportRemoveMode description. 232# Default is 'safe'. 233# 234# Returns: Error if the export is not found or @mode is 'safe' and the export 235# is still in use (e.g. by existing client connections) 236# 237# Since: 5.2 238## 239{ 'command': 'block-export-del', 240 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } } 241 242## 243# @BLOCK_EXPORT_DELETED: 244# 245# Emitted when a block export is removed and its id can be reused. 246# 247# @id: Block export id. 248# 249# Since: 5.2 250## 251{ 'event': 'BLOCK_EXPORT_DELETED', 252 'data': { 'id': 'str' } } 253 254## 255# @BlockExportInfo: 256# 257# Information about a single block export. 258# 259# @id: The unique identifier for the block export 260# 261# @type: The block export type 262# 263# @node-name: The node name of the block node that is exported 264# 265# @shutting-down: True if the export is shutting down (e.g. after a 266# block-export-del command, but before the shutdown has 267# completed) 268# 269# Since: 5.2 270## 271{ 'struct': 'BlockExportInfo', 272 'data': { 'id': 'str', 273 'type': 'BlockExportType', 274 'node-name': 'str', 275 'shutting-down': 'bool' } } 276 277## 278# @query-block-exports: 279# 280# Returns: A list of BlockExportInfo describing all block exports 281# 282# Since: 5.2 283## 284{ 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] } 285