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&gt; --- 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