libvirt/docs/schemas/domainbackup.rng

228 lines
6.6 KiB
Plaintext
Raw Normal View History

backup: Document new XML for backups Prepare for new backup APIs by describing the XML that will represent a backup. The XML resembles snapshots and checkpoints in being able to select actions for a set of disks, but has other differences. It can support both push model (the hypervisor does the backup directly into the destination file) and pull model (the hypervisor exposes an access port for a third party to grab what is necessary). Add testsuite coverage for some minimal uses of the XML. The <disk> element within <domainbackup> tries to model the same elements as a <disk> under <domain>, but sharing the RNG grammar proved to be hairy. That is in part because while <domain> use <source> to describe a host resource in use by the guest, a backup job is using a host resource that is not visible to the guest: a push backup action is instead describing a <target> (which ultimately could be a remote network resource, but for simplicity the RNG just validates a local file for now), and a pull backup action is instead describing a temporary local file <scratch> (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept <disk type='FOO'>...</disk> so that the name of the subelement can be <source> for domain, or <target> or <scratch> as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake <eblake@redhat.com> Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
2019-08-22 01:42:41 +00:00
<?xml version="1.0"?>
<!-- A Relax NG schema for the libvirt domain backup properties XML format -->
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<start>
<ref name='domainbackup'/>
</start>
<include href='domaincommon.rng'/>
<define name='domainbackup'>
<element name='domainbackup'>
<interleave>
<optional>
<element name='incremental'>
<text/>
</element>
</optional>
<choice>
<group>
<optional>
<attribute name='mode'>
<value>push</value>
</attribute>
</optional>
<ref name='backupDisksPush'/>
</group>
<group>
<attribute name='mode'>
<value>pull</value>
</attribute>
<interleave>
<element name='server'>
<choice>
<group>
<optional>
<attribute name='transport'>
<value>tcp</value>
</attribute>
</optional>
<attribute name='name'>
<choice>
<ref name='dnsName'/>
<ref name='ipAddr'/>
</choice>
</attribute>
<optional>
<attribute name='port'>
<ref name='unsignedInt'/>
</attribute>
</optional>
<!-- add tls? -->
</group>
<group>
<attribute name='transport'>
<value>unix</value>
</attribute>
<attribute name='socket'>
<ref name='absFilePath'/>
</attribute>
</group>
</choice>
</element>
<ref name='backupDisksPull'/>
</interleave>
</group>
</choice>
</interleave>
</element>
</define>
<define name='backupPushDriver'>
<optional>
<element name='driver'>
<attribute name='type'>
<ref name='storageFormat'/>
</attribute>
</element>
</optional>
</define>
<define name='backupPullDriver'>
<optional>
<element name='driver'>
<attribute name='type'>
<value>qcow2</value>
</attribute>
</element>
</optional>
</define>
<define name='backupAttr'>
<optional>
<attribute name='backup'>
<choice>
<value>yes</value>
</choice>
</attribute>
</optional>
</define>
<define name='backupDisksPush'>
<optional>
<element name='disks'>
<oneOrMore>
<element name='disk'>
<attribute name='name'>
<ref name='diskTarget'/>
backup: Document new XML for backups Prepare for new backup APIs by describing the XML that will represent a backup. The XML resembles snapshots and checkpoints in being able to select actions for a set of disks, but has other differences. It can support both push model (the hypervisor does the backup directly into the destination file) and pull model (the hypervisor exposes an access port for a third party to grab what is necessary). Add testsuite coverage for some minimal uses of the XML. The <disk> element within <domainbackup> tries to model the same elements as a <disk> under <domain>, but sharing the RNG grammar proved to be hairy. That is in part because while <domain> use <source> to describe a host resource in use by the guest, a backup job is using a host resource that is not visible to the guest: a push backup action is instead describing a <target> (which ultimately could be a remote network resource, but for simplicity the RNG just validates a local file for now), and a pull backup action is instead describing a temporary local file <scratch> (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept <disk type='FOO'>...</disk> so that the name of the subelement can be <source> for domain, or <target> or <scratch> as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake <eblake@redhat.com> Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
2019-08-22 01:42:41 +00:00
</attribute>
<choice>
<group>
<attribute name='backup'>
<value>no</value>
</attribute>
</group>
<group>
<ref name='backupAttr'/>
<attribute name='type'>
<value>file</value>
</attribute>
<interleave>
<optional>
<element name='target'>
<attribute name='file'>
<ref name='absFilePath'/>
</attribute>
<zeroOrMore>
<ref name='devSeclabel'/>
</zeroOrMore>
</element>
</optional>
<ref name='backupPushDriver'/>
</interleave>
</group>
<group>
<ref name='backupAttr'/>
<attribute name='type'>
<value>block</value>
</attribute>
<interleave>
<optional>
<element name='target'>
<attribute name='dev'>
<ref name='absFilePath'/>
</attribute>
<zeroOrMore>
<ref name='devSeclabel'/>
</zeroOrMore>
</element>
</optional>
<ref name='backupPushDriver'/>
</interleave>
</group>
</choice>
</element>
</oneOrMore>
</element>
</optional>
</define>
<define name='backupDisksPull'>
<optional>
<element name='disks'>
<oneOrMore>
<element name='disk'>
<attribute name='name'>
<ref name='diskTarget'/>
backup: Document new XML for backups Prepare for new backup APIs by describing the XML that will represent a backup. The XML resembles snapshots and checkpoints in being able to select actions for a set of disks, but has other differences. It can support both push model (the hypervisor does the backup directly into the destination file) and pull model (the hypervisor exposes an access port for a third party to grab what is necessary). Add testsuite coverage for some minimal uses of the XML. The <disk> element within <domainbackup> tries to model the same elements as a <disk> under <domain>, but sharing the RNG grammar proved to be hairy. That is in part because while <domain> use <source> to describe a host resource in use by the guest, a backup job is using a host resource that is not visible to the guest: a push backup action is instead describing a <target> (which ultimately could be a remote network resource, but for simplicity the RNG just validates a local file for now), and a pull backup action is instead describing a temporary local file <scratch> (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept <disk type='FOO'>...</disk> so that the name of the subelement can be <source> for domain, or <target> or <scratch> as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake <eblake@redhat.com> Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
2019-08-22 01:42:41 +00:00
</attribute>
<optional>
<attribute name='exportname'>
<text/>
</attribute>
<attribute name='exportbitmap'>
<text/>
</attribute>
</optional>
backup: Document new XML for backups Prepare for new backup APIs by describing the XML that will represent a backup. The XML resembles snapshots and checkpoints in being able to select actions for a set of disks, but has other differences. It can support both push model (the hypervisor does the backup directly into the destination file) and pull model (the hypervisor exposes an access port for a third party to grab what is necessary). Add testsuite coverage for some minimal uses of the XML. The <disk> element within <domainbackup> tries to model the same elements as a <disk> under <domain>, but sharing the RNG grammar proved to be hairy. That is in part because while <domain> use <source> to describe a host resource in use by the guest, a backup job is using a host resource that is not visible to the guest: a push backup action is instead describing a <target> (which ultimately could be a remote network resource, but for simplicity the RNG just validates a local file for now), and a pull backup action is instead describing a temporary local file <scratch> (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept <disk type='FOO'>...</disk> so that the name of the subelement can be <source> for domain, or <target> or <scratch> as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake <eblake@redhat.com> Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
2019-08-22 01:42:41 +00:00
<choice>
<group>
<attribute name='backup'>
<value>no</value>
</attribute>
</group>
<group>
<optional>
<ref name='backupAttr'/>
<attribute name='type'>
<value>file</value>
</attribute>
</optional>
<optional>
<interleave>
<element name='scratch'>
<attribute name='file'>
<ref name='absFilePath'/>
</attribute>
<zeroOrMore>
<ref name='devSeclabel'/>
</zeroOrMore>
</element>
<ref name='backupPullDriver'/>
</interleave>
</optional>
</group>
<group>
<ref name='backupAttr'/>
<attribute name='type'>
<value>block</value>
</attribute>
<interleave>
<element name='scratch'>
<attribute name='dev'>
<ref name='absFilePath'/>
</attribute>
<zeroOrMore>
<ref name='devSeclabel'/>
</zeroOrMore>
</element>
<ref name='backupPullDriver'/>
</interleave>
</group>
</choice>
</element>
</oneOrMore>
</element>
</optional>
</define>
</grammar>