7 **qemu-storage-daemon** [options]
12 qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
13 qemu-nbd in a long-running process controlled via QMP commands without running
14 a virtual machine. It can export disk images, run block job operations, and
15 perform other disk-related operations. The daemon is controlled via a QMP
16 monitor and initial configuration from the command-line.
18 The daemon offers the following subset of QEMU features:
29 Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
30 :manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the
33 The daemon runs until it is stopped using the ``quit`` QMP command or
34 SIGINT/SIGHUP/SIGTERM.
36 **Warning:** Never modify images in use by a running virtual machine or any
37 other process; this may destroy the image. Also, be aware that querying an
38 image that is being modified by another process may encounter inconsistent
44 .. program:: qemu-storage-daemon
48 .. option:: -h, --help
52 .. option:: -V, --version
54 Display version information and exit
56 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
58 .. include:: ../qemu-option-trace.rst.inc
60 .. option:: --blockdev BLOCKDEVDEF
62 is a block node definition. See the :manpage:`qemu(1)` manual page for a
63 description of block node properties and the :manpage:`qemu-block-drivers(7)`
64 manual page for a description of driver-specific parameters.
66 .. option:: --chardev CHARDEVDEF
68 is a character device definition. See the :manpage:`qemu(1)` manual page for
69 a description of character device properties. A common character device
70 definition configures a UNIX domain socket::
72 --chardev socket,id=char1,path=/var/run/qsd-qmp.sock,server=on,wait=off
74 .. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]
75 --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>]
76 --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 is a block export definition. ``node-name`` is the block node that should be
79 exported. ``writable`` determines whether or not the export allows write
80 requests for modifying data (the default is off).
82 The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
83 the NBD export name (if not specified, it defaults to the given
84 ``node-name``). ``bitmap`` is the name of a dirty bitmap reachable from the
85 block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
86 metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
88 The ``vhost-user-blk`` export type takes a vhost-user socket address on which
89 it accept incoming connections. Both
90 ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
91 ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
92 ``logical-block-size`` sets the logical block size in bytes (the default is
93 512). ``num-queues`` sets the number of virtqueues (the default is 1).
95 .. option:: --monitor MONITORDEF
97 is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
98 a description of QMP monitor properties. A common QMP monitor definition
99 configures a monitor on character device ``char1``::
101 --monitor chardev=char1
103 .. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
104 --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
105 --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
107 is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
108 A listen socket can be provided via file descriptor passing (see Examples
109 below). TLS encryption can be configured using ``--object`` tls-creds-* and
110 authz-* secrets (see below).
112 To configure an NBD server on UNIX domain socket path
113 ``/var/run/qsd-nbd.sock``::
115 --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
117 .. option:: --object help
119 --object <type>[,<property>=<value>...]
121 is a QEMU user creatable object definition. List object types with ``help``.
122 List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
123 manual page for a description of the object properties.
125 .. option:: --pidfile PATH
127 is the path to a file where the daemon writes its pid. This allows scripts to
128 stop the daemon by sending a signal::
130 $ kill -SIGTERM $(<path/to/qsd.pid)
132 A file lock is applied to the file so only one instance of the daemon can run
133 with a given pid file path. The daemon unlinks its pid file when terminating.
135 The pid file is written after chardevs, exports, and NBD servers have been
136 created but before accepting connections. The daemon has started successfully
137 when the pid file is written and clients may begin connecting.
141 Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
144 $ qemu-storage-daemon \
145 --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
146 --monitor chardev=char1
148 Launch the daemon from Python with a QMP monitor socket using file descriptor
149 passing so there is no need to busy wait for the QMP monitor to become
152 #!/usr/bin/env python3
156 sock_path = '/var/run/qmp.sock'
158 with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
159 listen_sock.bind(sock_path)
162 fd = listen_sock.fileno()
165 ['qemu-storage-daemon',
166 '--chardev', f'socket,fd={fd},server=on,id=char1',
167 '--monitor', 'chardev=char1'],
171 # listen_sock was automatically closed when leaving the 'with' statement
172 # body. If the daemon process terminated early then the following connect()
173 # will fail with "Connection refused" because no process has the listen
174 # socket open anymore. Launch errors can be detected this way.
176 qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
177 qmp_sock.connect(sock_path)
178 ...QMP interaction...
180 The same socket spawning approach also works with the ``--nbd-server
181 addr.type=fd,addr.str=<fd>`` and ``--export
182 type=vhost-user-blk,addr.type=fd,addr.str=<fd>`` options.
184 Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
186 $ qemu-storage-daemon \
187 --blockdev driver=file,node-name=disk,filename=disk.img \
188 --nbd-server addr.type=unix,addr.path=nbd.sock \
189 --export type=nbd,id=export,node-name=disk,writable=on
191 Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX
192 domain socket ``vhost-user-blk.sock``::
194 $ qemu-storage-daemon \
195 --blockdev driver=file,node-name=file,filename=disk.qcow2 \
196 --blockdev driver=qcow2,node-name=qcow2,file=file \
197 --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
202 :manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`