Re: [Qemu-devel] [PATCH v2 04/22] qemu-nbd: Enhance man page

[Eric Blake]

On 12/15/18 8:13 AM, Richard W.M. Jones wrote:
> On Sat, Dec 15, 2018 at 07:53:06AM -0600, Eric Blake wrote:
> > Document some useful qemu-nbd command lines. Mention some restrictions
> > on particular options, like -p being only for MBR images, or -c/-d
> > being Linux-only.  Update some text given the recent change to no
> > longer serve oldstyle protocol (missed in commit 7f7dfe2a).  Also,
> > consistently use trailing '.' in describing options.
> >
> > Signed-off-by: Eric Blake <address@hidden>
> >
> > ---
> > v2: new patch
> > ---
> >   qemu-nbd.texi | 85 +++++++++++++++++++++++++++++++++++++++------------
> >   1 file changed, 66 insertions(+), 19 deletions(-)
> >
> > diff --git a/qemu-nbd.texi b/qemu-nbd.texi
> > index 9a84e81eed9..0e24c2801ee 100644
> > --- a/qemu-nbd.texi
> > +++ b/qemu-nbd.texi
> > @@ -8,7 +8,10 @@
> >
> >   @c man begin DESCRIPTION
> >
> > -Export a QEMU disk image using the NBD protocol.
> > +Provide access to various QEMU NBD features.  Most commonly used to
> > +export a QEMU disk image using the NBD protocol as a server, but can
> > +also be used (on Linux) to manage kernel bindings of a /dev/nbdX
> > +block device to a QEMU server.
>
> This is only a minor quibble, but I thought the original text was a
> good summary, and only needs additional paragraphs describing the more
> minor use cases.  Thus the description would become by the end of the
> patch series:
>
>    DESCRIPTION
>
>    Export a QEMU disk image using the NBD protocol.
>
>    Other uses:
>    * (On Linux) bind /dev/nbdX block device to a QEMU server.
>    * As a client to query exports of a remote NBD server.

Seems reasonable.

> > address@hidden man begin EXAMPLES
> > +Start a server listening on port 10809 that exposes only the
> > +guest-visible contents of a qcow2 file, with no TLS encryption, and
> > +with the default export name (an empty string). The command will block
> > +until the first successful client disconnects:
>
> TBH I'd always include the -t option in every example.  I don't
> understand (except for backwards compatibility) why it isn't the
> default since it's something I always trip over when using qemu-nbd.

I'd still like one example without -t, to call out specifically that it 
creates a one-shot server that goes away after the first client, but 
don't mind fixing the rest of the examples to use -t.

Using -e for read-only connections makes sense, using -e for writable 
exports is a bit more questionable - we _don't_ advertise the 
NBD_FLAG_CAN_MULTI_CONN which states that caches are kept consistent 
between simultaneous write connections, although maybe we should see if 
qemu-nbd can start promising multi-write consistency in future patches?

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org