mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-08-28 03:21:19 +00:00
f609cb85ca
Just like VM saved state images (virsh save), snapshots MUST track the inactive domain xml to detect any ABI incompatibilities. The indentation is not perfect, but functionality comes before form. Later patches will actually supply a full domain; for now, this wires up the storage to support one, but doesn't ever generate one in dumpxml output. Happily, libvirt.c was already rejecting use of VIR_DOMAIN_XML_SECURE from read-only connections, even though before this patch, there was no information to be secured by the use of that flag. And while we're at it, mark the libvirt snapshot metadata files as internal-use only. * src/libvirt.c (virDomainSnapshotGetXMLDesc): Document flag. * src/conf/domain_conf.h (_virDomainSnapshotDef): Add member. (virDomainSnapshotDefParseString, virDomainSnapshotDefFormat): Update signature. * src/conf/domain_conf.c (virDomainSnapshotDefFree): Clean up. (virDomainSnapshotDefParseString): Optionally parse domain. (virDomainSnapshotDefFormat): Output full domain. * src/esx/esx_driver.c (esxDomainSnapshotCreateXML) (esxDomainSnapshotGetXMLDesc): Update callers. * src/vbox/vbox_tmpl.c (vboxDomainSnapshotCreateXML) (vboxDomainSnapshotGetXMLDesc): Likewise. * src/qemu/qemu_driver.c (qemuDomainSnapshotCreateXML) (qemuDomainSnapshotLoad, qemuDomainSnapshotGetXMLDesc) (qemuDomainSnapshotWriteMetadata): Likewise. * docs/formatsnapshot.html.in: Rework doc example. Based on a patch by Philipp Hahn.
109 lines
4.4 KiB
HTML
109 lines
4.4 KiB
HTML
<html>
|
|
<body>
|
|
<h1>Snapshot XML format</h1>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a name="SnapshotAttributes">Snapshot XML</a></h2>
|
|
|
|
<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>
|
|
and <code>description</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>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.
|
|
When the domain is reverted to this snapshot, the domain's
|
|
state will default to whatever is in this field. Readonly.
|
|
</dd>
|
|
<dt><code>parent</code></dt>
|
|
<dd>The parent of this snapshot. 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, as described above. 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 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">Examples</a></h2>
|
|
|
|
<p>Using this XML on creation:</p>
|
|
<pre>
|
|
<domainsnapshot>
|
|
<description>Snapshot of OS install and updates</description>
|
|
</domainsnapshot></pre>
|
|
|
|
<p>will result in XML similar to this from
|
|
virDomainSnapshotGetXMLDesc:</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>
|
|
<domain>
|
|
<name>fedora</name>
|
|
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
|
|
<memory>1048576</memory>
|
|
...
|
|
</devices>
|
|
</domain>
|
|
</domainsnapshot></pre>
|
|
</body>
|
|
</html>
|