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. 69# 70# @device: The device name or node name of the node to be exported 71# 72# @name: Export name. If unspecified, the @device parameter is used as the 73# export name. (Since 2.12) 74# 75# @description: Free-form description of the export, up to 4096 bytes. 76# (Since 5.0) 77# 78# @writable: Whether clients should be able to write to the device via the 79# NBD connection (default false). 80# 81# @bitmap: Also export the dirty bitmap reachable from @device, so the 82# NBD client can use NBD_OPT_SET_META_CONTEXT with 83# "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0) 84# 85# Since: 5.0 86## 87{ 'struct': 'BlockExportOptionsNbd', 88 'data': {'device': 'str', '*name': 'str', '*description': 'str', 89 '*writable': 'bool', '*bitmap': 'str' } } 90 91## 92# @nbd-server-add: 93# 94# Export a block node to QEMU's embedded NBD server. 95# 96# Returns: error if the server is not running, or export with the same name 97# already exists. 98# 99# Since: 1.3.0 100## 101{ 'command': 'nbd-server-add', 102 'data': 'BlockExportOptionsNbd', 'boxed': true } 103 104## 105# @NbdServerRemoveMode: 106# 107# Mode for removing an NBD export. 108# 109# @safe: Remove export if there are no existing connections, fail otherwise. 110# 111# @hard: Drop all connections immediately and remove export. 112# 113# Potential additional modes to be added in the future: 114# 115# hide: Just hide export from new clients, leave existing connections as is. 116# Remove export after all clients are disconnected. 117# 118# soft: Hide export from new clients, answer with ESHUTDOWN for all further 119# requests from existing clients. 120# 121# Since: 2.12 122## 123{'enum': 'NbdServerRemoveMode', 'data': ['safe', 'hard']} 124 125## 126# @nbd-server-remove: 127# 128# Remove NBD export by name. 129# 130# @name: Export name. 131# 132# @mode: Mode of command operation. See @NbdServerRemoveMode description. 133# Default is 'safe'. 134# 135# Returns: error if 136# - the server is not running 137# - export is not found 138# - mode is 'safe' and there are existing connections 139# 140# Since: 2.12 141## 142{ 'command': 'nbd-server-remove', 143 'data': {'name': 'str', '*mode': 'NbdServerRemoveMode'} } 144 145## 146# @nbd-server-stop: 147# 148# Stop QEMU's embedded NBD server, and unregister all devices previously 149# added via @nbd-server-add. 150# 151# Since: 1.3.0 152## 153{ 'command': 'nbd-server-stop' } 154 155## 156# @BlockExportType: 157# 158# An enumeration of block export types 159# 160# @nbd: NBD export 161# 162# Since: 4.2 163## 164{ 'enum': 'BlockExportType', 165 'data': [ 'nbd' ] } 166 167## 168# @BlockExportOptions: 169# 170# Describes a block export, i.e. how single node should be exported on an 171# external interface. 172# 173# @writethrough: If true, caches are flushed after every write request to the 174# export before completion is signalled. (since: 5.2; 175# default: false) 176# 177# Since: 4.2 178## 179{ 'union': 'BlockExportOptions', 180 'base': { 'type': 'BlockExportType', 181 '*writethrough': 'bool' }, 182 'discriminator': 'type', 183 'data': { 184 'nbd': 'BlockExportOptionsNbd' 185 } } 186 187## 188# @block-export-add: 189# 190# Creates a new block export. 191# 192# Since: 5.2 193## 194{ 'command': 'block-export-add', 195 'data': 'BlockExportOptions', 'boxed': true } 196