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 is a block export definition. node-name is the block node that
109 should be exported. writable determines whether or not the ex‐
110 port allows write requests for modifying data (the default is
111 off).
112 The nbd export type requires --nbd-server (see below). name is
114 the NBD export name (if not specified, it defaults to the given
115 node-name). bitmap is the name of a dirty bitmap reachable from
116 the block node, so the NBD client can use NBD_OPT_SET_META_CON‐
117 TEXT with the metadata context name "qemu:dirty-bitmap:BITMAP"
118 to inspect the bitmap.
119 The vhost-user-blk export type takes a vhost-user socket address
121 on which it accept incoming connections. Both
122 addr.type=unix,addr.path=<socket-path> for UNIX domain sockets
123 and addr.type=fd,addr.str=<fd> for file descriptor passing are
124 supported. logical-block-size sets the logical block size in
125 bytes (the default is 512). num-queues sets the number of
126 virtqueues (the default is 1).
127 The fuse export type takes a mount point, which must be a regu‐
129 lar file, on which to export the given block node. That file
130 will not be changed, it will just appear to have the block
131 node's content while the export is active (very much like mount‐
132 ing a filesystem on a directory does not change what the direc‐
133 tory contains, it only shows a different content while the
134 filesystem is mounted). Consequently, applications that have
135 opened the given file before the export became active will con‐
136 tinue to see its original content. If growable is set, writes
137 after the end of the exported file will grow the block node to
138 fit. The allow-other option controls whether users other than
139 the user running the process will be allowed to access the ex‐
140 port. Note that enabling this option as a non-root user re‐
141 quires enabling the user_allow_other option in the global
142 fuse.conf configuration file. Setting allow-other to auto (the
143 default) will try enabling this option, and on error fall back
144 to disabling it.
145 --monitor MONITORDEF
147 is a QMP monitor definition. See the qemu(1) manual page for a
148 description of QMP monitor properties. A common QMP monitor def‐
149 inition configures a monitor on character device char1:
150 --monitor chardev=char1
152 --nbd-server
154 addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-au‐
155 thz=<id>][,max-connections=<n>]
156 --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐
158 thz=<id>][,max-connections=<n>]
159 --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-au‐
161 thz=<id>][,max-connections=<n>]
162 is a server for NBD exports. Both TCP and UNIX domain sockets
163 are supported. A listen socket can be provided via file de‐
164 scriptor passing (see Examples below). TLS encryption can be
165 configured using --object tls-creds-* and authz-* secrets (see
166 below).
167 To configure an NBD server on UNIX domain socket path
169 /var/run/qsd-nbd.sock:
170 --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
172 --object help
174 --object <type>,help
176 --object <type>[,<property>=<value>...]
178 is a QEMU user creatable object definition. List object types
179 with help. List object properties with <type>,help. See the
180 qemu(1) manual page for a description of the object properties.
181 --pidfile PATH
183 is the path to a file where the daemon writes its pid. This al‐
184 lows scripts to stop the daemon by sending a signal:
185 $ kill -SIGTERM $(<path/to/qsd.pid)
187 A file lock is applied to the file so only one instance of the
189 daemon can run with a given pid file path. The daemon unlinks
190 its pid file when terminating.
191 The pid file is written after chardevs, exports, and NBD servers
193 have been created but before accepting connections. The daemon
194 has started successfully when the pid file is written and
195 clients may begin connecting.
196 --daemonize
198 Daemonize the process. The parent process will exit once startup
199 is complete (i.e., after the pid file has been or would have
200 been written) or failure occurs. Its exit code reflects whether
201 the child has started up successfully or failed to do so.
202
204 Launch the daemon with QMP monitor socket qmp.sock so clients can exe‐
205 cute QMP commands:
206 $ qemu-storage-daemon \
208 --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
209 --monitor chardev=char1
210 Launch the daemon from Python with a QMP monitor socket using file de‐
212 scriptor passing so there is no need to busy wait for the QMP monitor
213 to become available:
214 #!/usr/bin/env python3
216 import subprocess
217 import socket
218 sock_path = '/var/run/qmp.sock'
220 with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
222 listen_sock.bind(sock_path)
223 listen_sock.listen()
224 fd = listen_sock.fileno()
226 subprocess.Popen(
228 ['qemu-storage-daemon',
229 '--chardev', f'socket,fd={fd},server=on,id=char1',
230 '--monitor', 'chardev=char1'],
231 pass_fds=[fd],
232 )
233 # listen_sock was automatically closed when leaving the 'with' statement
235 # body. If the daemon process terminated early then the following connect()
236 # will fail with "Connection refused" because no process has the listen
237 # socket open anymore. Launch errors can be detected this way.
238 qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
240 qmp_sock.connect(sock_path)
241 ...QMP interaction...
242 The same socket spawning approach also works with the --nbd-server
244 addr.type=fd,addr.str=<fd> and --export
245 type=vhost-user-blk,addr.type=fd,addr.str=<fd> options.
246 Export raw image file disk.img over NBD UNIX domain socket nbd.sock:
248 $ qemu-storage-daemon \
250 --blockdev driver=file,node-name=disk,filename=disk.img \
251 --nbd-server addr.type=unix,addr.path=nbd.sock \
252 --export type=nbd,id=export,node-name=disk,writable=on
253 Export a qcow2 image file disk.qcow2 as a vhost-user-blk device over
255 UNIX domain socket vhost-user-blk.sock:
256 $ qemu-storage-daemon \
258 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
259 --blockdev driver=qcow2,node-name=qcow2,file=file \
260 --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
261 Export a qcow2 image file disk.qcow2 via FUSE on itself, so the disk
263 image file will then appear as a raw image:
264 $ qemu-storage-daemon \
266 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
267 --blockdev driver=qcow2,node-name=qcow2,file=file \
268 --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
269
271 qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
272
274 2023, The QEMU Project Developers
2757.0.0 Jan 19, 2023 QEMU-STORAGE-DAEMON(1)