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 <ebl...@redhat.com>
---
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.
+@c 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
