8 **qemu-storage-daemon** [options]
13 qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
14 qemu-nbd in a long-running process controlled via QMP commands without running
15 a virtual machine. It can export disk images, run block job operations, and
16 perform other disk-related operations. The daemon is controlled via a QMP
17 monitor and initial configuration from the command-line.
19 The daemon offers the following subset of QEMU features:
30 Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
31 :manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the
34 The daemon runs until it is stopped using the ``quit`` QMP command or
35 SIGINT/SIGHUP/SIGTERM.
37 **Warning:** Never modify images in use by a running virtual machine or any
38 other process; this may destroy the image. Also, be aware that querying an
39 image that is being modified by another process may encounter inconsistent
45 .. program:: qemu-storage-daemon
49 .. option:: -h, --help
53 .. option:: -V, --version
55 Display version information and exit
57 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
59 .. include:: ../qemu-option-trace.rst.inc
61 .. option:: --blockdev BLOCKDEVDEF
63 is a block node definition. See the :manpage:`qemu(1)` manual page for a
64 description of block node properties and the :manpage:`qemu-block-drivers(7)`
65 manual page for a description of driver-specific parameters.
67 .. option:: --chardev CHARDEVDEF
69 is a character device definition. See the :manpage:`qemu(1)` manual page for
70 a description of character device properties. A common character device
71 definition configures a UNIX domain socket::
73 --chardev socket,id=char1,path=/var/run/qsd-qmp.sock,server=on,wait=off
75 .. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]
76 --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
77 --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
78 --export [type=]fuse,id=<id>,node-name=<node-name>,mountpoint=<file>[,growable=on|off][,writable=on|off]
80 is a block export definition. ``node-name`` is the block node that should be
81 exported. ``writable`` determines whether or not the export allows write
82 requests for modifying data (the default is off).
84 The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
85 the NBD export name (if not specified, it defaults to the given
86 ``node-name``). ``bitmap`` is the name of a dirty bitmap reachable from the
87 block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
88 metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
90 The ``vhost-user-blk`` export type takes a vhost-user socket address on which
91 it accept incoming connections. Both
92 ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
93 ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
94 ``logical-block-size`` sets the logical block size in bytes (the default is
95 512). ``num-queues`` sets the number of virtqueues (the default is 1).
97 The ``fuse`` export type takes a mount point, which must be a regular file,
98 on which to export the given block node. That file will not be changed, it
99 will just appear to have the block node's content while the export is active
100 (very much like mounting a filesystem on a directory does not change what the
101 directory contains, it only shows a different content while the filesystem is
102 mounted). Consequently, applications that have opened the given file before
103 the export became active will continue to see its original content. If
104 ``growable`` is set, writes after the end of the exported file will grow the
107 .. option:: --monitor MONITORDEF
109 is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
110 a description of QMP monitor properties. A common QMP monitor definition
111 configures a monitor on character device ``char1``::
113 --monitor chardev=char1
115 .. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
116 --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
117 --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
119 is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
120 A listen socket can be provided via file descriptor passing (see Examples
121 below). TLS encryption can be configured using ``--object`` tls-creds-* and
122 authz-* secrets (see below).
124 To configure an NBD server on UNIX domain socket path
125 ``/var/run/qsd-nbd.sock``::
127 --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
129 .. option:: --object help
131 --object <type>[,<property>=<value>...]
133 is a QEMU user creatable object definition. List object types with ``help``.
134 List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
135 manual page for a description of the object properties.
137 .. option:: --pidfile PATH
139 is the path to a file where the daemon writes its pid. This allows scripts to
140 stop the daemon by sending a signal::
142 $ kill -SIGTERM $(<path/to/qsd.pid)
144 A file lock is applied to the file so only one instance of the daemon can run
145 with a given pid file path. The daemon unlinks its pid file when terminating.
147 The pid file is written after chardevs, exports, and NBD servers have been
148 created but before accepting connections. The daemon has started successfully
149 when the pid file is written and clients may begin connecting.
153 Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
156 $ qemu-storage-daemon \
157 --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
158 --monitor chardev=char1
160 Launch the daemon from Python with a QMP monitor socket using file descriptor
161 passing so there is no need to busy wait for the QMP monitor to become
164 #!/usr/bin/env python3
168 sock_path = '/var/run/qmp.sock'
170 with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
171 listen_sock.bind(sock_path)
174 fd = listen_sock.fileno()
177 ['qemu-storage-daemon',
178 '--chardev', f'socket,fd={fd},server=on,id=char1',
179 '--monitor', 'chardev=char1'],
183 # listen_sock was automatically closed when leaving the 'with' statement
184 # body. If the daemon process terminated early then the following connect()
185 # will fail with "Connection refused" because no process has the listen
186 # socket open anymore. Launch errors can be detected this way.
188 qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
189 qmp_sock.connect(sock_path)
190 ...QMP interaction...
192 The same socket spawning approach also works with the ``--nbd-server
193 addr.type=fd,addr.str=<fd>`` and ``--export
194 type=vhost-user-blk,addr.type=fd,addr.str=<fd>`` options.
196 Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
198 $ qemu-storage-daemon \
199 --blockdev driver=file,node-name=disk,filename=disk.img \
200 --nbd-server addr.type=unix,addr.path=nbd.sock \
201 --export type=nbd,id=export,node-name=disk,writable=on
203 Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX
204 domain socket ``vhost-user-blk.sock``::
206 $ qemu-storage-daemon \
207 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
208 --blockdev driver=qcow2,node-name=qcow2,file=file \
209 --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
211 Export a qcow2 image file ``disk.qcow2`` via FUSE on itself, so the disk image
212 file will then appear as a raw image::
214 $ qemu-storage-daemon \
215 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
216 --blockdev driver=qcow2,node-name=qcow2,file=file \
217 --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
222 :manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`