219 lines
8.2 KiB
Diff
219 lines
8.2 KiB
Diff
From f3831252e618e420ea24e53dbdee8eb51e8cad3e Mon Sep 17 00:00:00 2001
|
|
From: Kevin Wolf <kwolf@redhat.com>
|
|
Date: Tue, 16 Feb 2021 16:19:40 -0500
|
|
Subject: [PATCH 14/54] docs: add qemu-storage-daemon(1) man page
|
|
|
|
RH-Author: Kevin Wolf <kwolf@redhat.com>
|
|
Message-id: <20210216161943.126728-3-kwolf@redhat.com>
|
|
Patchwork-id: 101102
|
|
O-Subject: [RHEL-AV-8.4.0 qemu-kvm PATCH 2/5] docs: add qemu-storage-daemon(1) man page
|
|
Bugzilla: 1901323
|
|
RH-Acked-by: Sergio Lopez Pascual <slp@redhat.com>
|
|
RH-Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
|
|
RH-Acked-by: Max Reitz <mreitz@redhat.com>
|
|
|
|
From: Stefan Hajnoczi <stefanha@redhat.com>
|
|
|
|
Document the qemu-storage-daemon tool. Most of the command-line options
|
|
are identical to their QEMU counterparts. Perhaps Sphinx hxtool
|
|
integration could be extended to extract documentation for individual
|
|
command-line options so they can be shared. For now the
|
|
qemu-storage-daemon simply refers to the qemu(1) man page where the
|
|
command-line options are identical.
|
|
|
|
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
|
|
Message-Id: <20201209103802.350848-3-stefanha@redhat.com>
|
|
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
|
|
(cherry picked from commit 1982e1602d15313cd82f225e821c37733ece3404)
|
|
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
|
|
Signed-off-by: Danilo C. L. de Paula <ddepaula@redhat.com>
|
|
---
|
|
docs/tools/conf.py | 2 +
|
|
docs/tools/index.rst | 1 +
|
|
docs/tools/qemu-storage-daemon.rst | 148 +++++++++++++++++++++++++++++
|
|
3 files changed, 151 insertions(+)
|
|
create mode 100644 docs/tools/qemu-storage-daemon.rst
|
|
|
|
diff --git a/docs/tools/conf.py b/docs/tools/conf.py
|
|
index 4760d36ff2..7072d99324 100644
|
|
--- a/docs/tools/conf.py
|
|
+++ b/docs/tools/conf.py
|
|
@@ -20,6 +20,8 @@ html_theme_options['description'] = \
|
|
man_pages = [
|
|
('qemu-img', 'qemu-img', u'QEMU disk image utility',
|
|
['Fabrice Bellard'], 1),
|
|
+ ('qemu-storage-daemon', 'qemu-storage-daemon', u'QEMU storage daemon',
|
|
+ [], 1),
|
|
('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
|
|
['Anthony Liguori <anthony@codemonkey.ws>'], 8),
|
|
('qemu-pr-helper', 'qemu-pr-helper', 'QEMU persistent reservation helper',
|
|
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
|
|
index b99f86c7c6..3a5829c17a 100644
|
|
--- a/docs/tools/index.rst
|
|
+++ b/docs/tools/index.rst
|
|
@@ -11,6 +11,7 @@ Contents:
|
|
:maxdepth: 2
|
|
|
|
qemu-img
|
|
+ qemu-storage-daemon
|
|
qemu-nbd
|
|
qemu-pr-helper
|
|
qemu-trace-stap
|
|
diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
|
|
new file mode 100644
|
|
index 0000000000..f63627eaf6
|
|
--- /dev/null
|
|
+++ b/docs/tools/qemu-storage-daemon.rst
|
|
@@ -0,0 +1,148 @@
|
|
+QEMU Storage Daemon
|
|
+===================
|
|
+
|
|
+Synopsis
|
|
+--------
|
|
+
|
|
+**qemu-storage-daemon** [options]
|
|
+
|
|
+Description
|
|
+-----------
|
|
+
|
|
+qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
|
|
+qemu-nbd in a long-running process controlled via QMP commands without running
|
|
+a virtual machine. It can export disk images, run block job operations, and
|
|
+perform other disk-related operations. The daemon is controlled via a QMP
|
|
+monitor and initial configuration from the command-line.
|
|
+
|
|
+The daemon offers the following subset of QEMU features:
|
|
+
|
|
+* Block nodes
|
|
+* Block jobs
|
|
+* Block exports
|
|
+* Throttle groups
|
|
+* Character devices
|
|
+* Crypto and secrets
|
|
+* QMP
|
|
+* IOThreads
|
|
+
|
|
+Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
|
|
+:manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the
|
|
+commands.
|
|
+
|
|
+The daemon runs until it is stopped using the ``quit`` QMP command or
|
|
+SIGINT/SIGHUP/SIGTERM.
|
|
+
|
|
+**Warning:** Never modify images in use by a running virtual machine or any
|
|
+other process; this may destroy the image. Also, be aware that querying an
|
|
+image that is being modified by another process may encounter inconsistent
|
|
+state.
|
|
+
|
|
+Options
|
|
+-------
|
|
+
|
|
+.. program:: qemu-storage-daemon
|
|
+
|
|
+Standard options:
|
|
+
|
|
+.. option:: -h, --help
|
|
+
|
|
+ Display help and exit
|
|
+
|
|
+.. option:: -V, --version
|
|
+
|
|
+ Display version information and exit
|
|
+
|
|
+.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
|
|
+
|
|
+ .. include:: ../qemu-option-trace.rst.inc
|
|
+
|
|
+.. option:: --blockdev BLOCKDEVDEF
|
|
+
|
|
+ is a block node definition. See the :manpage:`qemu(1)` manual page for a
|
|
+ description of block node properties and the :manpage:`qemu-block-drivers(7)`
|
|
+ manual page for a description of driver-specific parameters.
|
|
+
|
|
+.. option:: --chardev CHARDEVDEF
|
|
+
|
|
+ is a character device definition. See the :manpage:`qemu(1)` manual page for
|
|
+ a description of character device properties. A common character device
|
|
+ definition configures a UNIX domain socket::
|
|
+
|
|
+ --chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
|
|
+
|
|
+.. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]
|
|
+ --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>]
|
|
+ --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>]
|
|
+
|
|
+ is a block export definition. ``node-name`` is the block node that should be
|
|
+ exported. ``writable`` determines whether or not the export allows write
|
|
+ requests for modifying data (the default is off).
|
|
+
|
|
+ The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
|
|
+ the NBD export name. ``bitmap`` is the name of a dirty bitmap reachable from
|
|
+ the block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
|
|
+ metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
|
|
+
|
|
+ The ``vhost-user-blk`` export type takes a vhost-user socket address on which
|
|
+ it accept incoming connections. Both
|
|
+ ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
|
|
+ ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
|
|
+ ``logical-block-size`` sets the logical block size in bytes (the default is
|
|
+ 512). ``num-queues`` sets the number of virtqueues (the default is 1).
|
|
+
|
|
+.. option:: --monitor MONITORDEF
|
|
+
|
|
+ is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
|
|
+ a description of QMP monitor properties. A common QMP monitor definition
|
|
+ configures a monitor on character device ``char1``::
|
|
+
|
|
+ --monitor chardev=char1
|
|
+
|
|
+.. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
|
|
+ --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
|
|
+
|
|
+ is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
|
|
+ TLS encryption can be configured using ``--object`` tls-creds-* and authz-*
|
|
+ secrets (see below).
|
|
+
|
|
+ To configure an NBD server on UNIX domain socket path ``/tmp/nbd.sock``::
|
|
+
|
|
+ --nbd-server addr.type=unix,addr.path=/tmp/nbd.sock
|
|
+
|
|
+.. option:: --object help
|
|
+ --object <type>,help
|
|
+ --object <type>[,<property>=<value>...]
|
|
+
|
|
+ is a QEMU user creatable object definition. List object types with ``help``.
|
|
+ List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
|
|
+ manual page for a description of the object properties.
|
|
+
|
|
+Examples
|
|
+--------
|
|
+Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
|
|
+QMP commands::
|
|
+
|
|
+ $ qemu-storage-daemon \
|
|
+ --chardev socket,path=qmp.sock,server,nowait,id=char1 \
|
|
+ --monitor chardev=char1
|
|
+
|
|
+Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
|
|
+
|
|
+ $ qemu-storage-daemon \
|
|
+ --blockdev driver=file,node-name=disk,filename=disk.img \
|
|
+ --nbd-server addr.type=unix,addr.path=nbd.sock \
|
|
+ --export type=nbd,id=export,node-name=disk,writable=on
|
|
+
|
|
+Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX
|
|
+domain socket ``vhost-user-blk.sock``::
|
|
+
|
|
+ $ qemu-storage-daemon \
|
|
+ --blockdev driver=file,node-name=file,filename=disk.qcow2 \
|
|
+ --blockdev driver=qcow2,node-name=qcow2,file=file \
|
|
+ --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
|
|
+
|
|
+See also
|
|
+--------
|
|
+
|
|
+:manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`
|
|
--
|
|
2.27.0
|
|
|