[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Eric Blake
Subject: Re: [Qemu-devel] [PATCH v2 04/22] qemu-nbd: Enhance man page
Date: Mon, 17 Dec 2018 09:19:26 -0600
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.3.1

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:


   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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]