Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.32.0			  2013-07-30			  Sys::Virt(3)

NAME | SYNOPSIS | DESCRIPTION | ERROR HANDLING | METHODS | CONSTANTS | BUGS | AUTHORS | COPYRIGHT | LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Sys::Virt&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help