Libguestfs - May 2021 - [PATCH libnbd 3/3] copy: Update nbdcopy(1) about multiple connections

Using multiple connections does not depend now on NBD multi-conn flag.

Add a note about using --shared=4 in qemu-nbd to allow multiple
connections.

Signed-off-by: Nir Soffer <nsoffer at redhat.com>
---
 copy/nbdcopy.pod | 25 +++++++------------------
 1 file changed, 7 insertions(+), 18 deletions(-)

diff --git a/copy/nbdcopy.pod b/copy/nbdcopy.pod
index f710093..781bb10 100644
--- a/copy/nbdcopy.pod
+++ b/copy/nbdcopy.pod
@@ -103,10 +103,9 @@ output on the destination.
 
 =item B<--connections=>N
 
-Set the maximum number of NBD connections ("multi-conn").  By default
-nbdcopy will try to use multi-conn with up to 4 connections if the NBD
-server supports it.  If copying between NBD servers then nbdcopy
-cannot use multi-conn if either of the servers does not support it.
+Set the maximum number of NBD connections.  By default nbdcopy will try
+to use multiple connections with up to 4 connections. Some servers
+like L<qemu-nbd(8)> support only one connection by default.
 
 =item B<--destination-is-zero>
 
@@ -216,23 +215,13 @@ pipe, or a socket, or if you use the
I<--synchronous> option, then
 nbdcopy works in synchronous mode with no parallelism, and nothing
 else in this section applies.
 
-The I<--connections=N> option controls NBD multi-conn (see
-L<libnbd(3)/Multi-conn>), opening up to N connections to the NBD
+The I<--connections=N> option open up to N connections to the NBD
 server (or to both NBD servers if copying between NBD servers).  This
-defaults to 4.  The NBD servers must support and advertise multi-conn.
-For L<nbdkit(1)> availability of multi-conn can depend on the plugin.
-You can use L<nbdinfo(1)> to find out if a particular NBD server is
-advertising multi-conn.  If the NBD server doesn?t advertise
-multi-conn then only one connection will be opened regardless of the
-I<--connections> flag.
-
-When copying between two NBD servers, the number of connections is
-limited to the minimum multi-conn supported on both sides.  For the
-purposes of this calculation, you can consider local files and block
-devices as supporting infinite multi-conn.
+defaults to 4. When using L<qemu-nbd(8)> you need to enable multiple
+conections using the I<--shared=4> command line option.
 
 When you run an NBD server as a subprocess (using the S<C<[ ... ]>>
-syntax) multi-conn cannot be used.
+syntax) multiple connections cannot be used.
 
 The I<--threads=N> option allows nbdcopy to start up to N threads
 (defaulting to the number of cores).  However nbdcopy cannot use more
-- 
2.26.3

I want to see what Eric has to say about whether we can or should
change qemu-nbd.

There's a small typo in this patch:
> @@ -216,23 +215,13 @@ pipe, or a socket, or if you use the
I<--synchronous> option, then
>  nbdcopy works in synchronous mode with no parallelism, and nothing
>  else in this section applies.
>  
> -The I<--connections=N> option controls NBD multi-conn (see
> -L<libnbd(3)/Multi-conn>), opening up to N connections to the NBD
> +The I<--connections=N> option open up to N connections to the NBD
s/open/opens/

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v