[Libguestfs] [PATCH nbdkit 1/5] nbd: Rework the documentation.
Richard W.M. Jones
rjones at redhat.com
Tue Jun 30 15:26:37 UTC 2020
* Change the title so it's informative and searchable.
* Remove references to the non-libnbd plugin.
* Headings for examples.
* Correct reference to qemu-nbd(8) man page.
* General copy-editing to improve readability.
* Change style in places so it matches other manual pages.
---
plugins/nbd/nbdkit-nbd-plugin.pod | 192 +++++++++++++++++-------------
1 file changed, 109 insertions(+), 83 deletions(-)
diff --git a/plugins/nbd/nbdkit-nbd-plugin.pod b/plugins/nbd/nbdkit-nbd-plugin.pod
index 618058ac..5653703f 100644
--- a/plugins/nbd/nbdkit-nbd-plugin.pod
+++ b/plugins/nbd/nbdkit-nbd-plugin.pod
@@ -1,109 +1,119 @@
=head1 NAME
-nbdkit-nbd-plugin - nbdkit nbd plugin
+nbdkit-nbd-plugin - proxy / forward to another NBD server
=head1 SYNOPSIS
- nbdkit nbd { socket=SOCKNAME | hostname=HOST [port=PORT] | [uri=]URI }
- [export=NAME] [retry=N] [shared=BOOL] [tls=MODE] [tls-certificates=DIR]
- [tls-verify=BOOL] [tls-username=NAME] [tls-psk=FILE]
+ nbdkit nbd { hostname=HOST [port=PORT] |
+ socket=SOCKNAME |
+ [uri=]URI }
+ [export=NAME] [retry=N] [shared=BOOL]
+ [tls=MODE] [tls-certificates=DIR] [tls-verify=BOOL]
+ [tls-username=NAME] [tls-psk=FILE]
=head1 DESCRIPTION
-C<nbdkit-nbd-plugin> is an NBD forwarding plugin for L<nbdkit(1)>.
-
-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). 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.
-
-Remember that when using this plugin as a bridge between an encrypted
-and a non-encrypted endpoint, it is best to preserve encryption over
-TCP and use plaintext only on a Unix socket.
+C<nbdkit-nbd-plugin> is a plugin for L<nbdkit(1)> that lets you
+forward the connection to another NBD server. There are several uses
+for this plugin:
+
+=over 4
+
+=item *
+
+Adjust the set of features seen by the ultimate NBD client without
+having to change the original server. For example, convert between
+the oldstyle and newstyle protocols, or add TLS support if the
+original server lacks it.
+
+=item *
+
+Apply nbdkit filters to any other NBD server.
+
+=item *
+
+With L<qemu-nbd(8)>, read and write qcow2 files with nbdkit.
+
+=back
=head1 PARAMETERS
-One of B<socket>, B<hostname> or B<uri> must be provided to designate
-the server. The server can speak either new or old style
-protocol. C<uri=> is a magic config key and may be omitted in most
-cases. See L<nbdkit(1)/Magic parameters>.
-
-The following parameters are available whether or not the plugin was
-compiled against libnbd:
+One of B<socket>, B<hostname> (optionally with B<port>), or B<uri>
+must be given to specify which NBD server to forward to:
=over 4
-=item B<socket=>SOCKNAME
-
-Connect to the NBD server located at the Unix socket C<SOCKNAME>.
-
=item B<hostname=>HOST
-Connect to the NBD server at the given remote C<HOST> using a TCP socket.
+Connect to the NBD server at the remote C<HOST> using a TCP socket.
=item B<port=>PORT
-When B<hostname> is supplied, use B<PORT> instead of the default port
+When C<hostname> is supplied, use C<PORT> instead of the default port
10809.
+=item B<socket=>SOCKNAME
+
+Connect to the NBD server using Unix domain socket C<SOCKNAME>.
+
+=item [B<uri=>]URI
+
+When C<uri> is supplied, decode C<URI> to determine the address to
+connect to. A URI can specify a TCP connection (such as
+C<nbd://localhost:10809/export>) or a Unix socket (such as
+C<nbd+unix:///export?socket=/path/to/sock>). Remember you may need to
+quote the parameter to protect it from the shell.
+
+C<uri=> is a magic config key and may be omitted in most
+cases. See L<nbdkit(1)/Magic parameters>.
+
+=back
+
+Other parameters control the NBD connection:
+
+=over 4
+
=item B<export=>NAME
If this parameter is given, and the server speaks new style protocol,
then connect to the named export instead of the default export (the
-empty string). If C<uri> is supplied, the export name should be
+empty string). If C<uri> is supplied, the export name should be
embedded in the URI instead.
=item B<retry=>N
If the initial connection attempt to the server fails, retry up to
-B<N> times more after a one-second delay between tries (default 0).
+C<N> times more after a one-second delay between tries (default 0).
-=item B<shared=>BOOL
+=item B<shared=true>
-If this parameter is false (default), the plugin will open a distinct
-connection to the server for each client making a connection to
-nbdkit, and the remote server does not have to be started until
-immediately before the first nbdkit client. If this parameter is set
-to true, the plugin will open a single connection to the server when
-nbdkit is first started (the C<delay> parameter may be necessary to
-coordinate timing of the remote server startup), and all clients to
-nbdkit will share that single connection.
+By default the plugin will open a new connection to the server for
+each client making a connection to nbdkit. The remote server does not
+have to be started until immediately before the first nbdkit client
+connects.
-=back
+If this parameter is set to C<true>, the plugin will open a single
+connection to the server when nbdkit is first started (the C<retry>
+parameter may be necessary to coordinate timing of the remote server
+startup), and all clients to nbdkit will share that single connection.
-The following parameters are only available if the plugin was compiled
-against libnbd:
+=item B<tls=off>
-=over 4
+=item B<tls=on>
-=item B<uri=>URI
+=item B<tls=require>
-When B<uri> is supplied, decode B<URI> to determine the address to
-connect to. A URI can specify a TCP connection (such as
-C<nbd://localhost:10809/export>) or a Unix socket (such as
-C<nbd+unix:///export?socket=/path/to/sock>). Remember to use proper
-shell quoting to prevent B<URI> from accidentally being handled as a
-shell glob. The B<uri> parameter is only available when the plugin was
-compiled against libnbd with URI support; C<nbdkit --dump-plugin nbd>
-will contain C<libnbd_uri=1> if this is the case.
-
-=item B<tls=>MODE
-
-Selects which TLS mode to use with the server. If no other tls option
+Selects which TLS mode to use with the server. If no other tls option
is present, this defaults to C<off>, where the client does not attempt
-encryption (and may be rejected by a server that requires it). If
+encryption (and may be rejected by a server that requires it). If
omitted but another tls option is present, this defaults to C<on>,
where the client opportunistically attempts a TLS handshake, but will
continue running unencrypted if the server does not support
-encryption. If set to C<require> or if the C<uri> parameter is used
+encryption. If set to C<require> or if the C<uri> parameter is used
with a scheme that requires encryption (such as C<nbds://host>), then
this requires an encrypted connection to the server.
-The B<tls> parameter is only available when the plugin was compiled
+The C<tls> parameter is only available when the plugin was compiled
against libnbd with TLS support; C<nbdkit --dump-plugin nbd> will
contain C<libnbd_tls=1> if this is the case. Note the difference
between C<--tls=...> controlling what nbdkit serves, and C<tls=...>
@@ -114,11 +124,11 @@ controlling what the nbd plugin connects to as a client.
This specifies the directory containing X.509 client certificates to
present to the server.
-=item B<tls-verify=>BOOL
+=item B<tls-verify=false>
-This defaults to true; setting it to false disables server name
-verification, which opens you to potential Man-in-the-Middle (MITM)
-attacks, but allows for a simpler setup for distributing certificates.
+Setting this parameter to false disables server name verification,
+which opens you to potential Man-in-the-Middle (MITM) attacks, but
+allows for a simpler setup for distributing certificates.
=item B<tls-username=>NAME
@@ -128,16 +138,18 @@ alongside the certificate.
=item B<tls-psk=>FILE
If provided, this is the filename containing the Pre-Shared Keys (PSK)
-to present to the server. While this is easier to set up than X.509,
+to present to the server. While this is easier to set up than X.509,
it requires that the PSK file be transmitted over a secure channel.
=back
=head1 EXAMPLES
+=head2 Convert oldstyle server to encrypted newstyle
+
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
+data. Use I<--exit-with-parent> to clean up nbdkit at the same time
that the old server exits.
( sock=`mktemp -u`
@@ -148,23 +160,31 @@ that the old server exits.
│ 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. Allow multiple clients, even though
-C<qemu-nbd> without B<-t> normally quits after the first client, and
-utilize a 5-second retry to give qemu-nbd time to create the socket:
+=head2 Add nbdkit-partition-filter to qemu-nbd
+
+Combine nbdkit's partition filter with L<qemu-nbd(8)>’s ability to
+visit qcow2 files (since nbdkit does not have a native qcow2 plugin).
+
+This performs the same task as the deprecated qemu-nbd I<-P> option:
+
+ qemu-nbd -P 1 -f qcow2 /path/to/image.qcow2
+
+Also this allows multiple clients, even though C<qemu-nbd> without
+I<-t> normally quits after the first client, and utilizes a 5-second
+retry to give qemu-nbd time to create the socket:
( sock=`mktemp -u`
nbdkit --exit-with-parent --filter=partition nbd \
nbd+unix:///\?socket=$sock shared=1 retry=5 partition=1 &
exec qemu-nbd -k $sock -f qcow2 /path/to/image.qcow2 )
-Conversely, expose the contents of export I<foo> from a new style
-server with encrypted data to a client that can only consume
-unencrypted old style. Use I<--run> to clean up nbdkit at the time the
-client exits. In general, note that it is best to keep the plaintext
-connection limited to a Unix socket on the local machine.
+=head2 Convert newstyle server for oldstyle-only client
+
+Expose the contents of export C<foo> from a newstyle server with
+encrypted data to a client that can only consume unencrypted old
+style. Use I<--run> to clean up nbdkit at the time the client exits.
+In general, note that it is best to keep the plaintext connection
+limited to a Unix socket on the local machine.
nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
--run '/path/to/oldclient --socket=$unixsocket'
@@ -173,10 +193,16 @@ connection limited to a Unix socket on the local machine.
│ old client │ ───────────▶│ nbdkit │ ────────▶│ new server │
└────────────┘ Unix └────────┘ TCP └────────────┘
-Learn which features are provided by libnbd by inspecting the
-C<libnbd_*> lines:
+=head1 DUMP PLUGIN OUTPUT
- nbdkit --dump-plugin nbd
+You can learn which features are provided by libnbd by inspecting the
+C<libnbd_*> lines in I<--dump-plugin> output:
+
+ $ nbdkit --dump-plugin nbd
+ [...]
+ libnbd_version=1.2.3
+ libnbd_tls=1
+ libnbd_uri=1
=head1 FILES
@@ -202,7 +228,7 @@ L<nbdkit-filter(3)>,
L<nbdkit-tls(1)>,
L<nbdkit-plugin(3)>,
L<libnbd(3)>,
-L<qemu-nbd(1)>.
+L<qemu-nbd(8)>.
=head1 AUTHORS
--
2.25.0
More information about the Libguestfs
mailing list