.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sys::Virt::DomainSnapshot 3pm"
.TH Sys::Virt::DomainSnapshot 3pm 2024-01-21 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sys::Virt::DomainSnapshot \- Represent & manage a libvirt guest domain
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Sys::Virt::DomainSnapshot\*(C'\fR module represents a guest domain managed
by the virtual machine monitor.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "my $str = $domss\->\fBget_name()\fR" 4
.el .IP "my \f(CW$str\fR = \f(CW$domss\fR\->\fBget_name()\fR" 4
.IX Item "my $str = $domss->get_name()"
Return the name of the snapshot
.ie n .IP "my $xml = $domss\->get_xml_description($flags)" 4
.el .IP "my \f(CW$xml\fR = \f(CW$domss\fR\->get_xml_description($flags)" 4
.IX Item "my $xml = $domss->get_xml_description($flags)"
Returns an XML document containing a complete description of
the domain snapshot's configuration. The \f(CW$flags\fR parameter
accepts the following constants
.RS 4
.IP Sys::Virt::DomainSnapshot::XML_SECURE 4
.IX Item "Sys::Virt::DomainSnapshot::XML_SECURE"
Include security sensitive information in the XML dump, such as
passwords.
.RE
.RS 4
.RE
.ie n .IP $domss\->delete($flags) 4
.el .IP \f(CW$domss\fR\->delete($flags) 4
.IX Item "$domss->delete($flags)"
Deletes this snapshot object & its data. The optional \f(CW$flags\fR parameter controls
what should be deleted via the \f(CW\*(C`Sys::Virt::DomainSnapshot::DELETE_*\*(C'\fR
constants.
.ie n .IP $domss\->revert_to($flags) 4
.el .IP \f(CW$domss\fR\->revert_to($flags) 4
.IX Item "$domss->revert_to($flags)"
Revert the domain to the state associated with this snapshot. The optional
\&\f(CW$flags\fR control the state of the VM after the revert via the
\&\f(CW\*(C`Sys::Virt::DomainSnapshot::REVERT_*\*(C'\fR constants.
.ie n .IP "$parentss = $domss\->\fBget_parent()\fR;" 4
.el .IP "\f(CW$parentss\fR = \f(CW$domss\fR\->\fBget_parent()\fR;" 4
.IX Item "$parentss = $domss->get_parent();"
Return the parent of the snapshot, if any
.ie n .IP "$res = $domss\->\fBis_current()\fR" 4
.el .IP "\f(CW$res\fR = \f(CW$domss\fR\->\fBis_current()\fR" 4
.IX Item "$res = $domss->is_current()"
Returns a true value if this is the current snapshot. False otherwise.
.ie n .IP "$res = $domss\->\fBhas_metadata()\fR" 4
.el .IP "\f(CW$res\fR = \f(CW$domss\fR\->\fBhas_metadata()\fR" 4
.IX Item "$res = $domss->has_metadata()"
Returns a true value if this snapshot has metadata associated with
it.
.ie n .IP "$count = $domss\->\fBnum_of_child_snapshots()\fR" 4
.el .IP "\f(CW$count\fR = \f(CW$domss\fR\->\fBnum_of_child_snapshots()\fR" 4
.IX Item "$count = $domss->num_of_child_snapshots()"
Return the number of saved snapshots which are children of this snapshot
.ie n .IP "@names = $domss\->\fBlist_child_snapshot_names()\fR" 4
.el .IP "\f(CW@names\fR = \f(CW$domss\fR\->\fBlist_child_snapshot_names()\fR" 4
.IX Item "@names = $domss->list_child_snapshot_names()"
List the names of all saved snapshots which are children of this
snapshot . The names can be used with the \f(CW\*(C`lookup_snapshot_by_name\*(C'\fR
.ie n .IP "@snapshots = $domss\->\fBlist_child_snapshots()\fR" 4
.el .IP "\f(CW@snapshots\fR = \f(CW$domss\fR\->\fBlist_child_snapshots()\fR" 4
.IX Item "@snapshots = $domss->list_child_snapshots()"
Return a list of all snapshots that are children of this snapshot. The elements
in the returned list are instances of the Sys::Virt::DomainSnapshot class.
This method requires O(n) RPC calls, so the \f(CW\*(C`list_all_children\*(C'\fR method is
recommended as a more efficient alternative.
.ie n .IP "my @snapshots = $domss\->list_all_children($flags)" 4
.el .IP "my \f(CW@snapshots\fR = \f(CW$domss\fR\->list_all_children($flags)" 4
.IX Item "my @snapshots = $domss->list_all_children($flags)"
Return a list of all domain snapshots that are children of this
snapshot. The elements in the returned list are instances of the
Sys::Virt::DomainSnapshot class. The \f(CW$flags\fR parameter can be
used to filter the list of return domain snapshots.
.SH CONSTANTS
.IX Header "CONSTANTS"
.SS "SNAPSHOT CREATION"
.IX Subsection "SNAPSHOT CREATION"
The following constants are useful when creating snapshots
.IP Sys::Virt::DomainSnapshot::CREATE_CURRENT 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_CURRENT"
Set the defined snapshot to be the current snapshot
.IP Sys::Virt::DomainSnapshot::CREATE_DISK_ONLY 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_DISK_ONLY"
Only snapshot the disk, not the memory state
.IP Sys::Virt::DomainSnapshot::CREATE_HALT 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_HALT"
Stop the guest after creating the snapshot
.IP Sys::Virt::DomainSnapshot::CREATE_NO_METADATA 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_NO_METADATA"
Do not save any metadata for the snapshot
.IP Sys::Virt::DomainSnapshot::CREATE_REDEFINE 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_REDEFINE"
Replace/set the metadata with the snapshot
.IP Sys::Virt::DomainSnapshot::CREATE_QUIESCE 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_QUIESCE"
Quiesce the guest disks while taking the snapshot
.IP Sys::Virt::DomainSnapshot::CREATE_REUSE_EXT 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_REUSE_EXT"
Reuse the existing snapshot data files (if any)
.IP Sys::Virt::DomainSnapshot::CREATE_ATOMIC 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_ATOMIC"
Create multiple disk snapshots atomically
.IP Sys::Virt::DomainSnapshot::CREATE_LIVE 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_LIVE"
Create snapshot while the guest is running
.IP Sys::Virt::DomainSnapshot::CREATE_VALIDATE 4
.IX Item "Sys::Virt::DomainSnapshot::CREATE_VALIDATE"
Validate the XML document against the schema
.SS "SNAPSHOT DELETION"
.IX Subsection "SNAPSHOT DELETION"
The following constants are useful when deleting snapshots
.IP Sys::Virt::DomainSnapshot::DELETE_CHILDREN 4
.IX Item "Sys::Virt::DomainSnapshot::DELETE_CHILDREN"
Recursively delete any child snapshots
.IP Sys::Virt::DomainSnapshot::DELETE_CHILDREN_ONLY 4
.IX Item "Sys::Virt::DomainSnapshot::DELETE_CHILDREN_ONLY"
Only delete the child snapshots
.IP Sys::Virt::DomainSnapshot::DELETE_METADATA_ONLY 4
.IX Item "Sys::Virt::DomainSnapshot::DELETE_METADATA_ONLY"
Only delete the snapshot metadata
.SS "SNAPSHOT LIST"
.IX Subsection "SNAPSHOT LIST"
The following constants are useful when listing snapshots
.IP Sys::Virt::DomainSnapshot::LIST_METADATA 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_METADATA"
Only list snapshots which have metadata
.IP Sys::Virt::DomainSnapshot::LIST_ROOTS 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_ROOTS"
Only list snapshots which are root nodes in the tree
.IP Sys::Virt::DomainSnapshot::LIST_DESCENDANTS 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_DESCENDANTS"
Only list snapshots which are descendants of the current
snapshot
.IP Sys::Virt::DomainSnapshot::LIST_LEAVES 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_LEAVES"
Only list leaf nodes in the snapshot tree
.IP Sys::Virt::DomainSnapshot::LIST_NO_LEAVES 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_NO_LEAVES"
Only list non-leaf nodes in the snapshot tree
.IP Sys::Virt::DomainSnapshot::LIST_NO_METADATA 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_NO_METADATA"
Only list snapshots without metadata
.IP Sys::Virt::DomainSnapshot::LIST_ACTIVE 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_ACTIVE"
Only list snapshots taken while the guest was running
.IP Sys::Virt::DomainSnapshot::LIST_INACTIVE 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_INACTIVE"
Only list snapshots taken while the guest was inactive
.IP Sys::Virt::DomainSnapshot::LIST_EXTERNAL 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_EXTERNAL"
Only list snapshots stored in external disk images
.IP Sys::Virt::DomainSnapshot::LIST_INTERNAL 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_INTERNAL"
Only list snapshots stored in internal disk images
.IP Sys::Virt::DomainSnapshot::LIST_DISK_ONLY 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_DISK_ONLY"
Only list snapshots taken while the guest was running,
which did not include memory state.
.IP Sys::Virt::DomainSnapshot::LIST_TOPOLOGICAL 4
.IX Item "Sys::Virt::DomainSnapshot::LIST_TOPOLOGICAL"
Sort list in topological order wrt to parent/child
relationships.
.SS "SNAPSHOT REVERT"
.IX Subsection "SNAPSHOT REVERT"
The following constants are useful when reverting snapshots
.IP Sys::Virt::DomainSnapshot::REVERT_PAUSED 4
.IX Item "Sys::Virt::DomainSnapshot::REVERT_PAUSED"
Leave the guest CPUs paused after reverting to the snapshot state
.IP Sys::Virt::DomainSnapshot::REVERT_RUNNING 4
.IX Item "Sys::Virt::DomainSnapshot::REVERT_RUNNING"
Start the guest CPUs after reverting to the snapshot state
.IP Sys::Virt::DomainSnapshot::REVERT_FORCE 4
.IX Item "Sys::Virt::DomainSnapshot::REVERT_FORCE"
Force the snapshot to revert, even if it is risky to do so
.IP Sys::Virt::DomainSnapshot::REVERT_RESET_NVRAM 4
.IX Item "Sys::Virt::DomainSnapshot::REVERT_RESET_NVRAM"
Reset the firmware NVRAM state from its original template
.SH AUTHORS
.IX Header "AUTHORS"
Daniel P. Berrange <berrange@redhat.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2006 Red Hat
Copyright (C) 2006\-2007 Daniel P. Berrange
.SH LICENSE
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify
it under the terms of either the GNU General Public License as published
by the Free Software Foundation (either version 2 of the License, or at
your option any later version), or, the Artistic License, as specified
in the Perl README file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sys::Virt, Sys::Virt::Error, \f(CW\*(C`http://libvirt.org\*(C'\fR