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

[Stefan Hajnoczi]

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

-- 
2.28.0