qemu: Allow migration over UNIX socket

This allows:

 a) migration without access to network

 b) complete control of the migration stream

 c) easy migration between containerised libvirt daemons on the same host

Resolves: https://bugzilla.redhat.com/1638889

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>

docs/manpages/virsh.rst

@@ -3270,6 +3270,14 @@ There are a few scenarios where specifying *migrateuri* may help:
   might be specified to choose a specific port number outside the default range in
   order to comply with local firewall policies.
 
+* The *desturi* uses UNIX transport method.  In this advanced case libvirt
+  should not guess a *migrateuri* and it should be specified using
+  UNIX socket path URI:
+
+.. code-block::
+
+      unix:///path/to/socket
+
 See `https://libvirt.org/migration.html#uris <https://libvirt.org/migration.html#uris>`_ for more details on
 migration URIs.
 
@@ -3296,8 +3304,9 @@ specific parameters separated by '&'. Currently recognized parameters are
 Optional *listen-address* sets the listen address that hypervisor on the
 destination side should bind to for incoming migration. Both IPv4 and IPv6
 addresses are accepted as well as hostnames (the resolving is done on
-destination). Some hypervisors do not support this feature and will return an
-error if this parameter is used.
+destination).  Some hypervisors do not support specifying the listen address and
+will return an error if this parameter is used. This parameter cannot be used if
+*desturi* uses UNIX transport method.
 
 Optional *disks-port* sets the port that hypervisor on destination side should
 bind to for incoming disks traffic. Currently it is supported only by QEMU.

docs/migration.html.in

@@ -201,6 +201,9 @@
         numbers. In the latter case the management application may wish
         to choose a specific port number outside the default range in order
         to comply with local firewall policies.</li>
+      <li>The second URI uses UNIX transport method.  In this advanced case
+        libvirt should not guess a *migrateuri* and it should be specified using
+        UNIX socket path URI: <code>unix:///path/to/socket</code>.</li>
     </ol>
 
     <h2><a id="config">Configuration file handling</a></h2>
@@ -628,5 +631,35 @@ virsh migrate --p2p --tunnelled web1 qemu+ssh://desthost/system qemu+ssh://10.0.
       Supported by QEMU driver
     </p>
 
+
+    <h3><a id="scenariounixsocket">Migration using only UNIX sockets</a></h3>
+
+    <p>
+      In niche scenarios where libvirt daemon does not have access to the
+      network (e.g. running in a restricted container on a host that has
+      accessible network), when a management application wants to have complete
+      control over the transfer or when migrating between two containers on the
+      same host all the communication can be done using UNIX sockets.  This
+      includes connecting to non-standard socket path for the destination
+      daemon, using UNIX sockets for hypervisor's communication or for the NBD
+      data transfer.  All of that can be used with both peer2peer and direct
+      migration options.
+    </p>
+
+    <p>
+      Example using <code>/tmp/migdir</code> as a directory representing the
+      same path visible from both libvirt daemons.  That can be achieved by
+      bind-mounting the same directory to different containers running separate
+      daemons or forwarding connections to these sockets manually
+      (using <code>socat</code>, <code>netcat</code> or a custom piece of
+      software):
+    <pre>
+virsh migrate web1 [--p2p] --copy-storage-all 'qemu+unix:///system?socket=/tmp/migdir/test-sock-driver' 'unix:///tmp/migdir/test-sock-qemu' --disks-uri unix:///tmp/migdir/test-sock-nbd
+    </pre>
+
+    <p>
+      Supported by QEMU driver
+    </p>
+
   </body>
 </html>