From nobody Sun Feb 8 23:41:02 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1593701206; cv=none; d=zohomail.com; s=zohoarc; b=YLUPd6tFjzIuRtq0eJT1x4VDqFEqz0qhFKEmIeCar40Beg+0QXFnJbqNYLe+us9q4ReDt/dVba0RSIigE5bTcYc/Hi8BcjnM/lvHrG/5S/QFYFDMayRSTKtanZaOBe1MO8Mmm9kgBXZYqoA3EwYiuj+QH6ubT2GltrS2NtGUHKI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1593701206; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Z6Z3aUwPRePpRZkhLLvmEgfFs6BZcQMjo1nm+nXR3QI=; b=EYdnsNJKrP5DBVmQXbYBGTAAlK1NaVP1plZ2xhNaos0ycn9XupConb6atgKpvaFplelg0XteexU+cwE57DU/i5A9H6jmeVcx1sQqzF7SAaGq8FAJvbamW0HHzVrvoFwzTN0T0trPAFY7dVacw7sl33LNqI0N9vazcW+/lZcYVJo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 1593701206134350.23107780474913; Thu, 2 Jul 2020 07:46:46 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-272-N7pa_OcMMC2U-FqlJMDIAw-1; Thu, 02 Jul 2020 10:46:42 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 807F0EC1A1; Thu, 2 Jul 2020 14:46:34 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 613922B4BE; Thu, 2 Jul 2020 14:46:34 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 3307A6C9D1; Thu, 2 Jul 2020 14:46:34 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 062EeYA1011846 for ; Thu, 2 Jul 2020 10:40:34 -0400 Received: by smtp.corp.redhat.com (Postfix) id 0E1481002397; Thu, 2 Jul 2020 14:40:34 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.18]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7034710013D2 for ; Thu, 2 Jul 2020 14:40:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1593701204; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Z6Z3aUwPRePpRZkhLLvmEgfFs6BZcQMjo1nm+nXR3QI=; b=ZBQRcCQ6hcSeG+NDH0/7wdkaHXlpVA66HI6xWb6hx/iDd50eaqLcjmoy1DRlIPP0Gbv9mb 57rvNlbBOvywVumjG3T7oXWAiTYZKs3DIkSZVZlI/bSXy9TqR7l7huUE043hpYSAezUP4T EAN8oLE2tw1C1WZzzuBbOnCA+7kM1Ss= X-MC-Unique: N7pa_OcMMC2U-FqlJMDIAw-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 16/24] docs: checkpoint: Convert XML documentation to RST Date: Thu, 2 Jul 2020 16:40:02 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Switch to the new format for easier extension. Signed-off-by: Peter Krempa Reviewed-by: Eric Blake --- docs/formatcheckpoint.html.in | 198 ---------------------------------- docs/formatcheckpoint.rst | 162 ++++++++++++++++++++++++++++ 2 files changed, 162 insertions(+), 198 deletions(-) delete mode 100644 docs/formatcheckpoint.html.in create mode 100644 docs/formatcheckpoint.rst diff --git a/docs/formatcheckpoint.html.in b/docs/formatcheckpoint.html.in deleted file mode 100644 index ee56194523..0000000000 --- a/docs/formatcheckpoint.html.in +++ /dev/null @@ -1,198 +0,0 @@ - - - - -

Checkpoint XML format

