NAME

Sys::Virt::Domain - Represent & manage a libvirt guest domain

DESCRIPTION

The Sys::Virt::Domain module represents a guest domain managed by the virtual machine monitor.

METHODS

my $id = $dom->get_id()

Returns an integer with a locally unique identifier for the domain.

my $uuid = $dom->get_uuid()

Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the domain.

my $uuid = $dom->get_uuid_string()

Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'.

my $name = $dom->get_name()

Returns a string with a locally unique name of the domain

my $xml = $dom->get_xml_description()

Returns an XML document containing a complete description of the domain's configuration

my $type = $dom->get_os_type()

Returns a string containing the name of the OS type running within the domain.

$dom->create()

Start a domain whose configuration was previously defined using the define_domain method in Sys::Virt.

$dom->undefine()

Remove the configuration associated with a domain previously defined with the define_domain method in Sys::Virt. If the domain is running, you probably want to use the shutdown or destroy methods instead.

$dom->suspend()

Temporarily stop execution of the domain, allowing later continuation by calling the resume method.

$dom->resume()

Resume execution of a domain previously halted with the suspend method.

$dom->save($filename)

Take a snapshot of the domain's state and save the information to the file named in the $filename parameter. The domain can later be restored from this file with the restore_domain method on the Sys::Virt object.

$dom->destroy()

Immediately terminate the machine, and remove it from the virtual machine monitor. The $dom handle is invalid after this call completes and should not be used again.

my $info = $dom->get_info()

Returns a hash reference summarising the execution state of the domain. The elements of the hash are as follows:

maxMem

The maximum memory allowed for this domain, in kilobytes

memory

The current memory allocated to the domain in kilobytes

cpuTime

The amount of CPU time used by the domain

nrVirtCpu

The current number of virtual CPUs enabled in the domain

state

The execution state of the machine, which will be one of the constants &Sys::Virt::Domain::STATE_*.

$dom->set_max_memory($mem)

Set the maximum memory for the domain to the value $mem. The value of the $mem parameter is specified in kilobytes.

$mem = $dom->get_max_memory()

Returns the current maximum memory allowed for this domain in kilobytes.

$dom->set_memory($mem)

Set the current memory for the domain to the value $mem. The value of the $mem parameter is specified in kilobytes. This must be less than, or equal to the domain's max memory limit.

$dom->shutdown()

Request that the guest OS perform a graceful shutdown and poweroff.

$dom->reboot($flags)

Request that the guest OS perform a graceful shutdown and optionally restart. The $flags parameter determines how the domain restarts (if at all). It should be one of the constants &Sys::Virt::Domain::REBOOT_* listed later in this document.

$dom->get_max_vcpus()

Return the maximum number of vcpus that are configured for the domain

CONSTANTS

The first set of constants enumerate the possible machine runtime states, returned by the get_info method.

&Sys::Virt::Domain::STATE_NOSTATE

The domain is active, but is not running / blocked (eg idle)

&Sys::Virt::Domain::STATE_RUNNING

The domain is active and running

&Sys::Virt::Domain::STATE_BLOCKED

The domain is active, but execution is blocked

&Sys::Virt::Domain::STATE_PAUSED

The domain is active, but execution has been paused

&Sys::Virt::Domain::STATE_SHUTDOWN

The domain is active, but in the shutdown phase

&Sys::Virt::Domain::STATE_SHUTOFF

The domain is inactive, and shut down.

&Sys::Virt::Domain::STATE_CRASHED

The domain is inactive, and crashed.

The next set of constants enumerate the different flags which can be passed when requesting a reboot.

&Sys::Virt::Domain::REBOOT_DESTROY

Destroy the domain, rather than restarting the domain

&Sys::Virt::Domain::REBOOT_RESTART

Restart the domain after shutdown is complete

&Sys::Virt::Domain::REBOOT_PRESERVE

Leave the domain inactive after shutdown is complete

&Sys::Virt::Domain::REBOOT_RENAME_RESTART

Restart the domain under a different (automatically generated) name after shutdown is complete

AUTHORS

Daniel P. Berrange <berrange@redhat.com>

COPYRIGHT

Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange

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.

SEE ALSO

Sys::Virt, Sys::Virt::Error, http://libvirt.org