docs: add qemu-storage-daemon documentation
v3 cover docs: add qemu-storage-daemon documentation
v3:
* Address Kevin's comments
v2:
* Drop block-core.json h2 header removal, add an h1 header to storage-daemon/qapi/qapi-schema.json instead [Kevin]
* Add Examples section to man page [Kevin]
Add documentation for the qemu-storage-daemon program and its QMP commands.
The man page looks like this:
QEMU-STORAGE-DAEMON(1) QEMU QEMU-STORAGE-DAEMON(1)
NAME
qemu-storage-daemon - 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 con‐ trolled 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) connec‐ tion. See the 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 ma‐ chine or any other process; this may destroy the image. Also, be aware that querying an image that is being modified by an‐ other process may encounter inconsistent state.
OPTIONS
Standard options:
-h, --help
Display help and exit
-V, --version
Display version information and exit
-T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
Specify tracing options.
[enable=]PATTERN
Immediately enable events matching PATTERN (either event name or a globbing pattern). This option is only available if QEMU has been compiled with the simple, log or ftrace tracing backend. To specify multiple events or patterns, specify the -trace op‐ tion multiple times.
Use -trace help to print a list of names of trace points.
events=FILE
Immediately enable events listed in FILE. The file
must contain one event name (as listed in the trace-events-all file) per line; globbing patterns are accepted too. This option is only available if QEMU has been compiled with the simple, log or ftrace tracing backend.
file=FILE
Log output traces to FILE. This option is only
available if QEMU has been compiled with the simple tracing backend.
--blockdev BLOCKDEVDEF
is a block node definition. See the qemu(1) manual page for a description of block node properties and the qemu-block-drivers(7) manual page for a description of driver-specific parameters.
--chardev CHARDEVDEF
is a character device definition. See the qemu(1) manual page for a description of character device properties. A common character device definition configures a UNIX do‐ main socket:
--chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
--export [type=]nbd,id=<id>,node-name=<node-name>[,name=<ex‐
port-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][,log‐ ical-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][,log‐ ical-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 mod‐
ifying 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 meta‐ data 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 descrip‐ tor 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).
--monitor MONITORDEF
is a QMP monitor definition. See the 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
--nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-au‐ thz=<id>][,max-connections=<n>]
--nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐ thz=<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 be‐ low).
To configure an NBD server on UNIX domain socket path /tmp/nbd.sock:
--nbd-server addr.type=unix,addr.path=/tmp/nbd.sock
--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 qemu(1) manual page for a descrip‐ tion 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 de‐
vice 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=qcow2SEE ALSO
qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
COPYRIGHT
2020, The QEMU Project Developers
5.1.94 Dec 09, 2020 QEMU-STORAGE-DAEMON(1)
Stefan Hajnoczi (3):
docs: generate qemu-storage-daemon-qmp-ref(7) man page
docs: add qemu-storage-daemon(1) man page
MAINTAINERS: add Kevin Wolf as storage daemon maintainer
MAINTAINERS | 9 ++ docs/interop/index.rst | 1 + docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 ++ docs/tools/index.rst | 1 + docs/tools/qemu-storage-daemon.rst | 148 +++++++++++++++++++ storage-daemon/qapi/qapi-schema.json | 3 + docs/interop/conf.py | 2 + docs/meson.build | 1 + docs/tools/conf.py | 2 + 9 files changed, 180 insertions(+) create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst create mode 100644 docs/tools/qemu-storage-daemon.rst
Signature · 1 line
2.28.0
PATCH v3 1/3 docs: generate qemu-storage-daemon-qmp-ref(7) man page
Although individual qemu-storage-daemon QMP commands are identical to QEMU QMP commands, qemu-storage-daemon only supports a subset of QEMU's QMP commands. Generate a manual page of just the commands supported by qemu-storage-daemon so that users know exactly what is available in qemu-storage-daemon.
Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that block-core.json is at the h2 heading level.
--- docs/interop/index.rst | 1 + docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 +++++++++++++ storage-daemon/qapi/qapi-schema.json | 3 +++ docs/interop/conf.py | 2 ++ docs/meson.build | 1 + 5 files changed, 20 insertions(+) create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst
docs/interop/index.rst +1 -0
@@ -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
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +13 -0
@@ -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
storage-daemon/qapi/qapi-schema.json +3 -0
@@ -15,6 +15,9 @@ { 'include': '../../qapi/pragma.json' } +## +# = Block devices +## { 'include': '../../qapi/block-core.json' } { 'include': '../../qapi/block-export.json' } { 'include': '../../qapi/char.json' }
docs/interop/conf.py +2 -0
@@ -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), ]
docs/meson.build +1 -0
@@ -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' : ''),
Signature · 1 line
2.28.0
Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
Am 09.12.2020 um 11:38 hat Stefan Hajnoczi geschrieben:
Quoted 40 lines
Although individual qemu-storage-daemon QMP commands are identical to QEMU QMP commands, qemu-storage-daemon only supports a subset of QEMU's QMP commands. Generate a manual page of just the commands supported by qemu-storage-daemon so that users know exactly what is available in qemu-storage-daemon.
Add an h1 heading in
storage-daemon/qapi/qapi-schema.jsonso that block-core.json is at the h2 heading level.Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/interop/index.rst | 1 + docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 +++++++++++++ storage-daemon/qapi/qapi-schema.json | 3 +++ docs/interop/conf.py | 2 ++ docs/meson.build | 1 + 5 files changed, 20 insertions(+) create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rstdocs/interop/index.rst +1
-0@@ -20,6 +20,7 @@ Contents: qemu-ga qemu-ga-ref qemu-qmp-ref + qemu-storage-daemon-qmp-ref vhost-user vhost-user-gpu vhost-vdpadocs/interop/qemu-storage-daemon-qmp-ref.rst new file +3
-0@@ -0,0 +1,13 @@ +QEMU Storage Daemon QMP Reference Manual +======================================== +
docs/interop/qemu-storage-daemon-qmp-ref.rst line 13
Quoted 10 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +10
-0+.. + 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
Did you intend to actually merge the TODO comments like this into master or was this meant to be resolved before you send the series?
Kevin
Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
Quoted 14 lines · Kevin Wolf
Quoted 14 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +8
-0@@ -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. +
Quoted 8 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst line 13
Quoted 5 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +5
-0+.. + TODO: display the QEMU version, both here and in our Sphinx manuals + more generally. + +.. qapi-doc:: storage-daemon/qapi/qapi-schema.jsonDid you intend to actually merge the TODO comments like this into master or was this meant to be resolved before you send the series?
Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst have these comments and I copied them when creating the file. I don't intend to try to solve that in this series.
Would you like to keep the comments or should I drop them?
Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
Quoted 25 lines · Stefan Hajnoczi
Quoted 14 lines · Kevin Wolf
Quoted 14 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +8
-0@@ -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. +Quoted 8 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst line 13
Quoted 5 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +5
-0+.. + TODO: display the QEMU version, both here and in our Sphinx manuals + more generally. + +.. qapi-doc:: storage-daemon/qapi/qapi-schema.jsonDid you intend to actually merge the TODO comments like this into master or was this meant to be resolved before you send the series?
Quoted 5 lines
Thanks for pointing this out. Both
qemu-qmp-ref.rstandqemu-ga-ref.rsthave these comments and I copied them when creating the file. I don't intend to try to solve that in this series.Would you like to keep the comments or should I drop them?
FWIW, the ones in those two docs are the result of a request from Markus when we were doing the conversion of QAPI generated docs from Texinfo to rST -- the old separate Texinfo-generated docs ended up with a version/license statement in the generated docs. Fixing this depends I think on the "merge the 5 manuals into one single manual" patch; once that's done then it should be easier to have one consistent place to note license, copyright, version, etc.
thanks
-- PMM
Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
In reply to Stefan HajnocziAm 16.12.2020 um 17:21 hat Stefan Hajnoczi geschrieben:
Quoted 24 lines · Kevin Wolf
Quoted 14 lines
Quoted 14 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +8
-0@@ -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. +Quoted 8 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst line 13
Quoted 5 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +5
-0+.. + TODO: display the QEMU version, both here and in our Sphinx manuals + more generally. + +.. qapi-doc:: storage-daemon/qapi/qapi-schema.jsonDid you intend to actually merge the TODO comments like this into master or was this meant to be resolved before you send the series?
Quoted 5 lines
Thanks for pointing this out. Both
qemu-qmp-ref.rstandqemu-ga-ref.rsthave these comments and I copied them when creating the file. I don't intend to try to solve that in this series.Would you like to keep the comments or should I drop them?
Ah, I see. If the same already exists in other places, I'll just merge it as it is. Thanks!
Kevin
Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
Quoted 25 lines · Kevin Wolf
Am 16.12.2020 um 17:21 hat Stefan Hajnoczi geschrieben:
Quoted 24 lines · Kevin Wolf
Quoted 22 lines
Quoted 9 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +3
-0@@ -0,0 +1,13 @@ +QEMU Storage Daemon QMP Reference Manual +======================================== +docs/interop/qemu-storage-daemon-qmp-ref.rst line 13
Quoted 10 lines
docs/interop/qemu-storage-daemon-qmp-ref.rst new file +10
-0+.. + 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.jsonDid you intend to actually merge the TODO comments like this into master or was this meant to be resolved before you send the series?
Quoted 8 lines
Quoted 5 lines
Thanks for pointing this out. Both
qemu-qmp-ref.rstandqemu-ga-ref.rsthave these comments and I copied them when creating the file. I don't intend to try to solve that in this series.Would you like to keep the comments or should I drop them?
Ah, I see. If the same already exists in other places, I'll just merge it as it is. Thanks!
Great, thanks!
Stefan
PATCH v3 2/3 docs: add qemu-storage-daemon(1) man page
In reply to Stefan HajnocziDocument 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.
--- docs/tools/index.rst | 1 + docs/tools/qemu-storage-daemon.rst | 148 +++++++++++++++++++++++++++++ docs/tools/conf.py | 2 + 3 files changed, 151 insertions(+) create mode 100644 docs/tools/qemu-storage-daemon.rst
docs/tools/index.rst +1 -0
@@ -11,6 +11,7 @@ Contents: :maxdepth: 2 qemu-img + qemu-storage-daemon qemu-nbd qemu-pr-helper qemu-trace-stap
docs/tools/qemu-storage-daemon.rst new file +148 -0
148 lines not on this page · raw message
docs/tools/conf.py +2 -0
@@ -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 <[email protected]>'], 8), ('qemu-pr-helper', 'qemu-pr-helper', 'QEMU persistent reservation helper',
Signature · 1 line
2.28.0
PATCH v3 3/3 MAINTAINERS: add Kevin Wolf as storage daemon maintainer
In reply to Stefan HajnocziThe MAINTAINERS file was not updated when the storage daemon was merged.
--- MAINTAINERS | 9 +++++++++ 1 file changed, 9 insertions(+)
MAINTAINERS +9 -0
@@ -2146,6 +2146,15 @@ F: qobject/block-qdict.c F: tests/check-block-qdict.c T: git https://repo.or.cz/qemu/kevin.git block +Storage daemon +M: Kevin Wolf <[email protected]> +L: [email protected] +S: Supported +F: storage-daemon/ +F: docs/interop/qemu-storage-daemon-qmp-ref.rst +F: docs/tools/qemu-storage-daemon.rst +T: git https://repo.or.cz/qemu/kevin.git block + Block I/O path M: Stefan Hajnoczi <[email protected]> M: Fam Zheng <[email protected]>
Signature · 1 line
2.28.0