1QEMU-STORAGE-DAEMON(1)               QEMU               QEMU-STORAGE-DAEMON(1)
2
3
4

NAME

6       qemu-storage-daemon - QEMU storage daemon
7

SYNOPSIS

9       qemu-storage-daemon [options]
10

DESCRIPTION

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
19       The daemon offers the following subset of QEMU features:
20
21       • Block nodes
22
23       • Block jobs
24
25       • Block exports
26
27       • Throttle groups
28
29       • Character devices
30
31       • Crypto and secrets
32
33       • QMP
34
35       • IOThreads
36
37       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
41       The daemon runs until it is stopped using the quit QMP command or  SIG‐
42       INT/SIGHUP/SIGTERM.
43
44       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

OPTIONS

50       Standard options:
51
52       -h, --help
53              Display help and exit
54
55       -V, --version
56              Display version information and exit
57
58       -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
59              Specify tracing options.
60
61              [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
68                 Use -trace help to print a list of names of trace points.
69
70              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
77              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
81       --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
87       --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
92                 --chardev socket,id=char1,path=/var/run/qsd-qmp.sock,server=on,wait=off
93
94       --export            [type=]nbd,id=<id>,node-name=<node-name>[,name=<ex‐
95       port-name>][,writable=on|off][,bitmap=<name>]
96
97       --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
101       --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
105       --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
112              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
119              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
127              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
139       --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
144                 --monitor chardev=char1
145
146       --nbd-server
147       addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-au‐
148       thz=<id>][,max-connections=<n>]
149
150       --nbd-server  addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐
151       thz=<id>][,max-connections=<n>]
152
153       --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
161              To  configure  an  NBD  server  on  UNIX  domain   socket   path
162              /var/run/qsd-nbd.sock:
163
164                 --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
165
166       --object help
167
168       --object <type>,help
169
170       --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
175       --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
179                 $ kill -SIGTERM $(<path/to/qsd.pid)
180
181              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
185              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

EXAMPLES

191       Launch  the daemon with QMP monitor socket qmp.sock so clients can exe‐
192       cute QMP commands:
193
194          $ qemu-storage-daemon \
195              --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
196              --monitor chardev=char1
197
198       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
202          #!/usr/bin/env python3
203          import subprocess
204          import socket
205
206          sock_path = '/var/run/qmp.sock'
207
208          with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
209              listen_sock.bind(sock_path)
210              listen_sock.listen()
211
212              fd = listen_sock.fileno()
213
214              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
221          # 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
226          qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
227          qmp_sock.connect(sock_path)
228          ...QMP interaction...
229
230       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
234       Export raw image file disk.img over NBD UNIX domain socket nbd.sock:
235
236          $ 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
241       Export a qcow2 image file disk.qcow2 as a vhosts-user-blk  device  over
242       UNIX domain socket vhost-user-blk.sock:
243
244          $ 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
249       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
252          $ 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

SEE ALSO

258       qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
259
261       2022, The QEMU Project Developers
262
263
264
265
2666.2.0                            Jun 11, 2022           QEMU-STORAGE-DAEMON(1)
Impressum