NAME

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

SYNOPSIS

  my $vmm = Sys::Virt->new(address => $addr);

  my @domains = $vmm->list_domains();

  foreach my $dom (@domains) {
    print "Domain ", $dom->get_id, " ", $dom->get_name, "\n";
  }

DESCRIPTION

The Sys::Virt module provides a Perl XS binding to the libvirt virtual machine management APIs. This allows machines running within arbitrary virtualization containers to be managed with a consistent API.

ERROR HANDLING

Any operations in the Sys::Virt API which have failure scenarios will result in an instance of the Sys::Virt::Error module being thrown. To catch these errors, simply wrap the method in an eval block. For details of the information contained in the error objects, consult the Sys::Virt::Error manual page.

METHODS

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

Attach to the virtual machine monitor with the address of address. The address parameter may be omitted, in which case the default connection made will be to the local Xen hypervisor. In the future it wil be possible to specify explicit addresses for other types of hypervisor connection. 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. THis in turn requires that the calling application be running as root.

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

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

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

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

my @doms = $vmm->list_domains()

Return a list of all domains currently known to the VMM. The elements in the returned list are instances of the Sys::Virt::Domain class.

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

$vmm->restore_domain($savefile)

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

my $type = $vmm->get_type()

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

my $ver = $vmm->get_version()

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

my $ver = $vmm->get_major_version

Return the major version number of the libvirt library

my $ver = $vmm->get_minor_version

Return the minor version number of the libvirt library

my $ver = $vmm->get_micro_version

Return the micro version number of the libvirt library

my $info = $con->get_node_info()

Returns a hash reference summarising the capabilities of the host node. The elements of the hash ar

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

BUGS

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

AUTHORS

Daniel P. Berrange <berrange@redhat.com>

COPYRIGHT / LICENSE

Copyright (C) 2006 Red Hat

Sys::Virt is distributed under the terms of the GPLv2 or later

SEE ALSO

Sys::Virt::Domain, Sys::Virt::Error, http://libvirt.org