API: migration: Warn about use of VIR_MIGRATE_PERSIST_DEST with VIR_MIGRATE_PARAM_DES...

When a VM is being migrated to a destination host it can be made
persistent on the destination by using VIR_MIGRATE_PERSIST_DEST. That
may not work as intended if VIR_MIGRATE_PARAM_DEST_XML or the 'xmlin'
parameter is used 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 VIR_MIGRATE_PARAM_PERSIST_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/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 9232ce2e6b9b515962726a0446fee95f12ec7138..d4f15739545d1702599aaa372ebe2a6e96999ffc 100644 (file)
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -929,6 +929,19 @@ typedef enum {
      * VIR_MIGRATE_UNDEFINE_SOURCE is not used, it will end up persistent on
      * both hosts.
      *
+     * Note: If VIR_MIGRATE_PERSIST_DEST flag is used together with the
+     *       VIR_MIGRATE_PARAM_DEST_XML migration parameter which supplies an
+     *       updated definition for the destination host it's required to
+     *       supply also VIR_MIGRATE_PARAM_PERSIST_XML updated the same way.
+     *       Otherwise the persistent definition on the destination will not
+     *       contain the updates.
+     *
+     *       The VIR_MIGRATE_PERSIST_DEST flag should not be used with the
+     *       "xmlin" parameter of older APIs as that way an updated persistent
+     *       XML can't be supplied and thus the persistent definition will
+     *       likely be incorrect as it will be based on the persistent definition
+     *       on the source of the migration.
+     *
      * Since: 0.7.3
      */
     VIR_MIGRATE_PERSIST_DEST = (1 << 3),