1QEMU-STORAGE-DAEMON(1) QEMU QEMU-STORAGE-DAEMON(1)
2
6 qemu-storage-daemon - QEMU storage daemon
7
9 qemu-storage-daemon [options]
10
12 qemu-storage-daemon provides disk image functionality from QEMU,
13 qemu-img, and qemu-nbd in a long-running process controlled via QMP
14 commands without running a virtual machine. It can export disk images,
15 run block job operations, and perform other disk-related operations.
16 The daemon is controlled via a QMP monitor and initial configuration
17 from the command-line.
18 The daemon offers the following subset of QEMU features:
20 • Block nodes
22 • Block jobs
24 • Block exports
26 • Throttle groups
28 • Character devices
30 • Crypto and secrets
32 • QMP
34 • IOThreads
36 Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See
38 the qemu-storage-daemon-qmp-ref(7) manual page for a description of the
39 commands.
40 The daemon runs until it is stopped using the quit QMP command or SIG‐
42 INT/SIGHUP/SIGTERM.
43 Warning: Never modify images in use by a running virtual machine or any
45 other process; this may destroy the image. Also, be aware that querying
46 an image that is being modified by another process may encounter incon‐
47 sistent state.
48
50 Standard options:
51 -h, --help
53 Display help and exit
54 -V, --version
56 Display version information and exit
57 -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
59 Specify tracing options.
60 [enable=]PATTERN
62 Immediately enable events matching PATTERN (either event name
63 or a globbing pattern). This option is only available if
64 QEMU has been compiled with the simple, log or ftrace tracing
65 backend. To specify multiple events or patterns, specify the
66 -trace option multiple times.
67 Use -trace help to print a list of names of trace points.
69 events=FILE
71 Immediately enable events listed in FILE. The file must con‐
72 tain one event name (as listed in the trace-events-all file)
73 per line; globbing patterns are accepted too. This option is
74 only available if QEMU has been compiled with the simple, log
75 or ftrace tracing backend.
76 file=FILE
78 Log output traces to FILE. This option is only available if
79 QEMU has been compiled with the simple tracing backend.
80 --blockdev BLOCKDEVDEF
82 is a block node definition. See the qemu(1) manual page for a
83 description of block node properties and the qemu-block-driv‐
84 ers(7) manual page for a description of driver-specific parame‐
85 ters.
86 --chardev CHARDEVDEF
88 is a character device definition. See the qemu(1) manual page
89 for a description of character device properties. A common char‐
90 acter device definition configures a UNIX domain socket:
91 --chardev socket,id=char1,path=/var/run/qsd-qmp.sock,server=on,wait=off
93 --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<ex‐
95 port-name>][,writable=on|off][,bitmap=<name>]
96 --export
98 [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,log‐
99 ical-block-size=<block-size>][,num-queues=<num-queues>]
100 --export
102 [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,log‐
103 ical-block-size=<block-size>][,num-queues=<num-queues>]
104 --export [type=]fuse,id=<id>,node-name=<node-name>,mount‐
106 point=<file>[,growable=on|off][,writable=on|off][,al‐
107 low-other=on|off|auto]
108 --export
110 [type=]vduse-blk,id=<id>,node-name=<node-name>,name=<vduse-name>[,writable=on|off][,num-queues=<num-queues>][,queue-size=<queue-size>][,log‐
111 ical-block-size=<block-size>][,serial=<serial-number>]
112 is a block export definition. node-name is the block node that
113 should be exported. writable determines whether or not the ex‐
114 port allows write requests for modifying data (the default is
115 off).
116 The nbd export type requires --nbd-server (see below). name is
118 the NBD export name (if not specified, it defaults to the given
119 node-name). bitmap is the name of a dirty bitmap reachable from
120 the block node, so the NBD client can use NBD_OPT_SET_META_CON‐
121 TEXT with the metadata context name "qemu:dirty-bitmap:BITMAP"
122 to inspect the bitmap.
123 The vhost-user-blk export type takes a vhost-user socket address
125 on which it accept incoming connections. Both
126 addr.type=unix,addr.path=<socket-path> for UNIX domain sockets
127 and addr.type=fd,addr.str=<fd> for file descriptor passing are
128 supported. logical-block-size sets the logical block size in
129 bytes (the default is 512). num-queues sets the number of
130 virtqueues (the default is 1).
131 The fuse export type takes a mount point, which must be a regu‐
133 lar file, on which to export the given block node. That file
134 will not be changed, it will just appear to have the block
135 node's content while the export is active (very much like mount‐
136 ing a filesystem on a directory does not change what the direc‐
137 tory contains, it only shows a different content while the
138 filesystem is mounted). Consequently, applications that have
139 opened the given file before the export became active will con‐
140 tinue to see its original content. If growable is set, writes
141 after the end of the exported file will grow the block node to
142 fit. The allow-other option controls whether users other than
143 the user running the process will be allowed to access the ex‐
144 port. Note that enabling this option as a non-root user re‐
145 quires enabling the user_allow_other option in the global
146 fuse.conf configuration file. Setting allow-other to auto (the
147 default) will try enabling this option, and on error fall back
148 to disabling it.
149 The vduse-blk export type takes a name (must be unique across
151 the host) to create the VDUSE device. num-queues sets the num‐
152 ber of virtqueues (the default is 1). queue-size sets the
153 virtqueue descriptor table size (the default is 256).
154 The instantiated VDUSE device must then be added to the vDPA bus
156 using the vdpa(8) command from the iproute2 project:
157 # vdpa dev add name <id> mgmtdev vduse
159 The device can be removed from the vDPA bus later as follows:
161 # vdpa dev del <id>
163 For more information about attaching vDPA devices to the host
165 with virtio_vdpa.ko or attaching them to guests with
166 vhost_vdpa.ko, see https://vdpa-dev.gitlab.io/.
167 For more information about VDUSE, see
169 https://docs.kernel.org/userspace-api/vduse.html.
170 --monitor MONITORDEF
172 is a QMP monitor definition. See the qemu(1) manual page for a
173 description of QMP monitor properties. A common QMP monitor def‐
174 inition configures a monitor on character device char1:
175 --monitor chardev=char1
177 --nbd-server
179 addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-au‐
180 thz=<id>][,max-connections=<n>]
181 --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐
183 thz=<id>][,max-connections=<n>]
184 --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-au‐
186 thz=<id>][,max-connections=<n>]
187 is a server for NBD exports. Both TCP and UNIX domain sockets
188 are supported. A listen socket can be provided via file de‐
189 scriptor passing (see Examples below). TLS encryption can be
190 configured using --object tls-creds-* and authz-* secrets (see
191 below).
192 To configure an NBD server on UNIX domain socket path
194 /var/run/qsd-nbd.sock:
195 --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
197 --object help
199 --object <type>,help
201 --object <type>[,<property>=<value>...]
203 is a QEMU user creatable object definition. List object types
204 with help. List object properties with <type>,help. See the
205 qemu(1) manual page for a description of the object properties.
206 --pidfile PATH
208 is the path to a file where the daemon writes its pid. This al‐
209 lows scripts to stop the daemon by sending a signal:
210 $ kill -SIGTERM $(<path/to/qsd.pid)
212 A file lock is applied to the file so only one instance of the
214 daemon can run with a given pid file path. The daemon unlinks
215 its pid file when terminating.
216 The pid file is written after chardevs, exports, and NBD servers
218 have been created but before accepting connections. The daemon
219 has started successfully when the pid file is written and
220 clients may begin connecting.
221 --daemonize
223 Daemonize the process. The parent process will exit once startup
224 is complete (i.e., after the pid file has been or would have
225 been written) or failure occurs. Its exit code reflects whether
226 the child has started up successfully or failed to do so.
227
229 Launch the daemon with QMP monitor socket qmp.sock so clients can exe‐
230 cute QMP commands:
231 $ qemu-storage-daemon \
233 --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
234 --monitor chardev=char1
235 Launch the daemon from Python with a QMP monitor socket using file de‐
237 scriptor passing so there is no need to busy wait for the QMP monitor
238 to become available:
239 #!/usr/bin/env python3
241 import subprocess
242 import socket
243 sock_path = '/var/run/qmp.sock'
245 with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
247 listen_sock.bind(sock_path)
248 listen_sock.listen()
249 fd = listen_sock.fileno()
251 subprocess.Popen(
253 ['qemu-storage-daemon',
254 '--chardev', f'socket,fd={fd},server=on,id=char1',
255 '--monitor', 'chardev=char1'],
256 pass_fds=[fd],
257 )
258 # listen_sock was automatically closed when leaving the 'with' statement
260 # body. If the daemon process terminated early then the following connect()
261 # will fail with "Connection refused" because no process has the listen
262 # socket open anymore. Launch errors can be detected this way.
263 qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
265 qmp_sock.connect(sock_path)
266 ...QMP interaction...
267 The same socket spawning approach also works with the --nbd-server
269 addr.type=fd,addr.str=<fd> and --export
270 type=vhost-user-blk,addr.type=fd,addr.str=<fd> options.
271 Export raw image file disk.img over NBD UNIX domain socket nbd.sock:
273 $ qemu-storage-daemon \
275 --blockdev driver=file,node-name=disk,filename=disk.img \
276 --nbd-server addr.type=unix,addr.path=nbd.sock \
277 --export type=nbd,id=export,node-name=disk,writable=on
278 Export a qcow2 image file disk.qcow2 as a vhost-user-blk device over
280 UNIX domain socket vhost-user-blk.sock:
281 $ qemu-storage-daemon \
283 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
284 --blockdev driver=qcow2,node-name=qcow2,file=file \
285 --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
286 Export a qcow2 image file disk.qcow2 via FUSE on itself, so the disk
288 image file will then appear as a raw image:
289 $ qemu-storage-daemon \
291 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
292 --blockdev driver=qcow2,node-name=qcow2,file=file \
293 --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
294
296 qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
297
299 2023, The QEMU Project Developers
3008.1.3 Nov 28, 2023 QEMU-STORAGE-DAEMON(1)