| blob | e819e70cac0d94674150fbe71f58eb127b7967cb |
1 # -*- Mode: Python -*-
2 # vim: filetype=python
4 ##
5 # == Block device exports
6 ##
8 { 'include': 'sockets.json' }
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' } }
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
58 ##
59 { 'command': 'nbd-server-start',
60 'data': { 'addr': 'SocketAddressLegacy',
61 '*tls-creds': 'str',
62 '*tls-authz': 'str',
63 '*max-connections': 'uint32' } }
65 ##
66 # @BlockExportOptionsNbdBase:
67 #
68 # An NBD block export (common options shared between nbd-server-add and
69 # the NBD branch 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 # Since: 5.0
78 ##
79 { 'struct': 'BlockExportOptionsNbdBase',
80 'data': { '*name': 'str', '*description': 'str' } }
82 ##
83 # @BlockExportOptionsNbd:
84 #
85 # An NBD block export (distinct options used in the NBD branch of
86 # block-export-add).
87 #
88 # @bitmaps: Also export each of the named dirty bitmaps reachable from
89 # @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
90 # the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
91 # each bitmap.
92 #
93 # @allocation-depth: Also export the allocation depth map for @device, so
94 # the NBD client can use NBD_OPT_SET_META_CONTEXT with
95 # the metadata context name "qemu:allocation-depth" to
96 # inspect allocation details. (since 5.2)
97 #
98 # Since: 5.2
99 ##
100 { 'struct': 'BlockExportOptionsNbd',
101 'base': 'BlockExportOptionsNbdBase',
102 'data': { '*bitmaps': ['str'], '*allocation-depth': 'bool' } }
104 ##
105 # @BlockExportOptionsVhostUserBlk:
106 #
107 # A vhost-user-blk block export.
108 #
109 # @addr: The vhost-user socket on which to listen. Both 'unix' and 'fd'
110 # SocketAddress types are supported. Passed fds must be UNIX domain
111 # sockets.
112 # @logical-block-size: Logical block size in bytes. Defaults to 512 bytes.
113 # @num-queues: Number of request virtqueues. Must be greater than 0. Defaults
114 # to 1.
115 #
116 # Since: 5.2
117 ##
118 { 'struct': 'BlockExportOptionsVhostUserBlk',
119 'data': { 'addr': 'SocketAddress',
120 '*logical-block-size': 'size',
121 '*num-queues': 'uint16'} }
123 ##
124 # @BlockExportOptionsFuse:
125 #
126 # Options for exporting a block graph node on some (file) mountpoint
127 # as a raw image.
128 #
129 # @mountpoint: Path on which to export the block device via FUSE.
130 # This must point to an existing regular file.
131 #
132 # @growable: Whether writes beyond the EOF should grow the block node
133 # accordingly. (default: false)
134 #
135 # Since: 6.0
136 ##
137 { 'struct': 'BlockExportOptionsFuse',
138 'data': { 'mountpoint': 'str',
139 '*growable': 'bool' },
140 'if': 'defined(CONFIG_FUSE)' }
142 ##
143 # @NbdServerAddOptions:
144 #
145 # An NBD block export, per legacy nbd-server-add command.
146 #
147 # @device: The device name or node name of the node to be exported
148 #
149 # @writable: Whether clients should be able to write to the device via the
150 # NBD connection (default false).
151 #
152 # @bitmap: Also export a single dirty bitmap reachable from @device, so the
153 # NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
154 # context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
155 # (since 4.0).
156 #
157 # Since: 5.0
158 ##
159 { 'struct': 'NbdServerAddOptions',
160 'base': 'BlockExportOptionsNbdBase',
161 'data': { 'device': 'str',
162 '*writable': 'bool', '*bitmap': 'str' } }
164 ##
165 # @nbd-server-add:
166 #
167 # Export a block node to QEMU's embedded NBD server.
168 #
169 # The export name will be used as the id for the resulting block export.
170 #
171 # Features:
172 # @deprecated: This command is deprecated. Use @block-export-add instead.
173 #
174 # Returns: error if the server is not running, or export with the same name
175 # already exists.
176 #
177 # Since: 1.3
178 ##
179 { 'command': 'nbd-server-add',
180 'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'] }
182 ##
183 # @BlockExportRemoveMode:
184 #
185 # Mode for removing a block export.
186 #
187 # @safe: Remove export if there are no existing connections, fail otherwise.
188 #
189 # @hard: Drop all connections immediately and remove export.
190 #
191 # Potential additional modes to be added in the future:
192 #
193 # hide: Just hide export from new clients, leave existing connections as is.
194 # Remove export after all clients are disconnected.
195 #
196 # soft: Hide export from new clients, answer with ESHUTDOWN for all further
197 # requests from existing clients.
198 #
199 # Since: 2.12
200 ##
201 {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']}
203 ##
204 # @nbd-server-remove:
205 #
206 # Remove NBD export by name.
207 #
208 # @name: Block export id.
209 #
210 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
211 # Default is 'safe'.
212 #
213 # Features:
214 # @deprecated: This command is deprecated. Use @block-export-del instead.
215 #
216 # Returns: error if
217 # - the server is not running
218 # - export is not found
219 # - mode is 'safe' and there are existing connections
220 #
221 # Since: 2.12
222 ##
223 { 'command': 'nbd-server-remove',
224 'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'},
225 'features': ['deprecated'] }
227 ##
228 # @nbd-server-stop:
229 #
230 # Stop QEMU's embedded NBD server, and unregister all devices previously
231 # added via @nbd-server-add.
232 #
233 # Since: 1.3
234 ##
235 { 'command': 'nbd-server-stop' }
237 ##
238 # @BlockExportType:
239 #
240 # An enumeration of block export types
241 #
242 # @nbd: NBD export
243 # @vhost-user-blk: vhost-user-blk export (since 5.2)
244 # @fuse: FUSE export (since: 6.0)
245 #
246 # Since: 4.2
247 ##
248 { 'enum': 'BlockExportType',
249 'data': [ 'nbd', 'vhost-user-blk',
250 { 'name': 'fuse', 'if': 'defined(CONFIG_FUSE)' } ] }
252 ##
253 # @BlockExportOptions:
254 #
255 # Describes a block export, i.e. how single node should be exported on an
256 # external interface.
257 #
258 # @id: A unique identifier for the block export (across all export types)
259 #
260 # @node-name: The node name of the block node to be exported (since: 5.2)
261 #
262 # @writable: True if clients should be able to write to the export
263 # (default false)
264 #
265 # @writethrough: If true, caches are flushed after every write request to the
266 # export before completion is signalled. (since: 5.2;
267 # default: false)
268 #
269 # @iothread: The name of the iothread object where the export will run. The
270 # default is to use the thread currently associated with the
271 # block node. (since: 5.2)
272 #
273 # @fixed-iothread: True prevents the block node from being moved to another
274 # thread while the export is active. If true and @iothread is
275 # given, export creation fails if the block node cannot be
276 # moved to the iothread. The default is false. (since: 5.2)
277 #
278 # Since: 4.2
279 ##
280 { 'union': 'BlockExportOptions',
281 'base': { 'type': 'BlockExportType',
282 'id': 'str',
283 '*fixed-iothread': 'bool',
284 '*iothread': 'str',
285 'node-name': 'str',
286 '*writable': 'bool',
287 '*writethrough': 'bool' },
288 'discriminator': 'type',
289 'data': {
290 'nbd': 'BlockExportOptionsNbd',
291 'vhost-user-blk': 'BlockExportOptionsVhostUserBlk',
292 'fuse': { 'type': 'BlockExportOptionsFuse',
293 'if': 'defined(CONFIG_FUSE)' }
294 } }
296 ##
297 # @block-export-add:
298 #
299 # Creates a new block export.
300 #
301 # Since: 5.2
302 ##
303 { 'command': 'block-export-add',
304 'data': 'BlockExportOptions', 'boxed': true }
306 ##
307 # @block-export-del:
308 #
309 # Request to remove a block export. This drops the user's reference to the
310 # export, but the export may still stay around after this command returns until
311 # the shutdown of the export has completed.
312 #
313 # @id: Block export id.
314 #
315 # @mode: Mode of command operation. See @BlockExportRemoveMode description.
316 # Default is 'safe'.
317 #
318 # Returns: Error if the export is not found or @mode is 'safe' and the export
319 # is still in use (e.g. by existing client connections)
320 #
321 # Since: 5.2
322 ##
323 { 'command': 'block-export-del',
324 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } }
326 ##
327 # @BLOCK_EXPORT_DELETED:
328 #
329 # Emitted when a block export is removed and its id can be reused.
330 #
331 # @id: Block export id.
332 #
333 # Since: 5.2
334 ##
335 { 'event': 'BLOCK_EXPORT_DELETED',
336 'data': { 'id': 'str' } }
338 ##
339 # @BlockExportInfo:
340 #
341 # Information about a single block export.
342 #
343 # @id: The unique identifier for the block export
344 #
345 # @type: The block export type
346 #
347 # @node-name: The node name of the block node that is exported
348 #
349 # @shutting-down: True if the export is shutting down (e.g. after a
350 # block-export-del command, but before the shutdown has
351 # completed)
352 #
353 # Since: 5.2
354 ##
355 { 'struct': 'BlockExportInfo',
356 'data': { 'id': 'str',
357 'type': 'BlockExportType',
358 'node-name': 'str',
359 'shutting-down': 'bool' } }
361 ##
362 # @query-block-exports:
363 #
364 # Returns: A list of BlockExportInfo describing all block exports
365 #
366 # Since: 5.2
367 ##
368 { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] }