[Libguestfs] [nbdkit PATCH] nbd: Give some examples
Richard W.M. Jones
rjones at redhat.com
Tue Apr 30 11:55:49 UTC 2019
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 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.
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 at 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
More information about the Libguestfs
mailing list