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:

  eval { my $vmm = Sys::Virt->new(address => $addr); };
  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.

METHODS¶

my $vmm = Sys::Virt->new(uri => $uri, readonly => $ro, flags => $flags);

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:

    my $address  = "qemu+tcp://192.168.122.1/system";
    my $username = "test";
    my $password = "123456";
    my $con = Sys::Virt->new(address => $address,
                             auth => 1,
                             credlist => [
                               Sys::Virt::CRED_AUTHNAME,
                               Sys::Virt::CRED_PASSPHRASE,
                             ],
                             callback =>
         sub {
               my $creds = shift;
               foreach my $cred (@{$creds}) {
                  if ($cred->{type} == Sys::Virt::CRED_AUTHNAME) {
                      $cred->{result} = $username;
                  }
                  if ($cred->{type} == Sys::Virt::CRED_PASSPHRASE) {
                      $cred->{result} = $password;
                  }
               }
               return 0;
         });

my $st = $vmm->new_stream($flags)

Create a new stream, with the given flags

my $dom = $vmm->create_domain($xml, $flags);

Create a new domain based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::Domain class. This method is not available with unprivileged connections to the VMM. The $flags parameter accepts one of the DOMAIN CREATION constants documented in Sys::Virt::Domain, and defaults to 0 if omitted.

my $dom = $vmm->define_domain($xml);

Defines, but does not start, a new domain based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::Domain class. This method is not available with unprivileged connections to the VMM. The defined domain can be later started by calling the "create" method on the returned "Sys::Virt::Domain" object.

my $dom = $vmm->create_network($xml);

Create a new network based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::Network class. This method is not available with unprivileged connections to the VMM.

my $dom = $vmm->define_network($xml);

Defines, but does not start, a new network based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::Network class. This method is not available with unprivileged connections to the VMM. The defined network can be later started by calling the "create" method on the returned "Sys::Virt::Network" object.

my $dom = $vmm->create_storage_pool($xml);

Create a new storage pool based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::StoragePool class. This method is not available with unprivileged connections to the VMM.

my $dom = $vmm->define_storage_pool($xml);

Defines, but does not start, a new storage pol based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::StoragePool class. This method is not available with unprivileged connections to the VMM. The defined pool can be later started by calling the "create" method on the returned "Sys::Virt::StoragePool" object.

my $dom = $vmm->create_interface($xml);

Create a new interface based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::Interface class. This method is not available with unprivileged connections to the VMM.

my $dom = $vmm->define_interface($xml);

Defines, but does not start, a new interface based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::Interface class. This method is not available with unprivileged connections to the VMM. The defined interface can be later started by calling the "create" method on the returned "Sys::Virt::Interface" object.

my $dom = $vmm->create_node_device($xml);

Create a new virtual node device based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::NodeDevice class. This method is not available with unprivileged connections to the VMM.

my @doms = $vmm->list_domains()

Return a list of all 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.

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. This method requires O(n) RPC calls, so the "list_all_domains" method is recommended as a more efficient alternative.

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 @doms = $vmm->list_all_domains($flags)

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.

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. This method requires O(n) RPC calls, so the "list_all_networks" method is recommended as a more efficient alternative.

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. This method requires O(n) RPC calls, so the "list_all_networks" method is recommended as a more efficient alternative.

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 @nets = $vmm->list_all_networks($flags)

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.

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. This method requires O(n) RPC calls, so the "list_all_storage_pools" method is recommended as a more efficient alternative.

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. This method requires O(n) RPC calls, so the "list_all_storage_pools" method is recommended as a more efficient alternative.

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 @pools = $vmm->list_all_storage_pools($flags)

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.

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. This method requires O(n) RPC calls, so the "list_all_node_devices" method is recommended as a more efficient alternative.

my $nnames = $vmm->num_of_node_devices($capability[, $flags])

Return the number of host devices known to the VMM. This can be used as the "maxids" parameter to "list_node_device_names". The "capability" parameter allows the list to be restricted to only devices with a particular capability type, and should be left as "undef" if the full list is required. The optional <flags> parameter is currently unused and defaults to 0 if omitted.

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

Return a list of all host device names currently known to the VMM. The names can be used with the "get_node_device_by_name" method. The "capability" parameter allows the list to be restricted to only devices with a particular capability type, and should be left as "undef" if the full list is required. The optional <flags> parameter is currently unused and defaults to 0 if omitted.

my @devs = $vmm->list_all_node_devices($flags)

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.

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. This method requires O(n) RPC calls, so the "list_all_interfaces" method is recommended as a more efficient alternative.

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. This method requires O(n) RPC calls, so the "list_all_interfaces" method is recommended as a more efficient alternative.

