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