From nobody Mon Feb 9 17:21:56 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 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=1646668824; cv=none; d=zohomail.com; s=zohoarc; b=KQT0F6wvnCVYElLqx6A8Q/smCvGBponv1SEBn+j66f/OZnnkTzyf9bx/aAi991NbzRaDxOhj6rOpqACIghFZrgqyGDFxK1ZRqp34Yl4sWTBDnD2frc1KVNum4P+eaIeQhOKMMGbMoR8RHoQFFk4z7FYgr4RW6SaWJt/8nVoO7Fo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668824; 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=dXmmkfxXy6/GIyoKPFdz0Qd6YxFqSAR5eU7bZC8fS3s=; b=mTXEOw2Pv3rwIqwpRxkGtCpSx6gOmVM0zDdsqu4UUJCWjulvsmTCBNL3BIWxacRlJcnpaiysctJYxIxu3Ys28fzOW9d8d35fQ0JpBxu806xPERR46LjPTEs4UpI7GDMxdgN+eaXAilpP+QGc9GAX9xZ0KA3SMd0p/8BDb+GT0pk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646668823990963.8751329229657; Mon, 7 Mar 2022 08:00:23 -0800 (PST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-288-LXdWd1AJPzS0iet1FXXSYQ-1; Mon, 07 Mar 2022 11:00:17 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 39BC1106655D; Mon, 7 Mar 2022 16:00:02 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1561340CFD14; Mon, 7 Mar 2022 16:00:02 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id ACE541931BE9; Mon, 7 Mar 2022 16:00:01 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B701A196BB83 for ; Mon, 7 Mar 2022 16:00:00 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 86F547DE5E; Mon, 7 Mar 2022 16:00:00 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id A42CB7D3CE for ; Mon, 7 Mar 2022 15:59:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668822; 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=dXmmkfxXy6/GIyoKPFdz0Qd6YxFqSAR5eU7bZC8fS3s=; b=Zd3PxAj5rCSuqqqwbaNuxMiGe0pUXTGXjsP9gP7KJSomPxVA7f9TgJL4156B0XspzRZtUE t3+6/4z1XU5itlWBx9p3G5gd1mt5HIJaajVzJzO5KteeE+DqWTO0mxi7pxqtjIkLyVbVxO nPfT15Taz61NT7BVNbs8T9cHP0QCi48= X-MC-Unique: LXdWd1AJPzS0iet1FXXSYQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 03/17] docs: formatsnapshot: Convert to 'rst' Date: Mon, 7 Mar 2022 16:59:23 +0100 Message-Id: <014b0b8400fef80098e185fb54231720faf54a23.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 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) X-ZM-MESSAGEID: 1646668827857100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/formatsnapshot.html.in | 352 ------------------------------------ docs/formatsnapshot.rst | 297 ++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 298 insertions(+), 353 deletions(-) delete mode 100644 docs/formatsnapshot.html.in create mode 100644 docs/formatsnapshot.rst diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in deleted file mode 100644 index e481284aa8..0000000000 --- a/docs/formatsnapshot.html.in +++ /dev/null @@ -1,352 +0,0 @@ - - - - -

Snapshot XML format

