2013-05-03 22:25:37 +08:00
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
2017-07-27 01:01:25 +08:00
|
|
|
<!DOCTYPE html>
|
2013-05-03 22:25:37 +08:00
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
2010-04-06 01:27:41 +08:00
|
|
|
<body>
|
|
|
|
|
<h1>Snapshot XML format</h1>
|
|
|
|
|
|
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
|
|
2017-07-26 22:52:42 +08:00
|
|
|
<h2><a id="SnapshotAttributes">Snapshot XML</a></h2>
|
2010-04-06 01:27:41 +08:00
|
|
|
|
2011-08-19 08:14:40 +08:00
|
|
|
<p>
|
2019-07-11 01:09:22 +08:00
|
|
|
Snapshots are one form
|
|
|
|
|
of <a href="kbase/domainstatecapture.html">domain state
|
|
|
|
|
capture</a>. There are several types of snapshots:
|
2011-08-19 08:14:40 +08:00
|
|
|
</p>
|
|
|
|
|
<dl>
|
2016-10-31 20:04:54 +08:00
|
|
|
<dt>disk snapshot</dt>
|
2011-08-19 08:14:40 +08:00
|
|
|
<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>
|
2016-10-31 20:04:54 +08:00
|
|
|
<dt>memory state (or VM state)</dt>
|
2011-08-19 08:14:40 +08:00
|
|
|
<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>
|
2018-06-11 21:59:10 +08:00
|
|
|
<dt>full system</dt>
|
2011-08-19 08:14:40 +08:00
|
|
|
<dd>A combination of disk snapshots for all disks as well as VM
|
snapshot: new XML for external system checkpoint
Each <domainsnapshot> can now contain an optional <memory>
element that describes how the VM state was handled, similar
to disk snapshots. The new element will always appear in
output; for back-compat, an input that lacks the element will
assume 'no' or 'internal' according to the domain state.
Along with this change, it is now possible to pass <disks> in
the XML for an offline snapshot; this also needs to be wired up
in a future patch, to make it possible to choose internal vs.
external on a per-disk basis for each disk in an offline domain.
At that point, using the --disk-only flag for an offline domain
will be able to work.
For some examples below, remember that qemu supports the
following snapshot actions:
qemu-img: offline external and internal disk
savevm: online internal VM and disk
migrate: online external VM
transaction: online external disk
=====
<domainsnapshot>
<memory snapshot='no'/>
...
</domainsnapshot>
implies that there is no VM state saved (mandatory for
offline and disk-only snapshots, not possible otherwise);
using qemu-img for offline domains and transaction for online.
=====
<domainsnapshot>
<memory snapshot='internal'/>
...
</domainsnapshot>
state is saved inside one of the disks (as in qemu's 'savevm'
system checkpoint implementation). If needed in the future,
we can also add an attribute pointing out _which_ disk saved
the internal state; maybe disk='vda'.
=====
<domainsnapshot>
<memory snapshot='external' file='/path/to/state'/>
...
</domainsnapshot>
This is not wired up yet, but future patches will allow this to
control a combination of 'virsh save /path/to/state' plus disk
snapshots from the same point in time.
=====
So for 1.0.1 (and later, as needed), I plan to implement this table
of combinations, with '*' designating new code and '+' designating
existing code reached through new combinations of xml and/or the
existing DISK_ONLY flag:
domain memory disk disk-only | result
-----------------------------------------
offline omit omit any | memory=no disk=int, via qemu-img
offline no omit any |+memory=no disk=int, via qemu-img
offline omit/no no any | invalid combination (nothing to snapshot)
offline omit/no int any |+memory=no disk=int, via qemu-img
offline omit/no ext any |*memory=no disk=ext, via qemu-img
offline int/ext any any | invalid combination (no memory to save)
online omit omit off | memory=int disk=int, via savevm
online omit omit on | memory=no disk=default, via transaction
online omit no/ext off | unsupported for now
online omit no on | invalid combination (nothing to snapshot)
online omit ext on | memory=no disk=ext, via transaction
online omit int off |+memory=int disk=int, via savevm
online omit int on | unsupported for now
online no omit any |+memory=no disk=default, via transaction
online no no any | invalid combination (nothing to snapshot)
online no int any | unsupported for now
online no ext any |+memory=no disk=ext, via transaction
online int/ext any on | invalid combination (disk-only vs. memory)
online int omit off |+memory=int disk=int, via savevm
online int no/ext off | unsupported for now
online int int off |+memory=int disk=int, via savevm
online ext omit off |*memory=ext disk=default, via migrate+trans
online ext no off |+memory=ext disk=no, via migrate
online ext int off | unsupported for now
online ext ext off |*memory=ext disk=ext, via migrate+transaction
* docs/schemas/domainsnapshot.rng (memory): New RNG element.
* docs/formatsnapshot.html.in: Document it.
* src/conf/snapshot_conf.h (virDomainSnapshotDef): New fields.
* src/conf/domain_conf.c (virDomainSnapshotDefFree)
(virDomainSnapshotDefParseString, virDomainSnapshotDefFormat):
Manage new fields.
* tests/domainsnapshotxml2xmltest.c: New test.
* tests/domainsnapshotxml2xmlin/*.xml: Update existing tests.
* tests/domainsnapshotxml2xmlout/*.xml: Likewise.
2012-10-23 23:12:23 +08:00
|
|
|
memory state, which can be used to resume the guest from where it
|
2011-08-19 08:14:40 +08:00
|
|
|
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
|
snapshot: new XML for external system checkpoint
Each <domainsnapshot> can now contain an optional <memory>
element that describes how the VM state was handled, similar
to disk snapshots. The new element will always appear in
output; for back-compat, an input that lacks the element will
assume 'no' or 'internal' according to the domain state.
Along with this change, it is now possible to pass <disks> in
the XML for an offline snapshot; this also needs to be wired up
in a future patch, to make it possible to choose internal vs.
external on a per-disk basis for each disk in an offline domain.
At that point, using the --disk-only flag for an offline domain
will be able to work.
For some examples below, remember that qemu supports the
following snapshot actions:
qemu-img: offline external and internal disk
savevm: online internal VM and disk
migrate: online external VM
transaction: online external disk
=====
<domainsnapshot>
<memory snapshot='no'/>
...
</domainsnapshot>
implies that there is no VM state saved (mandatory for
offline and disk-only snapshots, not possible otherwise);
using qemu-img for offline domains and transaction for online.
=====
<domainsnapshot>
<memory snapshot='internal'/>
...
</domainsnapshot>
state is saved inside one of the disks (as in qemu's 'savevm'
system checkpoint implementation). If needed in the future,
we can also add an attribute pointing out _which_ disk saved
the internal state; maybe disk='vda'.
=====
<domainsnapshot>
<memory snapshot='external' file='/path/to/state'/>
...
</domainsnapshot>
This is not wired up yet, but future patches will allow this to
control a combination of 'virsh save /path/to/state' plus disk
snapshots from the same point in time.
=====
So for 1.0.1 (and later, as needed), I plan to implement this table
of combinations, with '*' designating new code and '+' designating
existing code reached through new combinations of xml and/or the
existing DISK_ONLY flag:
domain memory disk disk-only | result
-----------------------------------------
offline omit omit any | memory=no disk=int, via qemu-img
offline no omit any |+memory=no disk=int, via qemu-img
offline omit/no no any | invalid combination (nothing to snapshot)
offline omit/no int any |+memory=no disk=int, via qemu-img
offline omit/no ext any |*memory=no disk=ext, via qemu-img
offline int/ext any any | invalid combination (no memory to save)
online omit omit off | memory=int disk=int, via savevm
online omit omit on | memory=no disk=default, via transaction
online omit no/ext off | unsupported for now
online omit no on | invalid combination (nothing to snapshot)
online omit ext on | memory=no disk=ext, via transaction
online omit int off |+memory=int disk=int, via savevm
online omit int on | unsupported for now
online no omit any |+memory=no disk=default, via transaction
online no no any | invalid combination (nothing to snapshot)
online no int any | unsupported for now
online no ext any |+memory=no disk=ext, via transaction
online int/ext any on | invalid combination (disk-only vs. memory)
online int omit off |+memory=int disk=int, via savevm
online int no/ext off | unsupported for now
online int int off |+memory=int disk=int, via savevm
online ext omit off |*memory=ext disk=default, via migrate+trans
online ext no off |+memory=ext disk=no, via migrate
online ext int off | unsupported for now
online ext ext off |*memory=ext disk=ext, via migrate+transaction
* docs/schemas/domainsnapshot.rng (memory): New RNG element.
* docs/formatsnapshot.html.in: Document it.
* src/conf/snapshot_conf.h (virDomainSnapshotDef): New fields.
* src/conf/domain_conf.c (virDomainSnapshotDefFree)
(virDomainSnapshotDefParseString, virDomainSnapshotDefFormat):
Manage new fields.
* tests/domainsnapshotxml2xmltest.c: New test.
* tests/domainsnapshotxml2xmlin/*.xml: Update existing tests.
* tests/domainsnapshotxml2xmlout/*.xml: Likewise.
2012-10-23 23:12:23 +08:00
|
|
|
state (memory) snapshots are created only by
|
2011-08-19 08:14:40 +08:00
|
|
|
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>
|
2018-06-11 21:59:10 +08:00
|
|
|
<p>Full system snapshots are created
|
|
|
|
|
by <code>virDomainSnapshotCreateXML()</code> with no flags, while
|
2011-08-19 08:14:40 +08:00
|
|
|
disk snapshots are created by the same function with
|
2018-06-11 21:59:10 +08:00
|
|
|
the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code>
|
|
|
|
|
flag. Regardless of the flags provided, restoration of the
|
|
|
|
|
snapshot is handled by
|
2011-08-19 08:14:40 +08:00
|
|
|
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>
|
|
|
|
|
|
2010-04-06 01:27:41 +08:00
|
|
|
<p>
|
|
|
|
|
Attributes of libvirt snapshots are stored as child elements of
|
|
|
|
|
the <code>domainsnapshot</code> element. At snapshot creation
|
2011-08-19 07:33:36 +08:00
|
|
|
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
|
snapshot: allow recreation of metadata
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.
2011-08-31 09:02:46 +08:00
|
|
|
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
|
snapshot: More clarification about REDEFINE
Based on recent list questions about the proposed addition of
virDomainCheckpointCreateXML(REDEFINE), it is worth adding some
clarification to the existing snapshot redefine documentation that is
serving as the basis for checkpoints.
Normal snapshot creation requires very few elements from the user XML
(libvirt can pick sane defaults for items that are omitted, and many
fields, including <domain>, are documented as readonly output fields
ignored on input, produced by drivers that track it). But during
REDEFINE, the API wants the complete XML produced by an earlier
virDomainSnapshotGetXMLDesc; as the domain definition has likely
changed since the snapshot was first created, libvirt is unable to
recreate a <domain> sub-element that matches the original output
representing the domain state at the time the snapshot was first
created. In fact, reverting without a <domain> sub-element is risky
enough that we had to add a FORCE flag for virDomainSnapshotRevert().
In short, we only support omitting domain for qemu because of
backwards-compatibility to snapshots created before 0.9.5 started
capturing <domain>; even though there are other drivers like vbox that
do not output <domain> because they have other reliable ways to
revert.
And based on the confusion caused when omitting <domain> from snapshot
XML, the initial design for checkpoints in later patches will make
<domain> a mandatory element during its REDEFINE.
[Side note: the fact that <domain> can appear in <domainsnapshot> is a
reason we cannot add a new API for a bulk listing or redefine of all
snapshots of a single domain in one XML call (for example, a 1M
<domain> XML * 16 snapshots explodes into 16M in a bulk form, which
gets difficult to send over RPC). Perhaps we could add a flag to
request that the <domain> sub-element be omitted on output, but such
output is no longer suitable for sane REDEFINE input.]
Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-03-14 10:38:52 +08:00
|
|
|
described here is relevant on input, even the fields that are
|
|
|
|
|
normally described as readonly for output.
|
snapshot: allow recreation of metadata
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.
2011-08-31 09:02:46 +08:00
|
|
|
</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
|
2019-07-24 13:17:23 +08:00
|
|
|
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.
|
2010-04-06 01:27:41 +08:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The top-level <code>domainsnapshot</code> element may contain
|
|
|
|
|
the following elements:
|
|
|
|
|
</p>
|
|
|
|
|
<dl>
|
|
|
|
|
<dt><code>name</code></dt>
|
2019-03-26 13:20:04 +08:00
|
|
|
<dd>The optional name for this snapshot. If the name is
|
|
|
|
|
omitted, libvirt will create a name based on the time of the
|
|
|
|
|
creation.
|
2010-04-06 01:27:41 +08:00
|
|
|
</dd>
|
|
|
|
|
<dt><code>description</code></dt>
|
2019-03-26 13:20:04 +08:00
|
|
|
<dd>An optional human-readable description of the snapshot. If
|
|
|
|
|
the description is omitted when initially creating the
|
|
|
|
|
snapshot, then this field will be empty.
|
2010-04-06 01:27:41 +08:00
|
|
|
</dd>
|
snapshot: new XML for external system checkpoint
Each <domainsnapshot> can now contain an optional <memory>
element that describes how the VM state was handled, similar
to disk snapshots. The new element will always appear in
output; for back-compat, an input that lacks the element will
assume 'no' or 'internal' according to the domain state.
Along with this change, it is now possible to pass <disks> in
the XML for an offline snapshot; this also needs to be wired up
in a future patch, to make it possible to choose internal vs.
external on a per-disk basis for each disk in an offline domain.
At that point, using the --disk-only flag for an offline domain
will be able to work.
For some examples below, remember that qemu supports the
following snapshot actions:
qemu-img: offline external and internal disk
savevm: online internal VM and disk
migrate: online external VM
transaction: online external disk
=====
<domainsnapshot>
<memory snapshot='no'/>
...
</domainsnapshot>
implies that there is no VM state saved (mandatory for
offline and disk-only snapshots, not possible otherwise);
using qemu-img for offline domains and transaction for online.
=====
<domainsnapshot>
<memory snapshot='internal'/>
...
</domainsnapshot>
state is saved inside one of the disks (as in qemu's 'savevm'
system checkpoint implementation). If needed in the future,
we can also add an attribute pointing out _which_ disk saved
the internal state; maybe disk='vda'.
=====
<domainsnapshot>
<memory snapshot='external' file='/path/to/state'/>
...
</domainsnapshot>
This is not wired up yet, but future patches will allow this to
control a combination of 'virsh save /path/to/state' plus disk
snapshots from the same point in time.
=====
So for 1.0.1 (and later, as needed), I plan to implement this table
of combinations, with '*' designating new code and '+' designating
existing code reached through new combinations of xml and/or the
existing DISK_ONLY flag:
domain memory disk disk-only | result
-----------------------------------------
offline omit omit any | memory=no disk=int, via qemu-img
offline no omit any |+memory=no disk=int, via qemu-img
offline omit/no no any | invalid combination (nothing to snapshot)
offline omit/no int any |+memory=no disk=int, via qemu-img
offline omit/no ext any |*memory=no disk=ext, via qemu-img
offline int/ext any any | invalid combination (no memory to save)
online omit omit off | memory=int disk=int, via savevm
online omit omit on | memory=no disk=default, via transaction
online omit no/ext off | unsupported for now
online omit no on | invalid combination (nothing to snapshot)
online omit ext on | memory=no disk=ext, via transaction
online omit int off |+memory=int disk=int, via savevm
online omit int on | unsupported for now
online no omit any |+memory=no disk=default, via transaction
online no no any | invalid combination (nothing to snapshot)
online no int any | unsupported for now
online no ext any |+memory=no disk=ext, via transaction
online int/ext any on | invalid combination (disk-only vs. memory)
online int omit off |+memory=int disk=int, via savevm
online int no/ext off | unsupported for now
online int int off |+memory=int disk=int, via savevm
online ext omit off |*memory=ext disk=default, via migrate+trans
online ext no off |+memory=ext disk=no, via migrate
online ext int off | unsupported for now
online ext ext off |*memory=ext disk=ext, via migrate+transaction
* docs/schemas/domainsnapshot.rng (memory): New RNG element.
* docs/formatsnapshot.html.in: Document it.
* src/conf/snapshot_conf.h (virDomainSnapshotDef): New fields.
* src/conf/domain_conf.c (virDomainSnapshotDefFree)
(virDomainSnapshotDefParseString, virDomainSnapshotDefFormat):
Manage new fields.
* tests/domainsnapshotxml2xmltest.c: New test.
* tests/domainsnapshotxml2xmlin/*.xml: Update existing tests.
* tests/domainsnapshotxml2xmlout/*.xml: Likewise.
2012-10-23 23:12:23 +08:00
|
|
|
<dt><code>memory</code></dt>
|
|
|
|
|
<dd>On input, this is an optional request for how to handle VM
|
|
|
|
|
memory state. For an offline domain or a disk-only snapshot,
|
|
|
|
|
attribute <code>snapshot</code> must be <code>no</code>, since
|
|
|
|
|
there is no VM state saved; otherwise, the attribute can
|
|
|
|
|
be <code>internal</code> if the memory state is piggy-backed with
|
|
|
|
|
other internal disk state, or <code>external</code> along with
|
|
|
|
|
a second attribute <code>file</code> giving the absolute path
|
|
|
|
|
of the file holding the VM memory state. <span class="since">Since
|
|
|
|
|
1.0.1</span>
|
|
|
|
|
</dd>
|
2011-08-19 07:33:36 +08:00
|
|
|
<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
|
2018-06-11 21:59:10 +08:00
|
|
|
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 <code>disk</code>
|
2011-08-19 07:33:36 +08:00
|
|
|
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
|
snapshot: also support disks by path
I got confused when 'virsh domblkinfo dom disk' required the
path to a disk (which can be ambiguous, since a single file
can back multiple disks), rather than the unambiguous target
device name that I was using in disk snapshots. So, in true
developer fashion, I went for the best of both worlds - all
interfaces that operate on a disk (aka block) now accept
either the target name or the unambiguous path to the backing
file used by the disk.
* src/conf/domain_conf.h (virDomainDiskIndexByName): Add
parameter.
(virDomainDiskPathByName): New prototype.
* src/libvirt_private.syms (domain_conf.h): Export it.
* src/conf/domain_conf.c (virDomainDiskIndexByName): Also allow
searching by path, and decide whether ambiguity is okay.
(virDomainDiskPathByName): New function.
(virDomainDiskRemoveByName, virDomainSnapshotAlignDisks): Update
callers.
* src/qemu/qemu_driver.c (qemudDomainBlockPeek)
(qemuDomainAttachDeviceConfig, qemuDomainUpdateDeviceConfig)
(qemuDomainGetBlockInfo, qemuDiskPathToAlias): Likewise.
* src/qemu/qemu_process.c (qemuProcessFindDomainDiskByPath):
Likewise.
* src/libxl/libxl_driver.c (libxlDomainAttachDeviceDiskLive)
(libxlDomainDetachDeviceDiskLive, libxlDomainAttachDeviceConfig)
(libxlDomainUpdateDeviceConfig): Likewise.
* src/uml/uml_driver.c (umlDomainBlockPeek): Likewise.
* src/xen/xend_internal.c (xenDaemonDomainBlockPeek): Likewise.
* docs/formatsnapshot.html.in: Update documentation.
* tools/virsh.pod (domblkstat, domblkinfo): Likewise.
* docs/schemas/domaincommon.rng (diskTarget): Tighten pattern on
disk targets.
* docs/schemas/domainsnapshot.rng (disksnapshot): Update to match.
* tests/domainsnapshotxml2xmlin/disk_snapshot.xml: Update test.
2011-08-20 10:38:36 +08:00
|
|
|
mandatory, and must match either the <code><target
|
2019-06-20 15:57:54 +08:00
|
|
|
dev='name'/></code> (recommended) or an unambiguous
|
|
|
|
|
<code><source file='name'/></code> of one of
|
2011-08-19 07:33:36 +08:00
|
|
|
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
|
2013-04-26 03:40:33 +08:00
|
|
|
optional, and the possible values are the same as the
|
2013-05-02 01:59:56 +08:00
|
|
|
<code>snapshot</code> attribute for
|
2013-04-26 03:40:33 +08:00
|
|
|
<a href="formatdomain.html#elementsDisks">disk devices</a>
|
2011-08-19 07:33:36 +08:00
|
|
|
(<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
|
2015-04-10 20:25:37 +08:00
|
|
|
override the domain default.
|
|
|
|
|
|
|
|
|
|
<dl>
|
|
|
|
|
<dt><code>source</code></dt>
|
|
|
|
|
<dd>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 of the new file.
|
|
|
|
|
If <code>source</code> 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.
|
2018-06-05 21:54:00 +08:00
|
|
|
<p/>
|
|
|
|
|
The <code>source</code> element also may contain the
|
|
|
|
|
<code>seclabel</code> element (described in the
|
|
|
|
|
<a href="formatdomain.html#seclabel">domain XML documentation</a>)
|
|
|
|
|
which can be used to override the domain security labeling policy
|
|
|
|
|
for <code>source</code>.
|
2015-04-10 20:25:37 +08:00
|
|
|
</dd>
|
|
|
|
|
<dt><code>driver</code></dt>
|
|
|
|
|
<dd>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.
|
|
|
|
|
</dd>
|
2018-06-05 21:54:00 +08:00
|
|
|
<dt><code>seclabel</code></dt>
|
2015-04-10 20:25:37 +08:00
|
|
|
</dl>
|
2013-11-12 21:15:51 +08:00
|
|
|
|
|
|
|
|
<span class="since">Since 1.2.2</span> the <code>disk</code> element
|
|
|
|
|
supports an optional attribute <code>type</code> if the
|
|
|
|
|
<code>snapshot</code> attribute is set to <code>external</code>.
|
|
|
|
|
This attribute specifies the snapshot target storage type and allows
|
|
|
|
|
to overwrite the default <code>file</code> type. The <code>type</code>
|
|
|
|
|
attribute along with the format of the <code>source</code>
|
|
|
|
|
sub-element is identical to the <code>source</code> element used in
|
|
|
|
|
domain disk definitions. See the
|
|
|
|
|
<a href="formatdomain.html#elementsDisks">disk devices</a> section
|
|
|
|
|
documentation for further information.
|
|
|
|
|
|
|
|
|
|
Libvirt currently supports the <code>type</code> element in the qemu
|
2013-11-26 01:56:24 +08:00
|
|
|
driver and supported values are <code>file</code>, <code>block</code>
|
|
|
|
|
and <code>network</code> with a protocol of <code>gluster</code>
|
|
|
|
|
<span class="since">(since 1.2.2)</span>.
|
2011-08-19 07:33:36 +08:00
|
|
|
</dd>
|
|
|
|
|
</dl>
|
|
|
|
|
</dd>
|
2010-04-06 01:27:41 +08:00
|
|
|
<dt><code>creationTime</code></dt>
|
2019-03-26 13:20:04 +08:00
|
|
|
<dd>A readonly representation of the time this snapshot was
|
|
|
|
|
created. The time is specified in seconds since the Epoch,
|
|
|
|
|
UTC (i.e. Unix time).
|
2010-04-06 01:27:41 +08:00
|
|
|
</dd>
|
|
|
|
|
<dt><code>state</code></dt>
|
2019-03-26 13:20:04 +08:00
|
|
|
<dd>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
|
2018-06-11 21:59:10 +08:00
|
|
|
by <code>virDomainRevertToSnapshot()</code> flags to revert to
|
2019-03-26 13:20:04 +08:00
|
|
|
a running or paused state. 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 memory state),
|
|
|
|
|
and reverting to this snapshot will default to an inactive
|
|
|
|
|
guest.
|
2010-04-06 01:27:41 +08:00
|
|
|
</dd>
|
|
|
|
|
<dt><code>parent</code></dt>
|
2019-07-13 04:43:01 +08:00
|
|
|
<dd>Readonly, present only if this snapshot has a parent. The
|
|
|
|
|
parent name is given by the sub-element <code>name</code>. The
|
|
|
|
|
parent relationship allows tracking a tree of related snapshots.
|
2010-04-06 01:27:41 +08:00
|
|
|
</dd>
|
|
|
|
|
<dt><code>domain</code></dt>
|
2019-03-26 13:20:04 +08:00
|
|
|
<dd>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 <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
|
snapshot: allow full domain xml in snapshot
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.
2011-08-13 09:19:47 +08:00
|
|
|
in <code>virDomainRevertToSnapshot()</code>. Newer versions
|
2019-03-26 13:20:04 +08:00
|
|
|
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>). The domain will have
|
|
|
|
|
security-sensitive information omitted
|
|
|
|
|
unless the flag <code>VIR_DOMAIN_SNAPSHOT_XML_SECURE</code> is
|
|
|
|
|
provided on a read-write connection.
|
2010-04-06 01:27:41 +08:00
|
|
|
</dd>
|
2017-05-25 16:20:57 +08:00
|
|
|
<dt><code>cookie</code></dt>
|
2019-03-26 13:20:04 +08:00
|
|
|
<dd>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 <code>domain</code> to maintain
|
|
|
|
|
compatibility with older libvirt or hypervisor.
|
2017-05-25 16:20:57 +08:00
|
|
|
</dd>
|
2010-04-06 01:27:41 +08:00
|
|
|
</dl>
|
|
|
|
|
|
2017-07-26 22:52:42 +08:00
|
|
|
<h2><a id="example">Examples</a></h2>
|
2010-04-06 01:27:41 +08:00
|
|
|
|
2011-08-19 07:33:36 +08:00
|
|
|
<p>Using this XML to create a disk snapshot of just vda on a qemu
|
|
|
|
|
domain with two disks:</p>
|
2010-04-06 01:27:41 +08:00
|
|
|
<pre>
|
snapshot: allow recreation of metadata
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.
2011-08-31 09:02:46 +08:00
|
|
|
<domainsnapshot>
|
snapshot: allow full domain xml in snapshot
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.
2011-08-13 09:19:47 +08:00
|
|
|
<description>Snapshot of OS install and updates</description>
|
2011-08-19 07:33:36 +08:00
|
|
|
<disks>
|
2019-06-20 15:57:54 +08:00
|
|
|
<disk name='vda'>
|
2011-08-19 07:33:36 +08:00
|
|
|
<source file='/path/to/new'/>
|
|
|
|
|
</disk>
|
|
|
|
|
<disk name='vdb' snapshot='no'/>
|
2018-06-05 21:54:00 +08:00
|
|
|
<disk name='vdc'>
|
|
|
|
|
<source file='/path/to/newc'>
|
|
|
|
|
<seclabel model='dac' relabel='no'/>
|
|
|
|
|
</source>
|
|
|
|
|
</disk>
|
2011-08-19 07:33:36 +08:00
|
|
|
</disks>
|
snapshot: allow full domain xml in snapshot
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.
2011-08-13 09:19:47 +08:00
|
|
|
</domainsnapshot></pre>
|
|
|
|
|
|
|
|
|
|
<p>will result in XML similar to this from
|
2011-08-19 07:33:36 +08:00
|
|
|
<code>virDomainSnapshotGetXMLDesc()</code>:</p>
|
snapshot: allow full domain xml in snapshot
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.
2011-08-13 09:19:47 +08:00
|
|
|
<pre>
|
|
|
|
|
<domainsnapshot>
|
|
|
|
|
<name>1270477159</name>
|
snapshot: allow recreation of metadata
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.
2011-08-31 09:02:46 +08:00
|
|
|
<description>Snapshot of OS install and updates</description>
|
|
|
|
|
<state>running</state>
|
|
|
|
|
<creationTime>1270477159</creationTime>
|
|
|
|
|
<parent>
|
|
|
|
|
<name>bare-os-install</name>
|
|
|
|
|
</parent>
|
snapshot: new XML for external system checkpoint
Each <domainsnapshot> can now contain an optional <memory>
element that describes how the VM state was handled, similar
to disk snapshots. The new element will always appear in
output; for back-compat, an input that lacks the element will
assume 'no' or 'internal' according to the domain state.
Along with this change, it is now possible to pass <disks> in
the XML for an offline snapshot; this also needs to be wired up
in a future patch, to make it possible to choose internal vs.
external on a per-disk basis for each disk in an offline domain.
At that point, using the --disk-only flag for an offline domain
will be able to work.
For some examples below, remember that qemu supports the
following snapshot actions:
qemu-img: offline external and internal disk
savevm: online internal VM and disk
migrate: online external VM
transaction: online external disk
=====
<domainsnapshot>
<memory snapshot='no'/>
...
</domainsnapshot>
implies that there is no VM state saved (mandatory for
offline and disk-only snapshots, not possible otherwise);
using qemu-img for offline domains and transaction for online.
=====
<domainsnapshot>
<memory snapshot='internal'/>
...
</domainsnapshot>
state is saved inside one of the disks (as in qemu's 'savevm'
system checkpoint implementation). If needed in the future,
we can also add an attribute pointing out _which_ disk saved
the internal state; maybe disk='vda'.
=====
<domainsnapshot>
<memory snapshot='external' file='/path/to/state'/>
...
</domainsnapshot>
This is not wired up yet, but future patches will allow this to
control a combination of 'virsh save /path/to/state' plus disk
snapshots from the same point in time.
=====
So for 1.0.1 (and later, as needed), I plan to implement this table
of combinations, with '*' designating new code and '+' designating
existing code reached through new combinations of xml and/or the
existing DISK_ONLY flag:
domain memory disk disk-only | result
-----------------------------------------
offline omit omit any | memory=no disk=int, via qemu-img
offline no omit any |+memory=no disk=int, via qemu-img
offline omit/no no any | invalid combination (nothing to snapshot)
offline omit/no int any |+memory=no disk=int, via qemu-img
offline omit/no ext any |*memory=no disk=ext, via qemu-img
offline int/ext any any | invalid combination (no memory to save)
online omit omit off | memory=int disk=int, via savevm
online omit omit on | memory=no disk=default, via transaction
online omit no/ext off | unsupported for now
online omit no on | invalid combination (nothing to snapshot)
online omit ext on | memory=no disk=ext, via transaction
online omit int off |+memory=int disk=int, via savevm
online omit int on | unsupported for now
online no omit any |+memory=no disk=default, via transaction
online no no any | invalid combination (nothing to snapshot)
online no int any | unsupported for now
online no ext any |+memory=no disk=ext, via transaction
online int/ext any on | invalid combination (disk-only vs. memory)
online int omit off |+memory=int disk=int, via savevm
online int no/ext off | unsupported for now
online int int off |+memory=int disk=int, via savevm
online ext omit off |*memory=ext disk=default, via migrate+trans
online ext no off |+memory=ext disk=no, via migrate
online ext int off | unsupported for now
online ext ext off |*memory=ext disk=ext, via migrate+transaction
* docs/schemas/domainsnapshot.rng (memory): New RNG element.
* docs/formatsnapshot.html.in: Document it.
* src/conf/snapshot_conf.h (virDomainSnapshotDef): New fields.
* src/conf/domain_conf.c (virDomainSnapshotDefFree)
(virDomainSnapshotDefParseString, virDomainSnapshotDefFormat):
Manage new fields.
* tests/domainsnapshotxml2xmltest.c: New test.
* tests/domainsnapshotxml2xmlin/*.xml: Update existing tests.
* tests/domainsnapshotxml2xmlout/*.xml: Likewise.
2012-10-23 23:12:23 +08:00
|
|
|
<memory snapshot='no'/>
|
2011-08-19 07:33:36 +08:00
|
|
|
<disks>
|
|
|
|
|
<disk name='vda' snapshot='external'>
|
|
|
|
|
<driver type='qcow2'/>
|
|
|
|
|
<b><source file='/path/to/new'/></b>
|
|
|
|
|
</disk>
|
|
|
|
|
<disk name='vdb' snapshot='no'/>
|
|
|
|
|
</disks>
|
snapshot: allow recreation of metadata
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.
2011-08-31 09:02:46 +08:00
|
|
|
<domain>
|
snapshot: allow full domain xml in snapshot
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.
2011-08-13 09:19:47 +08:00
|
|
|
<name>fedora</name>
|
snapshot: allow recreation of metadata
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.
2011-08-31 09:02:46 +08:00
|
|
|
<uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
|
snapshot: allow full domain xml in snapshot
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.
2011-08-13 09:19:47 +08:00
|
|
|
<memory>1048576</memory>
|
|
|
|
|
...
|
2011-08-19 07:33:36 +08:00
|
|
|
<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>
|
|
|
|
|
...
|
snapshot: allow full domain xml in snapshot
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.
2011-08-13 09:19:47 +08:00
|
|
|
</devices>
|
snapshot: allow recreation of metadata
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.
2011-08-31 09:02:46 +08:00
|
|
|
</domain>
|
|
|
|
|
</domainsnapshot></pre>
|
2011-08-19 07:33:36 +08:00
|
|
|
|
|
|
|
|
<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>
|
2010-04-06 01:27:41 +08:00
|
|
|
</body>
|
|
|
|
|
</html>
|