Libguestfs - Apr 2019 - [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@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

On Mon, Apr 29, 2019 at 02:00:28PM -0500, Eric Blake
wrote:
> 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@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.
Looks fine, and nice to see good use of unicode box drawing characters :-)

Rich.
>  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
> 
> _______________________________________________
> Libguestfs mailing list
> Libguestfs@redhat.com
> https://www.redhat.com/mailman/listinfo/libguestfs
-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-top is 'top' for virtual machines.  Tiny program with many
powerful monitoring features, net stats, disk stats, logging, etc.
http://people.redhat.com/~rjones/virt-top