mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-01-25 22:15:20 +00:00
af65695af0
The first two flags are essential for being able to replicate snapshot hierarchies across multiple hosts, which will come in handy for supervised migrations. It also allows a management app to take a snapshot of a transient domain, save the metadata, stop the domain, recreate a new transient domain by the same name, redefine the snapshot, then revert to it. This is not quite as convenient as leaving the metadata behind after a domain is no longer around, but doing that has a few problems: 1. the libvirt API can only delete snapshot metadata if there is a valid domain handle to use to get to that snapshot object - if stale data is left behind without a domain, there is no way to request that the data be cleaned up. 2. creating a new domain with the same name but different uuid than the older domain where a snapshot existed cannot use the older snapshot data; this risks confusing libvirt, and forbidding the stale data is similar to the recent patch to forbid stale managed save. The first two flags might be useful on hypervisors with no metadata, but only for modifying the notion of the current snapshot; however, I don't know how to do that for ESX or VBox. The third flag is a convenience option, to combine a creation with a delete metadata into one step. It is trivial for hypervisors with no metadata. The qemu changes will be involved enough to warrant a separate patch. * include/libvirt/libvirt.h.in (VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE) (VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT) (VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA): New flags. * src/libvirt.c (virDomainSnapshotCreateXML): Document them, and enforce mutual exclusion. * src/esx/esx_driver.c (esxDomainSnapshotCreateXML): Trivial implementation. * src/vbox/vbox_tmpl.c (vboxDomainSnapshotCreateXML): Likewise. * docs/formatsnapshot.html.in: Document re-creation.
90 lines
3.6 KiB
HTML
90 lines
3.6 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. This
|
|
element contains exactly one child element, uuid. This
|
|
specifies the uuid of the domain that this snapshot was taken
|
|
against. Readonly.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2><a name="example">Example</a></h2>
|
|
|
|
<pre>
|
|
<domainsnapshot>
|
|
<name>os-updates</name>
|
|
<description>Snapshot of OS install and updates</description>
|
|
<state>running</state>
|
|
<creationTime>1270477159</creationTime>
|
|
<parent>
|
|
<name>bare-os-install</name>
|
|
</parent>
|
|
<domain>
|
|
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
|
|
</domain>
|
|
</domainsnapshot></pre>
|
|
</body>
|
|
</html>
|