my $nnames = $vmm->num_of_defined_interfaces()

Return the number of inactive interfaces known to the VMM. This can be used as the "maxnames" parameter to "list_defined_interface_names".

my @names = $vmm->list_defined_interface_names($maxnames)

Return a list of inactive interface names currently known to the VMM. The names can be used with the "get_interface_by_name" method.

my @ifaces = $vmm->list_all_interfaces($flags)

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.

my @ifaces = $vmm->list_secrets()

Return a list of all secrets currently known to the VMM. The elements in the returned list are instances of the Sys::Virt::Secret class. This method requires O(n) RPC calls, so the "list_all_secrets" method is recommended as a more efficient alternative.

my $nuuids = $vmm->num_of_secrets()

Return the number of secrets known to the VMM. This can be used as the "maxuuids" parameter to "list_secrets".

my @uuids = $vmm->list_secret_uuids($maxuuids)

Return a list of all secret uuids currently known to the VMM. The uuids can be used with the "get_secret_by_uuid" method.

my @secrets = $vmm->list_all_secrets($flags)

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.

my @nets = $vmm->list_nwfilters()

Return a list of all nwfilters currently known to the VMM. The elements in the returned list are instances of the Sys::Virt::NWFilter class. This method requires O(n) RPC calls, so the "list_all_nwfilters" method is recommended as a more efficient alternative.

my $nnames = $vmm->num_of_nwfilters()

Return the number of running nwfilters known to the VMM. This can be used as the "maxids" parameter to "list_nwfilter_names".

my @filterNames = $vmm->list_nwfilter_names($maxnames)

Return a list of all nwfilter names currently known to the VMM. The names can be used with the "get_nwfilter_by_name" method.

my @nwfilters = $vmm->list_all_nwfilters($flags)

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.

$vmm->define_save_image_xml($file, $dxml, $flags=0)

Update the XML associated with a virtual machine's save image. The $file parameter is the fully qualified path to the save image XML, while $dxml is the new XML document to write. The $flags parameter is currently unused and defaults to zero.

$xml = $vmm->get_save_image_xml_description($file, $flags=1)

Retrieve the current XML configuration associated with the virtual machine's save image identified by $file. The $flags parameter is currently unused and defaults to zero.

my $dom = $vmm->get_domain_by_name($name)

Return the domain with a name of $name. The returned object is an instance of the Sys::Virt::Domain class.

my $dom = $vmm->get_domain_by_id($id)

Return the domain with a local id of $id. The returned object is an instance of the Sys::Virt::Domain class.

my $dom = $vmm->get_domain_by_uuid($uuid)

Return the domain with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::Domain class.

my $net = $vmm->get_network_by_name($name)

Return the network with a name of $name. The returned object is an instance of the Sys::Virt::Network class.

my $net = $vmm->get_network_by_uuid($uuid)

Return the network with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::Network class.

my $pool = $vmm->get_storage_pool_by_name($name)

Return the storage pool with a name of $name. The returned object is an instance of the Sys::Virt::StoragePool class.

my $pool = $vmm->get_storage_pool_by_uuid($uuid)

Return the storage pool with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::StoragePool class.

my $pool = $vmm->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 $vol = $vmm->get_storage_volume_by_path($path)

Return the storage volume with a location of $path. The returned object is an instance of the Sys::Virt::StorageVol class.

my $vol = $vmm->get_storage_volume_by_key($key)

Return the storage volume with a globally unique id of $key. The returned object is an instance of the Sys::Virt::StorageVol class.

my $dev = $vmm->get_node_device_by_name($name)

Return the node device with a name of $name. The returned object is an instance of the Sys::Virt::NodeDevice class.

my $iface = $vmm->get_interface_by_name($name)

Return the interface with a name of $name. The returned object is an instance of the Sys::Virt::Interface class.

my $iface = $vmm->get_interface_by_mac($mac)

Return the interface with a MAC address of $mac. The returned object is an instance of the Sys::Virt::Interface class.

my $sec = $vmm->get_secret_by_uuid($uuid)

Return the secret with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::Secret class.

my $sec = $vmm->get_secret_by_usage($usageType, $usageID)

Return the secret with a usage type of $usageType, identified by $usageID. The returned object is an instance of the Sys::Virt::Secret class.

my $dom = $vmm->get_nwfilter_by_name($name)

Return the domain with a name of $name. The returned object is an instance of the Sys::Virt::NWFilter class.

my $dom = $vmm->get_nwfilter_by_uuid($uuid)

