manpage: virsh: Add warning about 'migrate' with '--persistent' together with '-...

When a VM is being migrated to a destination host it can be made
persistent on the destination by using '--persistent'. That may not
work as intended if '--xml' is used as well as that allows overriding
certain aspects of the VM xml, but does not involve the persistent
definition. In most cases users will need to supply also
'--persistent-xml' with the same set of modification.

Modify the man page to clarify the above so that users don't end up with
broken VM after migrating and restarting it.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
index 6776ea53d0c7f99dfd90b68d8caf36e9c329d2d7..2e525d3fac4dcc332f006e0dcb539a077f1e2d4d 100644 (file)
--- a/docs/manpages/virsh.rst
+++ b/docs/manpages/virsh.rst
@@ -3409,7 +3409,8 @@ starting the domain on destination and without stopping it on source host.
 Offline migration may be used with inactive domains and it must be used with
 *--persistent* option.
 
-*--persistent* leaves the domain persistent on destination host,
+*--persistent* leaves the domain persistent on destination host (See below
+for quirks when used together with *--xml*),
 *--undefinesource* undefines the domain on the source host, and *--suspend*
 leaves the domain paused on the destination host.
 
@@ -3489,13 +3490,18 @@ such as GFS2 or GPFS. If you are sure the migration is safe or you just do not
 care, use *--unsafe* to force the migration.
 
 *dname* is used for renaming the domain to new name during migration, which
-also usually can be omitted.  Likewise, *--xml* ``file`` is usually
-omitted, but can be used to supply an alternative XML file for use on
-the destination to supply a larger set of changes to any host-specific
-portions of the domain XML, such as accounting for naming differences
-between source and destination in accessing underlying storage.
-If *--persistent* is enabled, *--persistent-xml* ``file`` can be used to
-supply an alternative XML file which will be used as the persistent guest
+also usually can be omitted.
+
+*--xml* ``file``, while usually not required, can be used to supply an
+alternative XML file for use on the destination to supply a larger set of
+changes to any host-specific portions of the domain XML, such as accounting for
+naming differences between source and destination in accessing underlying
+storage. If *--xml* is used together with *--persistent* it's usually required
+to provide a persistent XML definition via *--persistent-xml* (see below) which
+is fixed the same way as the XML passed to *--file* was.
+
+If *--persistent* is enabled, *--persistent-xml* ``file`` can be used
+to supply an alternative XML file which will be used as the persistent guest
 definition on the destination host.
 
 *--timeout* ``seconds`` tells virsh to run a specified action when live