[libvirt] [PATCH 1/7] domain: Document VIR_DOMAIN_XML_MIGRATABLE
Commit 28f8dfdc (1.0.0) added a flag to virDomainGetXMLDesc, but
failed to document its effects. And considering that the
MIGRATABLE flag has been the source of past bugs (CVE-2014-7823,
fixed in commit b1674ad5 (1.2.11), or even cf2d4c60 (1.2.13) where
flag mismatch broke virsh edit), make the wording wishy-washy
enough to discourage using the flag casually, by mentioning that
the resulting XML is more for internal use than for validation
against the schema.
Signed-off-by: Eric Blake <eblake(a)redhat.com>
---
src/libvirt-domain.c | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index e2ed8b2772..072b92b717 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -2561,6 +2561,15 @@ virDomainGetControlInfo(virDomainPtr domain,
* describing CPU capabilities is modified to match actual
* capabilities of the host.
*
+ * If @flags contains VIR_DOMAIN_XML_MIGRATABLE, the XML is altered to
+ * assist in migrations, since the source and destination may be
+ * running different libvirt versions. This may include trimming
+ * redundant or default information that might confuse an older
+ * recipient, or exposing internal details that aid a newer recipient;
+ * this flag is rejected on read-only connections, and the resulting
+ * XML might not validate against the schema, so it is mainly for
+ * internal use.
+ *
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value.
*/
--
2.20.1