qapi/block-export.json

   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 # @BlockExportNbd:
  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': 'BlockExportNbd',
  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': 'BlockExportNbd', '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 # @BlockExport:
 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': 'BlockExport',
 170   'base': { 'type': 'BlockExportType' },
 171   'discriminator': 'type',
 172   'data': {
 173       'nbd': 'BlockExportNbd'
 174    } }