1Backup XML format 2================= 3 4.. contents:: 5 6Backup XML 7---------- 8 9Creating a backup, whether full or incremental, is done via 10``virDomainBackupBegin()``, which takes an XML description of the actions to 11perform, as well as an optional second XML document `describing a 12checkpoint <formatcheckpoint.html>`__ to create at the same point in time. See 13also `a comparison <kbase/domainstatecapture.html>`__ between the various state 14capture APIs. 15 16There are two general modes for backups: a push mode (where the hypervisor 17writes out the data to the destination file, which may be local or remote), and 18a pull mode (where the hypervisor creates an NBD server that a third-party 19client can then read as needed, and which requires the use of temporary storage, 20typically local, until the backup is complete). 21 22The instructions for beginning a backup job are provided as attributes and 23elements of the top-level ``domainbackup`` element. This element includes an 24optional attribute ``mode`` which can be either "push" or "pull" (default push). 25``virDomainBackupGetXMLDesc()`` can be used to see the actual values selected 26for elements omitted during creation (for example, learning which port the NBD 27server is using in the pull model or what file names libvirt generated when none 28were supplied). The following child elements and attributes are supported: 29 30``incremental`` 31 An optional element giving the name of an existing checkpoint of the domain, 32 which will be used to make this backup an incremental one. In the push model, 33 only changes since the named checkpoint are written to the destination. In 34 the pull model, the NBD server uses the NBD_OPT_SET_META_CONTEXT extension to 35 advertise to the client which portions of the export contain changes since 36 the named checkpoint. If omitted, a full backup is performed. 37 38``server`` 39 Present only for a pull mode backup. Contains the same attributes as the 40 ```protocol`` element of a disk <formatdomain.html#elementsDisks>`__ attached 41 via NBD in the domain (such as transport, socket, name, port, or tls), 42 necessary to set up an NBD server that exposes the content of each disk at 43 the time the backup is started. 44 45 Note that for the QEMU hypervisor the TLS environment in controlled using 46 ``backup_tls_x509_cert_dir``, ``backup_tls_x509_verify``, and 47 ``backup_tls_x509_secret_uuid`` properties in ``/etc/libvirt/qemu.conf``. 48 49``disks`` 50 An optional listing of instructions for disks participating in the backup (if 51 omitted, all disks participate and libvirt attempts to generate filenames by 52 appending the current timestamp as a suffix). If the entire element was 53 omitted on input, then all disks participate in the backup, otherwise, only 54 the disks explicitly listed which do not also use ``backup='no'`` will 55 participate. On output, this is the state of each of the domain's disk in 56 relation to the backup operation. 57 58 ``disk`` 59 This sub-element describes the backup properties of a specific disk, with 60 the following attributes and child elements: 61 62 ``name`` 63 A mandatory attribute which must match the ``<target dev='name'/>`` of 64 one of the `disk devices <formatdomain.html#elementsDisks>`__ specified 65 for the domain at the time of the checkpoint. 66 67 ``backup`` 68 Setting this attribute to ``yes``\ (default) specifies that the disk 69 should take part in the backup and using ``no`` excludes the disk from 70 the backup. 71 72 ``backupmode`` 73 This attribute overrides the implied backup mode inherited from the 74 definition of the backup itself. Value ``full`` forces a full backup 75 even if the backup calls for an incremental backup, and ``incremental`` 76 coupled with the attribute ``incremental='CHECKPOINTNAME`` for the disk 77 forces an incremental backup from ``CHECKPOINTNAME``. 78 79 ``incremental`` 80 An optional attribute giving the name of an existing checkpoint of the 81 domain which overrides the one set by the ``<incremental>`` element. 82 83 ``exportname`` 84 Allows modification of the NBD export name for the given disk. By 85 default equal to disk target. Valid only for pull mode backups. 86 87 ``exportbitmap`` 88 Allows modification of the name of the bitmap describing dirty blocks 89 for an incremental backup exported via NBD export name for the given 90 disk. Valid only for pull mode backups. 91 92 ``type`` 93 A mandatory attribute to describe the type of the disk, except when 94 ``backup='no'`` is used. Valid values include ``file``, or ``block``. 95 Similar to a disk declaration for a domain, the choice of type controls 96 what additional sub-elements are needed to describe the destination. 97 98 ``index`` 99 Output only. The value can be used to refer to the scratch or output 100 file of the backup in APIs such as ``virDomainSetBlockThreshold``. 101 102 ``target`` 103 Valid only for push mode backups, this is the primary sub-element that 104 describes the file name of the backup destination, similar to the 105 ``source`` sub-element of a domain disk. An optional sub-element 106 ``driver`` can also be used, with an attribute ``type`` to specify a 107 destination format different from qcow2. See documentation for 108 ``scratch`` below for additional configuration. 109 110 ``scratch`` 111 Valid only for pull mode backups, this is the primary sub-element that 112 describes the file name of the local scratch file to be used in 113 facilitating the backup, and is similar to the ``source`` sub-element 114 of a domain disk. Currently only ``file`` and ``block`` scratch storage 115 is supported. The ``file`` scratch file is created and deleted by 116 libvirt in the given location. A ``block`` scratch device must exist 117 prior to starting the backup and is formatted. The block device must 118 have enough space for the corresponding disk data including format 119 overhead. If ``VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL`` flag is used 120 the file for a scratch of ``file`` type must exist with the correct 121 format and size to hold the copy and is used without modification. The 122 file is not deleted after the backup but the contents of the file don't 123 make sense outside of the backup. The same applies for the block device 124 which must be formatted appropriately. Similarly to the domain 125 ```disk`` <formatdomain.html#elementsDisks>`__ definition ``scratch`` 126 and ``target`` can contain ``seclabel`` and/or ``encryption`` 127 subelements to configure the corresponding properties. 128 129Examples 130-------- 131 132Use ``virDomainBackupBegin()`` to perform a full backup using push mode. The 133example lets libvirt pick the destination and format for 'vda', fully specifies 134that we want a raw backup of 'vdb', and omits 'vdc' from the operation. 135 136:: 137 138 <domainbackup> 139 <disks> 140 <disk name='vda' backup='yes'/> 141 <disk name='vdb' type='file'> 142 <target file='/path/to/vdb.backup'/> 143 <driver type='raw'/> 144 </disk> 145 <disk name='vdc' backup='no'/> 146 </disks> 147 </domainbackup> 148 149If the previous full backup also passed a parameter describing `checkpoint 150XML <formatcheckpoint.html>`__ that resulted in a checkpoint named 151``1525889631``, we can make another call to ``virDomainBackupBegin()`` to 152perform an incremental backup of just the data changed since that checkpoint, 153this time using the following XML to start a pull model export of the 'vda' and 154'vdb' disks, where a third-party NBD client connecting to '/path/to/server' 155completes the backup (omitting 'vdc' from the explicit list has the same effect 156as the backup='no' from the previous example): 157 158:: 159 160 <domainbackup mode="pull"> 161 <incremental>1525889631</incremental> 162 <server transport="unix" socket="/path/to/server"/> 163 <disks> 164 <disk name='vda' backup='yes' type='file'> 165 <scratch file='/path/to/file1.scratch'/> 166 </disk> 167 </disks> 168 </domainbackup> 169