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]
  80
  81   is a block export definition. ``node-name`` is the block node that should be
  82   exported. ``writable`` determines whether or not the export allows write
  83   requests for modifying data (the default is off).
  84
  85   The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
  86   the NBD export name (if not specified, it defaults to the given
  87   ``node-name``). ``bitmap`` is the name of a dirty bitmap reachable from the
  88   block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
  89   metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
  90
  91   The ``vhost-user-blk`` export type takes a vhost-user socket address on which
  92   it accept incoming connections. Both
  93   ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
  94   ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
  95   ``logical-block-size`` sets the logical block size in bytes (the default is
  96   512). ``num-queues`` sets the number of virtqueues (the default is 1).
  97
  98   The ``fuse`` export type takes a mount point, which must be a regular file,
  99   on which to export the given block node. That file will not be changed, it
 100   will just appear to have the block node's content while the export is active
 101   (very much like mounting a filesystem on a directory does not change what the
 102   directory contains, it only shows a different content while the filesystem is
 103   mounted). Consequently, applications that have opened the given file before
 104   the export became active will continue to see its original content. If
 105   ``growable`` is set, writes after the end of the exported file will grow the
 106   block node to fit.
 107
 108 .. option:: --monitor MONITORDEF
 109
 110   is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
 111   a description of QMP monitor properties. A common QMP monitor definition
 112   configures a monitor on character device ``char1``::
 113
 114   --monitor chardev=char1
 115
 116 .. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
 117   --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
 118   --nbd-server addr.type=fd,addr.str=<fd>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
 119
 120   is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
 121   A listen socket can be provided via file descriptor passing (see Examples
 122   below). TLS encryption can be configured using ``--object`` tls-creds-* and
 123   authz-* secrets (see below).
 124
 125   To configure an NBD server on UNIX domain socket path
 126   ``/var/run/qsd-nbd.sock``::
 127
 128   --nbd-server addr.type=unix,addr.path=/var/run/qsd-nbd.sock
 129
 130 .. option:: --object help
 131   --object <type>,help
 132   --object <type>[,<property>=<value>...]
 133
 134   is a QEMU user creatable object definition. List object types with ``help``.
 135   List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
 136   manual page for a description of the object properties.
 137
 138 .. option:: --pidfile PATH
 139
 140   is the path to a file where the daemon writes its pid. This allows scripts to
 141   stop the daemon by sending a signal::
 142
 143     $ kill -SIGTERM $(<path/to/qsd.pid)
 144
 145   A file lock is applied to the file so only one instance of the daemon can run
 146   with a given pid file path. The daemon unlinks its pid file when terminating.
 147
 148   The pid file is written after chardevs, exports, and NBD servers have been
 149   created but before accepting connections. The daemon has started successfully
 150   when the pid file is written and clients may begin connecting.
 151
 152 Examples
 153 --------
 154 Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
 155 QMP commands::
 156
 157   $ qemu-storage-daemon \
 158       --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
 159       --monitor chardev=char1
 160
 161 Launch the daemon from Python with a QMP monitor socket using file descriptor
 162 passing so there is no need to busy wait for the QMP monitor to become
 163 available::
 164
 165   #!/usr/bin/env python3
 166   import subprocess
 167   import socket
 168
 169   sock_path = '/var/run/qmp.sock'
 170
 171   with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listen_sock:
 172       listen_sock.bind(sock_path)
 173       listen_sock.listen()
 174
 175       fd = listen_sock.fileno()
 176
 177       subprocess.Popen(
 178           ['qemu-storage-daemon',
 179            '--chardev', f'socket,fd={fd},server=on,id=char1',
 180            '--monitor', 'chardev=char1'],
 181           pass_fds=[fd],
 182       )
 183
 184   # listen_sock was automatically closed when leaving the 'with' statement
 185   # body. If the daemon process terminated early then the following connect()
 186   # will fail with "Connection refused" because no process has the listen
 187   # socket open anymore. Launch errors can be detected this way.
 188
 189   qmp_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
 190   qmp_sock.connect(sock_path)
 191   ...QMP interaction...
 192
 193 The same socket spawning approach also works with the ``--nbd-server
 194 addr.type=fd,addr.str=<fd>`` and ``--export
 195 type=vhost-user-blk,addr.type=fd,addr.str=<fd>`` options.
 196
 197 Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
 198
 199   $ qemu-storage-daemon \
 200       --blockdev driver=file,node-name=disk,filename=disk.img \
 201       --nbd-server addr.type=unix,addr.path=nbd.sock \
 202       --export type=nbd,id=export,node-name=disk,writable=on
 203
 204 Export a qcow2 image file ``disk.qcow2`` as a vhost-user-blk device over UNIX
 205 domain socket ``vhost-user-blk.sock``::
 206
 207   $ qemu-storage-daemon \
 208       --blockdev driver=file,node-name=file,filename=disk.qcow2 \
 209       --blockdev driver=qcow2,node-name=qcow2,file=file \
 210       --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
 211
 212 Export a qcow2 image file ``disk.qcow2`` via FUSE on itself, so the disk image
 213 file will then appear as a raw image::
 214
 215   $ qemu-storage-daemon \
 216       --blockdev driver=file,node-name=file,filename=disk.qcow2 \
 217       --blockdev driver=qcow2,node-name=qcow2,file=file \
 218       --export type=fuse,id=export,node-name=qcow2,mountpoint=disk.qcow2,writable=on
 219
 220 See also
 221 --------
 222
 223 :manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`