From: Eric Blake Date: Wed, 13 Feb 2019 23:07:32 +0000 (-0600) Subject: domain: Document VIR_DOMAIN_XML_MIGRATABLE X-Git-Tag: v5.1.0-rc2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=438ff363170d3e25291f0d58244320f7769e230b;p=thirdparty%2Flibvirt.git 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 Reviewed-by: John Ferlan --- 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. */