]>
Commit | Line | Data |
---|---|---|
5daa6bfd KW |
1 | # -*- Mode: Python -*- |
2 | # vim: filetype=python | |
3 | ||
4 | ## | |
5 | # == Block device exports | |
6 | ## | |
7 | ||
8 | { 'include': 'sockets.json' } | |
e5fb29d5 | 9 | { 'include': 'block-core.json' } |
5daa6bfd KW |
10 | |
11 | ## | |
12 | # @NbdServerOptions: | |
13 | # | |
a937b6aa MA |
14 | # Keep this type consistent with the nbd-server-start arguments. The |
15 | # only intended difference is using SocketAddress instead of | |
16 | # SocketAddressLegacy. | |
5daa6bfd KW |
17 | # |
18 | # @addr: Address on which to listen. | |
a937b6aa | 19 | # |
5daa6bfd | 20 | # @tls-creds: ID of the TLS credentials object (since 2.6). |
a937b6aa | 21 | # |
5daa6bfd | 22 | # @tls-authz: ID of the QAuthZ authorization object used to validate |
a937b6aa MA |
23 | # the client's x509 distinguished name. This object is is only |
24 | # resolved at time of use, so can be deleted and recreated on the | |
25 | # fly while the NBD server is active. If missing, it will default | |
26 | # to denying access (since 4.0). | |
27 | # | |
28 | # @max-connections: The maximum number of connections to allow at the | |
29 | # same time, 0 for unlimited. Setting this to 1 also stops the | |
30 | # server from advertising multiple client support (since 5.2; | |
31 | # default: 0) | |
5daa6bfd KW |
32 | # |
33 | # Since: 4.2 | |
34 | ## | |
35 | { 'struct': 'NbdServerOptions', | |
36 | 'data': { 'addr': 'SocketAddress', | |
37 | '*tls-creds': 'str', | |
1c8222b0 KW |
38 | '*tls-authz': 'str', |
39 | '*max-connections': 'uint32' } } | |
5daa6bfd KW |
40 | |
41 | ## | |
42 | # @nbd-server-start: | |
43 | # | |
44 | # Start an NBD server listening on the given host and port. Block | |
a937b6aa MA |
45 | # devices can then be exported using @nbd-server-add. The NBD server |
46 | # will present them as named exports; for example, another QEMU | |
47 | # instance could refer to them as "nbd:HOST:PORT:exportname=NAME". | |
5daa6bfd | 48 | # |
a937b6aa MA |
49 | # Keep this type consistent with the NbdServerOptions type. The only |
50 | # intended difference is using SocketAddressLegacy instead of | |
51 | # SocketAddress. | |
5daa6bfd KW |
52 | # |
53 | # @addr: Address on which to listen. | |
a937b6aa | 54 | # |
5daa6bfd | 55 | # @tls-creds: ID of the TLS credentials object (since 2.6). |
a937b6aa | 56 | # |
5daa6bfd | 57 | # @tls-authz: ID of the QAuthZ authorization object used to validate |
a937b6aa MA |
58 | # the client's x509 distinguished name. This object is is only |
59 | # resolved at time of use, so can be deleted and recreated on the | |
60 | # fly while the NBD server is active. If missing, it will default | |
61 | # to denying access (since 4.0). | |
62 | # | |
63 | # @max-connections: The maximum number of connections to allow at the | |
64 | # same time, 0 for unlimited. Setting this to 1 also stops the | |
65 | # server from advertising multiple client support (since 5.2; | |
66 | # default: 0). | |
5daa6bfd KW |
67 | # |
68 | # Returns: error if the server is already running. | |
69 | # | |
9bc6e893 | 70 | # Since: 1.3 |
5daa6bfd KW |
71 | ## |
72 | { 'command': 'nbd-server-start', | |
73 | 'data': { 'addr': 'SocketAddressLegacy', | |
74 | '*tls-creds': 'str', | |
1c8222b0 | 75 | '*tls-authz': 'str', |
f55ba801 PB |
76 | '*max-connections': 'uint32' }, |
77 | 'allow-preconfig': true } | |
5daa6bfd KW |
78 | |
79 | ## | |
cbad81ce | 80 | # @BlockExportOptionsNbdBase: |
5daa6bfd | 81 | # |
a937b6aa MA |
82 | # An NBD block export (common options shared between nbd-server-add |
83 | # and the NBD branch of block-export-add). | |
5daa6bfd | 84 | # |
a937b6aa MA |
85 | # @name: Export name. If unspecified, the @device parameter is used |
86 | # as the export name. (Since 2.12) | |
5daa6bfd KW |
87 | # |
88 | # @description: Free-form description of the export, up to 4096 bytes. | |
a937b6aa | 89 | # (Since 5.0) |
5daa6bfd | 90 | # |
5daa6bfd KW |
91 | # Since: 5.0 |
92 | ## | |
cbad81ce EB |
93 | { 'struct': 'BlockExportOptionsNbdBase', |
94 | 'data': { '*name': 'str', '*description': 'str' } } | |
95 | ||
96 | ## | |
97 | # @BlockExportOptionsNbd: | |
98 | # | |
99 | # An NBD block export (distinct options used in the NBD branch of | |
100 | # block-export-add). | |
101 | # | |
102 | # @bitmaps: Also export each of the named dirty bitmaps reachable from | |
a937b6aa MA |
103 | # @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with |
104 | # the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect | |
105 | # each bitmap. Since 7.1 bitmap may be specified by node/name | |
106 | # pair. | |
cbad81ce | 107 | # |
a937b6aa MA |
108 | # @allocation-depth: Also export the allocation depth map for @device, |
109 | # so the NBD client can use NBD_OPT_SET_META_CONTEXT with the | |
110 | # metadata context name "qemu:allocation-depth" to inspect | |
111 | # allocation details. (since 5.2) | |
dbc7b014 | 112 | # |
cbad81ce EB |
113 | # Since: 5.2 |
114 | ## | |
143ea767 | 115 | { 'struct': 'BlockExportOptionsNbd', |
cbad81ce | 116 | 'base': 'BlockExportOptionsNbdBase', |
e5fb29d5 VSO |
117 | 'data': { '*bitmaps': ['BlockDirtyBitmapOrStr'], |
118 | '*allocation-depth': 'bool' } } | |
b6076afc | 119 | |
90fc91d5 SH |
120 | ## |
121 | # @BlockExportOptionsVhostUserBlk: | |
122 | # | |
123 | # A vhost-user-blk block export. | |
124 | # | |
a937b6aa MA |
125 | # @addr: The vhost-user socket on which to listen. Both 'unix' and |
126 | # 'fd' SocketAddress types are supported. Passed fds must be UNIX | |
127 | # domain sockets. | |
128 | # | |
129 | # @logical-block-size: Logical block size in bytes. Defaults to 512 | |
130 | # bytes. | |
131 | # | |
132 | # @num-queues: Number of request virtqueues. Must be greater than 0. | |
133 | # Defaults to 1. | |
90fc91d5 SH |
134 | # |
135 | # Since: 5.2 | |
136 | ## | |
137 | { 'struct': 'BlockExportOptionsVhostUserBlk', | |
d9b495f9 SH |
138 | 'data': { 'addr': 'SocketAddress', |
139 | '*logical-block-size': 'size', | |
140 | '*num-queues': 'uint16'} } | |
90fc91d5 | 141 | |
8fc54f94 HR |
142 | ## |
143 | # @FuseExportAllowOther: | |
144 | # | |
145 | # Possible allow_other modes for FUSE exports. | |
146 | # | |
147 | # @off: Do not pass allow_other as a mount option. | |
148 | # | |
149 | # @on: Pass allow_other as a mount option. | |
150 | # | |
151 | # @auto: Try mounting with allow_other first, and if that fails, retry | |
a937b6aa | 152 | # without allow_other. |
8fc54f94 HR |
153 | # |
154 | # Since: 6.1 | |
155 | ## | |
156 | { 'enum': 'FuseExportAllowOther', | |
157 | 'data': ['off', 'on', 'auto'] } | |
158 | ||
0c9b70d5 HR |
159 | ## |
160 | # @BlockExportOptionsFuse: | |
161 | # | |
162 | # Options for exporting a block graph node on some (file) mountpoint | |
163 | # as a raw image. | |
164 | # | |
a937b6aa MA |
165 | # @mountpoint: Path on which to export the block device via FUSE. This |
166 | # must point to an existing regular file. | |
0c9b70d5 | 167 | # |
4fba06d5 | 168 | # @growable: Whether writes beyond the EOF should grow the block node |
a937b6aa | 169 | # accordingly. (default: false) |
4fba06d5 | 170 | # |
8fc54f94 | 171 | # @allow-other: If this is off, only qemu's user is allowed access to |
a937b6aa MA |
172 | # this export. That cannot be changed even with chmod or chown. |
173 | # Enabling this option will allow other users access to the export | |
174 | # with the FUSE mount option "allow_other". Note that using | |
175 | # allow_other as a non-root user requires user_allow_other to be | |
176 | # enabled in the global fuse.conf configuration file. In auto | |
177 | # mode (the default), the FUSE export driver will first attempt to | |
178 | # mount the export with allow_other, and if that fails, try again | |
179 | # without. (since 6.1; default: auto) | |
8fc54f94 | 180 | # |
0c9b70d5 HR |
181 | # Since: 6.0 |
182 | ## | |
183 | { 'struct': 'BlockExportOptionsFuse', | |
4fba06d5 | 184 | 'data': { 'mountpoint': 'str', |
8fc54f94 HR |
185 | '*growable': 'bool', |
186 | '*allow-other': 'FuseExportAllowOther' }, | |
8a9f1e1d | 187 | 'if': 'CONFIG_FUSE' } |
0c9b70d5 | 188 | |
2a2359b8 XY |
189 | ## |
190 | # @BlockExportOptionsVduseBlk: | |
191 | # | |
192 | # A vduse-blk block export. | |
193 | # | |
779d82e1 | 194 | # @name: the name of VDUSE device (must be unique across the host). |
a937b6aa MA |
195 | # |
196 | # @num-queues: the number of virtqueues. Defaults to 1. | |
197 | # | |
198 | # @queue-size: the size of virtqueue. Defaults to 256. | |
199 | # | |
200 | # @logical-block-size: Logical block size in bytes. Range [512, | |
201 | # PAGE_SIZE] and must be power of 2. Defaults to 512 bytes. | |
202 | # | |
203 | # @serial: the serial number of virtio block device. Defaults to | |
204 | # empty string. | |
2a2359b8 XY |
205 | # |
206 | # Since: 7.1 | |
207 | ## | |
208 | { 'struct': 'BlockExportOptionsVduseBlk', | |
779d82e1 XY |
209 | 'data': { 'name': 'str', |
210 | '*num-queues': 'uint16', | |
2a2359b8 | 211 | '*queue-size': 'uint16', |
0862a087 XY |
212 | '*logical-block-size': 'size', |
213 | '*serial': 'str' } } | |
2a2359b8 | 214 | |
b6076afc KW |
215 | ## |
216 | # @NbdServerAddOptions: | |
217 | # | |
cbad81ce | 218 | # An NBD block export, per legacy nbd-server-add command. |
b6076afc KW |
219 | # |
220 | # @device: The device name or node name of the node to be exported | |
221 | # | |
a937b6aa MA |
222 | # @writable: Whether clients should be able to write to the device via |
223 | # the NBD connection (default false). | |
30dbc81d | 224 | # |
a937b6aa MA |
225 | # @bitmap: Also export a single dirty bitmap reachable from @device, |
226 | # so the NBD client can use NBD_OPT_SET_META_CONTEXT with the | |
227 | # metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the | |
228 | # bitmap (since 4.0). | |
cbad81ce | 229 | # |
b6076afc KW |
230 | # Since: 5.0 |
231 | ## | |
232 | { 'struct': 'NbdServerAddOptions', | |
cbad81ce | 233 | 'base': 'BlockExportOptionsNbdBase', |
30dbc81d | 234 | 'data': { 'device': 'str', |
cbad81ce | 235 | '*writable': 'bool', '*bitmap': 'str' } } |
5daa6bfd KW |
236 | |
237 | ## | |
238 | # @nbd-server-add: | |
239 | # | |
240 | # Export a block node to QEMU's embedded NBD server. | |
241 | # | |
a937b6aa MA |
242 | # The export name will be used as the id for the resulting block |
243 | # export. | |
d53be9ce | 244 | # |
443127e8 | 245 | # Features: |
443127e8 | 246 | # |
a937b6aa MA |
247 | # @deprecated: This command is deprecated. Use @block-export-add |
248 | # instead. | |
249 | # | |
250 | # Returns: error if the server is not running, or export with the same | |
251 | # name already exists. | |
5daa6bfd | 252 | # |
9bc6e893 | 253 | # Since: 1.3 |
5daa6bfd KW |
254 | ## |
255 | { 'command': 'nbd-server-add', | |
f55ba801 PB |
256 | 'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'], |
257 | 'allow-preconfig': true } | |
5daa6bfd KW |
258 | |
259 | ## | |
3c3bc462 | 260 | # @BlockExportRemoveMode: |
5daa6bfd | 261 | # |
3c3bc462 | 262 | # Mode for removing a block export. |
5daa6bfd | 263 | # |
a937b6aa MA |
264 | # @safe: Remove export if there are no existing connections, fail |
265 | # otherwise. | |
5daa6bfd KW |
266 | # |
267 | # @hard: Drop all connections immediately and remove export. | |
268 | # | |
b71fd73c | 269 | # Potential additional modes to be added in the future: |
5daa6bfd | 270 | # |
a937b6aa MA |
271 | # hide: Just hide export from new clients, leave existing connections |
272 | # as is. Remove export after all clients are disconnected. | |
5daa6bfd | 273 | # |
a937b6aa MA |
274 | # soft: Hide export from new clients, answer with ESHUTDOWN for all |
275 | # further requests from existing clients. | |
5daa6bfd KW |
276 | # |
277 | # Since: 2.12 | |
278 | ## | |
3c3bc462 | 279 | {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']} |
5daa6bfd KW |
280 | |
281 | ## | |
282 | # @nbd-server-remove: | |
283 | # | |
284 | # Remove NBD export by name. | |
285 | # | |
3c3bc462 | 286 | # @name: Block export id. |
5daa6bfd | 287 | # |
a937b6aa MA |
288 | # @mode: Mode of command operation. See @BlockExportRemoveMode |
289 | # description. Default is 'safe'. | |
5daa6bfd | 290 | # |
443127e8 | 291 | # Features: |
a937b6aa MA |
292 | # |
293 | # @deprecated: This command is deprecated. Use @block-export-del | |
294 | # instead. | |
443127e8 | 295 | # |
5daa6bfd | 296 | # Returns: error if |
c1101028 | 297 | # |
a937b6aa MA |
298 | # - the server is not running |
299 | # - export is not found | |
300 | # - mode is 'safe' and there are existing connections | |
5daa6bfd KW |
301 | # |
302 | # Since: 2.12 | |
303 | ## | |
304 | { 'command': 'nbd-server-remove', | |
443127e8 | 305 | 'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'}, |
f55ba801 PB |
306 | 'features': ['deprecated'], |
307 | 'allow-preconfig': true } | |
5daa6bfd KW |
308 | |
309 | ## | |
310 | # @nbd-server-stop: | |
311 | # | |
a937b6aa MA |
312 | # Stop QEMU's embedded NBD server, and unregister all devices |
313 | # previously added via @nbd-server-add. | |
5daa6bfd | 314 | # |
9bc6e893 | 315 | # Since: 1.3 |
5daa6bfd | 316 | ## |
f55ba801 PB |
317 | { 'command': 'nbd-server-stop', |
318 | 'allow-preconfig': true } | |
5daa6bfd KW |
319 | |
320 | ## | |
321 | # @BlockExportType: | |
322 | # | |
323 | # An enumeration of block export types | |
324 | # | |
325 | # @nbd: NBD export | |
a937b6aa | 326 | # |
90fc91d5 | 327 | # @vhost-user-blk: vhost-user-blk export (since 5.2) |
a937b6aa | 328 | # |
0c9b70d5 | 329 | # @fuse: FUSE export (since: 6.0) |
a937b6aa | 330 | # |
2a2359b8 | 331 | # @vduse-blk: vduse-blk export (since 7.1) |
5daa6bfd KW |
332 | # |
333 | # Since: 4.2 | |
334 | ## | |
335 | { 'enum': 'BlockExportType', | |
bb01ea73 | 336 | 'data': [ 'nbd', |
3a8fa0ed PMD |
337 | { 'name': 'vhost-user-blk', |
338 | 'if': 'CONFIG_VHOST_USER_BLK_SERVER' }, | |
2a2359b8 XY |
339 | { 'name': 'fuse', 'if': 'CONFIG_FUSE' }, |
340 | { 'name': 'vduse-blk', 'if': 'CONFIG_VDUSE_BLK_EXPORT' } ] } | |
5daa6bfd KW |
341 | |
342 | ## | |
143ea767 | 343 | # @BlockExportOptions: |
5daa6bfd | 344 | # |
a937b6aa MA |
345 | # Describes a block export, i.e. how single node should be exported on |
346 | # an external interface. | |
5daa6bfd | 347 | # |
a937b6aa MA |
348 | # @id: A unique identifier for the block export (across all export |
349 | # types) | |
d53be9ce | 350 | # |
a937b6aa MA |
351 | # @node-name: The node name of the block node to be exported |
352 | # (since: 5.2) | |
b6076afc | 353 | # |
30dbc81d | 354 | # @writable: True if clients should be able to write to the export |
a937b6aa | 355 | # (default false) |
30dbc81d | 356 | # |
a937b6aa MA |
357 | # @writethrough: If true, caches are flushed after every write request |
358 | # to the export before completion is signalled. (since: 5.2; | |
359 | # default: false) | |
fefee85d | 360 | # |
a937b6aa MA |
361 | # @iothread: The name of the iothread object where the export will |
362 | # run. The default is to use the thread currently associated with | |
363 | # the block node. (since: 5.2) | |
f51d23c8 | 364 | # |
a937b6aa MA |
365 | # @fixed-iothread: True prevents the block node from being moved to |
366 | # another thread while the export is active. If true and | |
367 | # @iothread is given, export creation fails if the block node | |
368 | # cannot be moved to the iothread. The default is false. | |
369 | # (since: 5.2) | |
f51d23c8 | 370 | # |
5daa6bfd KW |
371 | # Since: 4.2 |
372 | ## | |
143ea767 | 373 | { 'union': 'BlockExportOptions', |
fefee85d | 374 | 'base': { 'type': 'BlockExportType', |
d53be9ce | 375 | 'id': 'str', |
d9b495f9 SH |
376 | '*fixed-iothread': 'bool', |
377 | '*iothread': 'str', | |
b6076afc | 378 | 'node-name': 'str', |
30dbc81d | 379 | '*writable': 'bool', |
fefee85d | 380 | '*writethrough': 'bool' }, |
5daa6bfd KW |
381 | 'discriminator': 'type', |
382 | 'data': { | |
90fc91d5 | 383 | 'nbd': 'BlockExportOptionsNbd', |
bb01ea73 PMD |
384 | 'vhost-user-blk': { 'type': 'BlockExportOptionsVhostUserBlk', |
385 | 'if': 'CONFIG_VHOST_USER_BLK_SERVER' }, | |
0c9b70d5 | 386 | 'fuse': { 'type': 'BlockExportOptionsFuse', |
2a2359b8 XY |
387 | 'if': 'CONFIG_FUSE' }, |
388 | 'vduse-blk': { 'type': 'BlockExportOptionsVduseBlk', | |
389 | 'if': 'CONFIG_VDUSE_BLK_EXPORT' } | |
5daa6bfd | 390 | } } |
56ee8626 KW |
391 | |
392 | ## | |
393 | # @block-export-add: | |
394 | # | |
395 | # Creates a new block export. | |
396 | # | |
397 | # Since: 5.2 | |
398 | ## | |
399 | { 'command': 'block-export-add', | |
f55ba801 PB |
400 | 'data': 'BlockExportOptions', 'boxed': true, |
401 | 'allow-preconfig': true } | |
3c3bc462 KW |
402 | |
403 | ## | |
404 | # @block-export-del: | |
405 | # | |
a937b6aa MA |
406 | # Request to remove a block export. This drops the user's reference |
407 | # to the export, but the export may still stay around after this | |
408 | # command returns until the shutdown of the export has completed. | |
3c3bc462 KW |
409 | # |
410 | # @id: Block export id. | |
411 | # | |
a937b6aa MA |
412 | # @mode: Mode of command operation. See @BlockExportRemoveMode |
413 | # description. Default is 'safe'. | |
3c3bc462 | 414 | # |
a937b6aa MA |
415 | # Returns: Error if the export is not found or @mode is 'safe' and the |
416 | # export is still in use (e.g. by existing client connections) | |
3c3bc462 KW |
417 | # |
418 | # Since: 5.2 | |
419 | ## | |
420 | { 'command': 'block-export-del', | |
f55ba801 PB |
421 | 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' }, |
422 | 'allow-preconfig': true } | |
1a9f7a80 KW |
423 | |
424 | ## | |
425 | # @BLOCK_EXPORT_DELETED: | |
426 | # | |
427 | # Emitted when a block export is removed and its id can be reused. | |
428 | # | |
429 | # @id: Block export id. | |
430 | # | |
431 | # Since: 5.2 | |
432 | ## | |
433 | { 'event': 'BLOCK_EXPORT_DELETED', | |
434 | 'data': { 'id': 'str' } } | |
8cade320 KW |
435 | |
436 | ## | |
437 | # @BlockExportInfo: | |
438 | # | |
439 | # Information about a single block export. | |
440 | # | |
441 | # @id: The unique identifier for the block export | |
442 | # | |
443 | # @type: The block export type | |
444 | # | |
445 | # @node-name: The node name of the block node that is exported | |
446 | # | |
447 | # @shutting-down: True if the export is shutting down (e.g. after a | |
a937b6aa | 448 | # block-export-del command, but before the shutdown has completed) |
8cade320 | 449 | # |
23e46452 | 450 | # Since: 5.2 |
8cade320 KW |
451 | ## |
452 | { 'struct': 'BlockExportInfo', | |
453 | 'data': { 'id': 'str', | |
454 | 'type': 'BlockExportType', | |
455 | 'node-name': 'str', | |
456 | 'shutting-down': 'bool' } } | |
457 | ||
458 | ## | |
459 | # @query-block-exports: | |
460 | # | |
461 | # Returns: A list of BlockExportInfo describing all block exports | |
462 | # | |
463 | # Since: 5.2 | |
464 | ## | |
f55ba801 PB |
465 | { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'], |
466 | 'allow-preconfig': true } |