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