Skip to contentSkip to conversation

docs: add qemu-storage-daemon documentation

PATCH In review Stefan Hajnoczi 3 participants 9 messages Dec 9, 2020 – Dec 17, 2020 Arm/Amlogic Meson SoC support

lore
Share & tools
lore
#0 lore raw

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=qcow2

SEE 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
#1 lore raw

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
index cd78d679d8..95d56495f6 100644
@@ -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
new file mode 100644
index 0000000000..caf9dad23a
@@ -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
index c6ad5ae1e3..28117c3aac 100644
@@ -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
index 2634ca3410..f4370aaa13 100644
@@ -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
index ebd85d59f9..df5dc50485 100644
@@ -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
#2 lore raw

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.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
index cd78d679d8..95d56495f6 100644
@@ -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 +3 -0
new file mode 100644
index 0000000000..caf9dad23a
@@ -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

#3 lore raw

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
new file mode 100644
index 0000000000..caf9dad23a
@@ -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.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?

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?

#4 lore raw

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
new file mode 100644
index 0000000000..caf9dad23a
@@ -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.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?

Quoted 5 lines

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?

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

#5 lore raw

Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page

In reply to Stefan Hajnoczi

Am 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
new file mode 100644
index 0000000000..caf9dad23a
@@ -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.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?

Quoted 5 lines

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?

Ah, I see. If the same already exists in other places, I'll just merge it as it is. Thanks!

Kevin

#6 lore raw

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
new file mode 100644
index 0000000000..caf9dad23a
@@ -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?

Quoted 8 lines
Quoted 5 lines

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?

Ah, I see. If the same already exists in other places, I'll just merge it as it is. Thanks!

Great, thanks!

Stefan

#7 lore raw

PATCH v3 2/3 docs: add qemu-storage-daemon(1) man page

In reply to Stefan Hajnoczi

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.

---
 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
index b99f86c7c6..3a5829c17a 100644
@@ -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
index 4760d36ff2..7072d99324 100644
@@ -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
#8 lore raw

PATCH v3 3/3 MAINTAINERS: add Kevin Wolf as storage daemon maintainer

In reply to Stefan Hajnoczi

The MAINTAINERS file was not updated when the storage daemon was merged.

---
 MAINTAINERS | 9 +++++++++
 1 file changed, 9 insertions(+)
MAINTAINERS +9 -0
index 68bc160f41..8676730cc9 100644
@@ -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