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