Re: [libvirt] [PATCH v2 04/25] backup: Document new XML for backups
On Tue, Dec 03, 2019 at 06:17:26PM +0100, Peter Krempa wrote: From: Eric Blake 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 element within tries to model the same elements as a under , but sharing the RNG grammar proved to be hairy. That is in part because while use 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 (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 (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept ... so that the name of the subelement can be for domain, or or as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake Signed-off-by: Peter Krempa --- docs/docs.html.in | 3 +- docs/format.html.in | 1 + docs/formatbackup.html.in | 175 ++ docs/formatcheckpoint.html.in | 12 +- docs/index.html.in| 3 +- docs/schemas/domainbackup.rng | 223 ++ libvirt.spec.in | 1 + mingw-libvirt.spec.in | 2 + tests/Makefile.am | 1 + .../backup-pull-seclabel.xml | 18 ++ tests/domainbackupxml2xmlin/backup-pull.xml | 10 + .../backup-push-seclabel.xml | 17 ++ tests/domainbackupxml2xmlin/backup-push.xml | 10 + tests/domainbackupxml2xmlin/empty.xml | 1 + tests/virschematest.c | 1 + 15 files changed, 470 insertions(+), 8 deletions(-) create mode 100644 docs/formatbackup.html.in create mode 100644 docs/schemas/domainbackup.rng create mode 100644 tests/domainbackupxml2xmlin/backup-pull-seclabel.xml create mode 100644 tests/domainbackupxml2xmlin/backup-pull.xml create mode 100644 tests/domainbackupxml2xmlin/backup-push-seclabel.xml create mode 100644 tests/domainbackupxml2xmlin/backup-push.xml create mode 100644 tests/domainbackupxml2xmlin/empty.xml diff --git a/docs/formatbackup.html.in b/docs/formatbackup.html.in new file mode 100644 index 00..d2e4609c1c --- /dev/null +++ b/docs/formatbackup.html.in @@ -0,0 +1,175 @@ [...] +Examples + +Use virDomainBackupBegin() to perform a full + backup using push mode. The example lets libvirt pick the + destination and format for 'vda', fully specifies that we want a + raw backup of 'vdb', and omits 'vdc' from the operation. + + +domainbackup + disks/ extra slash -^ +disk name='vda' backup='yes'/ +disk name='vdb' type='file' + target file='/path/to/vdb.backup'/ + driver type='raw'/ +/disk +disk name='vdc' backup='no'/ + /disks/ here too -^ +/domainbackup + + +If the previous full backup also passed a parameter describing + checkpoint XML that resulted + in a checkpoint named 1525889631, we can make + another call to virDomainBackupBegin() to perform + an incremental backup of just the data changed since that + checkpoint, this time using the following XML to start a pull + model export of the 'vda' and 'vdb' disks, where a third-party + NBD client connecting to '/path/to/server' completes the backup + (omitting 'vdc' from the explicit list has the same effect as + the backup='no' from the previous example): + + +domainbackup mode="pull" + incremental1525889631/incremental + server transport="unix" socket="/path/to/server"/ + disks/ here too ^ +disk name='vda' backup='yes' type='file' + scratch file='/path/to/file1.scratch'/ +/disk + /disks/ here too -^ +/domainbackup + + + With that fixed: Reviewed-by: Ján Tomko Jano signature.asc Description: PGP signature -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH v2 04/25] backup: Document new XML for backups
On Tue, Dec 03, 2019 at 06:17:26PM +0100, Peter Krempa wrote: > From: Eric Blake > > 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 element within tries to model the same > elements as a under , but sharing the RNG grammar > proved to be hairy. That is in part because while use > 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 (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 (which probably should not > be a remote resource). A future refactoring may thus introduce some > way to parameterize RNG to accept ... so that > the name of the subelement can be for domain, or or > as needed for backups. Future patches may improve this area > of code. > > Signed-off-by: Eric Blake > Signed-off-by: Peter Krempa > --- > docs/docs.html.in | 3 +- > docs/format.html.in | 1 + > docs/formatbackup.html.in | 175 ++ > docs/formatcheckpoint.html.in | 12 +- > docs/index.html.in| 3 +- > docs/schemas/domainbackup.rng | 223 ++ > libvirt.spec.in | 1 + > mingw-libvirt.spec.in | 2 + > tests/Makefile.am | 1 + > .../backup-pull-seclabel.xml | 18 ++ > tests/domainbackupxml2xmlin/backup-pull.xml | 10 + > .../backup-push-seclabel.xml | 17 ++ > tests/domainbackupxml2xmlin/backup-push.xml | 10 + > tests/domainbackupxml2xmlin/empty.xml | 1 + > tests/virschematest.c | 1 + > 15 files changed, 470 insertions(+), 8 deletions(-) > create mode 100644 docs/formatbackup.html.in > create mode 100644 docs/schemas/domainbackup.rng > create mode 100644 tests/domainbackupxml2xmlin/backup-pull-seclabel.xml > create mode 100644 tests/domainbackupxml2xmlin/backup-pull.xml > create mode 100644 tests/domainbackupxml2xmlin/backup-push-seclabel.xml > create mode 100644 tests/domainbackupxml2xmlin/backup-push.xml > create mode 100644 tests/domainbackupxml2xmlin/empty.xml Reviewed-by: Daniel P. Berrangé Regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :| -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] [PATCH v2 04/25] backup: Document new XML for backups
From: Eric Blake 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 element within tries to model the same elements as a under , but sharing the RNG grammar proved to be hairy. That is in part because while use 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 (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 (which probably should not be a remote resource). A future refactoring may thus introduce some way to parameterize RNG to accept ... so that the name of the subelement can be for domain, or or as needed for backups. Future patches may improve this area of code. Signed-off-by: Eric Blake Signed-off-by: Peter Krempa --- docs/docs.html.in | 3 +- docs/format.html.in | 1 + docs/formatbackup.html.in | 175 ++ docs/formatcheckpoint.html.in | 12 +- docs/index.html.in| 3 +- docs/schemas/domainbackup.rng | 223 ++ libvirt.spec.in | 1 + mingw-libvirt.spec.in | 2 + tests/Makefile.am | 1 + .../backup-pull-seclabel.xml | 18 ++ tests/domainbackupxml2xmlin/backup-pull.xml | 10 + .../backup-push-seclabel.xml | 17 ++ tests/domainbackupxml2xmlin/backup-push.xml | 10 + tests/domainbackupxml2xmlin/empty.xml | 1 + tests/virschematest.c | 1 + 15 files changed, 470 insertions(+), 8 deletions(-) create mode 100644 docs/formatbackup.html.in create mode 100644 docs/schemas/domainbackup.rng create mode 100644 tests/domainbackupxml2xmlin/backup-pull-seclabel.xml create mode 100644 tests/domainbackupxml2xmlin/backup-pull.xml create mode 100644 tests/domainbackupxml2xmlin/backup-push-seclabel.xml create mode 100644 tests/domainbackupxml2xmlin/backup-push.xml create mode 100644 tests/domainbackupxml2xmlin/empty.xml diff --git a/docs/docs.html.in b/docs/docs.html.in index 268c16f3b3..f8a949bb53 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -82,7 +82,8 @@ node devices, secrets, snapshots, - checkpoints + checkpoints, + backup jobs URI format The URI formats used for connecting to libvirt diff --git a/docs/format.html.in b/docs/format.html.in index 3be2237663..d013528fe0 100644 --- a/docs/format.html.in +++ b/docs/format.html.in @@ -27,6 +27,7 @@ Secrets Snapshots Checkpoints + Backup jobs Command line validation diff --git a/docs/formatbackup.html.in b/docs/formatbackup.html.in new file mode 100644 index 00..d2e4609c1c --- /dev/null +++ b/docs/formatbackup.html.in @@ -0,0 +1,175 @@ + + +http://www.w3.org/1999/xhtml;> + +Backup XML format + + + +Backup XML + + + Creating a backup, whether full or incremental, is done + via virDomainBackupBegin(), which takes an XML + description of the actions to perform, as well as an optional + second XML document describing a + checkpoint to create at the same point in time. See + also a comparison between + the various state capture APIs. + + + There are two general modes for backups: a push mode (where the + hypervisor writes out the data to the destination file, which + may be local or remote), and a pull mode (where the hypervisor + creates an NBD server that a third-party client can then read as + needed, and which requires the use of temporary storage, + typically local, until the backup is complete). + + + The instructions for beginning a backup job are provided as + attributes and elements of the + top-level domainbackup element. This element + includes an optional attribute mode which can be + either "push" or "pull" (default + push). virDomainBackupGetXMLDesc() can be used to + see the actual values selected for elements omitted during + creation (for example, learning which port the NBD server is + using in the pull model or what file names libvirt generated + when none were supplied). The following child elements and attributes + are supported: + + + incremental +
