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

[Stefan Hajnoczi <stefanha@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 6749 bytes --]

On Thu, Sep 10, 2020 at 03:43:57PM +0100, Stefan Hajnoczi wrote:
> 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]

Ping

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]