]>
Commit | Line | Data |
---|---|---|
5daa6bfd KW |
1 | # -*- Mode: Python -*- |
2 | # vim: filetype=python | |
3 | ||
4 | ## | |
5 | # == Block device exports | |
6 | ## | |
7 | ||
8 | { 'include': 'sockets.json' } | |
9 | ||
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). | |
1c8222b0 KW |
23 | # @max-connections: The maximum number of connections to allow at the same |
24 | # time, 0 for unlimited. (since 5.2; default: 0) | |
5daa6bfd KW |
25 | # |
26 | # Since: 4.2 | |
27 | ## | |
28 | { 'struct': 'NbdServerOptions', | |
29 | 'data': { 'addr': 'SocketAddress', | |
30 | '*tls-creds': 'str', | |
1c8222b0 KW |
31 | '*tls-authz': 'str', |
32 | '*max-connections': 'uint32' } } | |
5daa6bfd KW |
33 | |
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). | |
1c8222b0 KW |
52 | # @max-connections: The maximum number of connections to allow at the same |
53 | # time, 0 for unlimited. (since 5.2; default: 0) | |
5daa6bfd KW |
54 | # |
55 | # Returns: error if the server is already running. | |
56 | # | |
57 | # Since: 1.3.0 | |
58 | ## | |
59 | { 'command': 'nbd-server-start', | |
60 | 'data': { 'addr': 'SocketAddressLegacy', | |
61 | '*tls-creds': 'str', | |
1c8222b0 KW |
62 | '*tls-authz': 'str', |
63 | '*max-connections': 'uint32' } } | |
5daa6bfd KW |
64 | |
65 | ## | |
143ea767 | 66 | # @BlockExportOptionsNbd: |
5daa6bfd | 67 | # |
b6076afc KW |
68 | # An NBD block export (options shared between nbd-server-add and the NBD branch |
69 | # of block-export-add). | |
5daa6bfd KW |
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 | # | |
5daa6bfd KW |
77 | # @bitmap: Also export the dirty bitmap reachable from @device, so the |
78 | # NBD client can use NBD_OPT_SET_META_CONTEXT with | |
79 | # "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0) | |
80 | # | |
81 | # Since: 5.0 | |
82 | ## | |
143ea767 | 83 | { 'struct': 'BlockExportOptionsNbd', |
b6076afc | 84 | 'data': { '*name': 'str', '*description': 'str', |
30dbc81d | 85 | '*bitmap': 'str' } } |
b6076afc | 86 | |
90fc91d5 SH |
87 | ## |
88 | # @BlockExportOptionsVhostUserBlk: | |
89 | # | |
90 | # A vhost-user-blk block export. | |
91 | # | |
92 | # @addr: The vhost-user socket on which to listen. Both 'unix' and 'fd' | |
93 | # SocketAddress types are supported. Passed fds must be UNIX domain | |
94 | # sockets. | |
95 | # @logical-block-size: Logical block size in bytes. Defaults to 512 bytes. | |
d9b495f9 SH |
96 | # @num-queues: Number of request virtqueues. Must be greater than 0. Defaults |
97 | # to 1. | |
90fc91d5 SH |
98 | # |
99 | # Since: 5.2 | |
100 | ## | |
101 | { 'struct': 'BlockExportOptionsVhostUserBlk', | |
d9b495f9 SH |
102 | 'data': { 'addr': 'SocketAddress', |
103 | '*logical-block-size': 'size', | |
104 | '*num-queues': 'uint16'} } | |
90fc91d5 | 105 | |
b6076afc KW |
106 | ## |
107 | # @NbdServerAddOptions: | |
108 | # | |
109 | # An NBD block export. | |
110 | # | |
111 | # @device: The device name or node name of the node to be exported | |
112 | # | |
30dbc81d KW |
113 | # @writable: Whether clients should be able to write to the device via the |
114 | # NBD connection (default false). | |
115 | # | |
b6076afc KW |
116 | # Since: 5.0 |
117 | ## | |
118 | { 'struct': 'NbdServerAddOptions', | |
119 | 'base': 'BlockExportOptionsNbd', | |
30dbc81d KW |
120 | 'data': { 'device': 'str', |
121 | '*writable': 'bool' } } | |
5daa6bfd KW |
122 | |
123 | ## | |
124 | # @nbd-server-add: | |
125 | # | |
126 | # Export a block node to QEMU's embedded NBD server. | |
127 | # | |
d53be9ce KW |
128 | # The export name will be used as the id for the resulting block export. |
129 | # | |
443127e8 KW |
130 | # Features: |
131 | # @deprecated: This command is deprecated. Use @block-export-add instead. | |
132 | # | |
5daa6bfd KW |
133 | # Returns: error if the server is not running, or export with the same name |
134 | # already exists. | |
135 | # | |
136 | # Since: 1.3.0 | |
137 | ## | |
138 | { 'command': 'nbd-server-add', | |
443127e8 | 139 | 'data': 'NbdServerAddOptions', 'boxed': true, 'features': ['deprecated'] } |
5daa6bfd KW |
140 | |
141 | ## | |
3c3bc462 | 142 | # @BlockExportRemoveMode: |
5daa6bfd | 143 | # |
3c3bc462 | 144 | # Mode for removing a block export. |
5daa6bfd KW |
145 | # |
146 | # @safe: Remove export if there are no existing connections, fail otherwise. | |
147 | # | |
148 | # @hard: Drop all connections immediately and remove export. | |
149 | # | |
150 | # Potential additional modes to be added in the future: | |
151 | # | |
152 | # hide: Just hide export from new clients, leave existing connections as is. | |
153 | # Remove export after all clients are disconnected. | |
154 | # | |
155 | # soft: Hide export from new clients, answer with ESHUTDOWN for all further | |
156 | # requests from existing clients. | |
157 | # | |
158 | # Since: 2.12 | |
159 | ## | |
3c3bc462 | 160 | {'enum': 'BlockExportRemoveMode', 'data': ['safe', 'hard']} |
5daa6bfd KW |
161 | |
162 | ## | |
163 | # @nbd-server-remove: | |
164 | # | |
165 | # Remove NBD export by name. | |
166 | # | |
3c3bc462 | 167 | # @name: Block export id. |
5daa6bfd | 168 | # |
3c3bc462 | 169 | # @mode: Mode of command operation. See @BlockExportRemoveMode description. |
5daa6bfd KW |
170 | # Default is 'safe'. |
171 | # | |
443127e8 KW |
172 | # Features: |
173 | # @deprecated: This command is deprecated. Use @block-export-del instead. | |
174 | # | |
5daa6bfd KW |
175 | # Returns: error if |
176 | # - the server is not running | |
177 | # - export is not found | |
178 | # - mode is 'safe' and there are existing connections | |
179 | # | |
180 | # Since: 2.12 | |
181 | ## | |
182 | { 'command': 'nbd-server-remove', | |
443127e8 KW |
183 | 'data': {'name': 'str', '*mode': 'BlockExportRemoveMode'}, |
184 | 'features': ['deprecated'] } | |
5daa6bfd KW |
185 | |
186 | ## | |
187 | # @nbd-server-stop: | |
188 | # | |
189 | # Stop QEMU's embedded NBD server, and unregister all devices previously | |
190 | # added via @nbd-server-add. | |
191 | # | |
192 | # Since: 1.3.0 | |
193 | ## | |
194 | { 'command': 'nbd-server-stop' } | |
195 | ||
196 | ## | |
197 | # @BlockExportType: | |
198 | # | |
199 | # An enumeration of block export types | |
200 | # | |
201 | # @nbd: NBD export | |
90fc91d5 | 202 | # @vhost-user-blk: vhost-user-blk export (since 5.2) |
5daa6bfd KW |
203 | # |
204 | # Since: 4.2 | |
205 | ## | |
206 | { 'enum': 'BlockExportType', | |
90fc91d5 | 207 | 'data': [ 'nbd', 'vhost-user-blk' ] } |
5daa6bfd KW |
208 | |
209 | ## | |
143ea767 | 210 | # @BlockExportOptions: |
5daa6bfd KW |
211 | # |
212 | # Describes a block export, i.e. how single node should be exported on an | |
213 | # external interface. | |
214 | # | |
d53be9ce KW |
215 | # @id: A unique identifier for the block export (across all export types) |
216 | # | |
b6076afc KW |
217 | # @node-name: The node name of the block node to be exported (since: 5.2) |
218 | # | |
30dbc81d KW |
219 | # @writable: True if clients should be able to write to the export |
220 | # (default false) | |
221 | # | |
fefee85d KW |
222 | # @writethrough: If true, caches are flushed after every write request to the |
223 | # export before completion is signalled. (since: 5.2; | |
224 | # default: false) | |
225 | # | |
f51d23c8 SH |
226 | # @iothread: The name of the iothread object where the export will run. The |
227 | # default is to use the thread currently associated with the | |
228 | # block node. (since: 5.2) | |
229 | # | |
230 | # @fixed-iothread: True prevents the block node from being moved to another | |
231 | # thread while the export is active. If true and @iothread is | |
232 | # given, export creation fails if the block node cannot be | |
233 | # moved to the iothread. The default is false. (since: 5.2) | |
234 | # | |
5daa6bfd KW |
235 | # Since: 4.2 |
236 | ## | |
143ea767 | 237 | { 'union': 'BlockExportOptions', |
fefee85d | 238 | 'base': { 'type': 'BlockExportType', |
d53be9ce | 239 | 'id': 'str', |
d9b495f9 SH |
240 | '*fixed-iothread': 'bool', |
241 | '*iothread': 'str', | |
b6076afc | 242 | 'node-name': 'str', |
30dbc81d | 243 | '*writable': 'bool', |
fefee85d | 244 | '*writethrough': 'bool' }, |
5daa6bfd KW |
245 | 'discriminator': 'type', |
246 | 'data': { | |
90fc91d5 SH |
247 | 'nbd': 'BlockExportOptionsNbd', |
248 | 'vhost-user-blk': 'BlockExportOptionsVhostUserBlk' | |
5daa6bfd | 249 | } } |
56ee8626 KW |
250 | |
251 | ## | |
252 | # @block-export-add: | |
253 | # | |
254 | # Creates a new block export. | |
255 | # | |
256 | # Since: 5.2 | |
257 | ## | |
258 | { 'command': 'block-export-add', | |
259 | 'data': 'BlockExportOptions', 'boxed': true } | |
3c3bc462 KW |
260 | |
261 | ## | |
262 | # @block-export-del: | |
263 | # | |
264 | # Request to remove a block export. This drops the user's reference to the | |
265 | # export, but the export may still stay around after this command returns until | |
266 | # the shutdown of the export has completed. | |
267 | # | |
268 | # @id: Block export id. | |
269 | # | |
270 | # @mode: Mode of command operation. See @BlockExportRemoveMode description. | |
271 | # Default is 'safe'. | |
272 | # | |
273 | # Returns: Error if the export is not found or @mode is 'safe' and the export | |
274 | # is still in use (e.g. by existing client connections) | |
275 | # | |
276 | # Since: 5.2 | |
277 | ## | |
278 | { 'command': 'block-export-del', | |
279 | 'data': { 'id': 'str', '*mode': 'BlockExportRemoveMode' } } | |
1a9f7a80 KW |
280 | |
281 | ## | |
282 | # @BLOCK_EXPORT_DELETED: | |
283 | # | |
284 | # Emitted when a block export is removed and its id can be reused. | |
285 | # | |
286 | # @id: Block export id. | |
287 | # | |
288 | # Since: 5.2 | |
289 | ## | |
290 | { 'event': 'BLOCK_EXPORT_DELETED', | |
291 | 'data': { 'id': 'str' } } | |
8cade320 KW |
292 | |
293 | ## | |
294 | # @BlockExportInfo: | |
295 | # | |
296 | # Information about a single block export. | |
297 | # | |
298 | # @id: The unique identifier for the block export | |
299 | # | |
300 | # @type: The block export type | |
301 | # | |
302 | # @node-name: The node name of the block node that is exported | |
303 | # | |
304 | # @shutting-down: True if the export is shutting down (e.g. after a | |
305 | # block-export-del command, but before the shutdown has | |
306 | # completed) | |
307 | # | |
308 | # Since: 5.2 | |
309 | ## | |
310 | { 'struct': 'BlockExportInfo', | |
311 | 'data': { 'id': 'str', | |
312 | 'type': 'BlockExportType', | |
313 | 'node-name': 'str', | |
314 | 'shutting-down': 'bool' } } | |
315 | ||
316 | ## | |
317 | # @query-block-exports: | |
318 | # | |
319 | # Returns: A list of BlockExportInfo describing all block exports | |
320 | # | |
321 | # Since: 5.2 | |
322 | ## | |
323 | { 'command': 'query-block-exports', 'returns': ['BlockExportInfo'] } |