[Libguestfs] [nbdkit PATCH] nbd: Give some examples

[Eric Blake]

The docs are a lot more useful with a graphic showing how to wire
together nbdkit as a bridge from old-to-new. The converse, bridging
new-to-old, is best deferred until I add support for the nbd plugin
connecting to a TCP socket.

It is also worth mentioning use of nbdkit filters (after all, qemu-nbd
4.0 was able to deprecate its --partition option by pointing to
'nbdkit --filter=partition nbd ...' as a viable replacement).

Signed-off-by: Eric Blake <eblake at redhat.com>
---

I'm pushing this one now, but as it is docs, I'm at least posting it
in case you have suggestions for improvements. I've got a counterpart
patch coming up that documents using the nbd plugin to a TCP
connection to provide TLS support from a modern NBD server to an
ancient oldstyle-only client, once I actually add TCP support.

 plugins/nbd/nbdkit-nbd-plugin.pod | 38 +++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/plugins/nbd/nbdkit-nbd-plugin.pod b/plugins/nbd/nbdkit-nbd-plugin.pod
index cd0db09..5add56f 100644
--- a/plugins/nbd/nbdkit-nbd-plugin.pod
+++ b/plugins/nbd/nbdkit-nbd-plugin.pod
@@ -14,8 +14,10 @@ It provides an NBD server that forwards all traffic as a client to
 another existing NBD server.  A primary usage of this setup is to
 alter the set of features available to the ultimate end client,
 without having to change the original server (for example, to convert
-between oldstyle and newstyle, or to add TLS support where the original
-server lacks it).
+between oldstyle and newstyle, or to add TLS support where the
+original server lacks it).  Use of this plugin along with nbdkit
+filters (adding I<--filter> to the nbdkit command line) makes it
+possible to apply any nbdkit filter to any other NBD server.

 For now, this is limited to connecting to another NBD server over a
 named Unix socket without TLS, although it is feasible that future
@@ -40,10 +42,38 @@ empty string).

 =back

+=head1 EXAMPLES
+
+Expose the contents of an export served by an old style server over a
+Unix socket to TCP network clients that only want to consume encrypted
+data. Use I<--exit-with-parent> to clean up nbdkit at the same time
+that the old server exits.
+
+ ( sock=`mktemp -u` &&
+   nbdkit --exit-with-parent --tls=require nbd socket=$sock &
+   exec /path/to/oldserver --socket=$sock )
+
+ ┌────────────┐          ┌────────┐          ┌────────────┐
+ │ new client │ ────────▶│ nbdkit │ ────────▶│ old server │
+ └────────────┘   TCP    └────────┘   Unix   └────────────┘
+
+Combine nbdkit's partition filter with qemu-nbd's ability to visit
+qcow2 files (nbdkit does not have a native qcow2 plugin), performing
+the same task as the deprecated C<qemu-nbd -P 1 -f qcow2
+/path/to/image.qcow2> command:
+
+ ( sock=`mktemp -u` &&
+   nbdkit --exit-with-parent --filter=partition nbd socket=$sock partition=1 &
+   exec qemu-nbd -k $sock -f qcow2 /path/to/image.qcow2 )
+
 =head1 SEE ALSO

 L<nbdkit(1)>,
-L<nbdkit-plugin(3)>.
+L<nbdkit-captive(1)>,
+L<nbdkit-filter(1)>,
+L<nbdkit-tls(1)>,
+L<nbdkit-plugin(3)>,
+L<qemu-nbd(1)>.

 =head1 AUTHORS

@@ -51,4 +81,4 @@ Eric Blake

 =head1 COPYRIGHT

-Copyright (C) 2017 Red Hat Inc.
+Copyright (C) 2017, 2019 Red Hat Inc.
-- 
2.20.1