docs/tools/qemu-storage-daemon.rst

   1 QEMU Storage Daemon
   2 ===================
   3
   4 Synopsis
   5 --------
   6
   7 **qemu-storage-daemon** [options]
   8
   9 Description
  10 -----------
  11
  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.
  17
  18 The 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
  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
  31 commands.
  32
  33 The daemon runs until it is stopped using the ``quit`` QMP command or
  34 SIGINT/SIGHUP/SIGTERM.
  35
  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
  39 state.
  40
  41 Options
  42 -------
  43
  44 .. program:: qemu-storage-daemon
  45
  46 Standard 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=on,wait=off
  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
 121 Examples
 122 --------
 123 Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
 124 QMP commands::
 125
 126   $ qemu-storage-daemon \
 127       --chardev socket,path=qmp.sock,server=on,wait=off,id=char1 \
 128       --monitor chardev=char1
 129
 130 Export 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
 137 Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX
 138 domain 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
 145 See also
 146 --------
 147
 148 :manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`