libvirt/src/conf/snapshot_conf.h

176 lines
7.3 KiB
C
Raw Normal View History

/*
* snapshot_conf.h: domain snapshot XML processing
*
* Copyright (C) 2006-2012 Red Hat, Inc.
* Copyright (C) 2006-2008 Daniel P. Berrange
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see
* <http://www.gnu.org/licenses/>.
*
* Author: Eric Blake <eblake@redhat.com>
*/
#ifndef __SNAPSHOT_CONF_H
# define __SNAPSHOT_CONF_H
# include "internal.h"
# include "domain_conf.h"
/* Items related to snapshot state */
enum virDomainSnapshotLocation {
VIR_DOMAIN_SNAPSHOT_LOCATION_DEFAULT = 0,
VIR_DOMAIN_SNAPSHOT_LOCATION_NONE,
VIR_DOMAIN_SNAPSHOT_LOCATION_INTERNAL,
VIR_DOMAIN_SNAPSHOT_LOCATION_EXTERNAL,
VIR_DOMAIN_SNAPSHOT_LOCATION_LAST
};
enum virDomainSnapshotState {
/* Inherit the VIR_DOMAIN_* states from virDomainState. */
VIR_DOMAIN_DISK_SNAPSHOT = VIR_DOMAIN_LAST,
VIR_DOMAIN_SNAPSHOT_STATE_LAST
};
/* Stores disk-snapshot information */
typedef struct _virDomainSnapshotDiskDef virDomainSnapshotDiskDef;
typedef virDomainSnapshotDiskDef *virDomainSnapshotDiskDefPtr;
struct _virDomainSnapshotDiskDef {
char *name; /* name matching the <target dev='...' of the domain */
int index; /* index within snapshot->dom->disks that matches name */
int snapshot; /* enum virDomainSnapshotLocation */
char *file; /* new source file when snapshot is external */
int format; /* enum virStorageFileFormat */
};
/* Stores the complete snapshot metadata */
typedef struct _virDomainSnapshotDef virDomainSnapshotDef;
typedef virDomainSnapshotDef *virDomainSnapshotDefPtr;
struct _virDomainSnapshotDef {
/* Public XML. */
char *name;
char *description;
char *parent;
long long creationTime; /* in seconds */
int state; /* enum virDomainSnapshotState */
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 15:12:23 +00:00
int memory; /* enum virDomainMemorySnapshot */
char *file; /* memory state file when snapshot is external */
size_t ndisks; /* should not exceed dom->ndisks */
virDomainSnapshotDiskDef *disks;
virDomainDefPtr dom;
/* Internal use. */
bool current; /* At most one snapshot in the list should have this set */
};
struct _virDomainSnapshotObj {
virDomainSnapshotDefPtr def; /* non-NULL except for metaroot */
virDomainSnapshotObjPtr parent; /* non-NULL except for metaroot, before
virDomainSnapshotUpdateRelations, or
after virDomainSnapshotDropParent */
virDomainSnapshotObjPtr sibling; /* NULL if last child of parent */
size_t nchildren;
virDomainSnapshotObjPtr first_child; /* NULL if no children */
};
virDomainSnapshotObjListPtr virDomainSnapshotObjListNew(void);
void virDomainSnapshotObjListFree(virDomainSnapshotObjListPtr snapshots);
typedef enum {
VIR_DOMAIN_SNAPSHOT_PARSE_REDEFINE = 1 << 0,
VIR_DOMAIN_SNAPSHOT_PARSE_DISKS = 1 << 1,
VIR_DOMAIN_SNAPSHOT_PARSE_INTERNAL = 1 << 2,
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 15:12:23 +00:00
VIR_DOMAIN_SNAPSHOT_PARSE_OFFLINE = 1 << 3,
} virDomainSnapshotParseFlags;
virDomainSnapshotDefPtr virDomainSnapshotDefParseString(const char *xmlStr,
virCapsPtr caps,
unsigned int expectedVirtTypes,
unsigned int flags);
void virDomainSnapshotDefFree(virDomainSnapshotDefPtr def);
char *virDomainSnapshotDefFormat(const char *domain_uuid,
virDomainSnapshotDefPtr def,
unsigned int flags,
int internal);
int virDomainSnapshotAlignDisks(virDomainSnapshotDefPtr snapshot,
int default_snapshot,
bool require_match);
virDomainSnapshotObjPtr virDomainSnapshotAssignDef(virDomainSnapshotObjListPtr snapshots,
const virDomainSnapshotDefPtr def);
int virDomainSnapshotObjListGetNames(virDomainSnapshotObjListPtr snapshots,
virDomainSnapshotObjPtr from,
char **const names, int maxnames,
unsigned int flags);
int virDomainSnapshotObjListNum(virDomainSnapshotObjListPtr snapshots,
virDomainSnapshotObjPtr from,
unsigned int flags);
virDomainSnapshotObjPtr virDomainSnapshotFindByName(const virDomainSnapshotObjListPtr snapshots,
const char *name);
void virDomainSnapshotObjListRemove(virDomainSnapshotObjListPtr snapshots,
virDomainSnapshotObjPtr snapshot);
int virDomainSnapshotForEach(virDomainSnapshotObjListPtr snapshots,
virHashIterator iter,
void *data);
int virDomainSnapshotForEachChild(virDomainSnapshotObjPtr snapshot,
virHashIterator iter,
void *data);
int virDomainSnapshotForEachDescendant(virDomainSnapshotObjPtr snapshot,
virHashIterator iter,
void *data);
int virDomainSnapshotUpdateRelations(virDomainSnapshotObjListPtr snapshots);
void virDomainSnapshotDropParent(virDomainSnapshotObjPtr snapshot);
# define VIR_DOMAIN_SNAPSHOT_FILTERS_METADATA \
(VIR_DOMAIN_SNAPSHOT_LIST_METADATA | \
VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA)
# define VIR_DOMAIN_SNAPSHOT_FILTERS_LEAVES \
(VIR_DOMAIN_SNAPSHOT_LIST_LEAVES | \
VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES)
# define VIR_DOMAIN_SNAPSHOT_FILTERS_STATUS \
(VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE | \
VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE | \
VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY)
# define VIR_DOMAIN_SNAPSHOT_FILTERS_LOCATION \
(VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL | \
VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL)
# define VIR_DOMAIN_SNAPSHOT_FILTERS_ALL \
(VIR_DOMAIN_SNAPSHOT_FILTERS_METADATA | \
VIR_DOMAIN_SNAPSHOT_FILTERS_LEAVES | \
VIR_DOMAIN_SNAPSHOT_FILTERS_STATUS | \
VIR_DOMAIN_SNAPSHOT_FILTERS_LOCATION)
int virDomainListSnapshots(virDomainSnapshotObjListPtr snapshots,
virDomainSnapshotObjPtr from,
virDomainPtr dom,
virDomainSnapshotPtr **snaps,
unsigned int flags);
bool virDomainSnapshotDefIsExternal(virDomainSnapshotDefPtr def);
bool virDomainSnapshotIsExternal(virDomainSnapshotObjPtr snap);
VIR_ENUM_DECL(virDomainSnapshotLocation)
VIR_ENUM_DECL(virDomainSnapshotState)
#endif /* __SNAPSHOT_CONF_H */