[libvirt] [PATCH v2 3/5] domain: Document VIR_DOMAIN_XML_MIGRATABLE

[Eric Blake]

On 2/19/19 1:33 PM, John Ferlan wrote:

>> + * capabilities of the host.  If @flags contains VIR_DOMAIN_XML_MIGRATABLE,
>> + * the XML is altered to trim redundant information that might interfere
>> + * with migration to an older version of libvirt, as well as expose additional
>> + * information internal to libvirt; this flag is rejected on read-only
>> + * connections, and the resulting XML might not validate against the schema,
>> + * but it can serve as a starting point for custom XML in calls such as
>> + * virDomainMigrate2().

Not for the public docs, but I may also mention that
VIR_DOMAIN_XML_MIGRATABLE caused CVE-2014-7823 (commit b1674ad5) as part
of my commit message.

> 
> You could just use the same attribution from the referenced commit
> message, e.g. "virDomainMigrate{,ToURI}2 or virDomainSaveFlags."
> 
> I'm not insistent, just following back links. There could be other
> examples by now too I suppose.

Yeah, the latter is what I feared, and did not want to audit for. So I'm
leaving it as written with just the one example.

> 
> Reviewed-by: John Ferlan <jferlan at redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org