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