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