[PATCH 0/4] docs: add qemu-storage-daemon documentation

Stefan Hajnoczi posted 4 patches 3 years, 7 months ago
Test docker-quick@centos7 failed
Test docker-mingw@fedora failed
Test checkpatch failed
Test FreeBSD failed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20200908093113.47564-1-stefanha@redhat.com
There is a newer version of this series
MAINTAINERS                                   |   9 ++
docs/interop/firmware.json                    |   4 +
qapi/block-core.json                          |   4 -
qapi/block.json                               |   1 +
docs/interop/qemu-storage-daemon-qmp-ref.texi |  80 +++++++++++++
docs/tools/conf.py                            |   2 +
docs/tools/index.rst                          |   1 +
docs/tools/qemu-storage-daemon.rst            | 105 ++++++++++++++++++
meson.build                                   |   9 ++
storage-daemon/qapi/meson.build               |   2 +
10 files changed, 213 insertions(+), 4 deletions(-)
create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.texi
create mode 100644 docs/tools/qemu-storage-daemon.rst
[PATCH 0/4] docs: add qemu-storage-daemon documentation
Posted by Stefan Hajnoczi 3 years, 7 months ago
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 controlled via QMP
       commands without running a virtual machine.

       It can export disk images over NBD, run block job operations, and
       perform other disk-related operations. The daemon is controlled via a
       QMP monitor socket and initial configuration from the command-line.

       The daemon offers the following subset of QEMU features:

       =C2=B7 Blockdev nodes

       =C2=B7 Block jobs

       =C2=B7 NBD server

       =C2=B7 Character devices

       =C2=B7 Crypto and secrets

       =C2=B7 QMP

       Commands can be sent over a QEMU Monitor Protocol (QMP) connection. 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 machine or any
       other process; this may destroy the image. Also, be aware that queryin=
g an
       image that is being modified by another process may encounter
       inconsistent state.

OPTIONS
       Standard options:

       -h, --help
              Display this help and exit

       -V, --version
              Display version information and exit

       -T, --trace [[enable=3D]PATTERN][,events=3DFILE][,file=3DFILE]
              Specify tracing options.

              [enable=3D]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 o=
r patterns, specify the -trace option multiple times.

                     Use -trace help to print a list of names of trace points.

              events=3DFILE
                     Immediately  enable  events  listed in FILE.  The file m=
ust 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 com=
piled with the simple, log or ftrace tracing backend.

              file=3DFILE
                     Log output traces to FILE.  This option is only availabl=
e if QEMU has been compiled with the simple tracing backend.

       --blockdev BLOCKDEVDEF
              is a blockdev node definition. See the qemu(1) manual page for =
a description of blockdev node properties and the qemu-block-drivers(7) manua=
l page  for  a  description  of
              driver-specific parameters.

       --chardev CHARDEVDEF
              is  a  character  device  definition.  See the qemu(1) manual p=
age for a description of character device properties. A common character devi=
ce definition configures a UNIX
              domain socket:

                 --chardev socket,id=3Dchar1,path=3D/tmp/qmp.sock,server,nowa=
it

       --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 config=
ures  a  monitor  on  character
              device char1:

                 --monitor chardev=3Dchar1

       --nbd-server addr.type=3Dinet,addr.host=3D<host>,addr.port=3D<port>[,t=
ls-creds=3D<id>][,tls-authz=3D<id>]

       --nbd-server addr.type=3Dunix,addr.path=3D<path>[,tls-creds=3D<id>][,t=
ls-authz=3D<id>]
              is a NBD server definition. Both TCP and UNIX domain sockets ar=
e 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=3Dunix,addr.path=3D/tmp/nbd.sock

       --object help

       --object <type>,help

       --object <type>[,<property>=3D<value>...]
              is  a  QEMU  user  creatable object definition. List object typ=
es with help.  List object properties with <type>,help. See the qemu(1) manua=
l page for a description of the
              object properties. The most common object type is a secret, whi=
ch is used to supply passwords and/or encryption keys.

SEE ALSO
       qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)

COPYRIGHT
       2020, The QEMU Project Developers

5.1.50                            Sep 08, 2020        QEMU-STORAGE-DAEMON(1)

Stefan Hajnoczi (4):
  docs: lift block-core.json rST header into parents
  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/firmware.json                    |   4 +
 qapi/block-core.json                          |   4 -
 qapi/block.json                               |   1 +
 docs/interop/qemu-storage-daemon-qmp-ref.texi |  80 +++++++++++++
 docs/tools/conf.py                            |   2 +
 docs/tools/index.rst                          |   1 +
 docs/tools/qemu-storage-daemon.rst            | 105 ++++++++++++++++++
 meson.build                                   |   9 ++
 storage-daemon/qapi/meson.build               |   2 +
 10 files changed, 213 insertions(+), 4 deletions(-)
 create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.texi
 create mode 100644 docs/tools/qemu-storage-daemon.rst

--=20
2.26.2