docs/formatcheckpoint.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Checkpoint XML format</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <h2><a id="CheckpointAttributes">Checkpoint XML</a></h2>
  10
  11     <p>
  12       One method of capturing domain disk backups is via the use of
  13       incremental backups. Right now, incremental backups are only
  14       supported for the QEMU hypervisor when using qcow2 disks at the
  15       active layer; if other disk formats are in use, capturing disk
  16       backups requires different libvirt APIs
  17       (see <a href="kbase/domainstatecapture.html">domain state
  18       capture</a> for a comparison between APIs).
  19     </p>
  20     <p>
  21       Libvirt is able to facilitate incremental backups by tracking
  22       disk checkpoints, which are points in time against which it is
  23       easy to compute which portion of the disk has changed. Given a
  24       full backup (a backup created from the creation of the disk to a
  25       given point in time), coupled with the creation of a disk
  26       checkpoint at that time, and an incremental backup (a backup
  27       created from just the dirty portion of the disk between the
  28       first checkpoint and the second backup operation), it is
  29       possible to do an offline reconstruction of the state of the
  30       disk at the time of the second backup without having to copy as
  31       much data as a second full backup would require. Most disk
  32       checkpoints are created in conjunction with a backup
  33       via <code>virDomainBackupBegin()</code>, although a future API
  34       addition of <code>virDomainSnapshotCreateXML2()</code> will also
  35       make this possible when creating external snapshots; however,
  36       libvirt also exposes enough support to create disk checkpoints
  37       independently from a backup operation
  38       via <code>virDomainCheckpointCreateXML()</code> <span class="since">since
  39       5.6.0</span>.  Likewise, the creation of checkpoints when
  40       external snapshots exist is currently forbidden, although future
  41       work will make it possible to integrate these two concepts.
  42     </p>
  43     <p>
  44       Attributes of libvirt checkpoints are stored as child elements
  45       of the <code>domaincheckpoint</code> element. At checkpoint
  46       creation time, normally only
  47       the <code>name</code>, <code>description</code>,
  48       and <code>disks</code> elements are settable. The rest of the
  49       fields are ignored on creation and will be filled in by libvirt
  50       in for informational purposes
  51       by <code>virDomainCheckpointGetXMLDesc()</code>. However, when
  52       redefining a checkpoint, with
  53       the <code>VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE</code> flag
  54       of <code>virDomainCheckpointCreateXML()</code>, all of the XML
  55       fields described here are relevant on input, even the fields
  56       that are normally described as readonly for output.
  57     </p>
  58     <p>
  59       The top-level <code>domaincheckpoint</code> element may contain
  60       the following elements:
  61     </p>
  62     <dl>
  63       <dt><code>name</code></dt>
  64       <dd>The optional name for this checkpoint. If the name is
  65         omitted, libvirt will create a name based on the time of the
  66         creation.
  67       </dd>
  68       <dt><code>description</code></dt>
  69       <dd>An optional human-readable description of the checkpoint.
  70         If the description is omitted when initially creating the
  71         checkpoint, then this field will be empty.
  72       </dd>
  73       <dt><code>disks</code></dt>
  74       <dd>On input, this is an optional listing of specific
  75         instructions for disk checkpoints; it is needed when making a
  76         checkpoint on only a subset of the disks associated with a
  77         domain. In particular, since QEMU checkpoints require qcow2
  78         disks, this element may be needed on input for excluding guest
  79         disks that are not in qcow2 format. If the entire element was
  80         omitted on input, then all disks participate in the
  81         checkpoint, otherwise, only the disks explicitly listed which
  82         do not also use <code>checkpoint='no'</code> will
  83         participate. On output, this is the checkpoint state of each
  84         of the domain's disks.
  85         <dl>
  86           <dt><code>disk</code></dt>
  87           <dd>This sub-element describes the checkpoint properties of
  88             a specific disk with the following attributes:
  89             <dl>
  90               <dt><code>name</code></dt>
  91               <dd>A mandatory attribute which must match either
  92                 the <code>&lt;target dev='name'/&gt;</code> or an
  93                 unambiguous <code>&lt;source file='name'/&gt;</code>
  94                 of one of
  95                 the <a href="formatdomain.html#elementsDisks">disk
  96                 devices</a> specified for the domain at the time of
  97                 the checkpoint.</dd>
  98               <dt><code>checkpoint</code></dt>
  99               <dd>An optional attribute; possible values
 100                 are <code>no</code> when the disk does not participate
 101                 in this checkpoint; or <code>bitmap</code> if the disk
 102                 will track all changes since the creation of this
 103                 checkpoint via a bitmap.</dd>
 104               <dt><code>bitmap</code></dt>
 105               <dd>The attribute <code>bitmap</code> is only valid
 106                 if <code>checkpoint='bitmap'</code>; it describes the
 107                 name of the tracking bitmap (defaulting to the
 108                 checkpoint name).</dd>
 109               <dt><code>size</code></dt>
 110               <dd>The attribute <code>size</code> is ignored on input;
 111                 on output, it is only present if
 112                 the <code>VIR_DOMAIN_CHECKPOINT_XML_SIZE</code> flag
 113                 was used to perform a dynamic query of the estimated
 114                 size in bytes of the changes made since the checkpoint
 115                 was created.</dd>
 116             </dl>
 117           </dd>
 118         </dl>
 119       </dd>
 120       <dt><code>creationTime</code></dt>
 121       <dd>A readonly representation of the time this checkpoint was
 122         created. The time is specified in seconds since the Epoch,
 123         UTC (i.e. Unix time).
 124       </dd>
 125       <dt><code>parent</code></dt>
 126       <dd>Readonly, present if this checkpoint has a parent. The
 127         parent name is given by the sub-element <code>name</code>. The
 128         parent relationship allows tracking a list of related checkpoints.
 129       </dd>
 130       <dt><code>domain</code></dt>
 131       <dd>A readonly representation of the
 132         inactive <a href="formatdomain.html">domain configuration</a>
 133         at the time the checkpoint was created. This element may be
 134         omitted for output brevity by supplying
 135         the <code>VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN</code> flag, but
 136         the resulting XML is no longer viable for use with
 137         the <code>VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE</code> flag
 138         of <code>virDomainCheckpointCreateXML()</code>. The domain
 139         will have security-sensitive information omitted unless the
 140         flag <code>VIR_DOMAIN_CHECKPOINT_XML_SECURE</code> is provided
 141         on a read-write connection.
 142       </dd>
 143     </dl>
 144
 145     <h2><a id="example">Examples</a></h2>
 146
 147     <p>Using this XML to create a checkpoint of just vda on a qemu
 148       domain with two disks and a prior checkpoint:</p>
 149     <pre>
 150 &lt;domaincheckpoint&gt;
 151   &lt;description&gt;Completion of updates after OS install&lt;/description&gt;
 152   &lt;disks&gt;
 153     &lt;disk name='vda' checkpoint='bitmap'/&gt;
 154     &lt;disk name='vdb' checkpoint='no'/&gt;
 155   &lt;/disks&gt;
 156 &lt;/domaincheckpoint&gt;</pre>
 157
 158     <p>will result in XML similar to this from
 159       <code>virDomainCheckpointGetXMLDesc()</code>:</p>
 160     <pre>
 161 &lt;domaincheckpoint&gt;
 162   &lt;name&gt;1525889631&lt;/name&gt;
 163   &lt;description&gt;Completion of updates after OS install&lt;/description&gt;
 164   &lt;parent&gt;
 165     &lt;name&gt;1525111885&lt;/name&gt;
 166   &lt;/parent&gt;
 167   &lt;creationTime&gt;1525889631&lt;/creationTime&gt;
 168   &lt;disks&gt;
 169     &lt;disk name='vda' checkpoint='bitmap' bitmap='1525889631'/&gt;
 170     &lt;disk name='vdb' checkpoint='no'/&gt;
 171   &lt;/disks&gt;
 172   &lt;domain type='qemu'&gt;
 173     &lt;name&gt;fedora&lt;/name&gt;
 174     &lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
 175     &lt;memory&gt;1048576&lt;/memory&gt;
 176     ...
 177     &lt;devices&gt;
 178       &lt;disk type='file' device='disk'&gt;
 179         &lt;driver name='qemu' type='qcow2'/&gt;
 180         &lt;source file='/path/to/file1'/&gt;
 181         &lt;target dev='vda' bus='virtio'/&gt;
 182       &lt;/disk&gt;
 183       &lt;disk type='file' device='disk' snapshot='external'&gt;
 184         &lt;driver name='qemu' type='raw'/&gt;
 185         &lt;source file='/path/to/file2'/&gt;
 186         &lt;target dev='vdb' bus='virtio'/&gt;
 187       &lt;/disk&gt;
 188       ...
 189     &lt;/devices&gt;
 190   &lt;/domain&gt;
 191 &lt;/domaincheckpoint&gt;</pre>
 192
 193     <p>With that checkpoint created, the qcow2 image is now tracking
 194       all changes that occur in the image since the checkpoint via
 195       the persistent bitmap named <code>1525889631</code>.
 196     </p>
 197   </body>
 198 </html>