- -
    - -

    Snapshot XML

    - -

    - Snapshots are one form - of domain state - capture. There are several types of snapshots: -

    -
    -
    disk snapshot
    -
    Contents of disks (whether a subset or all disks associated - with the domain) are saved at a given point of time, and can - be restored back to that state. On a running guest, a disk - snapshot is likely to be only crash-consistent rather than - clean (that is, it represents the state of the disk on a - sudden power outage, and may need fsck or journal replays to - be made consistent); on an inactive guest, a disk snapshot is - clean if the disks were clean when the guest was last shut - down. Disk snapshots exist in two forms: internal (file - formats such as qcow2 track both the snapshot and changes - since the snapshot in a single file) and external (the - snapshot is one file, and the changes since the snapshot are - in another file).
    -
    memory state (or VM state)
    -
    Tracks only the state of RAM and all other resources in use - by the VM. If the disks are unmodified between the time a VM - state snapshot is taken and restored, then the guest will - resume in a consistent state; but if the disks are modified - externally in the meantime, this is likely to lead to data - corruption.
    -
    full system
    -
    A combination of disk snapshots for all disks as well as VM - memory state, which can be used to resume the guest from where it - left off with symptoms similar to hibernation (that is, TCP - connections in the guest may have timed out, but no files or - processes are lost).
    -
    - -

    - Libvirt can manage all three types of snapshots. For now, VM - state (memory) snapshots are created only by - the virDomainSave(), virDomainSaveFlags, - and virDomainManagedSave() functions, and restored - via the virDomainRestore(), - virDomainRestoreFlags(), virDomainCreate(), - and virDomainCreateWithFlags() functions (as well - as via domain autostart). With managed snapshots, libvirt - tracks all information internally; with save images, the user - tracks the snapshot file, but libvirt provides functions such - as virDomainSaveImageGetXMLDesc() to work with - those files. -

    -

    Full system snapshots are created - by virDomainSnapshotCreateXML() with no flags, while - disk snapshots are created by the same function with - the VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY - flag. Regardless of the flags provided, restoration of the - snapshot is handled by - the virDomainRevertToSnapshot() function. For - these types of snapshots, libvirt tracks each snapshot as a - separate virDomainSnapshotPtr object, and maintains - a tree relationship of which snapshots descended from an earlier - point in time. -

    - -

    - Attributes of libvirt snapshots are stored as child elements of - the domainsnapshot element. At snapshot 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 virDomainSnapshotGetXMLDesc(). However, when - redefining a snapshot (since 0.9.5), - with the VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE flag - of virDomainSnapshotCreateXML(), all of the XML - described here is relevant on input, even the fields that are - normally described as readonly for output. -

    -

    - Snapshots are maintained in a hierarchy. A domain can have a - current snapshot, which is the most recent snapshot compared to - the current state of the domain (although a domain might have - snapshots without a current snapshot, if snapshots have been - deleted in the meantime). Creating or reverting to a snapshot - sets that snapshot as current, and the prior current snapshot is - the parent of the new snapshot. Branches in the hierarchy can - be formed by reverting to a snapshot with a child, then creating - another snapshot. For now, the creation of external snapshots - when checkpoints exist is forbidden, although future work will - make it possible to integrate these two concepts. -

    -

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

    -
    -
    name
    -
    The optional name for this snapshot. 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 snapshot. If - the description is omitted when initially creating the - snapshot, then this field will be empty. -
    -
    memory
    -
    On input, this is an optional request for how to handle VM - memory state. For an offline domain or a disk-only snapshot, - attribute snapshot must be no, since - there is no VM state saved; otherwise, the attribute can - be internal if the memory state is piggy-backed with - other internal disk state, or external along with - a second attribute file giving the absolute path - of the file holding the VM memory state. Si= nce - 1.0.1 -
    -
    disks
    -
    On input, this is an optional listing of specific - instructions for disk snapshots; it is needed when making a - snapshot of only a subset of the disks associated with a - domain, or when overriding the domain defaults for how to - snapshot each disk, or for providing specific control over - what file name is created in an external snapshot. On output, - this is fully populated to show the state of each disk in the - snapshot, including any properties that were generated by the - hypervisor defaults. For full system snapshots, this field is - ignored on input and omitted on output (a full system snapshot - implies that all disks participate in the snapshot process). - This element has a list of disk - sub-elements, describing anywhere from zero to all of the - disks associated with the domain. Since - 0.9.5 -
    -
    disk
    -
    This sub-element describes the snapshot properties of a - specific disk. The attribute name is - mandatory, and must match either the <target - dev=3D'name'/> (recommended) or an unambiguous - <source file=3D'name'/> of one of - the disk - devices specified for the domain at the time of the - snapshot. The attribute snapshot is - optional, and the possible values are the same as the - snapshot attribute for - disk devices - (no, internal, - or external). Some hypervisors like ESX - require that if specified, the snapshot mode must not - override any snapshot mode attached to the corresponding - domain disk, while others like qemu allow this field to - override the domain default. - -
    -
    source
    -
    If the snapshot mode is external (whether specified - or inherited), then there is an optional sub-element - source, with an attribute file - giving the name of the new file. - If source is not - given and the disk is backed by a local image file (not - a block device or remote storage), a file name is - generated that consists of the existing file name - with anything after the trailing dot replaced by the - snapshot name. Remember that with external - snapshots, the original file name becomes the read-only - snapshot, and the new file name contains the read-write - delta of all disk changes since the snapshot. -

    - The source element also may contain the - seclabel element (described in the - domain XML documentat= ion) - which can be used to override the domain security labeling p= olicy - for source. -

    -
    driver
    -
    An optional sub-element driver, - with an attribute type giving the driver type (= such - as qcow2), of the new file created by the external - snapshot of the new file. - - Optionally metadata_cache sub-element can be us= ed - with same semantics as the identically named subelement of t= he - domain definition disk's driver. -
    -
    seclabel
    -
    - - Since 1.2.2 the disk= element - supports an optional attribute type if the - snapshot attribute is set to external. - This attribute specifies the snapshot target storage type and = allows - to overwrite the default file type. The typ= e - attribute along with the format of the source - sub-element is identical to the source element us= ed in - domain disk definitions. See the - disk devices s= ection - documentation for further information. - - Libvirt currently supports the type element in th= e qemu - driver and supported values are file, block= - and network with a protocol of gluster - (since 1.2.2). -
    -
    -
    -
    creationTime
    -
    A readonly representation of the time this snapshot was - created. The time is specified in seconds since the Epoch, - UTC (i.e. Unix time). -
    -
    state
    -
    A readonly representation of the state of the domain at the - time this snapshot was taken. If a full system snapshot was - created, then this is the state of the domain at that - time. When the domain is reverted to this snapshot, the - domain's state will default to this state, unless overridden - by virDomainRevertToSnapshot() flags to revert to - a running or paused state. Additionally, this field can be the - value "disk-snapshot" (since 0.9.5) - when it represents only a disk snapshot (no VM memory state), - and reverting to this snapshot will default to an inactive - guest. -
    -
    parent
    -
    Readonly, present only if this snapshot has a parent. The - parent name is given by the sub-element name. The - parent relationship allows tracking a tree of related snapshots. -
    -
    domain
    -
    A readonly representation of the domain that this snapshot - was taken against. Older versions of libvirt stored only a - single child element, uuid; reverting to a snapshot like this - is risky if the current state of the domain differs from the - state that the domain was created in, and requires the use of - the VIR_DOMAIN_SNAPSHOT_REVERT_FORCE flag - in virDomainRevertToSnapshot(). Newer versions - of libvirt (since 0.9.5) store the - entire inactive domain - configuration at the time of the snapshot - (since 0.9.5). The domain will have - security-sensitive information omitted - unless the flag VIR_DOMAIN_SNAPSHOT_XML_SECURE is - provided on a read-write connection. -
    -
    cookie
    -
    An optional readonly representation of a save image cookie - containing additional data libvirt may need to properly - restore a domain from an active snapshot when such data cannot - be stored directly in the domain to maintain - compatibility with older libvirt or hypervisor. -
    -
    - -

    Examples

    - -

    Using this XML to create a disk snapshot of just vda on a qemu - domain with two disks:

    - 
    -<domainsnapshot>
