👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

CentOS 7.0 - man page for sys::virt (centos section 3)

Sys::Virt(3)		       User Contributed Perl Documentation		     Sys::Virt(3)

NAME
       Sys::Virt - Represent and manage a libvirt hypervisor connection

SYNOPSIS
	 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";
	 }

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

METHODS
       my $vmm = Sys::Virt->new(uri => $uri, readonly => $ro, flags => $flags);
	   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:

	   xen:///
	       Xen on the local machine

	   test:///default
	       Dummy "in memory" driver for test suites

	   qemu:///system
	       System-wide driver for QEMU / KVM virtualization

	   qemu:///session
	       Per-user driver for QEMU virtualization

	   qemu+tls://somehost/system
	       System-wide QEMU driver on "somehost" using TLS security

	   xen+tcp://somehost/
	       Xen driver on "somehost" using TCP / SASL security

	   For further details consult "http://libvirt.org/uri.html"

	   If the optional "readonly" parameter is supplied, then an unprivileged connection to
	   the VMM will be attempted. If it is not supplied, then it defaults to making a fully
	   privileged connection to the VMM. If the calling application is not running as root,
	   it may be necessary to provide authentication callbacks.

	   If the optional "auth" parameter is set to a non-zero value, authentication will be
	   enabled during connection, using the default set of credential gathering callbacks.
	   The default callbacks prompt for credentials on the console, so are not suitable for
	   graphical applications. For such apps a custom implementation should be supplied. The
	   "credlist" parameter should be an array reference listing the set of credential types
	   that will be supported. The credential constants in this module can be used as values
	   in this list. The "callback" parameter should be a subroutine reference containing the
	   code necessary to gather the credentials. When invoked it will be supplied with a
	   single parameter, a array reference of requested credentials. The elements of the
	   array are hash references, with keys "type" giving the type of credential, "prompt"
	   giving a user descriptive user prompt, "challenge" giving name of the credential
	   required. The answer should be collected from the user, and returned by setting the
	   "result" key. This key may already be set with a default result if applicable

	   As a simple example returning hardcoded credentials

	       my $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.

       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->create_domain_with_files($xml, $fds, $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.

       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 $dev = $vmm->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 = $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:

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

	     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 cummulative information for all CPUs in the host. If $cpuNum is zero or
	   larger, it returns information just for the specified number. The $flags parameter is
	   currently unused and defaults to zero. The fields in the returned hash reference are

	   kernel
	       The time spent in kernelspace

	   user
	       The time spent in userspace

	   idle
	       The idle time

	   iowait
	       The I/O wait time

	   utilization
	       The overall percentage utilization.

       my $info = $con->get_node_memory_stats($cellNum=-1, $flags=0)
	   Returns a hash reference providing information about the host memory statistics. If
	   <$cellNum> is omitted, it defaults to "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

	   total
	       The total memory

	   free
	       The free memory

	   buffers
	       The memory consumed by buffers

	   cached
	       The memory consumed for cache

       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

	   EVENT_ID_LIFECYCLE
	       Extra "event" and "detail" parameters defining the lifecycle transition that
	       occurred.

	   EVENT_ID_REBOOT
	       No extra parameters

	   EVENT_ID_RTC_CHANGE
	       The "utcoffset" gives the offset from UTC in seconds

	   EVENT_ID_WATCHDOG
	       The "action" defines the action that is taken as a result of the watchdog
	       triggering. One of the WATCHDOG constants described later

	   EVENT_ID_IO_ERROR
	       The "srcPath" is the file on the host which had the error.  The "devAlias" is the
	       unique device alias from the guest configuration associated with "srcPath". The
	       "action" is the action taken as a result of the error, one of the IO ERROR
	       constants described later

	   EVENT_ID_GRAPHICS
	       The "phase" is the stage of the connection, one of the GRAPHICS PHASE constants
	       described later. The "local" and "remote" parameters follow with the details of
	       the local and remote network addresses. The "authScheme" describes how the user
	       was authenticated (if at all). Finally "identities" is an array ref containing
	       authenticated identities for the user, if any.

	   The return value is a unique callback ID that must be used when unregistering the
	   event.

       $conn->domain_event_deregister_any($callbackID)
	   Unregister a callback, associated with the $callbackID previously obtained from
	   "domain_event_register_any".

       $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

   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

   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
       Sys::Virt::NODE_CPU_STATS_ALL_CPUS
	   Request statistics for all CPUs

   NODE MEMORY CONSTANTS
       Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS
	   Request statistics for all memory cells

   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.

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

BUGS
       Hopefully none, but the XS code needs to be audited to ensure it is not leaking memory.

AUTHORS
       Daniel P. Berrange <berrange@redhat.com>

COPYRIGHT
       Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange

LICENSE
       This program is free software; you can redistribute it and/or modify it under the terms of
       either the GNU General Public License as published by the Free Software Foundation (either
       version 2 of the License, or at your option any later version), or, the Artistic License,
       as specified in the Perl README file.

SEE ALSO
       Sys::Virt::Domain, Sys::Virt::Network, Sys::Virt::StoragePool, Sys::Virt::StorageVol,
       Sys::Virt::Error, "http://libvirt.org"

perl v5.16.3				    2013-07-30				     Sys::Virt(3)


All times are GMT -4. The time now is 01:36 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password