NAME
Sys::Virt - Represent and manage a libvirt hypervisor connection
SYNOPSIS
my
$conn
= Sys::Virt->new(
uri
=>
$uri
);
my
@domains
=
$conn
->list_domains();
foreach
my
$dom
(
@domains
) {
"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.
CALLBACK HANDLING
Each callback registration routine returns a $callbackID
(except for domain_event_register
and register_close_callback
). This return value must be retained and used for callback deregistration.
IMPORTANT: All callbacks must be deregistered (including the ones registered using domain_event_register
and register_close_callback
); failing to do so prevents the Sys::Virt
object from being garbage collected and the connection to libvirtd
from being closed.
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:
eval
{
my
$conn
= Sys::Virt->new(
uri
=>
$uri
); };
if
($@) {
STDERR
"Unable to open connection to $addr"
. $@->message .
"\n"
;
}
For details of the information contained in the error objects, consult the Sys::Virt::Error manual page.
METHODS
- my $conn = Sys::Virt->new(uri => $uri, readonly => $ro, flags => $flags);
-
Attach to the virtualization host identified by
uri
. Theuri
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 hypervisor will be attempted. If it is not supplied, then it defaults to making a fully privileged connection to the hypervisor. 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. Thecredlist
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. Thecallback
parameter should be a subroutine reference containing the code necessary to gather the credentials. When invoked it will be supplied with a single parameter, an array reference of requested credentials. The elements of the array are hash references, with keystype
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 theresult
key. This key may already be set with a default result if applicableAs a simple example returning hardcoded credentials
my
$username
=
"test"
;
my
$password
=
"123456"
;
my
$con
= Sys::Virt->new(
uri
=>
$uri
,
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;
});
For backwards compatibility with earlier releases, the
address
parameter is accepted as a synonym for theuri
parameter. The use ofuri
is recommended for all newly written code. - $conn->set_identity($identity, $flags=0)
-
Change the identity that is used for access control over the connection. Normally the remote daemon will use the identity associated with the UNIX domain socket that the app opens. Only a privileged client is usually able to override this. The
$identity
should be a hash reference whose keys are one of the IDENTITY constants. The$flags
parameter is currently unused, and defaults to 0 if omitted. - my $st = $conn->new_stream($flags)
-
Create a new stream, with the given flags
- my $dom = $conn->create_domain($xml, $flags=0);
-
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 hypervisor. The$flags
parameter accepts one of the DOMAIN CREATION constants documented in Sys::Virt::Domain, and defaults to 0 if omitted. - my $dom = $conn->create_domain_with_files($xml, $fds, $flags=0);
-
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 hypervisor. The$fds
parameter is an array of UNIX file descriptors which will be passed to the init process of the container. This is only supported with container based virtualization. The$flags
parameter accepts one of the DOMAIN CREATION constants documented in Sys::Virt::Domain, and defaults to 0 if omitted. - my $dom = $conn->define_domain($xml, $flags=0);
-
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 hypervisor. The defined domain can be later started by calling thecreate
method on the returnedSys::Virt::Domain
object. The$flags
parameter accepts one of the DOMAIN DEFINE constants documented in Sys::Virt::Domain, and defaults to 0 if omitted. - my $net = $conn->create_network($xml, $flags=0);
-
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 hypervisor. The$flags
parameter accepts one of the NETWORK CREATION constants documented in Sys::Virt::Network, and defaults to 0 if omitted. - my $net = $conn->define_network($xml, $flags=0);
-
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 hypervisor. The defined network can be later started by calling thecreate
method on the returnedSys::Virt::Network
object. The$flags
parameter accepts one of the NETWORK DEFINE constants documented in Sys::Virt::Network, and defaults to 0 if omitted. - my $nwfilter = $conn->define_nwfilter($xml, $flags=0);
-
Defines a new network filter based on the XML description passed into the
$xml
parameter. The returned object is an instance of the Sys::Virt::NWFilter class. This method is not available with unprivileged connections to the hypervisor. The$flags
parameter accepts one of the NWFILTER DEFINE constants documented in Sys::Virt::NWFilter, and defaults to 0 if omitted. - my $binding = $conn->create_nwfilter_binding($xml, $flags=0);
-
Create a new network filter binding based on the XML description passed into the
$xml
parameter. The returned object is an instance of the Sys::Virt::NWFilterBinding class. The$flags
parameter accepts one of the NETWORK FILTER BINDING CREATION constants documented in Sys::Virt::NWFilterBinding, and defaults to 0 if omitted. - my $secret = $conn->define_secret($xml, $flags=0);
-
Defines a new secret based on the XML description passed into the
$xml
parameter. The returned object is an instance of the Sys::Virt::Secret class. This method is not available with unprivileged connections to the hypervisor. The$flags
parameter accepts one of the SECRET DEFINE constants documented in Sys::Virt::Secret, and defaults to 0 if omitted. - my $pool = $conn->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 hypervisor. - my $pool = $conn->define_storage_pool($xml, $flags=0);
-
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 hypervisor. The defined pool can be later started by calling thecreate
method on the returnedSys::Virt::StoragePool
object. The$flags
parameter accepts one of the STORAGE POOL DEFINE constants documented in Sys::Virt::StoragePool, and defaults to 0 if omitted. - my $pool = $conn->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 hypervisor. - my $iface = $conn->define_interface($xml, $flags=0);
-
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 hypervisor. The defined interface can be later started by calling thecreate
method on the returnedSys::Virt::Interface
object. The$flags
parameter accepts one of the INTERFACE DEFINE constants documented in Sys::Virt::Interface, and defaults to 0 if omitted. - my $dev = $conn->create_node_device($xml, $flags=0);
-
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 hypervisor. The$flags
parameter accepts one of the NODE DEVICE CREATION constants documented in Sys::Virt::NodeDevice, and defaults to 0 if omitted. - my $dev = $conn->define_node_device($xml, $flags=0);
-
Defines, but does not start, a new node dev 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 hypervisor. The defined node device can be later started by calling thecreate
method on the returnedSys::Virt::NodeDevice
object. The$flags
parameter accepts one of the NODE DEVICE DEFINE constants documented in Sys::Virt::NodeDevice, and defaults to 0 if omitted. - my @doms = $conn->list_domains()
-
Return a list of all running domains currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::Domain class. This method requires O(n) RPC calls, so the
list_all_domains
method is recommended as a more efficient alternative. - my $nids = $conn->num_of_domains()
-
Return the number of running domains known to the hypervisor. This can be used as the
maxids
parameter tolist_domain_ids
. - my @domIDs = $conn->list_domain_ids($maxids)
-
Return a list of all domain IDs currently known to the hypervisor. The IDs can be used with the
get_domain_by_id
method. - my @doms = $conn->list_defined_domains()
-
Return a list of all domains defined, but not currently running, on the hypervisor. The elements in the returned list are instances of the Sys::Virt::Domain class. This method requires O(n) RPC calls, so the
list_all_domains
method is recommended as a more efficient alternative. - my $ndoms = $conn->num_of_defined_domains()
-
Return the number of running domains known to the hypervisor. This can be used as the
maxnames
parameter tolist_defined_domain_names
. - my @names = $conn->list_defined_domain_names($maxnames)
-
Return a list of names of all domains defined, but not currently running, on the hypervisor. The names can be used with the
get_domain_by_name
method. - my @doms = $conn->list_all_domains($flags)
-
Return a list of all domains currently known to the hypervisor, whether running or shutoff. The elements in the returned list are instances of the Sys::Virt::Domain class. The
$flags
parameter can be used to filter the list of returned domains. - my @nets = $conn->list_networks()
-
Return a list of all networks currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::Network class. This method requires O(n) RPC calls, so the
list_all_networks
method is recommended as a more efficient alternative. - my $nnets = $conn->num_of_networks()
-
Return the number of running networks known to the hypervisor. This can be used as the
maxids
parameter tolist_network_ids
. - my @netNames = $conn->list_network_names($maxnames)
-
Return a list of all network names currently known to the hypervisor. The names can be used with the
get_network_by_name
method. - my @nets = $conn->list_defined_networks()
-
Return a list of all networks defined, but not currently running, on the hypervisor. The elements in the returned list are instances of the Sys::Virt::Network class. This method requires O(n) RPC calls, so the
list_all_networks
method is recommended as a more efficient alternative. - my $nnets = $conn->num_of_defined_networks()
-
Return the number of running networks known to the host. This can be used as the
maxnames
parameter tolist_defined_network_names
. - my @names = $conn->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 @nets = $conn->list_all_networks($flags)
-
Return a list of all networks currently known to the hypervisor, whether running or shutoff. The elements in the returned list are instances of the Sys::Virt::Network class. The
$flags
parameter can be used to filter the list of returned networks. - my @pools = $conn->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. This method requires O(n) RPC calls, so the
list_all_storage_pools
method is recommended as a more efficient alternative. - my $npools = $conn->num_of_storage_pools()
-
Return the number of running storage pools known to the hypervisor. This can be used as the
maxids
parameter tolist_storage_pool_names
. - my @poolNames = $conn->list_storage_pool_names($maxnames)
-
Return a list of all storage pool names currently known to the hypervisor. The IDs can be used with the
get_network_by_id
method. - my @pools = $conn->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. This method requires O(n) RPC calls, so the
list_all_storage_pools
method is recommended as a more efficient alternative. - my $npools = $conn->num_of_defined_storage_pools()
-
Return the number of running networks known to the host. This can be used as the
maxnames
parameter tolist_defined_storage_pool_names
. - my @names = $conn->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 @pools = $conn->list_all_storage_pools($flags)
-
Return a list of all storage pools currently known to the hypervisor, whether running or shutoff. The elements in the returned list are instances of the Sys::Virt::StoragePool class. The
$flags
parameter can be used to filter the list of returned pools. - my @devs = $conn->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. This method requires O(n) RPC calls, so thelist_all_node_devices
method is recommended as a more efficient alternative. - my $ndevs = $conn->num_of_node_devices($capability[, $flags])
-
Return the number of host devices known to the hypervisor. This can be used as the
maxids
parameter tolist_node_device_names
. Thecapability
parameter allows the list to be restricted to only devices with a particular capability type, and should be left asundef
if the full list is required. The optional <flags> parameter is currently unused and defaults to 0 if omitted. - my @devNames = $conn->list_node_device_names($capability, $maxnames[, $flags])
-
Return a list of all host device names currently known to the hypervisor. The names can be used with the
get_node_device_by_name
method. Thecapability
parameter allows the list to be restricted to only devices with a particular capability type, and should be left asundef
if the full list is required. The optional <flags> parameter is currently unused and defaults to 0 if omitted. - my @devs = $conn->list_all_node_devices($flags)
-
Return a list of all node devices currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::NodeDevice class. The
$flags
parameter can be used to filter the list of returned devices. - my @ifaces = $conn->list_interfaces()
-
Return a list of all network interfaces currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::Interface class. This method requires O(n) RPC calls, so the
list_all_interfaces
method is recommended as a more efficient alternative. - my $nifaces = $conn->num_of_interfaces()
-
Return the number of running interfaces known to the hypervisor. This can be used as the
maxnames
parameter tolist_interface_names
. - my @names = $conn->list_interface_names($maxnames)
-
Return a list of all interface names currently known to the hypervisor. The names can be used with the
get_interface_by_name
method. - my @ifaces = $conn->list_defined_interfaces()
-
Return a list of all network interfaces currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::Interface class. This method requires O(n) RPC calls, so the
list_all_interfaces
method is recommended as a more efficient alternative. - my $nifaces = $conn->num_of_defined_interfaces()
-
Return the number of inactive interfaces known to the hypervisor. This can be used as the
maxnames
parameter tolist_defined_interface_names
. - my @names = $conn->list_defined_interface_names($maxnames)
-
Return a list of inactive interface names currently known to the hypervisor. The names can be used with the
get_interface_by_name
method. - my @ifaces = $conn->list_all_interfaces($flags)
-
Return a list of all interfaces currently known to the hypervisor, whether running or shutoff. The elements in the returned list are instances of the Sys::Virt::Interface class. The
$flags
parameter can be used to filter the list of returned interfaces. - my @ifaces = $conn->list_secrets()
-
Return a list of all secrets currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::Secret class. This method requires O(n) RPC calls, so the
list_all_secrets
method is recommended as a more efficient alternative. - my $nuuids = $conn->num_of_secrets()
-
Return the number of secrets known to the hypervisor. This can be used as the
maxuuids
parameter tolist_secrets
. - my @uuids = $conn->list_secret_uuids($maxuuids)
-
Return a list of all secret uuids currently known to the hypervisor. The uuids can be used with the
get_secret_by_uuid
method. - my @secrets = $conn->list_all_secrets($flags)
-
Return a list of all secrets currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::Network class. The
$flags
parameter can be used to filter the list of returned secrets. - my @nwfilters = $conn->list_nwfilters()
-
Return a list of all nwfilters currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::NWFilter class. This method requires O(n) RPC calls, so the
list_all_nwfilters
method is recommended as a more efficient alternative. - my $nnwfilters = $conn->num_of_nwfilters()
-
Return the number of running nwfilters known to the hypervisor. This can be used as the
maxids
parameter tolist_nwfilter_names
. - my @filterNames = $conn->list_nwfilter_names($maxnames)
-
Return a list of all nwfilter names currently known to the hypervisor. The names can be used with the
get_nwfilter_by_name
method. - my @nwfilters = $conn->list_all_nwfilters($flags)
-
Return a list of all nwfilters currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::NWFilter class. The
$flags
parameter is currently unused and defaults to zero. - my @bindings = $conn->list_all_nwfilter_bindings($flags)
-
Return a list of all nwfilter bindings currently known to the hypervisor. The elements in the returned list are instances of the Sys::Virt::NWFilterBinding class. The
$flags
parameter is currently unused and defaults to zero. - $conn->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 = $conn->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 accepts the same constants asSys::Virt::Domain::managed_save_get_xml_description
. - my $dom = $conn->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 = $conn->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 = $conn->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 = $conn->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 = $conn->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 = $conn->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 = $conn->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 $pool = $conn->get_storage_pool_by_volume($vol)
-
Return the storage pool with a storage volume
$vol
. The$vol
parameter must be an instance of the Sys::Virt::StorageVol class. The returned object is an instance of the Sys::Virt::StoragePool class. - my $pool = $conn->get_storage_pool_by_target_path($path)
-
Return the storage pool with a target path of
$path
. The returned object is an instance of the Sys::Virt::StoragePool class. - my $vol = $conn->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 = $conn->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 = $conn->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 $dev = $conn->get_node_device_scsihost_by_wwn($wwnn, $wwpn, $flags=0)
-
Return the node device which is a SCSI host identified by
$wwnn
and$wwpn
. The$flags
parameter is unused and defaults to zero. The returned object is an instance of the Sys::Virt::NodeDevice class. - my $iface = $conn->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 = $conn->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 = $conn->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 = $conn->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 $nwfilter = $conn->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 $nwfilter = $conn->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 $binding = $conn->get_nwfilter_binding_by_port_dev($name)
-
Return the network filter binding for the port device
$name
. The returned object is an instance of the Sys::Virt::NWFilterBinding class. - my $xml = $conn->find_storage_pool_sources($type, $srcspec[, $flags])
-
Probe for available storage pool sources for the pool of type
$type
. The$srcspec
parameter can beundef
, 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. - my @stats = $conn->get_all_domain_stats($stats, \@doms=undef, $flags=0);
-
Get a list of all statistics for domains known to the hypervisor. The
$stats
parameter controls which data fields to return and should be a combination of the DOMAIN STATS FIELD CONSTANTS.The optional
@doms
parameter is a list of Sys::Virt::Domain objects to return stats for. If this is undefined, then all domains will be returned. The$flags
method can be used to filter the list of returned domains.The return data for the method is a list, one element for each domain. The element will be a hash with two keys,
dom
pointing to an instance ofSys::Virt::Domain
anddata
pointing to another hash reference containing the actual statistics. - $conn->interface_change_begin($flags)
-
Begin a transaction for changing the configuration of one or more network interfaces
- $conn->interface_change_commit($flags)
-
Complete a transaction for changing the configuration of one or more network interfaces
- $conn->interface_change_rollback($flags)
-
Abort a transaction for changing the configuration of one or more network interfaces
- $conn->restore_domain($savefile, $dxml=undef, $params=undef, $flags=0)
-
Recreate a domain from the saved state file given in the
$savefile
parameter. The optional$dxml
parameter can be used to alter portions of the domain XML. The$params
parameter is a hash reference whose keys is a subset of the SAVE / RESTORE PARAMETER CONSTANTS. The$flags
parameter accepts one of the SAVE / RESTORE FLAG CONSTANTS described later and defaults to zero. - $conn->get_max_vcpus($domtype)
-
Return the maximum number of vcpus that can be configured for a domain of type
$domtype
- my $hostname = $conn->get_hostname()
-
Return the name of the host with which this connection is associated.
- my $uri = $conn->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 occurs.
- my $xml = $conn->get_sysinfo()
-
Return an XML documenting representing the host system information, typically obtained from SMBIOS tables.
- my $type = $conn->get_type()
-
Return the type of virtualization backend accessed by this hypervisor object. Currently the only supported type is
Xen
. - my $xml = $conn->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 = $conn->domain_xml_to_native($format, $xml)
-
Convert the libvirt domain XML configuration
$xml
to a native hypervisor configuration in format$format
- my $ver = $conn->get_version()
-
Return the complete version number as a string encoded in the formula
(major * 1000000) + (minor * 1000) + micro
. - my $ver = $conn->get_major_version
-
Return the major version number of the libvirt library.
- my $ver = $conn->get_minor_version
-
Return the minor version number of the libvirt library.
- my $ver = $conn->get_micro_version
-
Return the micro version number of the libvirt library.
- my $ver = $conn->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.
- $conn->is_alive()
-
Returns a true value if the connection is alive, as determined by keep-alive packets or other recent RPC traffic.
- $conn->set_keep_alive($interval, $count)
-
Change the operation of the keep alive protocol to send
$count
packets spaced$interval
seconds apart before considering the connection dead. - 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:
- 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
NB, more accurate information about the total number of CPUs and those online can be obtained using the
get_node_cpu_map
method. - my ($totcpus, $onlinemap, $totonline) = $con->get_node_cpu_map();
-
Returns an array containing information about the CPUs available on the host. The first element,
totcpus
, specifies the total number of CPUs available to the host regardless of their online stat. The second element,onlinemap
, provides a bitmap detailing which CPUs are currently online. The third element,totonline
, specifies the total number of online CPUs. The values in the bitmap can be extracted using theunpack
method as follows:my
@onlinemap
=
split
(//,
unpack
(
"b*"
,
$onlinemap
));
- 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
Sys::Virt::NODE_CPU_STATS_ALL_CPUS
which causes it to return cumulative 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 - 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
Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS
which causes it to return cumulative 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 - my $params = $conn->get_node_memory_parameters($flags=0)
-
Return a hash reference containing the set of memory tunable parameters for the node. The keys in the hash are one of the constants MEMORY PARAMETERS described later. The
$flags
parameter is currently unused, and defaults to 0 if omitted. - $conn->set_node_memory_parameters($params, $flags=0)
-
Update the memory tunable parameters for the node. The
$params
should be a hash reference whose keys are one of the MEMORY PARAMETERS constants. The$flags
parameter is currently unused, and defaults to 0 if omitted. - $info = $conn->get_node_sev_info($flags=0)
-
Get the AMD SEV information for the host.
$flags
is currently unused and defaults to 0 if omitted. The returned hash contains the following keys:- Sys::Virt::SEV_CBITPOS
-
The CBit position
- Sys::Virt::SEV_CERT_CHAIN
-
The certificate chain
- Sys::Virt::SEV_PDH
-
Platform diffie-hellman key
- Sys::Virt::SEV_REDUCED_PHYS_BITS
-
The number of physical address bits used by SEV
- Sys::Virt::SEV_MAX_GUESTS
-
Maximum number of SEV guests that can be launched
- Sys::Virt::SEV_MAX_ES_GUESTS
-
Maximum number of SEV-ES guests that can be launched
- Sys::Virt::SEV_CPU0_ID
-
The SEV firmware ID for CPU 0
- $conn->node_suspend_for_duration($target, $duration, $flags=0)
-
Suspend the the host, using mode
$target
which is one of the NODE SUSPEND constants listed later. The$duration
parameter controls how long the node is suspended for before waking up. - $conn->domain_event_register($callback)
-
Register a callback to received notifications 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 ofSys::Virt::Domain
for the domain changing state, and aevent
anddetail
arguments, corresponding to the event constants defined in theSys::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.
- $callbackID = $conn->domain_event_register_any($dom, $eventID, $callback)
-
Register a callback to received notifications of domain events. The
$dom
parameter can beundef
to request events on all known domains, or a specificSys::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 aSys::Virt::Domain
object indicating the domain on which the event occurred as the second parameter. Subsequent parameters vary according to the event type- EVENT_ID_LIFECYCLE
-
Extra
event
anddetail
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. ThedevAlias
is the unique device alias from the guest configuration associated withsrcPath
. Theaction
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. Thelocal
andremote
parameters follow with the details of the local and remote network addresses. TheauthScheme
describes how the user was authenticated (if at all). Finallyidentities
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 fromdomain_event_register_any
. - $callbackID = $conn->network_event_register_any($net, $eventID, $callback)
-
Register a callback to received notifications of network events. The
$net
parameter can beundef
to request events on all known networks, or a specificSys::Virt::Network
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 aSys::Virt::Network
object indicating the network on which the event occurred as the second parameter. Subsequent parameters vary according to the event type- EVENT_ID_LIFECYCLE
-
Extra
event
anddetail
parameters defining the lifecycle transition that occurred.
The return value is a unique callback ID that must be used when unregistering the event.
- $conn->network_event_deregister_any($callbackID)
-
Unregister a callback, associated with the
$callbackID
previously obtained fromnetwork_event_register_any
. - $callbackID = $conn->storage_pool_event_register_any($pool, $eventID, $callback)
-
Register a callback to received notifications of storage pool events. The
$pool
parameter can beundef
to request events on all known storage pools, or a specificSys::Virt::StoragePool
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 aSys::Virt::StoragePool
object indicating the storage pool on which the event occurred as the second parameter. Subsequent parameters vary according to the event type- EVENT_ID_LIFECYCLE
-
Extra
event
anddetail
parameters defining the lifecycle transition that occurred. - EVENT_ID_REFRESH
-
No extra parameters.
The return value is a unique callback ID that must be used when unregistering the event.
- $conn->storage_pool_event_deregister_any($callbackID)
-
Unregister a callback, associated with the
$callbackID
previously obtained fromstorage_pool_event_register_any
. - $callbackID = $conn->node_device_event_register_any($dev, $eventID, $callback)
-
Register a callback to received notifications of node device events. The
$dev
parameter can beundef
to request events on all known node devices, or a specificSys::Virt::NodeDevice
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 aSys::Virt::NodeDevice
object indicating the node device on which the event occurred as the second parameter. Subsequent parameters vary according to the event type- EVENT_ID_LIFECYCLE
-
Extra
event
anddetail
parameters defining the lifecycle transition that occurred.
The return value is a unique callback ID that must be used when unregistering the event.
- $conn->node_device_event_deregister_any($callbackID)
-
Unregister a callback, associated with the
$callbackID
previously obtained fromnode_device_event_register_any
. - $callbackID = $conn->secret_event_register_any($secret, $eventID, $callback)
-
Register a callback to received notifications of secret events. The
$secret
parameter can beundef
to request events on all known secrets, or a specificSys::Virt::Secret
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 aSys::Virt::Secret
object indicating the secret on which the event occurred as the second parameter. Subsequent parameters vary according to the event type- EVENT_ID_LIFECYCLE
-
Extra
event
anddetail
parameters defining the lifecycle transition that occurred. - EVENT_ID_VALUE_CHANGED
-
No extra parameters.
The return value is a unique callback ID that must be used when unregistering the event.
- $conn->secret_event_deregister_any($callbackID)
-
Unregister a callback, associated with the
$callbackID
previously obtained fromsecret_event_register_any
. - $conn->register_close_callback($coderef);
-
Register a callback to be invoked when the connection is closed. The callback will be invoked with two parameters, the
$conn
it was registered against, and the reason for the close event. The reason value will be one of theCLOSE REASON CONSTANTS
listed later in this document. - $conn->unregister_close_callback();
-
Remove the previously registered close callback.
- 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 can take one of - my $xml = $con->baseline_hypervisor_cpu($emulator, $arch, $machine, $virttype, \@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. Either
$emulator
or$arch
must be a valid string referring to an emulator binary or an architecture name respectively. The$machine
parameter is an optional name of a guest machine, and$virttype
is an optional name of the virtualization type. The optional$flags
parameter accepts the same values asbaseline_cpu
. - @names = $con->get_cpu_model_names($arch, $flags=0)
-
Get a list of valid CPU models names for the architecture given by
$arch
. The$arch
value should be one of the architectures listed in the capabilities XML document. The$flags
parameter is currently unused and defaults to 0. - 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') anddoi
specifying the 'domain of interpretation' for security labels. - my $xml = $con->get_capabilities();
-
Returns an XML document describing the hypervisor capabilities
- my $xml = $con->get_domain_capabilities($emulator, $arch, $machine, $virttype, flags=0);
-
Returns an XML document describing the capabilities of the requested guest configuration. Either
$emulator
or$arch
must be a valid string referring to an emulator binary or an architecture name respectively. The$machine
parameter is an optional name of a guest machine, and$virttype
is an optional name of the virtualization type.$flags
is unused and defaults to zero. - my $xml = $con->get_storage_pool_capabilities($flags=0);
-
Returns an XML document describing the storage pool driver capabilities (e.g. which storage pool types are supported and so on).
$flags
is currently unused and defaults to zero. - 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 The optional$flags
parameter can take one of the following constants - my $result = $con->compare_hypervisor_cpu($emulator, $arch, $machine, $virttype, $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. Either$emulator
or$arch
must be a valid string referring to an emulator binary or an architecture name respectively. The$machine
parameter is an optional name of a guest machine, and$virttype
is an optional name of the virtualization type. The returned result is one of the constants listed later The optional$flags
parameter can take the same values as thecompare_cpu
method. - $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
. - @pages = $con->get_node_free_pages(\@pagesizes, $start, $end);
-
Returns information about the number of pages free on each NUMA cell between
$start
and$end
inclusive. The@pagesizes
parameter should be an arrayref specifying which pages sizes information should be returned for. Information about supported page sizes is available in the capabilities XML. The returned array has an element for each NUMA cell requested. The elements are hash references with two keys, 'cell' specifies the NUMA cell number and 'pages' specifies the free page information for that cell. The 'pages' value is another hash reference where the keys are the page sizes and the values are the free count for that size. - $con->node_alloc_pages(\@pages, $start, $end, $flags=0)
-
Allocate further huge pages for the reserved dev. The <\@pages> parameter is an array reference with one entry per page size to allocate for. Each entry is a further array reference where the first element is the page size and the second element is the page count. The same number of pages will be allocated on each NUMA node in the range
$start
to$end
inclusive. The$flags
parameter accepts two constants
CONSTANTS
The following sets of constants are useful when dealing with APIs in this package
CONNECTION
When opening a connection the following constants can be used:
- Sys::Virt::CONNECT_RO
-
Request a read-only connection
- Sys::Virt::CONNECT_NO_ALIASES
-
Prevent the resolution of URI aliases
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
IDENTITY CONSTANTS
The following constants are useful to change the connection identity
- Sys::Virt::IDENTITY_USER_NAME
-
The process user name
- Sys::Virt::IDENTITY_UNIX_USER_ID
-
The process UNIX user ID
- Sys::Virt::IDENTITY_GROUP_NAME
-
The process group name
- Sys::Virt::IDENTITY_UNIX_GROUP_ID
-
The process UNIX group ID
- Sys::Virt::IDENTITY_PROCESS_ID
-
The process ID.
- Sys::Virt::IDENTITY_PROCESS_TIME
-
The process start time.
- Sys::Virt::IDENTITY_SASL_USER_NAME
-
The SASL authenticated user name
- Sys::Virt::IDENTITY_X509_DISTINGUISHED_NAME
-
The X509 certificate distinguished name for the TLS connection
- Sys::Virt::IDENTITY_SELINUX_CONTEXT
-
The SELinux process context
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
NODE SUSPEND CONSTANTS
- Sys::Virt::NODE_SUSPEND_TARGET_MEM
-
Suspends to memory (equivalent of S3 on x86 architectures)
- Sys::Virt::NODE_SUSPEND_TARGET_DISK
-
Suspends to disk (equivalent of S5 on x86 architectures)
- Sys::Virt::NODE_SUSPEND_TARGET_HYBRID
-
Suspends to memory and disk (equivalent of S3+S5 on x86 architectures)
NODE VCPU CONSTANTS
NODE MEMORY CONSTANTS
MEMORY PARAMETERS
The following constants are used to name memory parameters of the node
- Sys::Virt::NODE_MEMORY_SHARED_FULL_SCANS
-
How many times all mergeable areas have been scanned.
- Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARED
-
How many the shared memory pages are being used.
- Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARING
-
How many sites are sharing the pages
- Sys::Virt::NODE_MEMORY_SHARED_PAGES_TO_SCAN
-
How many present pages to scan before the shared memory service goes to sleep
- Sys::Virt::NODE_MEMORY_SHARED_PAGES_UNSHARED
-
How many pages unique but repeatedly checked for merging.
- Sys::Virt::NODE_MEMORY_SHARED_PAGES_VOLATILE
-
How many pages changing too fast to be placed in a tree.
- Sys::Virt::NODE_MEMORY_SHARED_SLEEP_MILLISECS
-
How many milliseconds the shared memory service should sleep before next scan.
- Sys::Virt::NODE_MEMORY_SHARED_MERGE_ACROSS_NODES
-
Whether pages can be merged across NUMA nodes
CLOSE REASON CONSTANTS
The following constants related to the connection close callback, describe the reason for the closing of the connection.
- Sys::Virt::CLOSE_REASON_CLIENT
-
The client application requested the connection be closed
- Sys::Virt::CLOSE_REASON_EOF
-
End-of-file was encountered reading data from the connection
- Sys::Virt::CLOSE_REASON_ERROR
-
An I/O error was encountered reading/writing data from/to the connection
- Sys::Virt::CLOSE_REASON_KEEPALIVE
-
The connection keepalive timer triggered due to lack of response from the server
CPU STATS CONSTANTS
The following constants provide the names of known CPU stats fields
- Sys::Virt::NODE_CPU_STATS_IDLE
-
Time spent idle
- Sys::Virt::NODE_CPU_STATS_IOWAIT
-
Time spent waiting for I/O to complete
- Sys::Virt::NODE_CPU_STATS_KERNEL
-
Time spent executing kernel code
- Sys::Virt::NODE_CPU_STATS_USER
-
Time spent executing user code
- Sys::Virt::NODE_CPU_STATS_INTR
-
Time spent processing interrupts
- Sys::Virt::NODE_CPU_STATS_UTILIZATION
-
Percentage utilization of the CPU.
MEMORY STAS CONSTANTS
The following constants provide the names of known memory stats fields
- Sys::Virt::NODE_MEMORY_STATS_BUFFERS
-
The amount of memory consumed by I/O buffers
- Sys::Virt::NODE_MEMORY_STATS_CACHED
-
The amount of memory consumed by disk cache
- Sys::Virt::NODE_MEMORY_STATS_FREE
-
The amount of free memory
- Sys::Virt::NODE_MEMORY_STATS_TOTAL
-
The total amount of memory
IP address constants
The following constants are used to interpret IP address types
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