Re: [PATCH 3/4] docs: add qemu-storage-daemon(1) man page

[Kashyap Chamarthy <kchamart@redhat.com>]

On Tue, Sep 08, 2020 at 10:31:12AM +0100, Stefan Hajnoczi wrote:
> 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.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/tools/conf.py                 |   2 +
>  docs/tools/index.rst               |   1 +
>  docs/tools/qemu-storage-daemon.rst | 105 +++++++++++++++++++++++++++++
>  3 files changed, 108 insertions(+)
>  create mode 100644 docs/tools/qemu-storage-daemon.rst
> 
> diff --git a/docs/tools/conf.py b/docs/tools/conf.py
> index 9052d17d6d..c16290e716 100644
> --- a/docs/tools/conf.py
> +++ b/docs/tools/conf.py
> @@ -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 <anthony@codemonkey.ws>'], 8),
>      ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
> diff --git a/docs/tools/index.rst b/docs/tools/index.rst
> index 232ce9f3e4..9b076adb62 100644
> --- a/docs/tools/index.rst
> +++ b/docs/tools/index.rst
> @@ -11,6 +11,7 @@ Contents:
>     :maxdepth: 2
>  
>     qemu-img
> +   qemu-storage-daemon
>     qemu-nbd
>     qemu-trace-stap
>     virtfs-proxy-helper
> diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
> new file mode 100644
> index 0000000000..729a5e7248
> --- /dev/null
> +++ b/docs/tools/qemu-storage-daemon.rst
> @@ -0,0 +1,105 @@
> +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
> +:manpage:`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.

I wonder if it's appropriate to mention libguestfs for safe, read-only
access to disk images (via `guestfish -ro -i -a disk.qcow2`).  I say
this because, the above warning tells what _not_ to do; a pointer on
what to do could be useful.  I let you decide on this.

The rest looks good to me; I couldn't even spot a typo.


Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>

[...]

-- 
/kashyap