diff --git a/docs/migration.html.in b/docs/migration.html.in
index 24162750b3..aecef41ce9 100644
--- a/docs/migration.html.in
+++ b/docs/migration.html.in
@@ -192,12 +192,12 @@
         should specify the hypervisor specific URI, using an IP address
         associated with the network to be used.</li>
       <li>The firewall restricts what ports are available. When libvirt
-        generates a migration URI will pick a port number using hypervisor
+        generates a migration URI it will pick a port number using hypervisor
         specific rules. Some hypervisors only require a single port to be
         open in the firewalls, while others require a whole range of port
         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>
+        to comply with local firewall policies.</li>
     </ol>
 
     <h2><a name="config">Configuration file handling</a></h2>
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 6ef509b3cd..89251af503 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -1080,7 +1080,7 @@ such as GFS2 or GPFS. If you are sure the migration is safe or you just do not
 care, use I<--unsafe> to force the migration.
 
 The I<desturi> is the connection URI of the destination host, and
-I<migrateuri> is the migration URI, which usually can be omitted.
+I<migrateuri> is the migration URI, which usually can be omitted (see below).
 I<dname> is used for renaming the domain to new name during migration, which
 also usually can be omitted.  Likewise, I<--xml> B<file> is usually
 omitted, but can be used to supply an alternative XML file for use on
@@ -1108,6 +1108,32 @@ seen from the source machine.
 
 =back
 
+When I<migrateuri> is not specified, libvirt will automatically determine the
+hypervisor specific URI, by looking up the target host's configured hostname.
+There are a few scenarios where specifying I<migrateuri> may help:
+
+=over 4
+
+=item * The configured hostname is incorrect, or DNS is broken.  If a host has a
+hostname which will not resolve to match one of its public IP addresses, then
+libvirt will generate an incorrect URI.  In this case I<migrateuri> should be
+explicitly specified, using an IP address, or a correct hostname.
+
+=item * The host has multiple network interaces.  If a host has multiple network
+interfaces, it might be desirable for the migration data stream to be sent over
+a specific interface for either security or performance reasons.  In this case
+I<migrateuri> should be explicitly specified, using an IP address associated
+with the network to be used.
+
+=item * The firewall restricts what ports are available.  When libvirt generates
+a migration URI, it will pick a port number using hypervisor specific rules.
+Some hypervisors only require a single port to be open in the firewalls, while
+others require a whole range of port numbers.  In the latter case I<migrateuri>
+might be specified to choose a specific port number outside the default range in
+order to comply with local firewall policies.
+
+=back
+
 =item B<migrate-setmaxdowntime> I<domain> I<downtime>
 
 Set maximum tolerable downtime for a domain which is being live-migrated to