-  <description>Snapshot of OS install and updates</description>
-  <disks>
-    <disk name=3D'vda'>
-      <source file=3D'/path/to/new'/>
-    </disk>
-    <disk name=3D'vdb' snapshot=3D'no'/>
-    <disk name=3D'vdc'>
-      <source file=3D'/path/to/newc'>
-        <seclabel model=3D'dac' relabel=3D'no'/>
-      </source>
-    </disk>
-  </disks>
-</domainsnapshot>
    - -

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

    - 
    -<domainsnapshot>
-  <name>1270477159</name>
-  <description>Snapshot of OS install and updates</description>
-  <state>running</state>
-  <creationTime>1270477159</creationTime>
-  <parent>
-    <name>bare-os-install</name>
-  </parent>
-  <memory snapshot=3D'no'/>
-  <disks>
-    <disk name=3D'vda' snapshot=3D'external'>
-      <driver type=3D'qcow2'/>
-      <source file=3D'/path/to/new'/>
-    </disk>
-    <disk name=3D'vdb' snapshot=3D'no'/>
-  </disks>
-  <domain>
-    <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'raw'/>
-        <source file=3D'/path/to/old'/>
-        <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/old2'/>
-        <target dev=3D'vdb' bus=3D'virtio'/>
-      </disk>
-      ...
-    </devices>
-  </domain>
-</domainsnapshot>
    - -

    With that snapshot created, /path/to/old is the - read-only backing file to the new active - file /path/to/new. The <domain> - element within the snapshot xml records the state of the domain - just before the snapshot; a call - to virDomainGetXMLDesc() will show that the domain - has been changed to reflect the snapshot: -

    - 
    -<domain>
