From 055379df2352556a0ab76dd73131acd23ed37b64 Mon Sep 17 00:00:00 2001 From: Peter Krempa Date: Mon, 18 Nov 2024 14:25:22 +0100 Subject: [PATCH] API: migration: Warn about use of VIR_MIGRATE_PERSIST_DEST with VIR_MIGRATE_PARAM_DEST_XML 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 Reviewed-by: Michal Privoznik --- include/libvirt/libvirt-domain.h | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 9232ce2e6b..d4f1573954 100644 --- 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),