Return the nwfilter with a globally unique id of $uuid. The returned object is an instance of the Sys::Virt::NWFilter class.

my $xml = $vmm->find_storage_pool_sources($type, $srcspec[, $flags])

Probe for available storage pool sources for the pool of type $type. The $srcspec parameter can be "undef", or a parameter to refine the discovery process, for example a server hostname for NFS discovery. The $flags parameter is optional, and if omitted defaults to zero. The returned scalar is an XML document describing the discovered storage pool sources.

$vmm->interface_change_begin($flags)

Begin a transaction for changing the configuration of one or more network interfaces

$vmm->interface_change_commit($flags)

Complete a transaction for changing the configuration of one or more network interfaces

$vmm->interface_change_rollback($flags)

Abort a transaction for changing the configuration of one or more network interfaces

$vmm->restore_domain($savefile)

Recreate a domain from the saved state file given in the $savefile parameter.

$vmm->get_max_vcpus($domtype)

Return the maximum number of vcpus that can be configured for a domain of type $domtype

my $hostname = $vmm->get_hostname()

Return the name of the host with which this connection is associated.

my $uri = $vmm->get_uri()

Return the URI associated with the open connection. This may be different from the URI used when initially connecting to libvirt, when 'auto-probing' or drivers occurrs.

my $xml = $vmm->get_sysinfo()

Return an XML documenting representing the host system information, typically obtained from SMBIOS tables.

my $type = $vmm->get_type()

Return the type of virtualization backend accessed by this VMM object. Currently the only supported type is "Xen".

my $xml = $vmm->domain_xml_from_native($format, $config);

Convert the native hypervisor configuration $config which is in format <$format> into libvirrt domain XML. Valid values of $format vary between hypervisor drivers.

my $config = $vmm->domain_xml_to_native($format, $xml)

Convert the libvirt domain XML configuration $xml to a native hypervisor configuration in format $format

my $ver = $vmm->get_version()

Return the complete version number as a string encoded in the formula "(major * 1000000) + (minor * 1000) + micro".

my $ver = $vmm->get_major_version

Return the major version number of the libvirt library.

my $ver = $vmm->get_minor_version

Return the minor version number of the libvirt library.

my $ver = $vmm->get_micro_version

Return the micro version number of the libvirt library.

my $ver = $vmm->get_library_version

Return the version number of the API associated with the active connection. This differs from "get_version" in that if the connection is to a remote libvirtd daemon, it will return the API version of the remote libvirt, rather than the local client.

$conn->is_secure()

Returns a true value if the current connection is secure against network interception. This implies either use of UNIX sockets, or encryption with a TCP stream.

$conn->is_encrypted()

Returns a true value if the current connection data stream is encrypted.

$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:

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 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

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 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

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.

$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 notificaitons of domain state change events. Only a single callback can be registered with each connection instance. The callback will be invoked with four parameters, an instance of "Sys::Virt" for the connection, an instance of "Sys::Virt::Domain" for the domain changing state, and a "event" and "detail" arguments, corresponding to the event constants defined in the "Sys::Virt::Domain" module. Before discarding the connection object, the callback must be deregistered, otherwise the connection object memory will never be released in garbage collection.

$conn->domain_event_deregister()

Unregister a callback, allowing the connection object to be garbage collected.

$callback = $conn->domain_event_register_any($dom, $eventID, $callback)

Register a callback to received notifications of domain events. The $dom parameter can be "undef" to request events on all known domains, or a specific "Sys::Virt::Domain" object to filter events. The $eventID parameter is one of the EVENT ID constants described later in this document. The $callback is a subroutine reference that will receive the events.

All callbacks receive a "Sys::Virt" connection as the first parameter and a "Sys::Virt::Domain" object indiciating the domain on which the event occurred as the second parameter. Subsequent parameters vary according to the event type

$conn->domain_event_deregister_any($callbackID)

Unregister a callback, associated with the $callbackID previously obtained from "domain_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 the "CLOSE 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 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') and "doi" specifying the 'domain of interpretation' for security labels.

my $xml = $con->get_capabilities();

Returns an XML document describing the hypervisor capabilities

my $result = $con->compare_cpu($xml, $flags=0);

Checks whether the CPU definition in $xml is compatible with the current hypervisor connection. This can be used to determine whether it is safe to migrate a guest to this host. The returned result is one of the constants listed later

$mem = $con->get_node_free_memory();

Returns the current free memory on the host

@mem = $con->get_node_cells_free_memory($start, $end);

Returns the free memory on each NUMA cell between $start and $end.

CONSTANTS¶

The following sets of constants are useful when dealing with APIs in this package

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"