Sys::Virt - Represent and manage a libvirt hypervisor connection
my $vmm = Sys::Virt->new(uri => $uri); my @domains = $vmm->list_domains(); foreach my $dom (@domains) { print "Domain ", $dom->get_id, " ", $dom->get_name, "\n"; }
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.
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 $vmm = Sys::Virt->new(uri => $uri); }; if ($@) { print 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.
Attach to the virtualization host identified by uri. The uri parameter may be omitted, in which case the default connection made will be to the local Xen hypervisor. Some example URIs include:
uri
Xen on the local machine
Dummy "in memory" driver for test suites
System-wide driver for QEMU / KVM virtualization
Per-user driver for QEMU virtualization
System-wide QEMU driver on somehost using TLS security
somehost
Xen driver on somehost using TCP / SASL security
For further details consult http://libvirt.org/uri.html
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.
readonly
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
auth
credlist
callback
type
prompt
challenge
result
As a simple example returning hardcoded credentials
my $uri = "qemu+tcp://192.168.122.1/system"; 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 the uri parameter. The use of uri is recommended for all newly written code.
address
Create a new stream, with the given 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.
$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 $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.
$fds
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.
create
Sys::Virt::Domain
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.
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.
Sys::Virt::Network
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.
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.
Sys::Virt::StoragePool
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.
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.
Sys::Virt::Interface
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.
Return a list of all running domains currently known to the VMM. 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.
list_all_domains
Return the number of running domains known to the VMM. This can be used as the maxids parameter to list_domain_ids.
maxids
list_domain_ids
Return a list of all domain IDs currently known to the VMM. The IDs can be used with the get_domain_by_id method.
get_domain_by_id
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. This method requires O(n) RPC calls, so the list_all_domains method is recommended as a more efficient alternative.
Return the number of running domains known to the VMM. This can be used as the maxnames parameter to list_defined_domain_names.
maxnames
list_defined_domain_names
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.
get_domain_by_name
Return a list of all domains currently known to the VMM, 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.
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. This method requires O(n) RPC calls, so the list_all_networks method is recommended as a more efficient alternative.
list_all_networks
Return the number of running networks known to the VMM. This can be used as the maxids parameter to list_network_ids.
list_network_ids
Return a list of all network names currently known to the VMM. The names can be used with the get_network_by_name method.
get_network_by_name
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. This method requires O(n) RPC calls, so the list_all_networks method is recommended as a more efficient alternative.
Return the number of running networks known to the host. This can be used as the maxnames parameter to list_defined_network_names.
list_defined_network_names
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.
Return a list of all networks currently known to the VMM, 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.
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.
list_all_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.
list_storage_pool_names
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.
get_network_by_id
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.
Return the number of running networks known to the host. This can be used as the maxnames parameter to list_defined_storage_pool_names.
list_defined_storage_pool_names
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.
get_storage_pool_by_name
Return a list of all storage pools currently known to the VMM, 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.
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 the list_all_node_devices method is recommended as a more efficient alternative.
capability
list_all_node_devices
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.
list_node_device_names
undef
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.
get_node_device_by_name
Return a list of all node devices currently known to the VMM. 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.
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. This method requires O(n) RPC calls, so the list_all_interfaces method is recommended as a more efficient alternative.
list_all_interfaces
Return the number of running interfaces known to the VMM. This can be used as the maxnames parameter to list_interface_names.
list_interface_names
Return a list of all interface names currently known to the VMM. The names can be used with the get_interface_by_name method.
get_interface_by_name
Return the number of inactive interfaces known to the VMM. This can be used as the maxnames parameter to list_defined_interface_names.
list_defined_interface_names
Return a list of inactive interface names currently known to the VMM. The names can be used with the get_interface_by_name method.
Return a list of all interfaces currently known to the VMM, 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.
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. This method requires O(n) RPC calls, so the list_all_secrets method is recommended as a more efficient alternative.
list_all_secrets
Return the number of secrets known to the VMM. This can be used as the maxuuids parameter to list_secrets.
maxuuids
list_secrets
Return a list of all secret uuids currently known to the VMM. The uuids can be used with the get_secret_by_uuid method.
get_secret_by_uuid
Return a list of all secrets currently known to the VMM. 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.
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. This method requires O(n) RPC calls, so the list_all_nwfilters method is recommended as a more efficient alternative.
list_all_nwfilters
Return the number of running nwfilters known to the VMM. This can be used as the maxids parameter to list_nwfilter_names.
list_nwfilter_names
Return a list of all nwfilter names currently known to the VMM. The names can be used with the get_nwfilter_by_name method.
get_nwfilter_by_name
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. The $flags parameter is currently unused and defaults to zero.
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.
$file
$dxml
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.
Return the domain with a name of $name. The returned object is an instance of the Sys::Virt::Domain class.
$name
Return the domain with a local id of $id. The returned object is an instance of the Sys::Virt::Domain class.
$id
Return the domain with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::Domain class.
$uuid
Return the network with a name of $name. The returned object is an instance of the Sys::Virt::Network class.
Return the network with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::Network class.
Return the storage pool with a name of $name. The returned object is an instance of the Sys::Virt::StoragePool class.
Return the storage pool with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::StoragePool class.
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.
$vol
Return the storage volume with a location of $path. The returned object is an instance of the Sys::Virt::StorageVol class.
$path
Return the storage volume with a globally unique id of $key. The returned object is an instance of the Sys::Virt::StorageVol class.
$key
Return the node device with a name of $name. The returned object is an instance of the Sys::Virt::NodeDevice class.
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.
$wwnn
$wwpn
Return the interface with a name of $name. The returned object is an instance of the Sys::Virt::Interface class.
Return the interface with a MAC address of $mac. The returned object is an instance of the Sys::Virt::Interface class.
$mac
Return the secret with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::Secret class.
Return the secret with a usage type of $usageType, identified by $usageID. The returned object is an instance of the Sys::Virt::Secret class.
$usageType
$usageID
Return the domain with a name of $name. The returned object is an instance of the Sys::Virt::NWFilter class.
Return the nwfilter with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::NWFilter class.
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.
$type
$srcspec
Begin a transaction for changing the configuration of one or more network interfaces
Complete a transaction for changing the configuration of one or more network interfaces
Abort a transaction for changing the configuration of one or more network interfaces
Recreate a domain from the saved state file given in the $savefile parameter.
$savefile
Return the maximum number of vcpus that can be configured for a domain of type $domtype
$domtype
Return the name of the host with which this connection is associated.
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.
Return an XML documenting representing the host system information, typically obtained from SMBIOS tables.
Return the type of virtualization backend accessed by this VMM object. Currently the only supported type is Xen.
Xen
Convert the native hypervisor configuration $config which is in format <$format> into libvirrt domain XML. Valid values of $format vary between hypervisor drivers.
$config
$format
Convert the libvirt domain XML configuration $xml to a native hypervisor configuration in format $format
Return the complete version number as a string encoded in the formula (major * 1000000) + (minor * 1000) + micro.
(major * 1000000) + (minor * 1000) + micro
Return the major version number of the libvirt library.
Return the minor version number of the libvirt library.
Return the micro version number of the libvirt library.
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.
get_version
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.
Returns a true value if the current connection data stream is encrypted.
Returns a true value if the connection is alive, as determined by keep-alive packets or other recent RPC traffic.
Change the operation of the keep alive protocol to send $count packets spaced $interval seconds apart before considering the connection dead.
$count
$interval
Returns a hash reference summarising the capabilities of the host node. The elements of the hash are as follows:
The amount of physical memory in the host
The model of the CPU, eg x86_64
The total number of logical CPUs.
The peak MHZ of the CPU
The number of NUMA cells
The number of CPU sockets
The number of cores per socket
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.
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 regardles 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 the unpack method as follows:
totcpus
onlinemap
totonline
unpack
my @onlinemap = split(//, unpack("b*", $onlinemap));
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 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
Sys::Virt::NODE_CPU_STATS_ALL_CPUS
$cpuNum
The time spent in kernelspace
The time spent in userspace
The idle time
The I/O wait time
The overall percentage utilization.
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 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
Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS
$cellNum
The total memory
The free memory
The memory consumed by buffers
The memory consumed for cache
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.
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.
$params
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.
$target
$duration
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.
Sys::Virt
event
detail
Unregister a callback, allowing the connection object to be garbage collected.
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.
$dom
$eventID
$callback
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
Extra event and detail parameters defining the lifecycle transition that occurred.
No extra parameters
The utcoffset gives the offset from UTC in seconds
utcoffset
The action defines the action that is taken as a result of the watchdog triggering. One of the WATCHDOG constants described later
action
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
srcPath
devAlias
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.
phase
local
remote
authScheme
identities
The return value is a unique callback ID that must be used when unregistering the event.
Unregister a callback, associated with the $callbackID previously obtained from domain_event_register_any.
$callbackID
domain_event_register_any
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 the CLOSE REASON CONSTANTS listed later in this document.
$conn
CLOSE REASON CONSTANTS
Remove the previously registered close callback.
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
Expand the CPU definition to list all feature flags, even those implied by the model name.
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.
$arch
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.
model
doi
Returns an XML document describing the hypervisor capabilities
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
Returns the current free memory on the host
Returns the free memory on each NUMA cell between $start and $end.
$start
$end
The following sets of constants are useful when dealing with APIs in this package
When opening a connection the following constants can be used:
Request a read-only connection
Prevent the resolution of URI aliases
When providing authentication callbacks, the following constants indicate the type of credential being requested
Identity to act as
Identity to authorize as
Client supplies a nonce
Authentication realm
Challenge response non-secret
Challenge response secret
Passphrase secret
RFC 1766 language code
Externally provided credential
This host is missing one or more CPU features in the CPU description
The host has an identical CPU description
The host offers a superset of the CPU descriptoon
Suspends to memory (equivalent of S3 on x86 architectures)
Suspends to disk (equivalent of S5 on x86 architectures)
Suspends to memory and disk (equivalent of S3+S5 on x86 architectures)
Request statistics for all CPUs
Request statistics for all memory cells
The following constants are used to name memory parameters of the node
How many times all mergeable areas have been scanned.
How many the shared memory pages are being used.
How many sites are sharing the pages
How many present pages to scan before the shared memory service goes to sleep
How many pages unique but repeatedly checked for merging.
How many pages changing too fast to be placed in a tree.
How many milliseconds the shared memory service should sleep before next scan.
The following constants related to the connection close callback, describe the reason for the closing of the connection.
The client application requested the connection be closed
End-of-file was encountered reading data from the connection
An I/O error was encountered reading/writing data from/to the connection
The connection keepalive timer triggered due to lack of response from the server
The following constants provide the names of known CPU stats fields
Time spent idle
Time spent waiting for I/O to complete
Time spent executing kernel code
Time spent executing user code
Percentage utilization of the CPU.
The following constants provide the names of known memory stats fields
The amount of memory consumed by I/O buffers
The amount of memory consumed by disk cache
The amount of free memory
The total amount of memory
Hopefully none, but the XS code needs to be audited to ensure it is not leaking memory.
Daniel P. Berrange <berrange@redhat.com>
Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange
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.
Sys::Virt::Domain, Sys::Virt::Network, Sys::Virt::StoragePool, Sys::Virt::StorageVol, Sys::Virt::Error, http://libvirt.org
http://libvirt.org
To install Sys::Virt, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sys::Virt
CPAN shell
perl -MCPAN -e shell install Sys::Virt
For more information on module installation, please visit the detailed CPAN module installation guide.