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]
107 is a block export definition. node-name is the block node that
108 should be exported. writable determines whether or not the ex‐
109 port allows write requests for modifying data (the default is
110 off).
111 The nbd export type requires --nbd-server (see below). name is
113 the NBD export name (if not specified, it defaults to the given
114 node-name). bitmap is the name of a dirty bitmap reachable from
115 the block node, so the NBD client can use NBD_OPT_SET_META_CON‐
116 TEXT with the metadata context name "qemu:dirty-bitmap:BITMAP"
117 to inspect the bitmap.
118 The vhost-user-blk export type takes a vhost-user socket address
120 on which it accept incoming connections. Both
121 addr.type=unix,addr.path=<socket-path> for UNIX domain sockets
122 and addr.type=fd,addr.str=<fd> for file descriptor passing are
123 supported. logical-block-size sets the logical block size in
124 bytes (the default is 512). num-queues sets the number of
125 virtqueues (the default is 1).
126 The fuse export type takes a mount point, which must be a regu‐
128 lar file, on which to export the given block node. That file
129 will not be changed, it will just appear to have the block
130 node's content while the export is active (very much like mount‐
131 ing a filesystem on a directory does not change what the direc‐
132 tory contains, it only shows a different content while the
133 filesystem is mounted). Consequently, applications that have
134 opened the given file before the export became active will con‐
135 tinue to see its original content. If growable is set, writes
136 after the end of the exported file will grow the block node to
137 fit.
138 --monitor MONITORDEF
140 is a QMP monitor definition. See the qemu(1) manual page for a
141 description of QMP monitor properties. A common QMP monitor def‐
142 inition configures a monitor on character device char1:
143 --monitor chardev=char1
145 --nbd-server
147 addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-au‐
148 thz=<id>][,max-connections=<n>]
149 --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐
151 thz=<id>][,max-connections=<n>]
152 --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-au‐
154 thz=<id>][,max-connections=<n>]
155 is a server for NBD exports. Both TCP and UNIX domain sockets
156 are supported. A listen socket can be provided via file de‐
157 scriptor passing (see Examples below). TLS encryption can be
158 configured using --object tls-creds-* and authz-* secrets (see
159 below).
160 To configure an NBD server on UNIX domain socket path
162 /var/run/qsd-nbd.sock:
163 --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
165 --object help
167 --object <type>,help
169 --object <type>[,<property>=<value>...]
171 is a QEMU user creatable object definition. List object types
172 with help. List object properties with <type>,help. See the
173 qemu(1) manual page for a description of the object properties.
174 --pidfile PATH
176 is the path to a file where the daemon writes its pid. This al‐
177 lows scripts to stop the daemon by sending a signal:
178 $ kill -SIGTERM $(<path/to/qsd.pid)
180 A file lock is applied to the file so only one instance of the
182 daemon can run with a given pid file path. The daemon unlinks
183 its pid file when terminating.
184 The pid file is written after chardevs, exports, and NBD servers
186 have been created but before accepting connections. The daemon
187 has started successfully when the pid file is written and
188 clients may begin connecting.
189
191 Launch the daemon with QMP monitor socket qmp.sock so clients can exe‐
192 cute QMP commands:
193 $ qemu-storage-daemon \
195 --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
196 --monitor chardev=char1
197 Launch the daemon from Python with a QMP monitor socket using file de‐
199 scriptor passing so there is no need to busy wait for the QMP monitor
200 to become available:
201 #!/usr/bin/env python3
203 import subprocess
204 import socket
205 sock_path = '/var/run/qmp.sock'
207 with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
209 listen_sock.bind(sock_path)
210 listen_sock.listen()
211 fd = listen_sock.fileno()
213 subprocess.Popen(
215 ['qemu-storage-daemon',
216 '--chardev', f'socket,fd={fd},server=on,id=char1',
217 '--monitor', 'chardev=char1'],
218 pass_fds=[fd],
219 )
220 # listen_sock was automatically closed when leaving the 'with' statement
222 # body. If the daemon process terminated early then the following connect()
223 # will fail with "Connection refused" because no process has the listen
224 # socket open anymore. Launch errors can be detected this way.
225 qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
227 qmp_sock.connect(sock_path)
228 ...QMP interaction...
229 The same socket spawning approach also works with the --nbd-server
231 addr.type=fd,addr.str=<fd> and --export
232 type=vhost-user-blk,addr.type=fd,addr.str=<fd> options.
233 Export raw image file disk.img over NBD UNIX domain socket nbd.sock:
235 $ qemu-storage-daemon \
237 --blockdev driver=file,node-name=disk,filename=disk.img \
238 --nbd-server addr.type=unix,addr.path=nbd.sock \
239 --export type=nbd,id=export,node-name=disk,writable=on
240 Export a qcow2 image file disk.qcow2 as a vhosts-user-blk device over
242 UNIX domain socket vhost-user-blk.sock:
243 $ qemu-storage-daemon \
245 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
246 --blockdev driver=qcow2,node-name=qcow2,file=file \
247 --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
248 Export a qcow2 image file disk.qcow2 via FUSE on itself, so the disk
250 image file will then appear as a raw image:
251 $ qemu-storage-daemon \
253 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
254 --blockdev driver=qcow2,node-name=qcow2,file=file \
255 --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
256
258 qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
259
261 2021, The QEMU Project Developers
2626.1.0 Nov 08, 2021 QEMU-STORAGE-DAEMON(1)