docs/tools/qemu-storage-daemon.rst

   1 ===================
   2 QEMU Storage Daemon
   3 ===================
   4
   5 Synopsis
   6 --------
   7
   8 **qemu-storage-daemon** [options]
   9
  10 Description
  11 -----------
  12
  13 ``qemu-storage-daemon`` provides disk image functionality from QEMU,
  14 ``qemu-img``, and ``qemu-nbd`` in a long-running process controlled via QMP
  15 commands without running a virtual machine.
  16 It can export disk images, run block job operations, and
  17 perform other disk-related operations. The daemon is controlled via a QMP
  18 monitor and initial configuration from the command-line.
  19
  20 The daemon offers the following subset of QEMU features:
  21
  22 * Block nodes
  23 * Block jobs
  24 * Block exports
  25 * Throttle groups
  26 * Character devices
  27 * Crypto and secrets
  28 * QMP
  29 * IOThreads
  30
  31 Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
  32 :manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the
  33 commands.
  34
  35 The daemon runs until it is stopped using the ``quit`` QMP command or
  36 SIGINT/SIGHUP/SIGTERM.
  37
  38 **Warning:** Never modify images in use by a running virtual machine or any
  39 other process; this may destroy the image. Also, be aware that querying an
  40 image that is being modified by another process may encounter inconsistent
  41 state.
  42
  43 Options
  44 -------
  45
  46 .. program:: qemu-storage-daemon
  47
  48 Standard options:
  49
  50 .. option:: -h, --help
  51
  52   Display help and exit
  53
  54 .. option:: -V, --version
  55
  56   Display version information and exit
  57
  58 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
  59
  60   .. include:: ../qemu-option-trace.rst.inc
  61
  62 .. option:: --blockdev BLOCKDEVDEF
  63
  64   is a block node definition. See the :manpage:`qemu(1)` manual page for a
  65   description of block node properties and the :manpage:`qemu-block-drivers(7)`
  66   manual page for a description of driver-specific parameters.
  67
  68 .. option:: --chardev CHARDEVDEF
  69
  70   is a character device definition. See the :manpage:`qemu(1)` manual page for
  71   a description of character device properties. A common character device
  72   definition configures a UNIX domain socket::
  73
  74   --chardev socket,id=char1,path=/var/run/qsd-qmp.sock,server=on,wait=off
  75
  76 .. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]
  77   --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>]
  78   --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>]
  79   --export [type=]fuse,id=<id>,node-name=<node-name>,mountpoint=<file>[,growable=on|off][,writable=on|off][,allow-other=on|off|auto]
  80   --export [type=]vduse-blk,id=<id>,node-name=<node-name>,name=<vduse-name>[,writable=on|off][,num-queues=<num-queues>][,queue-size=<queue-size>][,logical-block-size=<block-size>][,serial=<serial-number>]
  81
  82   is a block export definition. ``node-name`` is the block node that should be
  83   exported. ``writable`` determines whether or not the export allows write
  84   requests for modifying data (the default is off).
  85
  86   The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
  87   the NBD export name (if not specified, it defaults to the given
  88   ``node-name``). ``bitmap`` is the name of a dirty bitmap reachable from the
  89   block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
  90   metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
  91
  92   The ``vhost-user-blk`` export type takes a vhost-user socket address on which
  93   it accept incoming connections. Both
  94   ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
  95   ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
  96   ``logical-block-size`` sets the logical block size in bytes (the default is
  97   512). ``num-queues`` sets the number of virtqueues (the default is 1).
  98
  99   The ``fuse`` export type takes a mount point, which must be a regular file,
 100   on which to export the given block node. That file will not be changed, it
 101   will just appear to have the block node's content while the export is active
 102   (very much like mounting a filesystem on a directory does not change what the
 103   directory contains, it only shows a different content while the filesystem is
 104   mounted). Consequently, applications that have opened the given file before
 105   the export became active will continue to see its original content. If
 106   ``growable`` is set, writes after the end of the exported file will grow the
 107   block node to fit.  The ``allow-other`` option controls whether users other
 108   than the user running the process will be allowed to access the export.  Note
 109   that enabling this option as a non-root user requires enabling the
 110   user_allow_other option in the global fuse.conf configuration file.  Setting
 111   ``allow-other`` to auto (the default) will try enabling this option, and on
 112   error fall back to disabling it.
 113
 114   The ``vduse-blk`` export type takes a ``name`` (must be unique across the host)
 115   to create the VDUSE device.
 116   ``num-queues`` sets the number of virtqueues (the default is 1).
 117   ``queue-size`` sets the virtqueue descriptor table size (the default is 256).
 118
 119   The instantiated VDUSE device must then be added to the vDPA bus using the
 120   vdpa(8) command from the iproute2 project::
 121
 122   # vdpa dev add name <id> mgmtdev vduse
 123
 124   The device can be removed from the vDPA bus later as follows::
 125
 126   # vdpa dev del <id>
 127
 128   For more information about attaching vDPA devices to the host with
 129   virtio_vdpa.ko or attaching them to guests with vhost_vdpa.ko, see
 130   https://vdpa-dev.gitlab.io/.
 131
 132   For more information about VDUSE, see
 133   https://docs.kernel.org/userspace-api/vduse.html.
 134
 135 .. option:: --monitor MONITORDEF
 136
 137   is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
 138   a description of QMP monitor properties. A common QMP monitor definition
 139   configures a monitor on character device ``char1``::
 140
 141   --monitor chardev=char1
 142
 143 .. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
 144   --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
 145   --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
 146
 147   is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
 148   A listen socket can be provided via file descriptor passing (see Examples
 149   below). TLS encryption can be configured using ``--object`` tls-creds-* and
 150   authz-* secrets (see below).
 151
 152   To configure an NBD server on UNIX domain socket path
 153   ``/var/run/qsd-nbd.sock``::
 154
 155   --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
 156
 157 .. option:: --object help
 158   --object <type>,help
 159   --object <type>[,<property>=<value>...]
 160
 161   is a QEMU user creatable object definition. List object types with ``help``.
 162   List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
 163   manual page for a description of the object properties.
 164
 165 .. option:: --pidfile PATH
 166
 167   is the path to a file where the daemon writes its pid. This allows scripts to
 168   stop the daemon by sending a signal::
 169
 170     $ kill -SIGTERM $(<path/to/qsd.pid)
 171
 172   A file lock is applied to the file so only one instance of the daemon can run
 173   with a given pid file path. The daemon unlinks its pid file when terminating.
 174
 175   The pid file is written after chardevs, exports, and NBD servers have been
 176   created but before accepting connections. The daemon has started successfully
 177   when the pid file is written and clients may begin connecting.
 178
 179 .. option:: --daemonize
 180
 181   Daemonize the process. The parent process will exit once startup is complete
 182   (i.e., after the pid file has been or would have been written) or failure
 183   occurs. Its exit code reflects whether the child has started up successfully
 184   or failed to do so.
 185
 186 Examples
 187 --------
 188 Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
 189 QMP commands::
 190
 191   $ qemu-storage-daemon \
 192       --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
 193       --monitor chardev=char1
 194
 195 Launch the daemon from Python with a QMP monitor socket using file descriptor
 196 passing so there is no need to busy wait for the QMP monitor to become
 197 available::
 198
 199   #!/usr/bin/env python3
 200   import subprocess
 201   import socket
 202
 203   sock_path = '/var/run/qmp.sock'
 204
 205   with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
 206       listen_sock.bind(sock_path)
 207       listen_sock.listen()
 208
 209       fd = listen_sock.fileno()
 210
 211       subprocess.Popen(
 212           ['qemu-storage-daemon',
 213            '--chardev', f'socket,fd={fd},server=on,id=char1',
 214            '--monitor', 'chardev=char1'],
 215           pass_fds=[fd],
 216       )
 217
 218   # listen_sock was automatically closed when leaving the 'with' statement
 219   # body. If the daemon process terminated early then the following connect()
 220   # will fail with "Connection refused" because no process has the listen
 221   # socket open anymore. Launch errors can be detected this way.
 222
 223   qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
 224   qmp_sock.connect(sock_path)
 225   ...QMP interaction...
 226
 227 The same socket spawning approach also works with the ``--nbd-server
 228 addr.type=fd,addr.str=<fd>`` and ``--export
 229 type=vhost-user-blk,addr.type=fd,addr.str=<fd>`` options.
 230
 231 Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
 232
 233   $ qemu-storage-daemon \
 234       --blockdev driver=file,node-name=disk,filename=disk.img \
 235       --nbd-server addr.type=unix,addr.path=nbd.sock \
 236       --export type=nbd,id=export,node-name=disk,writable=on
 237
 238 Export a qcow2 image file ``disk.qcow2`` as a vhost-user-blk device over UNIX
 239 domain socket ``vhost-user-blk.sock``::
 240
 241   $ qemu-storage-daemon \
 242       --blockdev driver=file,node-name=file,filename=disk.qcow2 \
 243       --blockdev driver=qcow2,node-name=qcow2,file=file \
 244       --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
 245
 246 Export a qcow2 image file ``disk.qcow2`` via FUSE on itself, so the disk image
 247 file will then appear as a raw image::
 248
 249   $ qemu-storage-daemon \
 250       --blockdev driver=file,node-name=file,filename=disk.qcow2 \
 251       --blockdev driver=qcow2,node-name=qcow2,file=file \
 252       --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
 253
 254 See also
 255 --------
 256
 257 :manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`