.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sys::Virt::Domain 3pm"
.TH Sys::Virt::Domain 3pm "2012-05-21" "perl v5.14.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::Domain \- Represent & manage a libvirt guest domain
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Sys::Virt::Domain\*(C'\fR module represents a guest domain managed
by the virtual machine monitor.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $id = $dom\->\fIget_id()\fR" 4
.el .IP "my \f(CW$id\fR = \f(CW$dom\fR\->\fIget_id()\fR" 4
.IX Item "my $id = $dom->get_id()"
Returns an integer with a locally unique identifier for the
domain.
.ie n .IP "my $uuid = $dom\->\fIget_uuid()\fR" 4
.el .IP "my \f(CW$uuid\fR = \f(CW$dom\fR\->\fIget_uuid()\fR" 4
.IX Item "my $uuid = $dom->get_uuid()"
Returns a 16 byte long string containing the raw globally unique identifier
(\s-1UUID\s0) for the domain.
.ie n .IP "my $uuid = $dom\->\fIget_uuid_string()\fR" 4
.el .IP "my \f(CW$uuid\fR = \f(CW$dom\fR\->\fIget_uuid_string()\fR" 4
.IX Item "my $uuid = $dom->get_uuid_string()"
Returns a printable string representation of the raw \s-1UUID\s0, in the format
\&'\s-1XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX\s0'.
.ie n .IP "my $name = $dom\->\fIget_name()\fR" 4
.el .IP "my \f(CW$name\fR = \f(CW$dom\fR\->\fIget_name()\fR" 4
.IX Item "my $name = $dom->get_name()"
Returns a string with a locally unique name of the domain
.ie n .IP "my $str = $dom\->get_metadata($type, $uri, $flags =0)" 4
.el .IP "my \f(CW$str\fR = \f(CW$dom\fR\->get_metadata($type, \f(CW$uri\fR, \f(CW$flags\fR =0)" 4
.IX Item "my $str = $dom->get_metadata($type, $uri, $flags =0)"
Returns the metadata element of type \f(CW$type\fR associated
with the domain. If \f(CW$type\fR is \f(CW\*(C`Sys::Virt::Domain::METADATA_ELEMENT\*(C'\fR
then the \f(CW$uri\fR parameter specifies the \s-1XML\s0 namespace to
retrieve, otherwise \f(CW$uri\fR should be \f(CW\*(C`undef\*(C'\fR. The optional
\&\f(CW$flags\fR parameter defaults to zero.
.ie n .IP "$dom\->set_metadata($type, $val, $key, $uri, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->set_metadata($type, \f(CW$val\fR, \f(CW$key\fR, \f(CW$uri\fR, \f(CW$flags\fR=0)" 4
.IX Item "$dom->set_metadata($type, $val, $key, $uri, $flags=0)"
Sets the metadata element of type \f(CW$type\fR to hold the value
\&\f(CW$val\fR. If \f(CW$type\fR is  \f(CW\*(C`Sys::Virt::Domain::METADATA_ELEMENT\*(C'\fR
then the \f(CW$key\fR and \f(CW$uri\fR elements specify an \s-1XML\s0 namespace
to use, otherwise they should both be \f(CW\*(C`nudef\*(C'\fR. The optional
\&\f(CW$flags\fR parameter defaults to zero.
.ie n .IP "$dom\->\fIis_active()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIis_active()\fR" 4
.IX Item "$dom->is_active()"
Returns a true value if the domain is currently running
.ie n .IP "$dom\->\fIis_persistent()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIis_persistent()\fR" 4
.IX Item "$dom->is_persistent()"
Returns a true value if the domain has a persistent configuration
file defined
.ie n .IP "$dom\->\fIis_updated()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIis_updated()\fR" 4
.IX Item "$dom->is_updated()"
Returns a true value if the domain is running and has a persistent
configuration file defined that is out of date compared to the
current live config.
.ie n .IP "my $xml = $dom\->get_xml_description($flags=0)" 4
.el .IP "my \f(CW$xml\fR = \f(CW$dom\fR\->get_xml_description($flags=0)" 4
.IX Item "my $xml = $dom->get_xml_description($flags=0)"
Returns an \s-1XML\s0 document containing a complete description of
the domain's configuration. The optional \f(CW$flags\fR parameter
controls generation of the \s-1XML\s0 document, defaulting to 0 if
omitted. It can be one or more of the \s-1XML\s0 \s-1DUMP\s0 constants
listed later in this document.
.ie n .IP "my $type = $dom\->\fIget_os_type()\fR" 4
.el .IP "my \f(CW$type\fR = \f(CW$dom\fR\->\fIget_os_type()\fR" 4
.IX Item "my $type = $dom->get_os_type()"
Returns a string containing the name of the \s-1OS\s0 type running
within the domain.
.ie n .IP "$dom\->create($flags)" 4
.el .IP "\f(CW$dom\fR\->create($flags)" 4
.IX Item "$dom->create($flags)"
Start a domain whose configuration was previously defined using the
\&\f(CW\*(C`define_domain\*(C'\fR method in Sys::Virt. The \f(CW$flags\fR parameter
accepts one of the \s-1DOMAIN\s0 \s-1CREATION\s0 constants documented later, and
defaults to 0 if omitted.
.ie n .IP "$dom\->\fIundefine()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIundefine()\fR" 4
.IX Item "$dom->undefine()"
Remove the configuration associated with a domain previously defined
with the \f(CW\*(C`define_domain\*(C'\fR method in Sys::Virt. If the domain is
running, you probably want to use the \f(CW\*(C`shutdown\*(C'\fR or \f(CW\*(C`destroy\*(C'\fR
methods instead.
.ie n .IP "$dom\->\fIsuspend()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIsuspend()\fR" 4
.IX Item "$dom->suspend()"
Temporarily stop execution of the domain, allowing later continuation
by calling the \f(CW\*(C`resume\*(C'\fR method.
.ie n .IP "$dom\->\fIresume()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIresume()\fR" 4
.IX Item "$dom->resume()"
Resume execution of a domain previously halted with the \f(CW\*(C`suspend\*(C'\fR
method.
.ie n .IP "$dom\->\fIpm_wakeup()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIpm_wakeup()\fR" 4
.IX Item "$dom->pm_wakeup()"
Wakeup the guest from power management suspend state
.ie n .IP "$dom\->pm_suspend_for_duration($target, $duration, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->pm_suspend_for_duration($target, \f(CW$duration\fR, \f(CW$flags\fR=0)" 4
.IX Item "$dom->pm_suspend_for_duration($target, $duration, $flags=0)"
Tells the guest \s-1OS\s0 to enter the power management suspend state
identified by \f(CW$target\fR. The \f(CW$target\fR parameter should be
one of the \s-1NODE\s0 \s-1SUSPEND\s0 \s-1CONTANTS\s0 listed in \f(CW\*(C`Sys::Virt\*(C'\fR. The
\&\f(CW$duration\fR specifies when the guest should automatically
wakeup. The \f(CW$flags\fR parameter is optional and defaults to
zero.
.ie n .IP "$dom\->save($filename)" 4
.el .IP "\f(CW$dom\fR\->save($filename)" 4
.IX Item "$dom->save($filename)"
Take a snapshot of the domain's state and save the information to
the file named in the \f(CW$filename\fR parameter. The domain can later
be restored from this file with the \f(CW\*(C`restore_domain\*(C'\fR method on
the Sys::Virt object.
.ie n .IP "$dom\->managed_save($flags=0)" 4
.el .IP "\f(CW$dom\fR\->managed_save($flags=0)" 4
.IX Item "$dom->managed_save($flags=0)"
Take a snapshot of the domain's state and save the information to
a managed save location. The domain will be automatically restored
with this state when it is next started. The \f(CW$flags\fR parameter is
unused and defaults to zero.
.ie n .IP "$bool = $dom\->has_managed_save_image($flags=0)" 4
.el .IP "\f(CW$bool\fR = \f(CW$dom\fR\->has_managed_save_image($flags=0)" 4
.IX Item "$bool = $dom->has_managed_save_image($flags=0)"
Return a non-zero value if the domain has a managed save image
that will be used at next start. The \f(CW$flags\fR parameter is
unused and defaults to zero.
.ie n .IP "$dom\->managed_save_remove($flags=0)" 4
.el .IP "\f(CW$dom\fR\->managed_save_remove($flags=0)" 4
.IX Item "$dom->managed_save_remove($flags=0)"
Remove the current managed save image, causing the guest to perform
a full boot next time it is started. The \f(CW$flags\fR parameter is
unused and defaults to zero.
.ie n .IP "$dom\->core_dump($filename[, $flags])" 4
.el .IP "\f(CW$dom\fR\->core_dump($filename[, \f(CW$flags\fR])" 4
.IX Item "$dom->core_dump($filename[, $flags])"
Trigger a core dump of the guest virtual machine, saving its memory
image to \f(CW$filename\fR so it can be analysed by tools such as \f(CW\*(C`crash\*(C'\fR.
The optional \f(CW$flags\fR flags parameter is currently unused and if
omitted will default to 0.
.ie n .IP "$dom\->\fIdestroy()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIdestroy()\fR" 4
.IX Item "$dom->destroy()"
Immediately poweroff the machine. This is equivalent to removing the
power plug. The guest \s-1OS\s0 is given no time to cleanup / save state.
For a clean poweroff sequence, use the \f(CW\*(C`shutdown\*(C'\fR method instead.
.ie n .IP "my $info = $dom\->\fIget_info()\fR" 4
.el .IP "my \f(CW$info\fR = \f(CW$dom\fR\->\fIget_info()\fR" 4
.IX Item "my $info = $dom->get_info()"
Returns a hash reference summarising the execution state of the
domain. The elements of the hash are as follows:
.RS 4
.IP "maxMem" 4
.IX Item "maxMem"
The maximum memory allowed for this domain, in kilobytes
.IP "memory" 4
.IX Item "memory"
The current memory allocated to the domain in kilobytes
.IP "cpuTime" 4
.IX Item "cpuTime"
The amount of \s-1CPU\s0 time used by the domain
.IP "nrVirtCpu" 4
.IX Item "nrVirtCpu"
The current number of virtual CPUs enabled in the domain
.IP "state" 4
.IX Item "state"
The execution state of the machine, which will be one of the
constants &Sys::Virt::Domain::STATE_*.
.RE
.RS 4
.RE
.ie n .IP "my ($state, $reason) = $dom\->\fIget_state()\fR" 4
.el .IP "my ($state, \f(CW$reason\fR) = \f(CW$dom\fR\->\fIget_state()\fR" 4
.IX Item "my ($state, $reason) = $dom->get_state()"
Returns an array whose values specify the current state
of the guest, and the reason for it being in that state.
The \f(CW$state\fR values are the same as for the \f(CW\*(C`get_info\*(C'\fR
\&\s-1API\s0, and the \f(CW$reason\fR values come from:
.RS 4
.IP "Sys::Virt::Domain::STATE_CRASHED_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::STATE_CRASHED_UNKNOWN"
It is not known why the domain has crashed
.IP "Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN"
It is not known why the domain has no state
.IP "Sys::Virt::Domain::STATE_PAUSED_DUMP" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_DUMP"
The guest is paused due to a core dump operation
.IP "Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT"
The guest is paused due to a snapshot
.IP "Sys::Virt::Domain::STATE_PAUSED_IOERROR" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_IOERROR"
The guest is paused due to an I/O error
.IP "Sys::Virt::Domain::STATE_PAUSED_MIGRATION" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_MIGRATION"
The guest is paused due to migration
.IP "Sys::Virt::Domain::STATE_PAUSED_SAVE" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_SAVE"
The guest is paused due to a save operation
.IP "Sys::Virt::Domain::STATE_PAUSED_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_UNKNOWN"
It is not known why the domain has paused
.IP "Sys::Virt::Domain::STATE_PAUSED_USER" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_USER"
The guest is paused at admin request
.IP "Sys::Virt::Domain::STATE_PAUSED_WATCHDOG" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_WATCHDOG"
The guest is paused due to the watchdog
.IP "Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN"
The guest is paused while domain shutdown takes place
.IP "Sys::Virt::Domain::STATE_RUNNING_BOOTED" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_BOOTED"
The guest is running after being booted
.IP "Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT"
The guest is running after restore from snapshot
.IP "Sys::Virt::Domain::STATE_RUNNING_MIGRATED" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_MIGRATED"
The guest is running after migration
.IP "Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED"
The guest is running after migration abort
.IP "Sys::Virt::Domain::STATE_RUNNING_RESTORED" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_RESTORED"
The guest is running after restore from file
.IP "Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED"
The guest is running after save cancel
.IP "Sys::Virt::Domain::STATE_RUNNING_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_UNKNOWN"
It is not known why the domain has started
.IP "Sys::Virt::Domain::STATE_RUNNING_UNPAUSED" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_UNPAUSED"
The guest is running after a resume
.IP "Sys::Virt::Domain::STATE_RUNNING_WAKEUP" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING_WAKEUP"
The guest is running after wakeup from power management suspend
.IP "Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN"
It is not known why the domain has shutdown
.IP "Sys::Virt::Domain::STATE_SHUTDOWN_USER" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTDOWN_USER"
The guest is shutdown due to admin request
.IP "Sys::Virt::Domain::STATE_SHUTOFF_CRASHED" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_CRASHED"
The guest is shutoff after a crash
.IP "Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED"
The guest is shutoff after being destroyed
.IP "Sys::Virt::Domain::STATE_SHUTOFF_FAILED" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_FAILED"
The guest is shutoff due to a virtualization failure
.IP "Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT"
The guest is shutoff after a snapshot
.IP "Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED"
The guest is shutoff after migration
.IP "Sys::Virt::Domain::STATE_SHUTOFF_SAVED" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_SAVED"
The guest is shutoff after a save
.IP "Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN"
The guest is shutoff due to controlled shutdown
.IP "Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN"
It is not known why the domain has shutoff
.IP "Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN"
It is not known why the domain was suspended
.RE
.RS 4
.RE
.ie n .IP "my $info = $dom\->get_control_info($flags=0)" 4
.el .IP "my \f(CW$info\fR = \f(CW$dom\fR\->get_control_info($flags=0)" 4
.IX Item "my $info = $dom->get_control_info($flags=0)"
Returns a hash reference providing information about
the control channel. The returned keys in the hash
are
.RS 4
.ie n .IP """state""" 4
.el .IP "\f(CWstate\fR" 4
.IX Item "state"
One of the \s-1CONTROL\s0 \s-1INFO\s0 constants listed later
.ie n .IP """details""" 4
.el .IP "\f(CWdetails\fR" 4
.IX Item "details"
Currently unsed, always 0.
.ie n .IP """stateTime""" 4
.el .IP "\f(CWstateTime\fR" 4
.IX Item "stateTime"
The elapsed time since the control channel entered
the current state.
.RE
.RS 4
.RE
.ie n .IP "my @errs = $dom\->get_disk_errors($flags=0)" 4
.el .IP "my \f(CW@errs\fR = \f(CW$dom\fR\->get_disk_errors($flags=0)" 4
.IX Item "my @errs = $dom->get_disk_errors($flags=0)"
Returns a list of all disk errors that have occurred on
the backing store for the guest's virtual disks. The
returned array elements are hash references, containing
two keys
.RS 4
.ie n .IP """path""" 4
.el .IP "\f(CWpath\fR" 4
.IX Item "path"
The path of the disk with an error
.ie n .IP """error""" 4
.el .IP "\f(CWerror\fR" 4
.IX Item "error"
The error type
.RE
.RS 4
.RE
.ie n .IP "$dom\->send_key($keycodeset, $holdtime, \e@keycodes, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->send_key($keycodeset, \f(CW$holdtime\fR, \e@keycodes, \f(CW$flags\fR=0)" 4
.IX Item "$dom->send_key($keycodeset, $holdtime, @keycodes, $flags=0)"
Sends a sequence of keycodes to the guest domain. The
\&\f(CW$keycodeset\fR should be one of the constants listed
later in the \s-1KEYCODE\s0 \s-1SET\s0 section. \f(CW$holdtiem\fR is the
duration, in milliseconds, to keep the key pressed
before releasing it and sending the next keycode.
\&\f(CW@keycodes\fR is an array reference containing the list
of keycodes to send to the guest. The elements in the
array should be keycode values from the specified
keycode set. \f(CW$flags\fR is currently unused.
.ie n .IP "my $info = $dom\->get_block_info($dev, $flags=0)" 4
.el .IP "my \f(CW$info\fR = \f(CW$dom\fR\->get_block_info($dev, \f(CW$flags\fR=0)" 4
.IX Item "my $info = $dom->get_block_info($dev, $flags=0)"
Returns a hash reference summarising the disk usage of
the host backing store for a guest block device. The
\&\f(CW$dev\fR parameter should be the path to the backing
store on the host. \f(CW$flags\fR is currently unused and
defaults to 0 if omitted. The returned hash contains
the following elements
.RS 4
.IP "capacity" 4
.IX Item "capacity"
Logical size in bytes of the block device backing image *
.IP "allocation" 4
.IX Item "allocation"
Highest allocated extent in bytes of the block device backing image
.IP "physical" 4
.IX Item "physical"
Physical size in bytes of the container of the backing image
.RE
.RS 4
.RE
.ie n .IP "$dom\->set_max_memory($mem)" 4
.el .IP "\f(CW$dom\fR\->set_max_memory($mem)" 4
.IX Item "$dom->set_max_memory($mem)"
Set the maximum memory for the domain to the value \f(CW$mem\fR. The
value of the \f(CW$mem\fR parameter is specified in kilobytes.
.ie n .IP "$mem = $dom\->\fIget_max_memory()\fR" 4
.el .IP "\f(CW$mem\fR = \f(CW$dom\fR\->\fIget_max_memory()\fR" 4
.IX Item "$mem = $dom->get_max_memory()"
Returns the current maximum memory allowed for this domain in
kilobytes.
.ie n .IP "$dom\->set_memory($mem, $flags)" 4
.el .IP "\f(CW$dom\fR\->set_memory($mem, \f(CW$flags\fR)" 4
.IX Item "$dom->set_memory($mem, $flags)"
Set the current memory for the domain to the value \f(CW$mem\fR. The
value of the \f(CW$mem\fR parameter is specified in kilobytes. This
must be less than, or equal to the domain's max memory limit.
The \f(CW$flags\fR parameter can control whether the update affects
the live guest, or inactive config, defaulting to modifying
the current state.
.ie n .IP "$dom\->\fIshutdown()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIshutdown()\fR" 4
.IX Item "$dom->shutdown()"
Request that the guest \s-1OS\s0 perform a graceful shutdown and
poweroff. This usually requires some form of cooperation
from the guest operating system, such as responding to an
\&\s-1ACPI\s0 signal, or a guest agent process. For an immediate,
forceful poweroff, use the \f(CW\*(C`destroy\*(C'\fR method instead.
.ie n .IP "$dom\->reboot([$flags])" 4
.el .IP "\f(CW$dom\fR\->reboot([$flags])" 4
.IX Item "$dom->reboot([$flags])"
Request that the guest \s-1OS\s0 perform a graceful shutdown and
optionally restart. The optional \f(CW$flags\fR parameter is
currently unused and if omitted defaults to zero.
.ie n .IP "$dom\->reset([$flags])" 4
.el .IP "\f(CW$dom\fR\->reset([$flags])" 4
.IX Item "$dom->reset([$flags])"
Perform a hardware reset of the virtual machine. The guest
\&\s-1OS\s0 is given no opportunity to shutdown gracefully. The
optional \f(CW$flags\fR parameter is currently unused and if
omitted defaults to zero.
.ie n .IP "$dom\->\fIget_max_vcpus()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIget_max_vcpus()\fR" 4
.IX Item "$dom->get_max_vcpus()"
Return the maximum number of vcpus that are configured
for the domain
.ie n .IP "$dom\->attach_device($xml[, $flags])" 4
.el .IP "\f(CW$dom\fR\->attach_device($xml[, \f(CW$flags\fR])" 4
.IX Item "$dom->attach_device($xml[, $flags])"
Hotplug a new device whose configuration is given by \f(CW$xml\fR,
to the running guest. The optional <$flags> parameter defaults
to 0, but can accept one of the device hotplug flags described
later.
.ie n .IP "$dom\->detach_device($xml[, $flags])" 4
.el .IP "\f(CW$dom\fR\->detach_device($xml[, \f(CW$flags\fR])" 4
.IX Item "$dom->detach_device($xml[, $flags])"
Hotunplug a existing device whose configuration is given by \f(CW$xml\fR,
from the running guest. The optional <$flags> parameter defaults
to 0, but can accept one of the device hotplug flags described
later.
.ie n .IP "$dom\->update_device($xml[, $flags])" 4
.el .IP "\f(CW$dom\fR\->update_device($xml[, \f(CW$flags\fR])" 4
.IX Item "$dom->update_device($xml[, $flags])"
Update the configuration of an existing device. The new configuration
is given by \f(CW$xml\fR. The optional <$flags> parameter defaults to
0 but can accept one of the device hotplug flags described later.
.ie n .IP "$data = $dom\->block_peek($path, $offset, $size[, $flags)" 4
.el .IP "\f(CW$data\fR = \f(CW$dom\fR\->block_peek($path, \f(CW$offset\fR, \f(CW$size\fR[, \f(CW$flags\fR)" 4
.IX Item "$data = $dom->block_peek($path, $offset, $size[, $flags)"
Peek into the guest disk \f(CW$path\fR, at byte \f(CW$offset\fR capturing
\&\f(CW$size\fR bytes of data. The returned scalar may contain embedded
NULLs. The optional \f(CW$flags\fR parameter is currently unused and
if omitted defaults to zero.
.ie n .IP "$data = $dom\->memory_peek($offset, $size[, $flags])" 4
.el .IP "\f(CW$data\fR = \f(CW$dom\fR\->memory_peek($offset, \f(CW$size\fR[, \f(CW$flags\fR])" 4
.IX Item "$data = $dom->memory_peek($offset, $size[, $flags])"
Peek into the guest memory at byte \f(CW$offset\fR virtual address,
capturing \f(CW$size\fR bytes of memory. The return scalar may
contain embedded NULLs. The optional \f(CW$flags\fR parameter is
currently unused and if omitted defaults to zero.
.ie n .IP "$flag = $dom\->\fIget_autostart()\fR;" 4
.el .IP "\f(CW$flag\fR = \f(CW$dom\fR\->\fIget_autostart()\fR;" 4
.IX Item "$flag = $dom->get_autostart();"
Return a true value if the guest domain is configured to automatically
start upon boot. Return false, otherwise
.ie n .IP "$dom\->set_autostart($flag)" 4
.el .IP "\f(CW$dom\fR\->set_autostart($flag)" 4
.IX Item "$dom->set_autostart($flag)"
Set the state of the autostart flag, which determines whether the
guest will automatically start upon boot of the host \s-1OS\s0
.ie n .IP "$dom\->set_vcpus($count, [$flags])" 4
.el .IP "\f(CW$dom\fR\->set_vcpus($count, [$flags])" 4
.IX Item "$dom->set_vcpus($count, [$flags])"
Set the number of virtual CPUs in the guest \s-1VM\s0 to \f(CW$count\fR.
The optional \f(CW$flags\fR parameter can be used to control whether
the setting changes the live config or inactive config.
.ie n .IP "$count = $dom\->get_vcpus([$flags])" 4
.el .IP "\f(CW$count\fR = \f(CW$dom\fR\->get_vcpus([$flags])" 4
.IX Item "$count = $dom->get_vcpus([$flags])"
Get the number of virtual CPUs in the guest \s-1VM\s0.
The optional \f(CW$flags\fR parameter can be used to control whether
to query the setting of the live config or inactive config.
.ie n .IP "$type = $dom\->\fIget_scheduler_type()\fR" 4
.el .IP "\f(CW$type\fR = \f(CW$dom\fR\->\fIget_scheduler_type()\fR" 4
.IX Item "$type = $dom->get_scheduler_type()"
Return the scheduler type for the guest domain
.ie n .IP "$stats = $dom\->block_stats($path)" 4
.el .IP "\f(CW$stats\fR = \f(CW$dom\fR\->block_stats($path)" 4
.IX Item "$stats = $dom->block_stats($path)"
Fetch the current I/O statistics for the block device given by \f(CW$path\fR.
The returned hash reference contains keys for
.RS 4
.ie n .IP """rd_req""" 4
.el .IP "\f(CWrd_req\fR" 4
.IX Item "rd_req"
Number of read requests
.ie n .IP """rd_bytes""" 4
.el .IP "\f(CWrd_bytes\fR" 4
.IX Item "rd_bytes"
Number of bytes read
.ie n .IP """wr_req""" 4
.el .IP "\f(CWwr_req\fR" 4
.IX Item "wr_req"
Number of write requests
.ie n .IP """wr_bytes""" 4
.el .IP "\f(CWwr_bytes\fR" 4
.IX Item "wr_bytes"
Number of bytes written
.ie n .IP """errs""" 4
.el .IP "\f(CWerrs\fR" 4
.IX Item "errs"
Some kind of error count
.RE
.RS 4
.RE
.ie n .IP "my $params = $dom\->get_scheduler_parameters($flags=0)" 4
.el .IP "my \f(CW$params\fR = \f(CW$dom\fR\->get_scheduler_parameters($flags=0)" 4
.IX Item "my $params = $dom->get_scheduler_parameters($flags=0)"
Return the set of scheduler tunable parameters for the guest,
as a hash reference. The precise set of keys in the hash
are specific to the hypervisor.
.ie n .IP "$dom\->set_scheduler_parameters($params, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->set_scheduler_parameters($params, \f(CW$flags\fR=0)" 4
.IX Item "$dom->set_scheduler_parameters($params, $flags=0)"
Update the set of scheduler tunable parameters. The value names for
tunables vary, and can be discovered using the \f(CW\*(C`get_scheduler_params\*(C'\fR
call
.ie n .IP "my $params = $dom\->get_memory_parameters($flags=0)" 4
.el .IP "my \f(CW$params\fR = \f(CW$dom\fR\->get_memory_parameters($flags=0)" 4
.IX Item "my $params = $dom->get_memory_parameters($flags=0)"
Return a hash reference containing the set of memory tunable
parameters for the guest. The keys in the hash are one of the
constants \s-1MEMORY\s0 \s-1PARAMETERS\s0 described later.
.ie n .IP "$dom\->set_memory_parameters($params, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->set_memory_parameters($params, \f(CW$flags\fR=0)" 4
.IX Item "$dom->set_memory_parameters($params, $flags=0)"
Update the memory tunable parameters for the guest. The
\&\f(CW$params\fR should be a hash reference whose keys are one
of the \s-1MEMORY\s0 \s-1PARAMETERS\s0 constants.
.ie n .IP "my $params = $dom\->get_blkio_parameters($flags=0)" 4
.el .IP "my \f(CW$params\fR = \f(CW$dom\fR\->get_blkio_parameters($flags=0)" 4
.IX Item "my $params = $dom->get_blkio_parameters($flags=0)"
Return a hash reference containing the set of blkio tunable
parameters for the guest. The keys in the hash are one of the
constants \s-1BLKIO\s0 \s-1PARAMETERS\s0 described later.
.ie n .IP "$dom\->set_blkio_parameters($params, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->set_blkio_parameters($params, \f(CW$flags\fR=0)" 4
.IX Item "$dom->set_blkio_parameters($params, $flags=0)"
Update the blkio tunable parameters for the guest. The
\&\f(CW$params\fR should be a hash reference whose keys are one
of the \s-1BLKIO\s0 \s-1PARAMETERS\s0 constants.
.ie n .IP "$stats = $dom\->get_block_iotune($disk, $flags=0)" 4
.el .IP "\f(CW$stats\fR = \f(CW$dom\fR\->get_block_iotune($disk, \f(CW$flags\fR=0)" 4
.IX Item "$stats = $dom->get_block_iotune($disk, $flags=0)"
Return a hash reference containing the set of blkio tunable
parameters for the guest disk \f(CW$disk\fR. The keys in the hash
are one of the constants \s-1BLOCK\s0 \s-1IOTUNE\s0 \s-1PARAMETERS\s0 described later.
.ie n .IP "$dom\->set_block_iotune($disk, $params, $flags=0);" 4
.el .IP "\f(CW$dom\fR\->set_block_iotune($disk, \f(CW$params\fR, \f(CW$flags\fR=0);" 4
.IX Item "$dom->set_block_iotune($disk, $params, $flags=0);"
Update the blkio tunable parameters for the guest disk \f(CW$disk\fR. The
\&\f(CW$params\fR should be a hash reference whose keys are one
of the \s-1BLOCK\s0 \s-1IOTUNE\s0 \s-1PARAMETERS\s0 constants.
.ie n .IP "my $params = $dom\->get_interface_parameters($intf, $flags=0)" 4
.el .IP "my \f(CW$params\fR = \f(CW$dom\fR\->get_interface_parameters($intf, \f(CW$flags\fR=0)" 4
.IX Item "my $params = $dom->get_interface_parameters($intf, $flags=0)"
Return a hash reference containing the set of interface tunable
parameters for the guest. The keys in the hash are one of the
constants \s-1INTERFACE\s0 \s-1PARAMETERS\s0 described later.
.ie n .IP "$dom\->set_interface_parameters($intf, $params, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->set_interface_parameters($intf, \f(CW$params\fR, \f(CW$flags\fR=0)" 4
.IX Item "$dom->set_interface_parameters($intf, $params, $flags=0)"
Update the interface tunable parameters for the guest. The
\&\f(CW$params\fR should be a hash reference whose keys are one
of the \s-1INTERFACE\s0 \s-1PARAMETERS\s0 constants.
.ie n .IP "my $params = $dom\->get_numa_parameters($flags=0)" 4
.el .IP "my \f(CW$params\fR = \f(CW$dom\fR\->get_numa_parameters($flags=0)" 4
.IX Item "my $params = $dom->get_numa_parameters($flags=0)"
Return a hash reference containing the set of numa tunable
parameters for the guest. The keys in the hash are one of the
constants \s-1NUMA\s0 \s-1PARAMETERS\s0 described later.
.ie n .IP "$dom\->set_numa_parameters($params, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->set_numa_parameters($params, \f(CW$flags\fR=0)" 4
.IX Item "$dom->set_numa_parameters($params, $flags=0)"
Update the numa tunable parameters for the guest. The
\&\f(CW$params\fR should be a hash reference whose keys are one
of the \s-1NUMA\s0 \s-1PARAMETERS\s0 constants.
.ie n .IP "$dom\->block_resize($disk, $newsize, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->block_resize($disk, \f(CW$newsize\fR, \f(CW$flags\fR=0)" 4
.IX Item "$dom->block_resize($disk, $newsize, $flags=0)"
Resize the disk \f(CW$disk\fR to have new size \f(CW$newsize\fR \s-1KB\s0. If the disk
is backed by a special image format, the actual resize is done by the
hypervisor. If the disk is backed by a raw file, or block device,
the resize must be done prior to invoking this \s-1API\s0 call, and it
merely updates the hypervisor's view of the disk size. The following
flags may be used
.RS 4
.IP "Sys::Virt::Domain::BLOCK_RESIZE_BYTES" 4
.IX Item "Sys::Virt::Domain::BLOCK_RESIZE_BYTES"
Treat \f(CW$newsize\fR as if it were in bytes, rather than \s-1KB\s0.
.RE
.RS 4
.RE
.ie n .IP "$dom\->interface_stats($path)" 4
.el .IP "\f(CW$dom\fR\->interface_stats($path)" 4
.IX Item "$dom->interface_stats($path)"
Fetch the current I/O statistics for the block device given by \f(CW$path\fR.
The returned hash containins keys for
.RS 4
.ie n .IP """rx_bytes""" 4
.el .IP "\f(CWrx_bytes\fR" 4
.IX Item "rx_bytes"
Total bytes received
.ie n .IP """rx_packets""" 4
.el .IP "\f(CWrx_packets\fR" 4
.IX Item "rx_packets"
Total packets received
.ie n .IP """rx_errs""" 4
.el .IP "\f(CWrx_errs\fR" 4
.IX Item "rx_errs"
Total packets received with errors
.ie n .IP """rx_drop""" 4
.el .IP "\f(CWrx_drop\fR" 4
.IX Item "rx_drop"
Total packets drop at reception
.ie n .IP """tx_bytes""" 4
.el .IP "\f(CWtx_bytes\fR" 4
.IX Item "tx_bytes"
Total bytes transmitted
.ie n .IP """tx_packets""" 4
.el .IP "\f(CWtx_packets\fR" 4
.IX Item "tx_packets"
Total packets transmitted
.ie n .IP """tx_errs""" 4
.el .IP "\f(CWtx_errs\fR" 4
.IX Item "tx_errs"
Total packets transmitted with errors
.ie n .IP """tx_drop""" 4
.el .IP "\f(CWtx_drop\fR" 4
.IX Item "tx_drop"
Total packets dropped at transmission.
.RE
.RS 4
.RE
.ie n .IP "$dom\->memory_stats($flags=0)" 4
.el .IP "\f(CW$dom\fR\->memory_stats($flags=0)" 4
.IX Item "$dom->memory_stats($flags=0)"
Fetch the current memory statistics for the guest domain. The
\&\f(CW$flags\fR parameter is currently unused and can be omitted.
The returned hash containins keys for
.RS 4
.ie n .IP """swap_in""" 4
.el .IP "\f(CWswap_in\fR" 4
.IX Item "swap_in"
Data read from swap space
.ie n .IP """swap_out""" 4
.el .IP "\f(CWswap_out\fR" 4
.IX Item "swap_out"
Data written to swap space
.ie n .IP """major_fault""" 4
.el .IP "\f(CWmajor_fault\fR" 4
.IX Item "major_fault"
Page fault involving disk I/O
.ie n .IP """minor_fault""" 4
.el .IP "\f(CWminor_fault\fR" 4
.IX Item "minor_fault"
Page fault not involving disk I/O
.ie n .IP """unused""" 4
.el .IP "\f(CWunused\fR" 4
.IX Item "unused"
Memory not used by the system
.ie n .IP """available""" 4
.el .IP "\f(CWavailable\fR" 4
.IX Item "available"
Total memory seen by guest
.RE
.RS 4
.RE
.ie n .IP "$info = $dom\->\fIget_security_label()\fR" 4
.el .IP "\f(CW$info\fR = \f(CW$dom\fR\->\fIget_security_label()\fR" 4
.IX Item "$info = $dom->get_security_label()"
Fetch information about the security label assigned to the guest
domain. The returned hash reference has two keys, \f(CW\*(C`model\*(C'\fR gives
the name of the security model in effect (eg \f(CW\*(C`selinux\*(C'\fR), while
\&\f(CW\*(C`label\*(C'\fR provides the name of the security label applied to the
domain.
.ie n .IP "$ddom = $dom\->migrate(destcon, flags, dname, uri, bandwidth)" 4
.el .IP "\f(CW$ddom\fR = \f(CW$dom\fR\->migrate(destcon, flags, dname, uri, bandwidth)" 4
.IX Item "$ddom = $dom->migrate(destcon, flags, dname, uri, bandwidth)"
Migrate a domain to an alternative host. The \f(CW\*(C`destcon\*(C'\fR parameter
should be a \f(CW\*(C`Sys::Virt\*(C'\fR connection to the remote target host.
If the \f(CW\*(C`flags\*(C'\fR parameter is zero offline migration will be
performed. The \f(CW\*(C`Sys::Virt::Domain::MIGRATE_LIVE\*(C'\fR constant can be
used to request live migration. The \f(CW\*(C`dname\*(C'\fR parameter allows the
guest to be renamed on the target host, if set to \f(CW\*(C`undef\*(C'\fR, the
domains' current name will be maintained. In normal circumstances,
the source host determines the target hostname from the \s-1URI\s0 associated
with the \f(CW\*(C`destcon\*(C'\fR connection. If the destination host is multi-homed
it may be necessary to supply an alternate destination hostame
via the \f(CW\*(C`uri\*(C'\fR parameter. The \f(CW\*(C`bandwidth\*(C'\fR parameter allows network
usage to be throttled during migration. If set to zero, no throttling
will be performed. The \f(CW\*(C`flags\*(C'\fR, \f(CW\*(C`dname\*(C'\fR, \f(CW\*(C`uri\*(C'\fR and \f(CW\*(C`bandwidth\*(C'\fR
parameters are all optional, and if omitted default to zero, \f(CW\*(C`undef\*(C'\fR,
\&\f(CW\*(C`undef\*(C'\fR, and zero respectively.
.ie n .IP "$ddom = $dom\->migrate2(destcon, dxml, flags, dname, uri, bandwidth)" 4
.el .IP "\f(CW$ddom\fR = \f(CW$dom\fR\->migrate2(destcon, dxml, flags, dname, uri, bandwidth)" 4
.IX Item "$ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)"
Migrate a domain to an alternative host. This function works in the
same way as \f(CW\*(C`migrate\*(C'\fR, except is also allows \f(CW\*(C`dxml\*(C'\fR to specify a
changed \s-1XML\s0 configuration for the guest on the target host.
.ie n .IP "$dom\->migrate_to_uri(desturi, flags, dname, bandwidth)" 4
.el .IP "\f(CW$dom\fR\->migrate_to_uri(desturi, flags, dname, bandwidth)" 4
.IX Item "$dom->migrate_to_uri(desturi, flags, dname, bandwidth)"
Migrate a domain to an alternative host. The \f(CW\*(C`destri\*(C'\fR parameter
should be a valid libvirt connection \s-1URI\s0 for the remote target host.
If the \f(CW\*(C`flags\*(C'\fR parameter is zero offline migration will be
performed. The \f(CW\*(C`Sys::Virt::Domain::MIGRATE_LIVE\*(C'\fR constant can be
used to request live migration. The \f(CW\*(C`dname\*(C'\fR parameter allows the
guest to be renamed on the target host, if set to \f(CW\*(C`undef\*(C'\fR, the
domains' current name will be maintained. In normal circumstances,
the source host determines the target hostname from the \s-1URI\s0 associated
with the \f(CW\*(C`destcon\*(C'\fR connection. If the destination host is multi-homed
it may be necessary to supply an alternate destination hostame
via the \f(CW\*(C`uri\*(C'\fR parameter. The \f(CW\*(C`bandwidth\*(C'\fR parameter allows network
usage to be throttled during migration. If set to zero, no throttling
will be performed. The \f(CW\*(C`flags\*(C'\fR, \f(CW\*(C`dname\*(C'\fR and \f(CW\*(C`bandwidth\*(C'\fR
parameters are all optional, and if omitted default to zero, \f(CW\*(C`undef\*(C'\fR,
\&\f(CW\*(C`undef\*(C'\fR, and zero respectively.
.ie n .IP "$dom\->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)" 4
.el .IP "\f(CW$dom\fR\->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)" 4
.IX Item "$dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)"
Migrate a domain to an alternative host. This function works in almost
the same way as \f(CW\*(C`migrate_to_uri\*(C'\fR, except is also allows \f(CW\*(C`dxml\*(C'\fR to
specify a changed \s-1XML\s0 configuration for the guest on the target host.
The \f(CW\*(C`dconnuri\*(C'\fR must always specify the \s-1URI\s0 of the remote libvirtd
daemon, or be \f(CW\*(C`undef\*(C'\fR. The \f(CW\*(C`miguri\*(C'\fR parameter can be used to specify
the \s-1URI\s0 for initiating the migration operation, or be \f(CW\*(C`undef\*(C'\fR.
.ie n .IP "$dom\->migrate_set_max_downtime($downtime, $flags)" 4
.el .IP "\f(CW$dom\fR\->migrate_set_max_downtime($downtime, \f(CW$flags\fR)" 4
.IX Item "$dom->migrate_set_max_downtime($downtime, $flags)"
Set the maximum allowed downtime during migration of the guest. A
longer downtime makes it more likely that migration will complete,
at the cost of longer time blackout for the guest \s-1OS\s0 at the switch
over point. The \f(CW\*(C`downtime\*(C'\fR parameter is measured in milliseconds.
The \f(CW$flags\fR parameter is currently unused and defaults to zero.
.ie n .IP "$dom\->migrate_set_max_speed($bandwidth, $flags)" 4
.el .IP "\f(CW$dom\fR\->migrate_set_max_speed($bandwidth, \f(CW$flags\fR)" 4
.IX Item "$dom->migrate_set_max_speed($bandwidth, $flags)"
Set the maximum allowed bandwidth during migration of the guest.
The \f(CW\*(C`bandwidth\*(C'\fR parameter is measured in MB/second.
The \f(CW$flags\fR parameter is currently unused and defaults to zero.
.ie n .IP "$bandwidth = $dom\->migrate_get_max_speed($flag)" 4
.el .IP "\f(CW$bandwidth\fR = \f(CW$dom\fR\->migrate_get_max_speed($flag)" 4
.IX Item "$bandwidth = $dom->migrate_get_max_speed($flag)"
Get the maximum allowed bandwidth during migration fo the guest.
The returned <bandwidth> value is measured in MB/second.
The \f(CW$flags\fR parameter is currently unused and defaults to zero.
.ie n .IP "$dom\->inject_nmi($flags)" 4
.el .IP "\f(CW$dom\fR\->inject_nmi($flags)" 4
.IX Item "$dom->inject_nmi($flags)"
Trigger an \s-1NMI\s0 in the guest virtual machine. The \f(CW$flags\fR parameter
is currently unused and defaults to 0.
.ie n .IP "$dom\->open_console($st, $devname, $flags)" 4
.el .IP "\f(CW$dom\fR\->open_console($st, \f(CW$devname\fR, \f(CW$flags\fR)" 4
.IX Item "$dom->open_console($st, $devname, $flags)"
Open the text console for a serial, parallel or paravirt console
device identified by \f(CW$devname\fR, connecting it to the stream
\&\f(CW$st\fR. If \f(CW$devname\fR is undefined, the default console will be
opened. \f(CW$st\fR must be a \f(CW\*(C`Sys::Virt::Stream\*(C'\fR object used for
bi-directional communication with the console. \f(CW$flags\fR is
currently unused, defaulting to 0.
.ie n .IP "$dom\->open_graphics($idx, $fd, $flags)" 4
.el .IP "\f(CW$dom\fR\->open_graphics($idx, \f(CW$fd\fR, \f(CW$flags\fR)" 4
.IX Item "$dom->open_graphics($idx, $fd, $flags)"
Open the graphics console for a guest, identified by \f(CW$idx\fR,
counting from 0. The \f(CW$fd\fR should be a file descriptor for an
anoymous socket pair. The \f(CW$flags\fR argument should be one of
the constants listed at the end of this document, and defaults
to 0.
.ie n .IP "$dom\->screenshot($st, $screen, $flags)" 4
.el .IP "\f(CW$dom\fR\->screenshot($st, \f(CW$screen\fR, \f(CW$flags\fR)" 4
.IX Item "$dom->screenshot($st, $screen, $flags)"
Capture a screenshot of the virtual machine's monitor. The \f(CW$screen\fR
parameter controls which monitor is captured when using a multi-head
or multi-card configuration. \f(CW$st\fR must be a \f(CW\*(C`Sys::Virt::Stream\*(C'\fR
object from which the data can be read. \f(CW$flags\fR is currently unused
and defaults to 0.
.ie n .IP "@vcpuinfo = $dom\->\fIget_vcpu_info()\fR" 4
.el .IP "\f(CW@vcpuinfo\fR = \f(CW$dom\fR\->\fIget_vcpu_info()\fR" 4
.IX Item "@vcpuinfo = $dom->get_vcpu_info()"
Obtain information about the state of all virtual CPUs in a running
guest domain. The returned list will have one element for each vCPU,
where each elements contains a hash reference. The keys in the hash
are, \f(CW\*(C`number\*(C'\fR the vCPU number, \f(CW\*(C`cpu\*(C'\fR the physical \s-1CPU\s0 on which the
vCPU is currently scheduled, \f(CW\*(C`cpuTime\*(C'\fR the cummulative execution
time of the vCPU, \f(CW\*(C`state\*(C'\fR the running state and \f(CW\*(C`affinity\*(C'\fR giving
the allowed shedular placement. The value for \f(CW\*(C`affinity\*(C'\fR is a
string representing a bitmask against physical CPUs, 8 cpus per
character.
.ie n .IP "$dom\->pin_vcpu($vcpu, $mask)" 4
.el .IP "\f(CW$dom\fR\->pin_vcpu($vcpu, \f(CW$mask\fR)" 4
.IX Item "$dom->pin_vcpu($vcpu, $mask)"
Ping the virtual \s-1CPU\s0 given by index \f(CW$vcpu\fR to physical CPUs
given by \f(CW$mask\fR. The \f(CW$mask\fR is a string representing a bitmask
against physical CPUs, 8 cpus per character.
.ie n .IP "my @stats = $dom\->get_cpu_stats($startCpu, $numCpus, $flags=0)" 4
.el .IP "my \f(CW@stats\fR = \f(CW$dom\fR\->get_cpu_stats($startCpu, \f(CW$numCpus\fR, \f(CW$flags\fR=0)" 4
.IX Item "my @stats = $dom->get_cpu_stats($startCpu, $numCpus, $flags=0)"
Requests the guests host physical \s-1CPU\s0 usage statistics, starting
from host \s-1CPU\s0 <$startCpu> counting upto \f(CW$numCpus\fR. If \f(CW$startCpu\fR
is \-1 and \f(CW$numCpus\fR is 1, then the utilization across all CPUs
is returned. Returns an array of hash references, each element
containing stats for one \s-1CPU\s0.
.ie n .IP "my $info = $dom\->\fIget_job_info()\fR" 4
.el .IP "my \f(CW$info\fR = \f(CW$dom\fR\->\fIget_job_info()\fR" 4
.IX Item "my $info = $dom->get_job_info()"
Returns a hash reference summarising the execution state of the
background job. The elements of the hash are as follows:
.ie n .IP "$dom\->\fIabort_job()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIabort_job()\fR" 4
.IX Item "$dom->abort_job()"
Aborts the currently executing job
.ie n .IP "my $info = $dom\->get_block_job_info($path, $flags=0)" 4
.el .IP "my \f(CW$info\fR = \f(CW$dom\fR\->get_block_job_info($path, \f(CW$flags\fR=0)" 4
.IX Item "my $info = $dom->get_block_job_info($path, $flags=0)"
Returns a hash reference summarising the execution state of
the block job. The \f(CW$path\fR parameter should be the fully
qualified path of the block device being changed.
.ie n .IP "$dom\->set_block_job_speed($path, $bandwidth, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->set_block_job_speed($path, \f(CW$bandwidth\fR, \f(CW$flags\fR=0)" 4
.IX Item "$dom->set_block_job_speed($path, $bandwidth, $flags=0)"
Change the maximum I/O bandwidth used by the block job that
is currently executing for \f(CW$path\fR. The \f(CW$bandwidth\fR argument
is specified in MB/s
.ie n .IP "$dom\->abort_block_job($path, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->abort_block_job($path, \f(CW$flags\fR=0)" 4
.IX Item "$dom->abort_block_job($path, $flags=0)"
Abort the current job that is executing for the block device
associated with \f(CW$path\fR
.ie n .IP "$dom\->block_pull($path, $bandwith, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->block_pull($path, \f(CW$bandwith\fR, \f(CW$flags\fR=0)" 4
.IX Item "$dom->block_pull($path, $bandwith, $flags=0)"
Merge the backing files associated with \f(CW$path\fR into the
top level file. The \f(CW$bandwidth\fR parameter specifies the
maximum I/O rate to allow in MB/s.
.ie n .IP "$dom\->block_rebase($path, $backingpath, $bandwith, $flags=0)" 4
.el .IP "\f(CW$dom\fR\->block_rebase($path, \f(CW$backingpath\fR, \f(CW$bandwith\fR, \f(CW$flags\fR=0)" 4
.IX Item "$dom->block_rebase($path, $backingpath, $bandwith, $flags=0)"
Switch the backing path associated with \f(CW$path\fR to instead
use \f(CW$backingpath\fR. The \f(CW$bandwidth\fR parameter specifies the
maximum I/O rate to allow in MB/s.
.ie n .IP "$count = $dom\->\fInum_of_snapshots()\fR" 4
.el .IP "\f(CW$count\fR = \f(CW$dom\fR\->\fInum_of_snapshots()\fR" 4
.IX Item "$count = $dom->num_of_snapshots()"
Return the number of saved snapshots of the domain
.ie n .IP "@names = $dom\->\fIlist_snapshot_names()\fR" 4
.el .IP "\f(CW@names\fR = \f(CW$dom\fR\->\fIlist_snapshot_names()\fR" 4
.IX Item "@names = $dom->list_snapshot_names()"
List the names of all saved snapshots. The names can be
used with the \f(CW\*(C`lookup_snapshot_by_name\*(C'\fR
.ie n .IP "@snapshots = $dom\->\fIlist_snapshots()\fR" 4
.el .IP "\f(CW@snapshots\fR = \f(CW$dom\fR\->\fIlist_snapshots()\fR" 4
.IX Item "@snapshots = $dom->list_snapshots()"
Return a list of all snapshots currently known to the domain. The elements
in the returned list are instances of the Sys::Virt::DomainSnapshot class.
.ie n .IP "my $snapshot = $dom\->get_snapshot_by_name($name)" 4
.el .IP "my \f(CW$snapshot\fR = \f(CW$dom\fR\->get_snapshot_by_name($name)" 4
.IX Item "my $snapshot = $dom->get_snapshot_by_name($name)"
Return the domain snapshot with a name of \f(CW$name\fR. The returned object is
an instance of the Sys::Virt::DomainSnapshot class.
.ie n .IP "$dom\->\fIhas_current_snapshot()\fR" 4
.el .IP "\f(CW$dom\fR\->\fIhas_current_snapshot()\fR" 4
.IX Item "$dom->has_current_snapshot()"
Returns a true value if the domain has a currently active snapshot
.ie n .IP "$snapshot = $dom\->\fIcurrent_snapshot()\fR" 4
.el .IP "\f(CW$snapshot\fR = \f(CW$dom\fR\->\fIcurrent_snapshot()\fR" 4
.IX Item "$snapshot = $dom->current_snapshot()"
Returns the currently active snapshot for the domain.
.ie n .IP "$snapshot = $dom\->create_snapshot($xml[, $flags])" 4
.el .IP "\f(CW$snapshot\fR = \f(CW$dom\fR\->create_snapshot($xml[, \f(CW$flags\fR])" 4
.IX Item "$snapshot = $dom->create_snapshot($xml[, $flags])"
Create a new snapshot from the \f(CW$xml\fR.
.RS 4
.IP "type" 4
.IX Item "type"
The type of job, one of the \s-1JOB\s0 \s-1TYPE\s0 constants listed later in
this document.
.IP "timeElapsed" 4
.IX Item "timeElapsed"
The elapsed time in milliseconds
.IP "timeRemaining" 4
.IX Item "timeRemaining"
The expected remaining time in milliseconds. Only set if the
\&\f(CW\*(C`type\*(C'\fR is \s-1JOB_UNBOUNDED\s0.
.IP "dataTotal" 4
.IX Item "dataTotal"
The total amount of data expected to be processed by the job, in bytes.
.IP "dataProcessed" 4
.IX Item "dataProcessed"
The current amount of data processed by the job, in bytes.
.IP "dataRemaining" 4
.IX Item "dataRemaining"
The expected amount of data remaining to be processed by the job, in bytes.
.IP "memTotal" 4
.IX Item "memTotal"
The total amount of mem expected to be processed by the job, in bytes.
.IP "memProcessed" 4
.IX Item "memProcessed"
The current amount of mem processed by the job, in bytes.
.IP "memRemaining" 4
.IX Item "memRemaining"
The expected amount of mem remaining to be processed by the job, in bytes.
.IP "fileTotal" 4
.IX Item "fileTotal"
The total amount of file expected to be processed by the job, in bytes.
.IP "fileProcessed" 4
.IX Item "fileProcessed"
The current amount of file processed by the job, in bytes.
.IP "fileRemaining" 4
.IX Item "fileRemaining"
The expected amount of file remaining to be processed by the job, in bytes.
.RE
.RS 4
.RE
.SH "CONSTANTS"
.IX Header "CONSTANTS"
A number of the APIs take a \f(CW\*(C`flags\*(C'\fR parameter. In most cases
passing a value of zero will be satisfactory. Some APIs, however,
accept named constants to alter their behaviour. This section
documents the current known constants.
.SS "\s-1DOMAIN\s0 \s-1STATE\s0"
.IX Subsection "DOMAIN STATE"
The domain state constants are useful in interpreting the
\&\f(CW\*(C`state\*(C'\fR key in the hash returned by the \f(CW\*(C`get_info\*(C'\fR method.
.IP "Sys::Virt::Domain::STATE_NOSTATE" 4
.IX Item "Sys::Virt::Domain::STATE_NOSTATE"
The domain is active, but is not running / blocked (eg idle)
.IP "Sys::Virt::Domain::STATE_RUNNING" 4
.IX Item "Sys::Virt::Domain::STATE_RUNNING"
The domain is active and running
.IP "Sys::Virt::Domain::STATE_BLOCKED" 4
.IX Item "Sys::Virt::Domain::STATE_BLOCKED"
The domain is active, but execution is blocked
.IP "Sys::Virt::Domain::STATE_PAUSED" 4
.IX Item "Sys::Virt::Domain::STATE_PAUSED"
The domain is active, but execution has been paused
.IP "Sys::Virt::Domain::STATE_SHUTDOWN" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTDOWN"
The domain is active, but in the shutdown phase
.IP "Sys::Virt::Domain::STATE_SHUTOFF" 4
.IX Item "Sys::Virt::Domain::STATE_SHUTOFF"
The domain is inactive, and shut down.
.IP "Sys::Virt::Domain::STATE_CRASHED" 4
.IX Item "Sys::Virt::Domain::STATE_CRASHED"
The domain is inactive, and crashed.
.IP "Sys::Virt::Domain::STATE_PMSUSPENDED" 4
.IX Item "Sys::Virt::Domain::STATE_PMSUSPENDED"
The domain is active, but in power management suspend state
.SS "\s-1CONTROL\s0 \s-1INFO\s0"
.IX Subsection "CONTROL INFO"
The following constants can be used to determine what the
guest domain control channel status is
.IP "Sys::Virt::Domain::CONTROL_ERROR" 4
.IX Item "Sys::Virt::Domain::CONTROL_ERROR"
The control channel has a fatal error
.IP "Sys::Virt::Domain::CONTROL_OK" 4
.IX Item "Sys::Virt::Domain::CONTROL_OK"
The control channel is ready for jobs
.IP "Sys::Virt::Domain::CONTROL_OCCUPIED" 4
.IX Item "Sys::Virt::Domain::CONTROL_OCCUPIED"
The control channel is busy
.IP "Sys::Virt::Domain::CONTROL_JOB" 4
.IX Item "Sys::Virt::Domain::CONTROL_JOB"
The control channel is busy with a job
.SS "\s-1DOMAIN\s0 \s-1CREATION\s0"
.IX Subsection "DOMAIN CREATION"
The following constants can be used to control the behaviour
of domain creation
.IP "Sys::Virt::Domain::START_PAUSED" 4
.IX Item "Sys::Virt::Domain::START_PAUSED"
Keep the guest vCPUs paused after starting the guest
.IP "Sys::Virt::Domain::START_AUTODESTROY" 4
.IX Item "Sys::Virt::Domain::START_AUTODESTROY"
Automatically destroy the guest when the connection is closed (or fails)
.IP "Sys::Virt::Domain::START_BYPASS_CACHE" 4
.IX Item "Sys::Virt::Domain::START_BYPASS_CACHE"
Do not use \s-1OS\s0 I/O cache if starting a domain with a saved state image
.IP "Sys::Virt::Domain::START_FORCE_BOOT" 4
.IX Item "Sys::Virt::Domain::START_FORCE_BOOT"
Boot the guest, even if there was a saved snapshot
.SS "\s-1KEYCODE\s0 \s-1SETS\s0"
.IX Subsection "KEYCODE SETS"
The following constants define the set of supported keycode
sets
.IP "Sys::Virt::Domain::KEYCODE_SET_LINUX" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_LINUX"
The Linux event subsystem keycodes
.IP "Sys::Virt::Domain::KEYCODE_SET_XT" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_XT"
The original \s-1XT\s0 keycodes
.IP "Sys::Virt::Domain::KEYCODE_SET_ATSET1" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_ATSET1"
The \s-1AT\s0 Set1 keycodes (aka \s-1XT\s0)
.IP "Sys::Virt::Domain::KEYCODE_SET_ATSET2" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_ATSET2"
The \s-1AT\s0 Set2 keycodes (aka \s-1AT\s0)
.IP "Sys::Virt::Domain::KEYCODE_SET_ATSET3" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_ATSET3"
The \s-1AT\s0 Set3 keycodes (aka \s-1PS2\s0)
.IP "Sys::Virt::Domain::KEYCODE_SET_OSX" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_OSX"
The OS-X keycodes
.IP "Sys::Virt::Domain::KEYCODE_SET_XT_KBD" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_XT_KBD"
The \s-1XT\s0 keycodes from the Linux Keyboard driver
.IP "Sys::Virt::Domain::KEYCODE_SET_USB" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_USB"
The \s-1USB\s0 \s-1HID\s0 keycode set
.IP "Sys::Virt::Domain::KEYCODE_SET_WIN32" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_WIN32"
The Windows keycode set
.IP "Sys::Virt::Domain::KEYCODE_SET_RFB" 4
.IX Item "Sys::Virt::Domain::KEYCODE_SET_RFB"
The \s-1XT\s0 keycode set, with the extended scancodes using the
high bit of the first byte, instead of the low bit of the
second byte.
.SS "\s-1MEMORY\s0 \s-1PEEK\s0"
.IX Subsection "MEMORY PEEK"
The following constants can be used with the \f(CW\*(C`memory_peek\*(C'\fR
method's flags parameter
.IP "Sys::Virt::Domain::MEMORY_VIRTUAL" 4
.IX Item "Sys::Virt::Domain::MEMORY_VIRTUAL"
Indicates that the offset is using virtual memory addressing.
.IP "Sys::Virt::Domain::MEMORY_PHYSICAL" 4
.IX Item "Sys::Virt::Domain::MEMORY_PHYSICAL"
Indicates that the offset is using physical memory addressing.
.SS "\s-1VCPU\s0 \s-1STATE\s0"
.IX Subsection "VCPU STATE"
The following constants are useful when interpreting the
virtual \s-1CPU\s0 run state
.IP "Sys::Virt::Domain::VCPU_OFFLINE" 4
.IX Item "Sys::Virt::Domain::VCPU_OFFLINE"
The virtual \s-1CPU\s0 is not online
.IP "Sys::Virt::Domain::VCPU_RUNNING" 4
.IX Item "Sys::Virt::Domain::VCPU_RUNNING"
The virtual \s-1CPU\s0 is executing code
.IP "Sys::Virt::Domain::VCPU_BLOCKED" 4
.IX Item "Sys::Virt::Domain::VCPU_BLOCKED"
The virtual \s-1CPU\s0 is waiting to be scheduled
.SS "\s-1OPEN\s0 \s-1GRAPHICS\s0 \s-1CONSTANTS\s0"
.IX Subsection "OPEN GRAPHICS CONSTANTS"
The following constants are used when opening a connection
to the guest graphics server
.IP "Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH" 4
.IX Item "Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH"
Skip authentication of the client
.SS "\s-1OPEN\s0 \s-1CONSOLE\s0 \s-1CONSTANTS\s0"
.IX Subsection "OPEN CONSOLE CONSTANTS"
The following constants are used when opening a connection
to the guest console
.IP "Sys::Virt::Domain::OPEN_CONSOLE_FORCE" 4
.IX Item "Sys::Virt::Domain::OPEN_CONSOLE_FORCE"
Force opening of the console, disconnecting any other
open session
.IP "Sys::Virt::Domain::OPEN_CONSOLE_SAFE" 4
.IX Item "Sys::Virt::Domain::OPEN_CONSOLE_SAFE"
Check if the console driver supports safe operations
.SS "\s-1XML\s0 \s-1DUMP\s0 \s-1OPTIONS\s0"
.IX Subsection "XML DUMP OPTIONS"
The following constants are used to control the information
included in the \s-1XML\s0 configuration dump
.IP "Sys::Virt::Domain::XML_INACTIVE" 4
.IX Item "Sys::Virt::Domain::XML_INACTIVE"
Report the persistent inactive configuration for the guest, even
if it is currently running.
.IP "Sys::Virt::Domain::XML_SECURE" 4
.IX Item "Sys::Virt::Domain::XML_SECURE"
Include security sensitive information in the \s-1XML\s0 dump, such as
passwords.
.IP "Sys::Virt::Domain::XML_UPDATE_CPU" 4
.IX Item "Sys::Virt::Domain::XML_UPDATE_CPU"
Update the \s-1CPU\s0 model definition to match the current executing
state.
.SS "\s-1DEVICE\s0 \s-1HOTPLUG\s0 \s-1OPTIONS\s0"
.IX Subsection "DEVICE HOTPLUG OPTIONS"
The following constants are used to control device hotplug
operations
.IP "Sys::Virt::Domain::DEVICE_MODIFY_CURRENT" 4
.IX Item "Sys::Virt::Domain::DEVICE_MODIFY_CURRENT"
Modify the domain in its current state
.IP "Sys::Virt::Domain::DEVICE_MODIFY_LIVE" 4
.IX Item "Sys::Virt::Domain::DEVICE_MODIFY_LIVE"
Modify only the live state of the domain
.IP "Sys::Virt::Domain::DEVICE_MODIFY_CONFIG" 4
.IX Item "Sys::Virt::Domain::DEVICE_MODIFY_CONFIG"
Modify only the persistent config of the domain
.IP "Sys::Virt::Domain::DEVICE_MODIFY_FORCE" 4
.IX Item "Sys::Virt::Domain::DEVICE_MODIFY_FORCE"
Force the device to be modified
.SS "\s-1MEMORY\s0 \s-1OPTIONS\s0"
.IX Subsection "MEMORY OPTIONS"
The following constants are used to control memory change
operations
.IP "Sys::Virt::Domain::MEM_CURRENT" 4
.IX Item "Sys::Virt::Domain::MEM_CURRENT"
Modify the current state
.IP "Sys::Virt::Domain::MEM_LIVE" 4
.IX Item "Sys::Virt::Domain::MEM_LIVE"
Modify only the live state of the domain
.IP "Sys::Virt::Domain::MEM_CONFIG" 4
.IX Item "Sys::Virt::Domain::MEM_CONFIG"
Modify only the persistent config of the domain
.IP "Sys::Virt::Domain::MEM_MAXIMUM" 4
.IX Item "Sys::Virt::Domain::MEM_MAXIMUM"
Modify the maximum memory value
.SS "\s-1CONFIG\s0 \s-1OPTIONS\s0"
.IX Subsection "CONFIG OPTIONS"
The following constants are used to control what configuration
a domain update changes
.IP "Sys::Virt::Domain::AFFECT_CURRENT" 4
.IX Item "Sys::Virt::Domain::AFFECT_CURRENT"
Modify the current state
.IP "Sys::Virt::Domain::AFFECT_LIVE" 4
.IX Item "Sys::Virt::Domain::AFFECT_LIVE"
Modify only the live state of the domain
.IP "Sys::Virt::Domain::AFFECT_CONFIG" 4
.IX Item "Sys::Virt::Domain::AFFECT_CONFIG"
Modify only the persistent config of the domain
.SS "\s-1MIGRATE\s0 \s-1OPTIONS\s0"
.IX Subsection "MIGRATE OPTIONS"
The following constants are used to control how migration
is performed
.IP "Sys::Virt::Domain::MIGRATE_LIVE" 4
.IX Item "Sys::Virt::Domain::MIGRATE_LIVE"
Migrate the guest without interrupting its execution on the source
host.
.IP "Sys::Virt::Domain::MIGRATE_PEER2PEER" 4
.IX Item "Sys::Virt::Domain::MIGRATE_PEER2PEER"
Manage the migration process over a direct peer\-2\-peer connection between
the source and destination host libvirtd daemons.
.IP "Sys::Virt::Domain::MIGRATE_TUNNELLED" 4
.IX Item "Sys::Virt::Domain::MIGRATE_TUNNELLED"
Tunnel the migration data over the libvirt daemon connection, rather
than the native hypervisor data transport. Requires \s-1PEER2PEER\s0 flag to
be set.
.IP "Sys::Virt::Domain::MIGRATE_PERSIST_DEST" 4
.IX Item "Sys::Virt::Domain::MIGRATE_PERSIST_DEST"
Make the domain persistent on the destination host, defining its
configuration file upon completion of migration.
.IP "Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE" 4
.IX Item "Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE"
Remove the domain's persistent configuration after migration
completes successfully.
.IP "Sys::Virt::Domain::MIGRATE_PAUSED" 4
.IX Item "Sys::Virt::Domain::MIGRATE_PAUSED"
Do not re-start execution of the guest CPUs on the destination
host after migration completes.
.IP "Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK" 4
.IX Item "Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK"
Copy the complete contents of the disk images during migration
.IP "Sys::Virt::Domain::MIGRATE_NON_SHARED_INC" 4
.IX Item "Sys::Virt::Domain::MIGRATE_NON_SHARED_INC"
Copy the incrementally changed contents of the disk images
during migration
.IP "Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION" 4
.IX Item "Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION"
Do not allow changes to the virtual domain configuration while
migration is taking place. This option is automatically implied
if doing a peer\-2\-peer migration.
.IP "Sys::Virt::Domain::MIGRATE_UNSAFE" 4
.IX Item "Sys::Virt::Domain::MIGRATE_UNSAFE"
Migrate even if the compatibility check indicates the migration
will be unsafe to the guest.
.SS "\s-1UNDEFINE\s0 \s-1CONSTANTS\s0"
.IX Subsection "UNDEFINE CONSTANTS"
The following constants can be used when undefining virtual
domain configurations
.IP "Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE" 4
.IX Item "Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE"
Also remove any managed save image when undefining the virtual
domain
.IP "Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA" 4
.IX Item "Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA"
Also remove any snapshot metadata when undefining the virtual
domain.
.SS "\s-1JOB\s0 \s-1TYPES\s0"
.IX Subsection "JOB TYPES"
The following constants describe the different background job
types.
.IP "Sys::Virt::Domain::JOB_NONE" 4
.IX Item "Sys::Virt::Domain::JOB_NONE"
No job is active
.IP "Sys::Virt::Domain::JOB_BOUNDED" 4
.IX Item "Sys::Virt::Domain::JOB_BOUNDED"
A job with a finite completion time is active
.IP "Sys::Virt::Domain::JOB_UNBOUNDED" 4
.IX Item "Sys::Virt::Domain::JOB_UNBOUNDED"
A job with an unbounded completion time is active
.IP "Sys::Virt::Domain::JOB_COMPLETED" 4
.IX Item "Sys::Virt::Domain::JOB_COMPLETED"
The job has finished, but isn't cleaned up
.IP "Sys::Virt::Domain::JOB_FAILED" 4
.IX Item "Sys::Virt::Domain::JOB_FAILED"
The job has hit an error, but isn't cleaned up
.IP "Sys::Virt::Domain::JOB_CANCELLED" 4
.IX Item "Sys::Virt::Domain::JOB_CANCELLED"
The job was aborted at user request, but isn't cleaned up
.SS "\s-1MEMORY\s0 \s-1PARAMETERS\s0"
.IX Subsection "MEMORY PARAMETERS"
The following constants are useful when getting/setting
memory parameters for guests
.IP "Sys::Virt::Domain::MEMORY_HARD_LIMIT" 4
.IX Item "Sys::Virt::Domain::MEMORY_HARD_LIMIT"
The maximum memory the guest can use.
.IP "Sys::Virt::Domain::MEMORY_SOFT_LIMIT" 4
.IX Item "Sys::Virt::Domain::MEMORY_SOFT_LIMIT"
The memory upper limit enforced during memory contention.
.IP "Sys::Virt::Domain::MEMORY_MIN_GUARANTEE" 4
.IX Item "Sys::Virt::Domain::MEMORY_MIN_GUARANTEE"
The minimum memory guaranteed to be reserved for the guest.
.IP "Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT" 4
.IX Item "Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT"
The maximum swap the guest can use.
.IP "Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED" 4
.IX Item "Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED"
The value of an unlimited memory parameter
.SS "\s-1BLKIO\s0 \s-1PARAMETERS\s0"
.IX Subsection "BLKIO PARAMETERS"
The following parameters control I/O tuning for the domain
as a whole
.IP "Sys::Virt::Domain::BLKIO_WEIGHT" 4
.IX Item "Sys::Virt::Domain::BLKIO_WEIGHT"
The I/O weight parameter
.IP "Sys::Virt::Domain::BLKIO_DEVICE_WEIGHT" 4
.IX Item "Sys::Virt::Domain::BLKIO_DEVICE_WEIGHT"
The per-device I/O weight parameter
.SS "\s-1BLKIO\s0 \s-1TUNING\s0 \s-1PARAMETERS\s0"
.IX Subsection "BLKIO TUNING PARAMETERS"
The following parameters control I/O tuning for an individual
guest disk.
.IP "Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC" 4
.IX Item "Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC"
The total bytes processed per second.
.IP "Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC" 4
.IX Item "Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC"
The bytes read per second.
.IP "Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC" 4
.IX Item "Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC"
The bytes written per second.
.IP "Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC" 4
.IX Item "Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC"
The total I/O operations processed per second.
.IP "Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC" 4
.IX Item "Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC"
The I/O operations read per second.
.IP "Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC" 4
.IX Item "Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC"
The I/O operations written per second.
.SS "\s-1SCHEDULER\s0 \s-1CONSTANTS\s0"
.IX Subsection "SCHEDULER CONSTANTS"
.IP "Sys::Virt::Domain::SCHEDULER_CAP" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_CAP"
The \s-1VM\s0 cap tunable
.IP "Sys::Virt::Domain::SCHEDULER_CPU_SHARES" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_CPU_SHARES"
The \s-1CPU\s0 shares tunable
.IP "Sys::Virt::Domain::SCHEDULER_LIMIT" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_LIMIT"
The \s-1VM\s0 limit tunable
.IP "Sys::Virt::Domain::SCHEDULER_RESERVATION" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_RESERVATION"
The \s-1VM\s0 reservation tunable
.IP "Sys::Virt::Domain::SCHEDULER_SHARES" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_SHARES"
The \s-1VM\s0 shares tunable
.IP "Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD"
The \s-1VCPU\s0 period tunable
.IP "Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA"
The \s-1VCPU\s0 quota tunable
.IP "Sys::Virt::Domain::SCHEDULER_WEIGHT" 4
.IX Item "Sys::Virt::Domain::SCHEDULER_WEIGHT"
The \s-1VM\s0 weight tunable
.SS "\s-1NUMA\s0 \s-1PARAMETERS\s0"
.IX Subsection "NUMA PARAMETERS"
The following constants are useful when getting/setting the
guest \s-1NUMA\s0 memory policy
.IP "Sys::Virt::Domain::NUMA_MODE" 4
.IX Item "Sys::Virt::Domain::NUMA_MODE"
The \s-1NUMA\s0 policy mode
.IP "Sys::Virt::Domain::NUMA_NODESET" 4
.IX Item "Sys::Virt::Domain::NUMA_NODESET"
The \s-1NUMA\s0 nodeset mask
.PP
The following constants are useful when interpreting the
\&\f(CW\*(C`Sys::Virt::Domain::NUMA_MODE\*(C'\fR parameter value
.IP "Sys::Virt::Domain::NUMATUNE_MEM_STRICT" 4
.IX Item "Sys::Virt::Domain::NUMATUNE_MEM_STRICT"
Allocation is mandatory from the mask nodes
.IP "Sys::Virt::Domain::NUMATUNE_MEM_PREFERRED" 4
.IX Item "Sys::Virt::Domain::NUMATUNE_MEM_PREFERRED"
Allocation is preferred from the masked nodes
.IP "Sys::Virt::Domain::NUMATUNE_MEM_INTERLEAVE" 4
.IX Item "Sys::Virt::Domain::NUMATUNE_MEM_INTERLEAVE"
Allocation is interleaved across all masked nods
.SS "\s-1INTERFACE\s0 \s-1PARAMETERS\s0"
.IX Subsection "INTERFACE PARAMETERS"
The following constants are useful when getting/setting the
per network interface tunable parameters
.IP "Sys::Virt::Domain::BANDWIDTH_IN_AVERAGE" 4
.IX Item "Sys::Virt::Domain::BANDWIDTH_IN_AVERAGE"
The average inbound bandwidth
.IP "Sys::Virt::Domain::BANDWIDTH_IN_PEAK" 4
.IX Item "Sys::Virt::Domain::BANDWIDTH_IN_PEAK"
The peak inbound bandwidth
.IP "Sys::Virt::Domain::BANDWIDTH_IN_BURST" 4
.IX Item "Sys::Virt::Domain::BANDWIDTH_IN_BURST"
The burstable inbound bandwidth
.IP "Sys::Virt::Domain::BANDWIDTH_OUT_AVERAGE" 4
.IX Item "Sys::Virt::Domain::BANDWIDTH_OUT_AVERAGE"
The average outbound bandwidth
.IP "Sys::Virt::Domain::BANDWIDTH_OUT_PEAK" 4
.IX Item "Sys::Virt::Domain::BANDWIDTH_OUT_PEAK"
The peak outbound bandwidth
.IP "Sys::Virt::Domain::BANDWIDTH_OUT_BURST" 4
.IX Item "Sys::Virt::Domain::BANDWIDTH_OUT_BURST"
The burstable outbound bandwidth
.SS "\s-1VCPU\s0 \s-1FLAGS\s0"
.IX Subsection "VCPU FLAGS"
The following constants are useful when getting/setting the
\&\s-1VCPU\s0 count for a guest
.IP "Sys::Virt::Domain::VCPU_LIVE" 4
.IX Item "Sys::Virt::Domain::VCPU_LIVE"
Flag to request the live value
.IP "Sys::Virt::Domain::VCPU_CONFIG" 4
.IX Item "Sys::Virt::Domain::VCPU_CONFIG"
Flag to request the persistent config value
.IP "Sys::Virt::Domain::VCPU_CURRENT" 4
.IX Item "Sys::Virt::Domain::VCPU_CURRENT"
Flag to request the current config value
.IP "Sys::Virt::Domain::VCPU_MAXIMUM" 4
.IX Item "Sys::Virt::Domain::VCPU_MAXIMUM"
Flag to request adjustment of the maximum vCPU value
.SS "\s-1STATE\s0 \s-1CHANGE\s0 \s-1EVENTS\s0"
.IX Subsection "STATE CHANGE EVENTS"
The following constants allow domain state change events to be
interpreted. The events contain both a state change, and a
reason.
.IP "Sys::Virt::Domain::EVENT_DEFINED" 4
.IX Item "Sys::Virt::Domain::EVENT_DEFINED"
Indicates that a persistent configuration has been defined for
the domain.
.RS 4
.IP "Sys::Virt::Domain::EVENT_DEFINED_ADDED" 4
.IX Item "Sys::Virt::Domain::EVENT_DEFINED_ADDED"
The defined configuration is newly added
.IP "Sys::Virt::Domain::EVENT_DEFINED_UPDATED" 4
.IX Item "Sys::Virt::Domain::EVENT_DEFINED_UPDATED"
The defined configuration is an update to an existing configuration
.RE
.RS 4
.RE
.IP "Sys::Virt::Domain::EVENT_RESUMED" 4
.IX Item "Sys::Virt::Domain::EVENT_RESUMED"
The domain has resumed execution
.RS 4
.IP "Sys::Virt::Domain::EVENT_RESUMED_MIGRATED" 4
.IX Item "Sys::Virt::Domain::EVENT_RESUMED_MIGRATED"
The domain resumed because migration has completed. This is
emitted on the destination host.
.IP "Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED" 4
.IX Item "Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED"
The domain resumed because the admin unpaused it.
.IP "Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT" 4
.IX Item "Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT"
The domain resumed because it was restored from a snapshot
.RE
.RS 4
.RE
.IP "Sys::Virt::Domain::EVENT_STARTED" 4
.IX Item "Sys::Virt::Domain::EVENT_STARTED"
The domain has started running
.RS 4
.IP "Sys::Virt::Domain::EVENT_STARTED_BOOTED" 4
.IX Item "Sys::Virt::Domain::EVENT_STARTED_BOOTED"
The domain was booted from shutoff state
.IP "Sys::Virt::Domain::EVENT_STARTED_MIGRATED" 4
.IX Item "Sys::Virt::Domain::EVENT_STARTED_MIGRATED"
The domain started due to an incoming migration
.IP "Sys::Virt::Domain::EVENT_STARTED_RESTORED" 4
.IX Item "Sys::Virt::Domain::EVENT_STARTED_RESTORED"
The domain was restored from saved state file
.IP "Sys::Virt::Domain::EVENT_STARTED_FROM_SNAPSHOT" 4
.IX Item "Sys::Virt::Domain::EVENT_STARTED_FROM_SNAPSHOT"
The domain was restored from a snapshot
.IP "Sys::Virt::Domain::EVENT_STARTED_WAKEUP" 4
.IX Item "Sys::Virt::Domain::EVENT_STARTED_WAKEUP"
The domain was woken up from suspend
.RE
.RS 4
.RE
.IP "Sys::Virt::Domain::EVENT_STOPPED" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED"
The domain has stopped running
.RS 4
.IP "Sys::Virt::Domain::EVENT_STOPPED_CRASHED" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED_CRASHED"
The domain stopped because guest operating system has crashed
.IP "Sys::Virt::Domain::EVENT_STOPPED_DESTROYED" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED_DESTROYED"
The domain stopped because administrator issued a destroy
command.
.IP "Sys::Virt::Domain::EVENT_STOPPED_FAILED" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED_FAILED"
The domain stopped because of a fault in the host virtualization
environment.
.IP "Sys::Virt::Domain::EVENT_STOPPED_MIGRATED" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED_MIGRATED"
The domain stopped because it was migrated to another machine.
.IP "Sys::Virt::Domain::EVENT_STOPPED_SAVED" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED_SAVED"
The domain was saved to a state file
.IP "Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN"
The domain stopped due to graceful shutdown of the guest.
.IP "Sys::Virt::Domain::EVENT_STOPPED_FROM_SNAPSHOT" 4
.IX Item "Sys::Virt::Domain::EVENT_STOPPED_FROM_SNAPSHOT"
The domain was stopped due to a snapshot
.RE
.RS 4
.RE
.IP "Sys::Virt::Domain::EVENT_SHUTDOWN" 4
.IX Item "Sys::Virt::Domain::EVENT_SHUTDOWN"
The domain has shutdown but is not yet stopped
.RS 4
.IP "Sys::Virt::Domain::EVENT_SHUTDOWN_FINISHED" 4
.IX Item "Sys::Virt::Domain::EVENT_SHUTDOWN_FINISHED"
The domain finished shutting down
.RE
.RS 4
.RE
.IP "Sys::Virt::Domain::EVENT_SUSPENDED" 4
.IX Item "Sys::Virt::Domain::EVENT_SUSPENDED"
The domain has stopped executing, but still exists
.RS 4
.IP "Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED" 4
.IX Item "Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED"
The domain has been suspended due to offline migration
.IP "Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED" 4
.IX Item "Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED"
The domain has been suspended due to administrator pause
request.
.IP "Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR" 4
.IX Item "Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR"
The domain has been suspended due to a block device I/O
error.
.IP "Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT" 4
.IX Item "Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT"
The domain has been suspended due to resume from snapshot
.IP "Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG" 4
.IX Item "Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG"
The domain has been suspended due to the watchdog triggering
.IP "Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED" 4
.IX Item "Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED"
The domain has been suspended due to restore from saved state
.RE
.RS 4
.RE
.IP "Sys::Virt::Domain::EVENT_UNDEFINED" 4
.IX Item "Sys::Virt::Domain::EVENT_UNDEFINED"
The persistent configuration has gone away
.RS 4
.IP "Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED" 4
.IX Item "Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED"
The domain configuration has gone away due to it being
removed by administrator.
.RE
.RS 4
.RE
.IP "Sys::Virt::Domain::EVENT_PMSUSPENDED" 4
.IX Item "Sys::Virt::Domain::EVENT_PMSUSPENDED"
The domain has stopped running
.RS 4
.IP "Sys::Virt::Domain::EVENT_PMSUSPENDED_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::EVENT_PMSUSPENDED_UNKNOWN"
The domain has suspend for an unknown reason
.RE
.RS 4
.RE
.SS "\s-1EVENT\s0 \s-1ID\s0 \s-1CONSTANTS\s0"
.IX Subsection "EVENT ID CONSTANTS"
.IP "Sys::Virt::Domain::EVENT_ID_LIFECYCLE" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_LIFECYCLE"
Domain lifecycle events
.IP "Sys::Virt::Domain::EVENT_ID_REBOOT" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_REBOOT"
Soft / warm reboot events
.IP "Sys::Virt::Domain::EVENT_ID_RTC_CHANGE" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_RTC_CHANGE"
\&\s-1RTC\s0 clock adjustments
.IP "Sys::Virt::Domain::EVENT_ID_IO_ERROR" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_IO_ERROR"
File \s-1IO\s0 errors, typically from disks
.IP "Sys::Virt::Domain::EVENT_ID_WATCHDOG" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_WATCHDOG"
Watchdog device triggering
.IP "Sys::Virt::Domain::EVENT_ID_GRAPHICS" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_GRAPHICS"
Graphics client connections.
.IP "Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON"
File \s-1IO\s0 errors, typically from disks, with a root cause
.IP "Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR"
Errors from the virtualization control channel
.IP "Sys::Virt::Domain::EVENT_ID_BLOCK_JOB" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_BLOCK_JOB"
Completion status of asynchronous block jobs
.IP "Sys::Virt::Domain::EVENT_ID_DISK_CHANGE" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_DISK_CHANGE"
Changes in disk media
.IP "Sys::Virt::Domain::EVENT_ID_TRAY_CHANGE" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_TRAY_CHANGE"
\&\s-1CDROM\s0 media tray state
.IP "Sys::Virt::Domain::EVENT_ID_PMSUSPEND" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_PMSUSPEND"
Power management initiated suspend
.IP "Sys::Virt::Domain::EVENT_ID_PMWAKEUP" 4
.IX Item "Sys::Virt::Domain::EVENT_ID_PMWAKEUP"
Power management initiated wakeup
.SS "\s-1IO\s0 \s-1ERROR\s0 \s-1EVENT\s0 \s-1CONSTANTS\s0"
.IX Subsection "IO ERROR EVENT CONSTANTS"
These constants describe what action was taken due to the
\&\s-1IO\s0 error.
.IP "Sys::Virt::Domain::EVENT_IO_ERROR_NONE" 4
.IX Item "Sys::Virt::Domain::EVENT_IO_ERROR_NONE"
No action was taken, the error was ignored & reported as success to guest
.IP "Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE" 4
.IX Item "Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE"
The guest is paused since the error occurred
.IP "Sys::Virt::Domain::EVENT_IO_ERROR_REPORT" 4
.IX Item "Sys::Virt::Domain::EVENT_IO_ERROR_REPORT"
The error has been reported to the guest \s-1OS\s0
.SS "\s-1WATCHDOG\s0 \s-1EVENT\s0 \s-1CONSTANTS\s0"
.IX Subsection "WATCHDOG EVENT CONSTANTS"
These constants describe what action was taken due to the
watchdog firing
.IP "Sys::Virt::Domain::EVENT_WATCHDOG_NONE" 4
.IX Item "Sys::Virt::Domain::EVENT_WATCHDOG_NONE"
No action was taken, the watchdog was ignored
.IP "Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE" 4
.IX Item "Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE"
The guest is paused since the watchdog fired
.IP "Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF" 4
.IX Item "Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF"
The guest is powered off after the watchdog fired
.IP "Sys::Virt::Domain::EVENT_WATCHDOG_RESET" 4
.IX Item "Sys::Virt::Domain::EVENT_WATCHDOG_RESET"
The guest is reset after the watchdog fired
.IP "Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN" 4
.IX Item "Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN"
The guest attempted to gracefully shutdown after the watchdog fired
.IP "Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG" 4
.IX Item "Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG"
No action was taken, the watchdog was logged
.SS "\s-1GRAPHICS\s0 \s-1EVENT\s0 \s-1PHASE\s0 \s-1CONSTANTS\s0"
.IX Subsection "GRAPHICS EVENT PHASE CONSTANTS"
These constants describe the phase of the graphics connection
.IP "Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT" 4
.IX Item "Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT"
The initial client connection
.IP "Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE" 4
.IX Item "Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE"
The client has been authenticated & the connection is running
.IP "Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT" 4
.IX Item "Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT"
The client has disconnected
.SS "\s-1GRAPHICS\s0 \s-1EVENT\s0 \s-1ADDRESS\s0 \s-1CONSTANTS\s0"
.IX Subsection "GRAPHICS EVENT ADDRESS CONSTANTS"
These constants describe the format of the address
.IP "Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4" 4
.IX Item "Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4"
An IPv4 address
.IP "Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6" 4
.IX Item "Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6"
An IPv6 address
.IP "Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX" 4
.IX Item "Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX"
An \s-1UNIX\s0 socket path address
.SS "\s-1DISK\s0 \s-1CHANGE\s0 \s-1EVENT\s0 \s-1CONSTANTS\s0"
.IX Subsection "DISK CHANGE EVENT CONSTANTS"
These constants describe the reason for a disk change event
.IP "Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START" 4
.IX Item "Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START"
The disk media was missing when attempting to start the guest
.SS "\s-1TRAY\s0 \s-1CHANGE\s0 \s-1CONSTANTS\s0"
.IX Subsection "TRAY CHANGE CONSTANTS"
These constants describe the reason for a tray change event
.IP "Sys::Virt::Domain::EVENT_TRAY_CHANGE_CLOSE" 4
.IX Item "Sys::Virt::Domain::EVENT_TRAY_CHANGE_CLOSE"
The tray was closed
.IP "Sys::Virt::Domain::EVENT_TRAY_CHANGE_OPEN" 4
.IX Item "Sys::Virt::Domain::EVENT_TRAY_CHANGE_OPEN"
The tray was opened
.SS "\s-1DOMAIN\s0 \s-1BLOCK\s0 \s-1JOB\s0 \s-1TYPE\s0 \s-1CONSTANTS\s0"
.IX Subsection "DOMAIN BLOCK JOB TYPE CONSTANTS"
The following constants identify the different types of domain
block jobs
.IP "Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN"
An unknown block job type
.IP "Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL"
The block pull job type
.IP "Sys::Virt::Domain::BLOCK_JOB_TYPE_COPY" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_TYPE_COPY"
The block copy job type
.SS "\s-1DOMAIN\s0 \s-1BLOCK\s0 \s-1JOB\s0 \s-1COMPLETION\s0 \s-1CONSTANTS\s0"
.IX Subsection "DOMAIN BLOCK JOB COMPLETION CONSTANTS"
The following constants can be used to determine the completion
status of a block job
.IP "Sys::Virt::Domain::BLOCK_JOB_COMPLETED" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_COMPLETED"
A successfully completed block job
.IP "Sys::Virt::Domain::BLOCK_JOB_FAILED" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_FAILED"
An unsuccessful block job
.IP "Sys::Virt::Domain::BLOCK_JOB_CANCELED" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_CANCELED"
A block job canceled byy the user
.SS "\s-1DOMAIN\s0 \s-1BLOCK\s0 \s-1REBASE\s0 \s-1CONSTANTS\s0"
.IX Subsection "DOMAIN BLOCK REBASE CONSTANTS"
The following constants are useful when rebasing block devices
.IP "Sys::Virt::Domain::BLOCK_REBASE_SHALLOW" 4
.IX Item "Sys::Virt::Domain::BLOCK_REBASE_SHALLOW"
Limit copy to top of source backing chain
.IP "Sys::Virt::Domain::BLOCK_REBASE_REUSE_EXT" 4
.IX Item "Sys::Virt::Domain::BLOCK_REBASE_REUSE_EXT"
Reuse existing external file for copy
.IP "Sys::Virt::Domain::BLOCK_REBASE_COPY_RAW" 4
.IX Item "Sys::Virt::Domain::BLOCK_REBASE_COPY_RAW"
Make destination file raw
.IP "Sys::Virt::Domain::BLOCK_REBASE_COPY" 4
.IX Item "Sys::Virt::Domain::BLOCK_REBASE_COPY"
Start a copy job
.SS "\s-1DOMAIN\s0 \s-1BLOCK\s0 \s-1JOB\s0 \s-1ABORT\s0 \s-1CONSTANTS\s0"
.IX Subsection "DOMAIN BLOCK JOB ABORT CONSTANTS"
The following constants are useful when aborting job copy jobs
.IP "Sys::Virt::Domain::BLOCK_JOB_ABORT_ASYNC" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_ABORT_ASYNC"
Request only, do not wait for completion
.IP "Sys::Virt::Domain::BLOCK_JOB_ABORT_PIVOT" 4
.IX Item "Sys::Virt::Domain::BLOCK_JOB_ABORT_PIVOT"
Pivot to mirror when ending a copy job
.SS "\s-1DOMAIN\s0 \s-1SAVE\s0 / \s-1RESTORE\s0 \s-1CONSTANTS\s0"
.IX Subsection "DOMAIN SAVE / RESTORE CONSTANTS"
The following constants can be used when saving or restoring
virtual machines
.IP "Sys::Virt::Domain::SAVE_BYPASS_CACHE" 4
.IX Item "Sys::Virt::Domain::SAVE_BYPASS_CACHE"
Do not use \s-1OS\s0 I/O cache when saving state.
.IP "Sys::Virt::Domain::SAVE_PAUSED" 4
.IX Item "Sys::Virt::Domain::SAVE_PAUSED"
Mark the saved state as paused to prevent the guest CPUs
starting upon restore.
.IP "Sys::Virt::Domain::SAVE_RUNNING" 4
.IX Item "Sys::Virt::Domain::SAVE_RUNNING"
Mark the saved state as running to allow the guest CPUs
to start upon restore.
.SS "\s-1DOMAIN\s0 \s-1CORE\s0 \s-1DUMP\s0 \s-1CONSTANTS\s0"
.IX Subsection "DOMAIN CORE DUMP CONSTANTS"
The following constants can be used when triggering domain
core dumps
.IP "Sys::Virt::Domain::DUMP_LIVE" 4
.IX Item "Sys::Virt::Domain::DUMP_LIVE"
Do not pause execution while dumping the guest
.IP "Sys::Virt::Domain::DUMP_CRASH" 4
.IX Item "Sys::Virt::Domain::DUMP_CRASH"
Crash the guest after completing the core dump
.IP "Sys::Virt::Domain::DUMP_BYPASS_CACHE" 4
.IX Item "Sys::Virt::Domain::DUMP_BYPASS_CACHE"
Do not use \s-1OS\s0 I/O cache when writing core dump
.IP "Sys::Virt::Domain::DUMP_RESET" 4
.IX Item "Sys::Virt::Domain::DUMP_RESET"
Reset the virtual machine after finishing the dump
.SS "\s-1DESTROY\s0 \s-1CONSTANTS\s0"
.IX Subsection "DESTROY CONSTANTS"
The following constants are useful when terminating guests
using the \f(CW\*(C`destroy\*(C'\fR \s-1API\s0.
.IP "Sys::Virt::Domain::DESTROY_DEFAULT" 4
.IX Item "Sys::Virt::Domain::DESTROY_DEFAULT"
Destroy the guest using the default approach
.IP "Sys::Virt::Domain::DESTROY_GRACEFUL" 4
.IX Item "Sys::Virt::Domain::DESTROY_GRACEFUL"
Destroy the guest in a graceful manner
.SS "\s-1SHUTDOWN\s0 \s-1CONSTANTS\s0"
.IX Subsection "SHUTDOWN CONSTANTS"
The following constants are useful when requesting that a
guest terminate using the \f(CW\*(C`shutdown\*(C'\fR \s-1API\s0
.IP "Sys::Virt::Domain::SHUTDOWN_DEFAULT" 4
.IX Item "Sys::Virt::Domain::SHUTDOWN_DEFAULT"
Shutdown using the hypervisor's default mechanism
.IP "Sys::Virt::Domain::SHUTDOWN_GUEST_AGENT" 4
.IX Item "Sys::Virt::Domain::SHUTDOWN_GUEST_AGENT"
Shutdown by issuing a command to a guest agent
.IP "Sys::Virt::Domain::SHUTDOWN_ACPI_POWER_BTN" 4
.IX Item "Sys::Virt::Domain::SHUTDOWN_ACPI_POWER_BTN"
Shutdown by injecting an \s-1ACPI\s0 power button press
.SS "\s-1REBOOT\s0 \s-1CONSTANTS\s0"
.IX Subsection "REBOOT CONSTANTS"
The following constants are useful when requesting that a
guest terminate using the \f(CW\*(C`reboot\*(C'\fR \s-1API\s0
.IP "Sys::Virt::Domain::REBOOT_DEFAULT" 4
.IX Item "Sys::Virt::Domain::REBOOT_DEFAULT"
Reboot using the hypervisor's default mechanism
.IP "Sys::Virt::Domain::REBOOT_GUEST_AGENT" 4
.IX Item "Sys::Virt::Domain::REBOOT_GUEST_AGENT"
Reboot by issuing a command to a guest agent
.IP "Sys::Virt::Domain::REBOOT_ACPI_POWER_BTN" 4
.IX Item "Sys::Virt::Domain::REBOOT_ACPI_POWER_BTN"
Reboot by injecting an \s-1ACPI\s0 power button press
.SS "\s-1METADATA\s0 \s-1CONSTANTS\s0"
.IX Subsection "METADATA CONSTANTS"
The following constants are useful when reading/writing
metadata about a guest
.IP "Sys::Virt::Domain::METADATA_TITLE" 4
.IX Item "Sys::Virt::Domain::METADATA_TITLE"
The short human friendly title of the guest
.IP "Sys::Virt::Domain::METADATA_DESCRIPTION" 4
.IX Item "Sys::Virt::Domain::METADATA_DESCRIPTION"
The long free text description of the guest
.IP "Sys::Virt::Domain::METADATA_ELEMENT" 4
.IX Item "Sys::Virt::Domain::METADATA_ELEMENT"
The structured metadata elements for the guest
.SS "\s-1DISK\s0 \s-1ERROR\s0 \s-1CONSTANTS\s0"
.IX Subsection "DISK ERROR CONSTANTS"
The following constants are useful when interpreting
disk error codes
.IP "Sys::Virt::Domain::DISK_ERROR_NONE" 4
.IX Item "Sys::Virt::Domain::DISK_ERROR_NONE"
No error
.IP "Sys::Virt::Domain::DISK_ERROR_NO_SPACE" 4
.IX Item "Sys::Virt::Domain::DISK_ERROR_NO_SPACE"
The host storage has run out of free space
.IP "Sys::Virt::Domain::DISK_ERROR_UNSPEC" 4
.IX Item "Sys::Virt::Domain::DISK_ERROR_UNSPEC"
An unspecified error has ocurred.
.SS "\s-1MEMORY\s0 \s-1STATISTIC\s0 \s-1CONSTANTS\s0"
.IX Subsection "MEMORY STATISTIC CONSTANTS"
.IP "Sys::Virt::Domain::MEMORY_STAT_SWAP_IN" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_SWAP_IN"
Swap in
.IP "Sys::Virt::Domain::MEMORY_STAT_SWAP_OUT" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_SWAP_OUT"
Swap out
.IP "Sys::Virt::Domain::MEMORY_STAT_MINOR_FAULT" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_MINOR_FAULT"
Minor faults
.IP "Sys::Virt::Domain::MEMORY_STAT_MAJOR_FAULT" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_MAJOR_FAULT"
Major faults
.IP "Sys::Virt::Domain::MEMORY_STAT_RSS" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_RSS"
Resident memory
.IP "Sys::Virt::Domain::MEMORY_STAT_UNUSED" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_UNUSED"
Unused memory
.IP "Sys::Virt::Domain::MEMORY_STAT_AVAILABLE" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_AVAILABLE"
Available memory
.IP "Sys::Virt::Domain::MEMORY_STAT_ACTUAL_BALLOON" 4
.IX Item "Sys::Virt::Domain::MEMORY_STAT_ACTUAL_BALLOON"
Actual balloon limit
.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 \s-1GNU\s0 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 \s-1README\s0 file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sys::Virt, Sys::Virt::Error, \f(CW\*(C`http://libvirt.org\*(C'\fR