- -
    - -

    Checkpoint XML

    - -

    - One method of capturing domain disk backups is via the use of - incremental backups. Right now, incremental backups are only - supported for the QEMU hypervisor when using qcow2 disks at the - active layer; if other disk formats are in use, capturing disk - backups requires different libvirt APIs - (see domain state - capture for a comparison between APIs). -

    -

    - Libvirt is able to facilitate incremental backups by tracking - disk checkpoints, which are points in time against which it is - easy to compute which portion of the disk has changed. Given a - full backup (a backup created from the creation of the disk to a - given point in time), coupled with the creation of a disk - checkpoint at that time, and an incremental backup (a backup - created from just the dirty portion of the disk between the - first checkpoint and the second backup operation), it is - possible to do an offline reconstruction of the state of the - disk at the time of the second backup without having to copy as - much data as a second full backup would require. Most disk - checkpoints are created in conjunction with a backup - via virDomainBackupBegin(), although a future API - addition of virDomainSnapshotCreateXML2() will also - make this possible when creating external snapshots; however, - libvirt also exposes enough support to create disk checkpoints - independently from a backup operation - via virDomainCheckpointCreateXML() since - 5.6.0. Likewise, the creation of checkpoints when - external snapshots exist is currently forbidden, although future - work will make it possible to integrate these two concepts. -

    -

    - Attributes of libvirt checkpoints are stored as child elements - of the domaincheckpoint element. At checkpoint - creation time, normally only - the name, description, - and disks elements are settable. The rest of the - fields are ignored on creation and will be filled in by libvirt - in for informational purposes - by virDomainCheckpointGetXMLDesc(). However, when - redefining a checkpoint, with - the VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE flag - of virDomainCheckpointCreateXML(), all of the XML - fields described here are relevant on input, even the fields - that are normally described as readonly for output. -

    -

    - The top-level domaincheckpoint element may contain - the following elements: -

    -
    -
    name
    -
    The optional name for this checkpoint. If the name is - omitted, libvirt will create a name based on the time of the - creation. -
    -
    description
    -
    An optional human-readable description of the checkpoint. - If the description is omitted when initially creating the - checkpoint, then this field will be empty. -
    -
    disks
    -
    On input, this is an optional listing of specific - instructions for disk checkpoints; it is needed when making a - checkpoint on only a subset of the disks associated with a - domain. In particular, since QEMU checkpoints require qcow2 - disks, this element may be needed on input for excluding guest - disks that are not in qcow2 format. If the entire element was - omitted on input, then all disks participate in the - checkpoint, otherwise, only the disks explicitly listed which - do not also use checkpoint=3D'no' will - participate. On output, this is the checkpoint state of each - of the domain's disks. -
    -
    disk
    -
    This sub-element describes the checkpoint properties of - a specific disk with the following attributes: -
    -
    name
    -
    A mandatory attribute which must match either - the <target dev=3D'name'/> or an - unambiguous <source file=3D'name'/> - of one of - the disk - devices specified for the domain at the time of - the checkpoint.
    -
    checkpoint
    -
    An optional attribute; possible values - are no when the disk does not participate - in this checkpoint; or bitmap if the disk - will track all changes since the creation of this - checkpoint via a bitmap.
    -
    bitmap
    -
    The attribute bitmap is only valid - if checkpoint=3D'bitmap'; it describes the - name of the tracking bitmap (defaulting to the - checkpoint name).
    -
    size
    -
    The attribute size is ignored on input; - on output, it is only present if - the VIR_DOMAIN_CHECKPOINT_XML_SIZE flag - was used to perform a dynamic query of the estimated - size in bytes of the changes made since the checkpoint - was created.
    -
    -
    -
    -
    -
    creationTime
    -
    A readonly representation of the time this checkpoint was - created. The time is specified in seconds since the Epoch, - UTC (i.e. Unix time). -
    -
    parent
    -
    Readonly, present if this checkpoint has a parent. The - parent name is given by the sub-element name. The - parent relationship allows tracking a list of related checkpoints. -
    -
    domain
    -
    A readonly representation of the - inactive domain configuration - at the time the checkpoint was created. This element may be - omitted for output brevity by supplying - the VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN flag, but - the resulting XML is no longer viable for use with - the VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE flag - of virDomainCheckpointCreateXML(). The domain - will have security-sensitive information omitted unless the - flag VIR_DOMAIN_CHECKPOINT_XML_SECURE is provided - on a read-write connection. -
    -
    - -

    Examples

    - -

    Using this XML to create a checkpoint of just vda on a qemu - domain with two disks and a prior checkpoint:

    - 
    -<domaincheckpoint>
-  <description>Completion of updates after OS install</descriptio=
n>
-  <disks>
-    <disk name=3D'vda' checkpoint=3D'bitmap'/>
-    <disk name=3D'vdb' checkpoint=3D'no'/>
-  </disks>
-</domaincheckpoint>
    - -

    will result in XML similar to this from - virDomainCheckpointGetXMLDesc():

    - 
    -<domaincheckpoint>