-  <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/new'/>
-      <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/old2'/>
-      <target dev=3D'vdb' bus=3D'virtio'/>
-    </disk>
-    ...
-  </devices>
-</domain>
    - - diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst new file mode 100644 index 0000000000..0ad397316c --- /dev/null +++ b/docs/formatsnapshot.rst @@ -0,0 +1,297 @@ +.. role:: since + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Snapshot XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Snapshot XML +------------ + +Snapshots are one form of `domain state +capture `__. There are several types of +snapshots: + +disk snapshot + Contents of disks (whether a subset or all disks associated with the do= main) + are saved at a given point of time, and can be restored back to that st= ate. + On a running guest, a disk snapshot is likely to be only crash-consiste= nt + rather than clean (that is, it represents the state of the disk on a su= dden + power outage, and may need fsck or journal replays to be made consisten= t); on + an inactive guest, a disk snapshot is clean if the disks were clean whe= n the + guest was last shut down. Disk snapshots exist in two forms: internal (= file + formats such as qcow2 track both the snapshot and changes since the sna= pshot + in a single file) and external (the snapshot is one file, and the chang= es + since the snapshot are in another file). +memory state (or VM state) + Tracks only the state of RAM and all other resources in use by the VM. = If the + disks are unmodified between the time a VM state snapshot is taken and + restored, then the guest will resume in a consistent state; but if the = disks + are modified externally in the meantime, this is likely to lead to data + corruption. +full system + A combination of disk snapshots for all disks as well as VM memory stat= e, + which can be used to resume the guest from where it left off with sympt= oms + similar to hibernation (that is, TCP connections in the guest may have = timed + out, but no files or processes are lost). + +Libvirt can manage all three types of snapshots. For now, VM state (memory) +snapshots are created only by the ``virDomainSave()``, ``virDomainSaveFlag= s``, +and ``virDomainManagedSave()`` functions, and restored via the +``virDomainRestore()``, ``virDomainRestoreFlags()``, ``virDomainCreate()``= , and +``virDomainCreateWithFlags()`` functions (as well as via domain autostart)= . With +managed snapshots, libvirt tracks all information internally; with save im= ages, +the user tracks the snapshot file, but libvirt provides functions such as +``virDomainSaveImageGetXMLDesc()`` to work with those files. + +Full system snapshots are created by ``virDomainSnapshotCreateXML()`` with= no +flags, while disk snapshots are created by the same function with the +``VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY`` flag. Regardless of the flags pro= vided, +restoration of the snapshot is handled by the ``virDomainRevertToSnapshot(= )`` +function. For these types of snapshots, libvirt tracks each snapshot as a +separate ``virDomainSnapshotPtr`` object, and maintains a tree relationshi= p of +which snapshots descended from an earlier point in time. + +Attributes of libvirt snapshots are stored as child elements of the +``domainsnapshot`` element. At snapshot creation time, normally only the +``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 ``virDomainSnapshotGetXMLDesc()``. However, when +redefining a snapshot ( :since:`since 0.9.5` ), with the +``VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE`` flag of +``virDomainSnapshotCreateXML()``, all of the XML described here is relevan= t on +input, even the fields that are normally described as readonly for output. + +Snapshots are maintained in a hierarchy. A domain can have a current snaps= hot, +which is the most recent snapshot compared to the current state of the dom= ain +(although a domain might have snapshots without a current snapshot, if sna= pshots +have been deleted in the meantime). Creating or reverting to a snapshot se= ts +that snapshot as current, and the prior current snapshot is the parent of = the +new snapshot. Branches in the hierarchy can be formed by reverting to a sn= apshot +with a child, then creating another snapshot. For now, the creation of ext= ernal +snapshots when checkpoints exist is forbidden, although future work will m= ake it +possible to integrate these two concepts. + +The top-level ``domainsnapshot`` element may contain the following element= s: + +``name`` + + The optional name for this snapshot. If the name is omitted, libvirt wi= ll + create a name based on the time of the creation. + +``description`` + + An optional human-readable description of the snapshot. If the descript= ion + is omitted when initially creating the snapshot, then this field will be + empty. + +``memory`` + + On input, this is an optional request for how to handle VM memory state= . For + an offline domain or a disk-only snapshot, attribute ``snapshot`` must = be + ``no``, since there is no VM state saved; otherwise, the attribute can = be + ``internal`` if the memory state is piggy-backed with other internal di= sk + state, or ``external`` along with a second attribute ``file`` giving the + absolute path of the file holding the VM memory state. :since:`Since 1.= 0.1` + +``disks`` + + On input, this is an optional listing of specific instructions for disk + snapshots; it is needed when making a snapshot of only a subset of the = disks + associated with a domain, or when overriding the domain defaults for ho= w to + snapshot each disk, or for providing specific control over what file na= me is + created in an external snapshot. On output, this is fully populated to = show + the state of each disk in the snapshot, including any properties that w= ere + generated by the hypervisor defaults. For full system snapshots, this f= ield + is ignored on input and omitted on output (a full system snapshot impli= es + that all disks participate in the snapshot process). This element has a= list + of ``disk`` sub-elements, describing anywhere from zero to all of the d= isks + associated with the domain. :since:`Since 0.9.5` + + ``disk`` + + This sub-element describes the snapshot properties of a specific dis= k. + The attribute ``name`` is mandatory, and must match either the ```` (recommended) or an unambiguous ```` + of one of the `disk devices `__ + specified for the domain at the time of the snapshot. The attribute + ``snapshot`` is optional, and the possible values are the same as the + ``snapshot`` attribute for `disk devices + `__ (``no``, ``internal``, or + ``external``). Some hypervisors like ESX require that if specified, = the + snapshot mode must not override any snapshot mode attached to the + corresponding domain disk, while others like qemu allow this field to + override the domain default. + + ``source`` + + If the snapshot mode is external (whether specified or inherited), + then there is an optional sub-element ``source``, with an attribu= te + ``file`` giving the name of the new file. If ``source`` is not gi= ven + and the disk is backed by a local image file (not a block device = or + remote storage), a file name is generated that consists of the + existing file name with anything after the trailing dot replaced = by + the snapshot name. Remember that with external snapshots, the ori= ginal + file name becomes the read-only snapshot, and the new file name + contains the read-write delta of all disk changes since the snaps= hot. + + The ``source`` element also may contain the ``seclabel`` element + (described in the `domain XML documentation + `__) which can be used to override the + domain security labeling policy for ``source``. + + ``driver`` + + An optional sub-element ``driver``, with an attribute ``type`` gi= ving + the driver type (such as qcow2), of the new file created by the + external snapshot of the new file. Optionally ``metadata_cache`` + sub-element can be used with same semantics as the identically na= med + subelement of the domain definition disk's driver. + + ``seclabel`` + + :since:`Since 1.2.2` the ``disk`` element supports an optional attri= bute + ``type`` if the ``snapshot`` attribute is set to ``external``. This + attribute specifies the snapshot target storage type and allows to + overwrite the default ``file`` type. The ``type`` attribute along wi= th + the format of the ``source`` sub-element is identical to the ``sourc= e`` + element used in domain disk definitions. See the `disk devices + `__ section documentation for furth= er + information. Libvirt currently supports the ``type`` element in the = qemu + driver and supported values are ``file``, ``block`` and ``network`` = with + a protocol of ``gluster`` :since:`(since 1.2.2)` . + +``creationTime`` + + A readonly representation of the time this snapshot was created. The ti= me is + specified in seconds since the Epoch, UTC (i.e. Unix time). + +``state`` + + A readonly representation of the state of the domain at the time this + snapshot was taken. If a full system snapshot was created, then this is= the + state of the domain at that time. When the domain is reverted to this + snapshot, the domain's state will default to this state, unless overrid= den + by ``virDomainRevertToSnapshot()`` flags to revert to a running or paus= ed + state. Additionally, this field can be the value "disk-snapshot" ( + :since:`since 0.9.5`) when it represents only a disk snapshot (no VM me= mory + state), and reverting to this snapshot will default to an inactive gues= t. + +``parent`` + + Readonly, present only if this snapshot has a parent. The parent name is + given by the sub-element ``name``. The parent relationship allows track= ing a + tree of related snapshots. + +``domain`` + + A readonly representation of the domain that this snapshot was taken + against. Older versions of libvirt stored only a single child element, + uuid; reverting to a snapshot like this is risky if the current state o= f the + domain differs from the state that the domain was created in, and requi= res + the use of the ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in + ``virDomainRevertToSnapshot()``. Newer versions of libvirt ( :since:`s= ince + 0.9.5` ) store the entire inactive `domain configuration + `__ at the time of the snapshot ( :since:`since 0.9.= 5` ). + The domain will have security-sensitive information omitted unless the = flag + ``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connecti= on. + +``cookie`` + + An optional readonly representation of a save image cookie containing + additional data libvirt may need to properly restore a domain from an a= ctive + snapshot when such data cannot be stored directly in the ``domain`` to + maintain compatibility with older libvirt or hypervisor. + +Examples +-------- + +Using this XML to create a disk snapshot of just vda on a qemu domain with= two +disks: + +:: + + + Snapshot of OS install and updates + + + + + + + + + + + + + +will result in XML similar to this from ``virDomainSnapshotGetXMLDesc()``: + +:: + + + 1270477159 + Snapshot of OS install and updates + running + 1270477159 + + bare-os-install + + + + + + + + + + + fedora + 93a5c045-6457-2c09-e56c-927cdf34e178 + 1048576 + ... + + + + + + + + + + + + ... + + + + +With that snapshot created, ``/path/to/old`` is the read-only backing file= to +the new active file ``/path/to/new``. The ```` element within the +snapshot xml records the state of the domain just before the snapshot; a c= all to +``virDomainGetXMLDesc()`` will show that the domain has been changed to re= flect +the snapshot: + +:: + + + fedora + 93a5c045-6457-2c09-e56c-927cdf34e178 + 1048576 + ... + + + + + + + + + + + + ... + + diff --git a/docs/meson.build b/docs/meson.build index 3caaa76735..adb7ac091e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files =3D [ 'formatnode', 'formatnwfilter', 'formatsecret', - 'formatsnapshot', 'formatstoragecaps', 'formatstorageencryption', 'goals', @@ -99,6 +98,7 @@ docs_rst_files =3D [ 'formatbackup', 'formatcheckpoint', 'formatdomain', + 'formatsnapshot', 'formatstorage', 'glib-adoption', 'hacking', --=20 2.35.1