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

[Stefan Hajnoczi <stefanha@redhat.com>]

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 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:
       · Blockdev nodes
       · Block jobs
       · NBD server
       · Character devices
       · Crypto and secrets
       · 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 querying
       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=]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 option 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 blockdev node definition. See the qemu(1) manual page for a description of blockdev 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
              domain socket:

                 --chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait

       --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-authz=<id>]

       --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>]
              is a NBD server definition. 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

       --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 description of the
              object properties. The most common object type is a secret, which is used to supply passwords and/or encryption keys.

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,device=disk,writable=on

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

COPYRIGHT
       2020, The QEMU Project Developers

5.1.50                     Sep 10, 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 ++
 storage-daemon/qapi/qapi-schema.json          |   4 +
 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            | 121 ++++++++++++++++++
 meson.build                                   |   9 ++
 storage-daemon/qapi/meson.build               |   2 +
 8 files changed, 228 insertions(+)
 create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.texi
 create mode 100644 docs/tools/qemu-storage-daemon.rst

-- 
2.26.2