Sys::Virt(3pm)

1Sys::Virt(3)          User Contributed Perl Documentation         Sys::Virt(3)
2
3
4

NAME

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

SYNOPSIS

9         my $vmm = Sys::Virt->new(address => $addr);
10
11         my @domains = $vmm->list_domains();
12
13         foreach my $dom (@domains) {
14           print "Domain ", $dom->get_id, " ", $dom->get_name, "\n";
15         }
16

DESCRIPTION

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

ERROR HANDLING

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

METHODS

30       my $vmm = Sys::Virt->new(address => $address, readonly => $ro);
31           Attach to the virtual machine monitor with the address of
32           "address". The address parameter may be omitted, in which case the
33           default connection made will be to the local Xen hypervisor. In the
34           future it wil be possible to specify explicit addresses for other
35           types of hypervisor connection.  If the optional "readonly" parame‐
36           ter is supplied, then an unprivileged connection to the VMM will be
37           attempted. If it is not supplied, then it defaults to making a
38           fully privileged connection to the VMM. This in turn requires that
39           the calling application be running as root.
40
41       my $dom = $vmm->create_domain($xml);
42           Create a new domain based on the XML description passed into the
43           $xml parameter. The returned object is an instance of the
44           Sys::Virt::Domain class. This method is not available with unprivi‐
45           leged connections to the VMM.
46
47       my $dom = $vmm->define_domain($xml);
48           Defines, but does not start, a new domain based on the XML descrip‐
49           tion passed into the $xml parameter. The returned object is an
50           instance of the Sys::Virt::Domain class. This method is not avail‐
51           able with unprivileged connections to the VMM. The define can be
52           later started by calling the "create" method on the returned
53           "Sys::Virt::Domain" object.
54
55       my @doms = $vmm->list_domains()
56           Return a list of all domains currently known to the VMM. The ele‐
57           ments in the returned list are instances of the Sys::Virt::Domain
58           class.
59
60       my $dom = $vmm->get_domain_by_name($name)
61           Return the domain with a name of $name. The returned object is an
62           instance of the Sys::Virt::Domain class.
63
64       my $dom = $vmm->get_domain_by_id($id)
65           Return the domain with a local id of $id. The returned object is an
66           instance of the Sys::Virt::Domain class.
67
68       my $dom = $vmm->get_domain_by_uuid($uuid)
69           Return the domain with a globally unique id of $uuid. The returned
70           object is an instance of the Sys::Virt::Domain class.
71
72       $vmm->restore_domain($savefile)
73           Recreate a domain from the saved state file given in the $savefile
74           parameter.
75
76       my $type = $vmm->get_type()
77           Return the type of virtualization backend accessed by this VMM
78           object. Currently the only supported type is "Xen".
79
80       my $ver = $vmm->get_version()
81           Return the complete version number as a string encoded in the for‐
82           mula "(major * 1000000) + (minor * 1000) + micro".
83
84       my $ver = $vmm->get_major_version
85           Return the major version number of the libvirt library.
86
87       my $ver = $vmm->get_minor_version
88           Return the minor version number of the libvirt library.
89
90       my $ver = $vmm->get_micro_version
91           Return the micro version number of the libvirt library.
92
93       my $info = $con->get_node_info()
94           Returns a hash reference summarising the capabilities of the host
95           node. The elements of the hash are as follows:
96
97           memory
98               The amount of physical memory in the host
99
100           model
101               The model of the CPU, eg x86_64
102
103           cpus
104               The total number of logical CPUs
105
106           mhz The peak MHZ of the CPU
107
108           nodes
109               The number of NUMA cells
110
111           sockets
112               The number of CPU sockets
113
114           cores
115               The number of cores per socket
116
117           threads
118               The number of threads per core
119

BUGS

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

AUTHORS

125       Daniel P. Berrange <berrange@redhat.com>
126

COPYRIGHT / LICENSE

128       Copyright (C) 2006 Red Hat
129
130       Sys::Virt is distributed under the terms of the GPLv2 or later.
131