aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2020-12-31 19:16:13 +0000
committerPeter Maydell <peter.maydell@linaro.org>2020-12-31 19:16:13 +0000
commitc7e48f91653d6ace9dc42ec6b5b627b57d5d49e0 (patch)
treeeb748b8d0a1fc4a06cf13f6a5b6e157a2b3e8187 /docs
parent3fb340ccf5f8385088a3d3b0e07763a8f5b85f4a (diff)
parentbe7c5ddd0d80e2d6cf8e3ef12c049851d28d9c26 (diff)
Merge remote-tracking branch 'remotes/kevin/tags/for-upstream' into staging
Block layer patches: - Add qemu-storage-daemon documentation - hw/block/nand: Decommission the NAND museum - vpc: Clean up some buffer abuse - nfs: fix int overflow in nfs_client_open_qdict - Several iotests fixes # gpg: Signature made Fri 18 Dec 2020 12:07:30 GMT # gpg: using RSA key DC3DEB159A9AF95D3D7456FE7F09B272C88F2FD6 # gpg: issuer "kwolf@redhat.com" # gpg: Good signature from "Kevin Wolf <kwolf@redhat.com>" [full] # Primary key fingerprint: DC3D EB15 9A9A F95D 3D74 56FE 7F09 B272 C88F 2FD6 * remotes/kevin/tags/for-upstream: block/vpc: Use sizeof() instead of HEADER_SIZE for footer size block/vpc: Pass footer buffers as VHDFooter * instead of uint8_t * block/vpc: Pad VHDFooter, replace uint8_t[] buffers block/vpc: Use sizeof() instead of 1024 for dynamic header size block/vpc: Pad VHDDynDiskHeader, replace uint8_t[] buffers block/vpc: Make vpc_checksum() take void * block/vpc: Don't abuse the footer buffer for dynamic header block/vpc: Don't abuse the footer buffer as BAT sector buffer block/vpc: Make vpc_open() read the full dynamic header iotests:172: use _filter_qom_path iotests: make _filter_qom_path more strict MAINTAINERS: add Kevin Wolf as storage daemon maintainer docs: add qemu-storage-daemon(1) man page docs: generate qemu-storage-daemon-qmp-ref(7) man page block/nfs: fix int overflow in nfs_client_open_qdict hw/block/nand: Decommission the NAND museum iotests/210: Fix reference output Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/interop/conf.py2
-rw-r--r--docs/interop/index.rst1
-rw-r--r--docs/interop/qemu-storage-daemon-qmp-ref.rst13
-rw-r--r--docs/meson.build1
-rw-r--r--docs/tools/conf.py2
-rw-r--r--docs/tools/index.rst1
-rw-r--r--docs/tools/qemu-storage-daemon.rst148
7 files changed, 168 insertions, 0 deletions
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index 2634ca3410..f4370aaa13 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -23,4 +23,6 @@ man_pages = [
[], 7),
('qemu-qmp-ref', 'qemu-qmp-ref', 'QEMU QMP Reference Manual',
[], 7),
+ ('qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref',
+ 'QEMU Storage Daemon QMP Reference Manual', [], 7),
]
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index cd78d679d8..95d56495f6 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -20,6 +20,7 @@ Contents:
qemu-ga
qemu-ga-ref
qemu-qmp-ref
+ qemu-storage-daemon-qmp-ref
vhost-user
vhost-user-gpu
vhost-vdpa
diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
new file mode 100644
index 0000000000..caf9dad23a
--- /dev/null
+++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
@@ -0,0 +1,13 @@
+QEMU Storage Daemon QMP Reference Manual
+========================================
+
+..
+ TODO: the old Texinfo manual used to note that this manual
+ is GPL-v2-or-later. We should make that reader-visible
+ both here and in our Sphinx manuals more generally.
+
+..
+ TODO: display the QEMU version, both here and in our Sphinx manuals
+ more generally.
+
+.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
diff --git a/docs/meson.build b/docs/meson.build
index bb8fe4c9e4..71641b4fe0 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -56,6 +56,7 @@ if build_docs
'qemu-ga.8': (have_tools ? 'man8' : ''),
'qemu-ga-ref.7': 'man7',
'qemu-qmp-ref.7': 'man7',
+ 'qemu-storage-daemon-qmp-ref.7': (have_tools ? 'man7' : ''),
},
'tools': {
'qemu-img.1': (have_tools ? 'man1' : ''),
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)`