1QEMU Storage Daemon
2===================
3
4Synopsis
5--------
6
7**qemu-storage-daemon** [options]
8
9Description
10-----------
11
12qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
13qemu-nbd in a long-running process controlled via QMP commands without running
14a virtual machine. It can export disk images, run block job operations, and
15perform other disk-related operations. The daemon is controlled via a QMP
16monitor and initial configuration from the command-line.
17
18The daemon offers the following subset of QEMU features:
19
20* Block nodes
21* Block jobs
22* Block exports
23* Throttle groups
24* Character devices
25* Crypto and secrets
26* QMP
27* IOThreads
28
29Commands 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
31commands.
32
33The daemon runs until it is stopped using the ``quit`` QMP command or
34SIGINT/SIGHUP/SIGTERM.
35
36**Warning:** Never modify images in use by a running virtual machine or any
37other process; this may destroy the image. Also, be aware that querying an
38image that is being modified by another process may encounter inconsistent
39state.
40
41Options
42-------
43
44.. program:: qemu-storage-daemon
45
46Standard options:
47
48.. option:: -h, --help
49
50  Display help and exit
51
52.. option:: -V, --version
53
54  Display version information and exit
55
56.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
57
58  .. include:: ../qemu-option-trace.rst.inc
59
60.. option:: --blockdev BLOCKDEVDEF
61
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.
65
66.. option:: --chardev CHARDEVDEF
67
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::
71
72  --chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
73
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>]
77
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).
81
82  The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
83  the NBD export name. ``bitmap`` is the name of a dirty bitmap reachable from
84  the block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
85  metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
86
87  The ``vhost-user-blk`` export type takes a vhost-user socket address on which
88  it accept incoming connections. Both
89  ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
90  ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
91  ``logical-block-size`` sets the logical block size in bytes (the default is
92  512). ``num-queues`` sets the number of virtqueues (the default is 1).
93
94.. option:: --monitor MONITORDEF
95
96  is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
97  a description of QMP monitor properties. A common QMP monitor definition
98  configures a monitor on character device ``char1``::
99
100  --monitor chardev=char1
101
102.. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
103  --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
104
105  is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
106  TLS encryption can be configured using ``--object`` tls-creds-* and authz-*
107  secrets (see below).
108
109  To configure an NBD server on UNIX domain socket path ``/tmp/nbd.sock``::
110
111  --nbd-server addr.type=unix,addr.path=/tmp/nbd.sock
112
113.. option:: --object help
114  --object <type>,help
115  --object <type>[,<property>=<value>...]
116
117  is a QEMU user creatable object definition. List object types with ``help``.
118  List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
119  manual page for a description of the object properties.
120
121Examples
122--------
123Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
124QMP commands::
125
126  $ qemu-storage-daemon \
127      --chardev socket,path=qmp.sock,server,nowait,id=char1 \
128      --monitor chardev=char1
129
130Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
131
132  $ qemu-storage-daemon \
133      --blockdev driver=file,node-name=disk,filename=disk.img \
134      --nbd-server addr.type=unix,addr.path=nbd.sock \
135      --export type=nbd,id=export,node-name=disk,writable=on
136
137Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX
138domain socket ``vhost-user-blk.sock``::
139
140  $ qemu-storage-daemon \
141      --blockdev driver=file,node-name=file,filename=disk.qcow2 \
142      --blockdev driver=qcow2,node-name=qcow2,file=file \
143      --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
144
145See also
146--------
147
148:manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`
149