[Libguestfs] [nbdkit PATCH] nbd: Give some examples
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(a)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