Sys::Virt(3) User Contributed Perl Documentation Sys::Virt(3)NAMESys::Virt - Represent and manage a libvirt hypervisor connection
SYNOPSIS
my $vmm = Sys::Virt->new(address => $addr);
my @domains = $vmm->list_domains();
foreach my $dom (@domains) {
print "Domain ", $dom->get_id, " ", $dom->get_name, "\n";
}
DESCRIPTION
The Sys::Virt module provides a Perl XS binding to the libvirt virtual
machine management APIs. This allows machines running within arbitrary
virtualization containers to be managed with a consistent API.
ERROR HANDLING
Any operations in the Sys::Virt API which have failure scenarios will
result in an instance of the Sys::Virt::Error module being thrown. To
catch these errors, simply wrap the method in an eval block. For
details of the information contained in the error objects, consult the
Sys::Virt::Error manual page.
METHODS
my $vmm = Sys::Virt->new(uri => $uri, readonly => $ro);
Attach to the virtual machine monitor with the address of
"address". The uri parameter may be omitted, in which case the
default connection made will be to the local Xen hypervisor. Some
example URIs include:
xen:///
Xen on the local machine
test:///default
Dummy "in memory" driver for test suites
qemu:///system
System-wide driver for QEMU / KVM virtualization
qemu:///session
Per-user driver for QEMU virtualization
qemu+tls://somehost/system
System-wide QEMU driver on "somehost" using TLS security
xen+tcp://somehost/
Xen driver on "somehost" using TCP / SASL security
For further details consult "http://libvirt.org/uri.html"
If the optional "readonly" parameter is supplied, then an
unprivileged connection to the VMM will be attempted. If it is not
supplied, then it defaults to making a fully privileged connection
to the VMM. If the calling application is not running as root, it
may be necessary to provide authentication callbacks.
If the optional "auth" parameter is set to a non-zero value,
authentication will be enabled during connection, using the default
set of credential gathering callbacks. The default callbacks prompt
for credentials on the console, so are not suitable for graphical
applications. For such apps a custom implementation should be
supplied. The "credlist" parameter should be an array reference
listing the set of credential types that will be supported. The
credential constants in this module can be used as values in this
list. The "callback" parameter should be a subroutine reference
containing the code necessary to gather the credentials. When
invoked it will be supplied with a single parameter, a array
reference of requested credentials. The elements of the array are
hash references, with keys "type" giving the type of credential,
"prompt" giving a user descriptive user prompt, "challenge" giving
name of the credential required. The answer should be collected
from the user, and returned by setting the "result" key. This key
may already be set with a default result if applicable
As a simple example returning hardcoded credentials
my $address = "qemu+tcp://192.168.122.1/system";
my $username = "test";
my $password = "123456";
my $con = Sys::Virt->new(address => $address,
auth => 1,
credlist => [
Sys::Virt::CRED_AUTHNAME,
Sys::Virt::CRED_PASSPHRASE,
],
callback =>
sub {
my $creds = shift;
foreach my $cred (@{$creds}) {
if ($cred->{type} == Sys::Virt::CRED_AUTHNAME) {
$cred->{result} = $username;
}
if ($cred->{type} == Sys::Virt::CRED_PASSPHRASE) {
$cred->{result} = $password;
}
}
return 0;
});
my $st = $vmm->new_stream($flags)
Create a new stream, with the given flags
my $dom = $vmm->create_domain($xml, $flags);
Create a new domain based on the XML description passed into the
$xml parameter. The returned object is an instance of the
Sys::Virt::Domain class. This method is not available with
unprivileged connections to the VMM. The $flags parameter accepts
one of the DOMAIN CREATION constants documented in
Sys::Virt::Domain, and defaults to 0 if omitted.
my $dom = $vmm->define_domain($xml);
Defines, but does not start, a new domain based on the XML
description passed into the $xml parameter. The returned object is
an instance of the Sys::Virt::Domain class. This method is not
available with unprivileged connections to the VMM. The defined
domain can be later started by calling the "create" method on the
returned "Sys::Virt::Domain" object.
my $dom = $vmm->create_network($xml);
Create a new network based on the XML description passed into the
$xml parameter. The returned object is an instance of the
Sys::Virt::Network class. This method is not available with
unprivileged connections to the VMM.
my $dom = $vmm->define_network($xml);
Defines, but does not start, a new network based on the XML
description passed into the $xml parameter. The returned object is
an instance of the Sys::Virt::Network class. This method is not
available with unprivileged connections to the VMM. The defined
network can be later started by calling the "create" method on the
returned "Sys::Virt::Network" object.
my $dom = $vmm->create_storage_pool($xml);
Create a new storage pool based on the XML description passed into
the $xml parameter. The returned object is an instance of the
Sys::Virt::StoragePool class. This method is not available with
unprivileged connections to the VMM.
my $dom = $vmm->define_storage_pool($xml);
Defines, but does not start, a new storage pol based on the XML
description passed into the $xml parameter. The returned object is
an instance of the Sys::Virt::StoragePool class. This method is not
available with unprivileged connections to the VMM. The defined
pool can be later started by calling the "create" method on the
returned "Sys::Virt::StoragePool" object.
my $dom = $vmm->create_interface($xml);
Create a new interface based on the XML description passed into the
$xml parameter. The returned object is an instance of the
Sys::Virt::Interface class. This method is not available with
unprivileged connections to the VMM.
my $dom = $vmm->define_interface($xml);
Defines, but does not start, a new interface based on the XML
description passed into the $xml parameter. The returned object is
an instance of the Sys::Virt::Interface class. This method is not
available with unprivileged connections to the VMM. The defined
interface can be later started by calling the "create" method on
the returned "Sys::Virt::Interface" object.
my $dom = $vmm->create_node_device($xml);
Create a new virtual node device based on the XML description
passed into the $xml parameter. The returned object is an instance
of the Sys::Virt::NodeDevice class. This method is not available
with unprivileged connections to the VMM.
my @doms = $vmm->list_domains()
Return a list of all domains currently known to the VMM. The
elements in the returned list are instances of the
Sys::Virt::Domain class.
my $nids = $vmm->num_of_domains()
Return the number of running domains known to the VMM. This can be
used as the "maxids" parameter to "list_domain_ids".
my @domIDs = $vmm->list_domain_ids($maxids)
Return a list of all domain IDs currently known to the VMM. The IDs
can be used with the "get_domain_by_id" method.
my @doms = $vmm->list_defined_domains()
Return a list of all domains defined, but not currently running, on
the VMM. The elements in the returned list are instances of the
Sys::Virt::Domain class.
my $nnames = $vmm->num_of_defined_domains()
Return the number of running domains known to the VMM. This can be
used as the "maxnames" parameter to "list_defined_domain_names".
my @names = $vmm->list_defined_domain_names($maxnames)
Return a list of names of all domains defined, but not currently
running, on the VMM. The names can be used with the
"get_domain_by_name" method.
my @nets = $vmm->list_networks()
Return a list of all networks currently known to the VMM. The
elements in the returned list are instances of the
Sys::Virt::Network class.
my $nnames = $vmm->num_of_networks()
Return the number of running networks known to the VMM. This can be
used as the "maxids" parameter to "list_network_ids".
my @netNames = $vmm->list_network_names($maxnames)
Return a list of all network names currently known to the VMM. The
names can be used with the "get_network_by_name" method.
my @nets = $vmm->list_defined_networks()
Return a list of all networks defined, but not currently running,
on the VMM. The elements in the returned list are instances of the
Sys::Virt::Network class.
my $nnamess = $vmm->num_of_defined_networks()
Return the number of running networks known to the host. This can
be used as the "maxnames" parameter to
"list_defined_network_names".
my @names = $vmm->list_defined_network_names($maxnames)
Return a list of names of all networks defined, but not currently
running, on the host. The names can be used with the
"get_network_by_name" method.
my @pools = $vmm->list_storage_pools()
Return a list of all storage pools currently known to the host. The
elements in the returned list are instances of the
Sys::Virt::StoragePool class.
my $nnames = $vmm->num_of_storage_pools()
Return the number of running storage pools known to the VMM. This
can be used as the "maxids" parameter to "list_storage_pool_names".
my @poolNames = $vmm->list_storage_pool_names($maxnames)
Return a list of all storage pool names currently known to the VMM.
The IDs can be used with the "get_network_by_id" method.
my @pools = $vmm->list_defined_storage_pools()
Return a list of all storage pools defined, but not currently
running, on the host. The elements in the returned list are
instances of the Sys::Virt::StoragePool class.
my $nnames = $vmm->num_of_defined_storage_pools()
Return the number of running networks known to the host. This can
be used as the "maxnames" parameter to
"list_defined_storage_pool_names".
my @names = $vmm->list_defined_storage_pool_names($maxnames)
Return a list of names of all storage pools defined, but not
currently running, on the host. The names can be used with the
"get_storage_pool_by_name" method.
my @devs = $vmm->list_node_devices($capability)
Return a list of all devices currently known to the host OS. The
elements in the returned list are instances of the
Sys::Virt::NodeDevice class. The optional "capability" parameter
allows the list to be restricted to only devices with a particular
capability type.
my $nnames = $vmm->num_of_node_devices($capability[, $flags])
Return the number of host devices known to the VMM. This can be
used as the "maxids" parameter to "list_node_device_names". The
"capability" parameter allows the list to be restricted to only
devices with a particular capability type, and should be left as
"undef" if the full list is required. The optional <flags>
parameter is currently unused and defaults to 0 if omitted.
my @netNames = $vmm->list_node_device_names($capability, $maxnames[,
$flags])
Return a list of all host device names currently known to the VMM.
The names can be used with the "get_node_device_by_name" method.
The "capability" parameter allows the list to be restricted to only
devices with a particular capability type, and should be left as
"undef" if the full list is required. The optional <flags>
parameter is currently unused and defaults to 0 if omitted.
my @ifaces = $vmm->list_interfaces()
Return a list of all network interfaces currently known to the VMM.
The elements in the returned list are instances of the
Sys::Virt::Interface class.
my $nnames = $vmm->num_of_interfaces()
Return the number of running interfaces known to the VMM. This can
be used as the "maxnames" parameter to "list_interface_names".
my @names = $vmm->list_interface_names($maxnames)
Return a list of all interface names currently known to the VMM.
The names can be used with the "get_interface_by_name" method.
my @ifaces = $vmm->list_defined_interfaces()
Return a list of all network interfaces currently known to the VMM.
The elements in the returned list are instances of the
Sys::Virt::Interface class.
my $nnames = $vmm->num_of_defined_interfaces()
Return the number of inactive interfaces known to the VMM. This can
be used as the "maxnames" parameter to
"list_defined_interface_names".
my @names = $vmm->list_defined_interface_names($maxnames)
Return a list of inactive interface names currently known to the
VMM. The names can be used with the "get_interface_by_name" method.
my @ifaces = $vmm->list_secrets()
Return a list of all secrets currently known to the VMM. The
elements in the returned list are instances of the
Sys::Virt::Secret class.
my $nuuids = $vmm->num_of_secrets()
Return the number of secrets known to the VMM. This can be used as
the "maxuuids" parameter to "list_secrets".
my @uuids = $vmm->list_secret_uuids($maxuuids)
Return a list of all secret uuids currently known to the VMM. The
uuids can be used with the "get_secret_by_uuid" method.
my @nets = $vmm->list_nwfilters()
Return a list of all nwfilters currently known to the VMM. The
elements in the returned list are instances of the
Sys::Virt::NWFilter class.
my $nnames = $vmm->num_of_nwfilters()
Return the number of running nwfilters known to the VMM. This can
be used as the "maxids" parameter to "list_nwfilter_names".
my @filterNames = $vmm->list_nwfilter_names($maxnames)
Return a list of all nwfilter names currently known to the VMM. The
names can be used with the "get_nwfilter_by_name" method.
$vmm->define_save_image_xml($file, $dxml, $flags=0)
Update the XML associated with a virtual machine's save image. The
$file parameter is the fully qualified path to the save image XML,
while $dxml is the new XML document to write. The $flags parameter
is currently unused and defaults to zero.
$xml = $vmm->get_save_image_xml_description($file, $flags=1)
Retrieve the current XML configuration associated with the virtual
machine's save image identified by $file. The $flags parameter is
currently unused and defaults to zero.
my $dom = $vmm->get_domain_by_name($name)
Return the domain with a name of $name. The returned object is an
instance of the Sys::Virt::Domain class.
my $dom = $vmm->get_domain_by_id($id)
Return the domain with a local id of $id. The returned object is an
instance of the Sys::Virt::Domain class.
my $dom = $vmm->get_domain_by_uuid($uuid)
Return the domain with a globally unique id of $uuid. The returned
object is an instance of the Sys::Virt::Domain class.
my $net = $vmm->get_network_by_name($name)
Return the network with a name of $name. The returned object is an
instance of the Sys::Virt::Network class.
my $net = $vmm->get_network_by_uuid($uuid)
Return the network with a globally unique id of $uuid. The returned
object is an instance of the Sys::Virt::Network class.
my $pool = $vmm->get_storage_pool_by_name($name)
Return the storage pool with a name of $name. The returned object
is an instance of the Sys::Virt::StoragePool class.
my $pool = $vmm->get_storage_pool_by_uuid($uuid)
Return the storage pool with a globally unique id of $uuid. The
returned object is an instance of the Sys::Virt::StoragePool class.
my $vol = $vmm->get_storage_volume_by_path($path)
Return the storage volume with a location of $path. The returned
object is an instance of the Sys::Virt::StorageVol class.
my $vol = $vmm->get_storage_volume_by_key($key)
Return the storage volume with a globally unique id of $key. The
returned object is an instance of the Sys::Virt::StorageVol class.
my $dev = $vmm->get_node_device_by_name($name)
Return the node device with a name of $name. The returned object is
an instance of the Sys::Virt::NodeDevice class.
my $iface = $vmm->get_interface_by_name($name)
Return the interface with a name of $name. The returned object is
an instance of the Sys::Virt::Interface class.
my $iface = $vmm->get_interface_by_mac($mac)
Return the interface with a MAC address of $mac. The returned
object is an instance of the Sys::Virt::Interface class.
my $sec = $vmm->get_secret_by_uuid($uuid)
Return the secret with a globally unique id of $uuid. The returned
object is an instance of the Sys::Virt::Secret class.
my $sec = $vmm->get_secret_by_usage($usageType, $usageID)
Return the secret with a usage type of $usageType, identified by
$usageID. The returned object is an instance of the
Sys::Virt::Secret class.
my $dom = $vmm->get_nwfilter_by_name($name)
Return the domain with a name of $name. The returned object is an
instance of the Sys::Virt::NWFilter class.
my $dom = $vmm->get_nwfilter_by_uuid($uuid)
Return the nwfilter with a globally unique id of $uuid. The
returned object is an instance of the Sys::Virt::NWFilter class.
my $xml = $vmm->find_storage_pool_sources($type, $srcspec[, $flags])
Probe for available storage pool sources for the pool of type
$type. The $srcspec parameter can be "undef", or a parameter to
refine the discovery process, for example a server hostname for NFS
discovery. The $flags parameter is optional, and if omitted
defaults to zero. The returned scalar is an XML document describing
the discovered storage pool sources.
$vmm->interface_change_begin($flags)
Begin a transaction for changing the configuration of one or more
network interfaces
$vmm->interface_change_commit($flags)
Complete a transaction for changing the configuration of one or
more network interfaces
$vmm->interface_change_rollback($flags)
Abort a transaction for changing the configuration of one or more
network interfaces
$vmm->restore_domain($savefile)
Recreate a domain from the saved state file given in the $savefile
parameter.
$vmm->get_max_vcpus($domtype)
Return the maximum number of vcpus that can be configured for a
domain of type $domtype
my $hostname = $vmm->get_hostname()
Return the name of the host with which this connection is
associated.
my $uri = $vmm->get_uri()
Return the URI associated with the open connection. This may be
different from the URI used when initially connecting to libvirt,
when 'auto-probing' or drivers occurrs.
my $xml = $vmm->get_sysinfo()
Return an XML documenting representing the host system information,
typically obtained from SMBIOS tables.
my $type = $vmm->get_type()
Return the type of virtualization backend accessed by this VMM
object. Currently the only supported type is "Xen".
my $xml = $vmm->domain_xml_from_native($format, $config);
Convert the native hypervisor configuration $config which is in
format <$format> into libvirrt domain XML. Valid values of $format
vary between hypervisor drivers.
my $config = $vmm->domain_xml_to_native($format, $xml)
Convert the libvirt domain XML configuration $xml to a native
hypervisor configuration in format $format
my $ver = $vmm->get_version()
Return the complete version number as a string encoded in the
formula "(major * 1000000) + (minor * 1000) + micro".
my $ver = $vmm->get_major_version
Return the major version number of the libvirt library.
my $ver = $vmm->get_minor_version
Return the minor version number of the libvirt library.
my $ver = $vmm->get_micro_version
Return the micro version number of the libvirt library.
my $ver = $vmm->get_library_version
Return the version number of the API associated with the active
connection. This differs from "get_version" in that if the
connection is to a remote libvirtd daemon, it will return the API
version of the remote libvirt, rather than the local client.
$conn->is_secure()
Returns a true value if the current connection is secure against
network interception. This implies either use of UNIX sockets, or
encryption with a TCP stream.
$conn->is_encrypted()
Returns a true value if the current connection data stream is
encrypted.
my $info = $con->get_node_info()
Returns a hash reference summarising the capabilities of the host
node. The elements of the hash are as follows:
my $info = $con->get_node_cpu_stats($cpuNum=-1, $flags=0)
Returns a hash reference providing information about the host CPU
statistics. If <$cpuNum> is omitted, it defaults to -1 which causes
it to return cummulative information for all CPUs in the host. If
$cpuNum is zero or larger, it returns information just for the
specified number. The $flags parameter is currently unused and
defaults to zero. The fields in the returned hash reference are
kernel
The time spent in kernelspace
user
The time spent in userspace
idle
The idle time
iowait
The I/O wait time
utilization
The overall percentage utilization.
my $info = $con->get_node_memory_stats($cellNum=-1, $flags=0)
Returns a hash reference providing information about the host
memory statistics. If <$cellNum> is omitted, it defaults to -1
which causes it to return cummulative information for all NUMA
cells in the host. If $cellNum is zero or larger, it returns
information just for the specified number. The $flags parameter is
currently unused and defaults to zero. The fields in the returned
hash reference are
total
The total memory
free
The free memory
buffers
The memory consumed by buffers
cache
The memory consumed for cache
$conn->domain_event_register($callback)
Register a callback to received notificaitons of domain state
change events. Only a single callback can be registered with each
connection instance. The callback will be invoked with four
parameters, an instance of "Sys::Virt" for the connection, an
instance of "Sys::Virt::Domain" for the domain changing state, and
a "event" and "detail" arguments, corresponding to the event
constants defined in the "Sys::Virt::Domain" module. Before
discarding the connection object, the callback must be
deregistered, otherwise the connection object memory will never be
released in garbage collection.
$conn->domain_event_deregister()
Unregister a callback, allowing the connection object to be garbage
collected.
$callback = $conn->domain_event_register_any($dom, $eventID, $callback)
Register a callback to received notifications of domain events.
The $dom parameter can be "undef" to request events on all known
domains, or a specific "Sys::Virt::Domain" object to filter events.
The $eventID parameter is one of the EVENT ID constants described
later in this document. The $callback is a subroutine reference
that will receive the events.
All callbacks receive a "Sys::Virt" connection as the first
parameter and a "Sys::Virt::Domain" object indiciating the domain
on which the event occurred as the second parameter. Subsequent
parameters vary according to the event type
EVENT_ID_LIFECYCLE
Extra "event" and "detail" parameters defining the lifecycle
transition that occurred.
EVENT_ID_REBOOT
No extra parameters
EVENT_ID_RTC_CHANGE
The "utcoffset" gives the offset from UTC in seconds
EVENT_ID_WATCHDOG
The "action" defines the action that is taken as a result of
the watchdog triggering. One of the WATCHDOG constants
described later
EVENT_ID_IO_ERROR
The "srcPath" is the file on the host which had the error. The
"devAlias" is the unique device alias from the guest
configuration associated with "srcPath". The "action" is the
action taken as a result of the error, one of the IO ERROR
constants described later
EVENT_ID_GRAPHICS
The "phase" is the stage of the connection, one of the GRAPHICS
PHASE constants described later. The "local" and "remote"
parameters follow with the details of the local and remote
network addresses. The "authScheme" describes how the user was
authenticated (if at all). Finally "identities" is an array ref
containing authenticated identities for the user, if any.
The return value is a unique callback ID that must be used when
unregistering the event.
$conn->domain_event_deregister_any($callbackID)
Unregister a callback, associated with the $callbackID previously
obtained from "domain_event_register_any".
my $xml = $con->baseline_cpu(\@xml, $flags=0)
Given an array ref whose elements are XML documents describing host
CPUs, compute the baseline CPU model that is operable across all
hosts. The XML for the baseline CPU model is returned. The optional
$flags parameter is currently unused and defaults to 0.
memory
The amount of physical memory in the host
model
The model of the CPU, eg x86_64
cpus
The total number of logical CPUs
mhz The peak MHZ of the CPU
nodes
The number of NUMA cells
sockets
The number of CPU sockets
cores
The number of cores per socket
threads
The number of threads per core
my $info = $con->get_node_security_model()
Returns a hash reference summarising the security model of the host
node. There are two keys in the hash, "model" specifying the name
of the security model (eg 'selinux') and "doi" specifying the
'domain of interpretation' for security labels.
my $xml = $con->get_capabilities();
Returns an XML document describing the hypervisor capabilities
my $result = $con->compare_cpu($xml, $flags=0);
Checks whether the CPU definition in $xml is compatible with the
current hypervisor connection. This can be used to determine
whether it is safe to migrate a guest to this host. The returned
result is one of the constants listed later
$mem = $con->get_node_free_memory();
Returns the current free memory on the host
@mem = $con->get_node_cells_free_memory($start, $end);
Returns the free memory on each NUMA cell between $start and $end.
CONSTANTS
The following sets of constants are useful when dealing with APIs in
this package
CREDENTIAL TYPES
When providing authentication callbacks, the following constants
indicate the type of credential being requested
Sys::Virt::CRED_AUTHNAME
Identity to act as
Sys::Virt::CRED_USERNAME
Identity to authorize as
Sys::Virt::CRED_CNONCE
Client supplies a nonce
Sys::Virt::CRED_REALM
Authentication realm
Sys::Virt::CRED_ECHOPROMPT
Challenge response non-secret
Sys::Virt::CRED_NOECHOPROMPT
Challenge response secret
Sys::Virt::CRED_PASSPHRASE
Passphrase secret
Sys::Virt::CRED_LANGUAGE
RFC 1766 language code
Sys::Virt::CRED_EXTERNAL
Externally provided credential
CPU COMPARISON CONSTANTS
Sys::Virt::CPU_COMPARE_INCOMPATIBLE
This host is missing one or more CPU features in the CPU
description
Sys::Virt::CPU_COMPARE_IDENTICAL
The host has an identical CPU description
Sys::Virt::CPU_COMPARE_SUPERSET
The host offers a superset of the CPU descriptoon
BUGS
Hopefully none, but the XS code needs to be audited to ensure it is not
leaking memory.
AUTHORS
Daniel P. Berrange <berrange@redhat.com>
COPYRIGHT
Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 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::Domain, Sys::Virt::Network, Sys::Virt::StoragePool,
Sys::Virt::StorageVol, Sys::Virt::Error, "http://libvirt.org"
perl v5.14.1 2011-09-28 Sys::Virt(3)
