<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
This file is autogenerated from formatsnapshot.html.in
Do not edit this file. Changes will be lost.
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="SHORTCUT ICON" href="32favicon.png" />
<title>libvirt: Snapshot XML format</title>
<meta name="description" content="libvirt, virtualization, virtualization API" />
</head>
<body>
<div id="header">
<div id="headerLogo"></div>
<div id="headerSearch">
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
<input id="query" name="query" type="text" size="12" value="" />
<input id="submit" name="submit" type="submit" value="Search" />
</div></form>
</div>
</div>
<div id="body">
<div id="menu">
<ul class="l0"><li>
<div>
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
</div>
</li><li>
<div>
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
</div>
</li><li>
<div>
<a title="Applications known to use libvirt" class="inactive" href="apps.html">Applications</a>
</div>
</li><li>
<div>
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
</div>
</li><li>
<div>
<a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
<ul class="l1"><li>
<div>
<a title="How to compile libvirt" class="inactive" href="compiling.html">Compiling</a>
</div>
</li><li>
<div>
<a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
</div>
</li><li>
<div>
<a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
</div>
</li><li>
<div>
<a title="Description of the XML formats used in libvirt" class="active" href="format.html">XML format</a>
<ul class="l2"><li>
<div>
<a title="The domain XML format" class="inactive" href="formatdomain.html">Domains</a>
</div>
</li><li>
<div>
<a title="The virtual network XML format" class="inactive" href="formatnetwork.html">Networks</a>
</div>
</li><li>
<div>
<a title="Network filter XML format" class="inactive" href="formatnwfilter.html">Network Filtering</a>
</div>
</li><li>
<div>
<a title="The storage pool and volume XML format" class="inactive" href="formatstorage.html">Storage</a>
</div>
</li><li>
<div>
<a title="Storage volume encryption XML format" class="inactive" href="formatstorageencryption.html">Storage Encryption</a>
</div>
</li><li>
<div>
<a title="The driver capabilities XML format" class="inactive" href="formatcaps.html">Capabilities</a>
</div>
</li><li>
<div>
<a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
</div>
</li><li>
<div>
<a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
</div>
</li><li>
<div>
<span class="active">Snapshots</span>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
</div>
</li><li>
<div>
<a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
</div>
</li><li>
<div>
<a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
</div>
</li><li>
<div>
<a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
</div>
</li><li>
<div>
<a title="A guide and reference for developing with libvirt" class="inactive" href="devguide.html">Development Guide</a>
</div>
</li><li>
<div>
<a title="Command reference for virsh" class="inactive" href="virshcmdref.html">Virsh Commands</a>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
</div>
</li><li>
<div>
<a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a>
</div>
</li><li>
<div>
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
</div>
</li><li>
<div>
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
</div>
</li><li>
<div>
<a title="Available test suites for libvirt" class="inactive" href="testsuites.html">Test suites</a>
</div>
</li><li>
<div>
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
</div>
</li><li>
<div>
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
</div>
</li></ul>
</div>
<div id="content">
<h1>Snapshot XML format</h1>
<ul><li>
<a href="#SnapshotAttributes">Snapshot XML</a>
</li><li>
<a href="#example">Examples</a>
</li></ul>
<h2>
<a name="SnapshotAttributes" id="SnapshotAttributes">Snapshot XML</a>
</h2>
<p>
There are several types of snapshots:
</p>
<dl><dt>disk snapshot</dt><dd>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).</dd><dt>VM state</dt><dd>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.</dd><dt>system checkpoint</dt><dd>A combination of disk snapshots for all disks as well as VM
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).</dd></dl>
<p>
Libvirt can manage all three types of snapshots. For now, VM
state snapshots are created only by
the <code>virDomainSave()</code>, <code>virDomainSaveFlags</code>,
and <code>virDomainManagedSave()</code> functions, and restored
via the <code>virDomainRestore()</code>,
<code>virDomainRestoreFlags()</code>, <code>virDomainCreate()</code>,
and <code>virDomainCreateWithFlags()</code> 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 <code>virDomainSaveImageGetXMLDesc()</code> to work with
those files.
</p>
<p>System checkpoints are created
by <code>virDomainSnapshotCreateXML()</code> with no flags, and
disk snapshots are created by the same function with
the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code> flag; in
both cases, they are restored by
the <code>virDomainRevertToSnapshot()</code> function. For
these types of snapshots, libvirt tracks each snapshot as a
separate <code>virDomainSnapshotPtr</code> object, and maintains
a tree relationship of which snapshots descended from an earlier
point in time.
</p>
<p>
Attributes of libvirt snapshots are stored as child elements of
the <code>domainsnapshot</code> element. At snapshot creation
time, normally only the <code>name</code>, <code>description</code>,
and <code>disks</code> elements are settable; the rest of the
fields are ignored on creation, and will be filled in by
libvirt in for informational purposes
by <code>virDomainSnapshotGetXMLDesc()</code>. However, when
redefining a snapshot (<span class="since">since 0.9.5</span>),
with the <code>VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE</code> flag
of <code>virDomainSnapshotCreateXML()</code>, all of the XML
described here is relevant.
</p>
<p>
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.
</p>
<p>
The top-level <code>domainsnapshot</code> element may contain
the following elements:
</p>
<dl><dt><code>name</code></dt><dd>The name for this snapshot. If the name is specified when
initially creating the snapshot, then the snapshot will have
that particular name. If the name is omitted when initially
creating the snapshot, then libvirt will make up a name for
the snapshot, based on the time when it was created.
</dd><dt><code>description</code></dt><dd>A human-readable description of the snapshot. If the
description is omitted when initially creating the snapshot,
then this field will be empty.
</dd><dt><code>disks</code></dt><dd>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 system checkpoints, this field is
ignored on input and omitted on output (a system checkpoint
implies that all disks participate in the snapshot process,
and since the current implementation only does internal system
checkpoints, there are no extra details to add); a future
release may allow the use of <code>disks</code> with a system
checkpoint. This element has a list of <code>disk</code>
sub-elements, describing anywhere from zero to all of the
disks associated with the domain. <span class="since">Since
0.9.5</span>
<dl><dt><code>disk</code></dt><dd>This sub-element describes the snapshot properties of a
specific disk. The attribute <code>name</code> is
mandatory, and must match either the <code><target
dev='name'/></code> or an unambiguous <code><source
file='name'/></code> of one of
the <a href="formatdomain.html#elementsDisks">disk
devices</a> specified for the domain at the time of the
snapshot. The attribute <code>snapshot</code> is
optional, and has the same values of the disk device
element for a domain
(<code>no</code>, <code>internal</code>,
or <code>external</code>). 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. If the snapshot mode is
external (whether specified or inherited), then there is
an optional sub-element <code>source</code>, with an
attribute <code>file</code> giving the name, and an
optional sub-element <code>driver</code>, with an
attribute <code>type</code> giving the driver type (such
as qcow2), of the new file created by the external
snapshot of the new file. If <code>source</code> is not
given, 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.
</dd></dl></dd><dt><code>creationTime</code></dt><dd>The time this snapshot was created. The time is specified
in seconds since the Epoch, UTC (i.e. Unix time). Readonly.
</dd><dt><code>state</code></dt><dd>The state of the domain at the time this snapshot was taken.
If the snapshot was created as a system checkpoint, 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
whatever is in this field unless additional flags are passed
to <code>virDomainRevertToSnapshot()</code>. Additionally,
this field can be the value "disk-snapshot"
(<span class="since">since 0.9.5</span>) when it represents
only a disk snapshot (no VM state), and reverting to this
snapshot will default to an inactive guest. Readonly.
</dd><dt><code>parent</code></dt><dd>The parent of this snapshot. If present, this element
contains exactly one child element, name. This specifies the
name of the parent snapshot of this snapshot, and is used to
represent trees of snapshots. Readonly.
</dd><dt><code>domain</code></dt><dd>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
<code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
in <code>virDomainRevertToSnapshot()</code>. Newer versions
of libvirt (<span class="since">since 0.9.5</span>) store the entire
inactive <a href="formatdomain.html">domain configuration</a>
at the time of the snapshot (<span class="since">since
0.9.5</span>). Readonly.
</dd></dl>
<h2>
<a name="example" id="example">Examples</a>
</h2>
<p>Using this XML to create a disk snapshot of just vda on a qemu
domain with two disks:</p>
<pre>
<domainsnapshot>
<description>Snapshot of OS install and updates</description>
<disks>
<disk name='/path/to/old'>
<source file='/path/to/new'/>
</disk>
<disk name='vdb' snapshot='no'/>
</disks>
</domainsnapshot></pre>
<p>will result in XML similar to this from
<code>virDomainSnapshotGetXMLDesc()</code>:</p>
<pre>
<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>
<disks>
<disk name='vda' snapshot='external'>
<driver type='qcow2'/>
<b><source file='/path/to/new'/></b>
</disk>
<disk name='vdb' snapshot='no'/>
</disks>
<domain>
<name>fedora</name>
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
<memory>1048576</memory>
...
<devices>
<disk type='file' device='disk'>
<driver name='qemu' type='raw'/>
<b><source file='/path/to/old'/></b>
<target dev='vda' bus='virtio'/>
</disk>
<disk type='file' device='disk' snapshot='external'>
<driver name='qemu' type='raw'/>
<source file='/path/to/old2'/>
<target dev='vdb' bus='virtio'/>
</disk>
...
</devices>
</domain>
</domainsnapshot></pre>
<p>With that snapshot created, <code>/path/to/old</code> is the
read-only backing file to the new active
file <code>/path/to/new</code>. The <code><domain></code>
element within the snapshot xml records the state of the domain
just before the snapshot; a call
to <code>virDomainGetXMLDesc()</code> will show that the domain
has been changed to reflect the snapshot:
</p>
<pre>
<domain>
<name>fedora</name>
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
<memory>1048576</memory>
...
<devices>
<disk type='file' device='disk'>
<driver name='qemu' type='qcow2'/>
<b><source file='/path/to/new'/></b>
<target dev='vda' bus='virtio'/>
</disk>
<disk type='file' device='disk' snapshot='external'>
<driver name='qemu' type='raw'/>
<source file='/path/to/old2'/>
<target dev='vdb' bus='virtio'/>
</disk>
...
</devices>
</domain></pre>
</div>
</div>
<div id="footer">
<p id="sponsor">
Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
</div>
</body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
cd63cb6f90cc0190f381b8d56f10fc99
>
files
>
47
