NAME

Sys::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 neccessary 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 neccessary 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 $dom = $vmm->create_domain($xml);

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.

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)

Return the number of host devices known to the VMM. This can be used as the maxids parameter to list_node_device_names. The optional capability parameter allows the list to be restricted to only devices with a particular capability type.

my @netNames = $vmm->list_node_device_names($capability, $maxnames)

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 optional capability parameter allows the list to be restricted to only devices with a particular capability type.

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 $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 $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 can usually be left as zero. The return scalar is an XML document describing the discovered storage pool sources.

$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 $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 $info = $con->get_node_info()

Returns a hash reference summarising the capabilities of the host node. The elements of the hash are as follows:

$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 paramters, 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.

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

$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

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

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)