-  <name>1525889631</name>
-  <description>Completion of updates after OS install</descriptio=
n>
-  <parent>
-    <name>1525111885</name>
-  </parent>
-  <creationTime>1525889631</creationTime>
-  <disks>
-    <disk name=3D'vda' checkpoint=3D'bitmap' bitmap=3D'1525889631'/>
-    <disk name=3D'vdb' checkpoint=3D'no'/>
-  </disks>
-  <domain type=3D'qemu'>
-    <name>fedora</name>
-    <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
-    <memory>1048576</memory>
-    ...
-    <devices>
-      <disk type=3D'file' device=3D'disk'>
-        <driver name=3D'qemu' type=3D'qcow2'/>
-        <source file=3D'/path/to/file1'/>
-        <target dev=3D'vda' bus=3D'virtio'/>
-      </disk>
-      <disk type=3D'file' device=3D'disk' snapshot=3D'external'>
-        <driver name=3D'qemu' type=3D'raw'/>
-        <source file=3D'/path/to/file2'/>
-        <target dev=3D'vdb' bus=3D'virtio'/>
-      </disk>
-      ...
-    </devices>
-  </domain>
-</domaincheckpoint>
    - -

    With that checkpoint created, the qcow2 image is now tracking - all changes that occur in the image since the checkpoint via - the persistent bitmap named 1525889631. -

    - - diff --git a/docs/formatcheckpoint.rst b/docs/formatcheckpoint.rst new file mode 100644 index 0000000000..e45745390a --- /dev/null +++ b/docs/formatcheckpoint.rst @@ -0,0 +1,162 @@ +Checkpoint XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Checkpoint XML +-------------- + +One method of capturing domain disk backups is via the use of incremental +backups. Right now, incremental backups are only supported for the QEMU +hypervisor when using qcow2 disks at the active layer; if other disk forma= ts are +in use, capturing disk backups requires different libvirt APIs (see `domain +state capture `__ for a comparison between = APIs). + +Libvirt is able to facilitate incremental backups by tracking disk checkpo= ints, +which are points in time against which it is easy to compute which portion= of +the disk has changed. Given a full backup (a backup created from the creat= ion of +the disk to a given point in time), coupled with the creation of a disk +checkpoint at that time, and an incremental backup (a backup created from = just +the dirty portion of the disk between the first checkpoint and the second = backup +operation), it is possible to do an offline reconstruction of the state of= the +disk at the time of the second backup without having to copy as much data = as a +second full backup would require. Most disk checkpoints are created in +conjunction with a backup via ``virDomainBackupBegin()``, although a futur= e API +addition of ``virDomainSnapshotCreateXML2()`` will also make this possible= when +creating external snapshots; however, libvirt also exposes enough support = to +create disk checkpoints independently from a backup operation via +``virDomainCheckpointCreateXML()`` since 5.6.0. Likewise, the creation of +checkpoints when external snapshots exist is currently forbidden, although +future work will make it possible to integrate these two concepts. + +Attributes of libvirt checkpoints are stored as child elements of the +``domaincheckpoint`` element. At checkpoint creation time, normally only t= he +``name``, ``description``, and ``disks`` elements are settable. The rest o= f the +fields are ignored on creation and will be filled in by libvirt in for +informational purposes by ``virDomainCheckpointGetXMLDesc()``. However, wh= en +redefining a checkpoint, with the ``VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE`= ` flag +of ``virDomainCheckpointCreateXML()``, all of the XML fields described her= e are +relevant on input, even the fields that are normally described as readonly= for +output. + +The top-level ``domaincheckpoint`` element may contain the following eleme= nts: + +``name`` + The optional name for this checkpoint. If the name is omitted, libvirt = will + create a name based on the time of the creation. + +``description`` + An optional human-readable description of the checkpoint. If the descri= ption + is omitted when initially creating the checkpoint, then this field will= be + empty. + +``disks`` + On input, this is an optional listing of specific instructions for disk + checkpoints; it is needed when making a checkpoint on only a subset of = the + disks associated with a domain. In particular, since QEMU checkpoints r= equire + qcow2 disks, this element may be needed on input for excluding guest di= sks + that are not in qcow2 format. If the entire element was omitted on inpu= t, + then all disks participate in the checkpoint, otherwise, only the disks + explicitly listed which do not also use ``checkpoint=3D'no'`` will part= icipate. + On output, this is the checkpoint state of each of the domain's disks. + + ``disk`` + This sub-element describes the checkpoint properties of a specific d= isk + with the following attributes: + + ``name`` + A mandatory attribute which must match either the + ```` or an unambiguous ```` of + one of the `disk devices `__ spe= cified + for the domain at the time of the checkpoint. + + ``checkpoint`` + An optional attribute; possible values are ``no`` when the disk d= oes + not participate in this checkpoint; or ``bitmap`` if the disk will + track all changes since the creation of this checkpoint via a bit= map. + + ``bitmap`` + The attribute ``bitmap`` is only valid if ``checkpoint=3D'bitmap'= ``; it + describes the name of the tracking bitmap (defaulting to the chec= kpoint + name). + + ``size`` + The attribute ``size`` is ignored on input; on output, it is only + present if the ``VIR_DOMAIN_CHECKPOINT_XML_SIZE`` flag was used to + perform a dynamic query of the estimated size in bytes of the cha= nges + made since the checkpoint was created. + +``creationTime`` + A readonly representation of the time this checkpoint was created. The = time + is specified in seconds since the Epoch, UTC (i.e. Unix time). + +``parent`` + Readonly, present if this checkpoint has a parent. The parent name is g= iven + by the sub-element ``name``. The parent relationship allows tracking a = list + of related checkpoints. + +``domain`` + A readonly representation of the inactive `domain + configuration `__ at the time the checkpoint was cre= ated. + This element may be omitted for output brevity by supplying the + ``VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN`` flag, but the resulting XML is = no + longer viable for use with the ``VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE`= ` flag + of ``virDomainCheckpointCreateXML()``. The domain will have + security-sensitive information omitted unless the flag + ``VIR_DOMAIN_CHECKPOINT_XML_SECURE`` is provided on a read-write connec= tion. + +Examples +-------- + +Using this XML to create a checkpoint of just vda on a qemu domain with two +disks and a prior checkpoint: + +:: + + + Completion of updates after OS install + + + + + + +will result in XML similar to this from ``virDomainCheckpointGetXMLDesc()`= `: + +:: + + + 1525889631 + Completion of updates after OS install + + 1525111885 + + 1525889631 + + + + + + fedora + 93a5c045-6457-2c09-e56c-927cdf34e178 + 1048576 + ... + + + + + + + + + + + + ... + + + + +With that checkpoint created, the qcow2 image is now tracking all changes = that +occur in the image since the checkpoint via the persistent bitmap named +``1525889631``. --=20 2.26.2