1Sys::Virt(3) User Contributed Perl Documentation Sys::Virt(3)
2
6 Sys::Virt - Represent and manage a libvirt hypervisor connection
7
9 my $vmm = Sys::Virt->new(address => $addr);
10 my @domains = $vmm->list_domains();
12 foreach my $dom (@domains) {
14 print "Domain ", $dom->get_id, " ", $dom->get_name, "\n";
15 }
16
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
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
30 my $vmm = Sys::Virt->new(uri => $uri, readonly => $ro);
31 Attach to the virtual machine monitor with the address of
32 "address". The uri parameter may be omitted, in which case the
33 default connection made will be to the local Xen hypervisor. Some
34 example URIs include:
35 xen:///
37 Xen on the local machine
38 test:///default
40 Dummy "in memory" driver for test suites
41 qemu:///system
43 System-wide driver for QEMU / KVM virtualization
44 qemu:///session
46 Per-user driver for QEMU virtualization
47 qemu+tls://somehost/system
49 System-wide QEMU driver on "somehost" using TLS security
50 xen+tcp://somehost/
52 Xen driver on "somehost" using TCP / SASL security
53 For further details consult "http://libvirt.org/uri.html"
55 If the optional "readonly" parameter is supplied, then an
57 unprivileged connection to the VMM will be attempted. If it is not
58 supplied, then it defaults to making a fully privileged connection
59 to the VMM. If the calling application is not running as root, it
60 may be necessary to provide authentication callbacks.
61 If the optional "auth" parameter is set to a non-zero value,
63 authentication will be enabled during connection, using the default
64 set of credential gathering callbacks. The default callbacks prompt
65 for credentials on the console, so are not suitable for graphical
66 applications. For such apps a custom implementation should be
67 supplied. The "credlist" parameter should be an array reference
68 listing the set of credential types that will be supported. The
69 credential constants in this module can be used as values in this
70 list. The "callback" parameter should be a subroutine reference
71 containing the code necessary to gather the credentials. When
72 invoked it will be supplied with a single parameter, a array
73 reference of requested credentials. The elements of the array are
74 hash references, with keys "type" giving the type of credential,
75 "prompt" giving a user descriptive user prompt, "challenge" giving
76 name of the credential required. The answer should be collected
77 from the user, and returned by setting the "result" key. This key
78 may already be set with a default result if applicable
79 As a simple example returning hardcoded credentials
81 my $address = "qemu+tcp://192.168.122.1/system";
83 my $username = "test";
84 my $password = "123456";
85 my $con = Sys::Virt->new(address => $address,
87 auth => 1,
88 credlist => [
89 Sys::Virt::CRED_AUTHNAME,
90 Sys::Virt::CRED_PASSPHRASE,
91 ],
92 callback =>
93 sub {
94 my $creds = shift;
95 foreach my $cred (@{$creds}) {
97 if ($cred->{type} == Sys::Virt::CRED_AUTHNAME) {
98 $cred->{result} = $username;
99 }
100 if ($cred->{type} == Sys::Virt::CRED_PASSPHRASE) {
101 $cred->{result} = $password;
102 }
103 }
104 return 0;
105 });
106 my $dom = $vmm->create_domain($xml);
108 Create a new domain based on the XML description passed into the
109 $xml parameter. The returned object is an instance of the
110 Sys::Virt::Domain class. This method is not available with
111 unprivileged connections to the VMM.
112 my $dom = $vmm->define_domain($xml);
114 Defines, but does not start, a new domain based on the XML
115 description passed into the $xml parameter. The returned object is
116 an instance of the Sys::Virt::Domain class. This method is not
117 available with unprivileged connections to the VMM. The defined
118 domain can be later started by calling the "create" method on the
119 returned "Sys::Virt::Domain" object.
120 my $dom = $vmm->create_network($xml);
122 Create a new network based on the XML description passed into the
123 $xml parameter. The returned object is an instance of the
124 Sys::Virt::Network class. This method is not available with
125 unprivileged connections to the VMM.
126 my $dom = $vmm->define_network($xml);
128 Defines, but does not start, a new network based on the XML
129 description passed into the $xml parameter. The returned object is
130 an instance of the Sys::Virt::Network class. This method is not
131 available with unprivileged connections to the VMM. The defined
132 network can be later started by calling the "create" method on the
133 returned "Sys::Virt::Network" object.
134 my $dom = $vmm->create_storage_pool($xml);
136 Create a new storage pool based on the XML description passed into
137 the $xml parameter. The returned object is an instance of the
138 Sys::Virt::StoragePool class. This method is not available with
139 unprivileged connections to the VMM.
140 my $dom = $vmm->define_storage_pool($xml);
142 Defines, but does not start, a new storage pol based on the XML
143 description passed into the $xml parameter. The returned object is
144 an instance of the Sys::Virt::StoragePool class. This method is not
145 available with unprivileged connections to the VMM. The defined
146 pool can be later started by calling the "create" method on the
147 returned "Sys::Virt::StoragePool" object.
148 my $dom = $vmm->create_interface($xml);
150 Create a new interface based on the XML description passed into the
151 $xml parameter. The returned object is an instance of the
152 Sys::Virt::Interface class. This method is not available with
153 unprivileged connections to the VMM.
154 my $dom = $vmm->define_interface($xml);
156 Defines, but does not start, a new interface based on the XML
157 description passed into the $xml parameter. The returned object is
158 an instance of the Sys::Virt::Interface class. This method is not
159 available with unprivileged connections to the VMM. The defined
160 interface can be later started by calling the "create" method on
161 the returned "Sys::Virt::Interface" object.
162 my $dom = $vmm->create_node_device($xml);
164 Create a new virtual node device based on the XML description
165 passed into the $xml parameter. The returned object is an instance
166 of the Sys::Virt::NodeDevice class. This method is not available
167 with unprivileged connections to the VMM.
168 my @doms = $vmm->list_domains()
170 Return a list of all domains currently known to the VMM. The
171 elements in the returned list are instances of the
172 Sys::Virt::Domain class.
173 my $nids = $vmm->num_of_domains()
175 Return the number of running domains known to the VMM. This can be
176 used as the "maxids" parameter to "list_domain_ids".
177 my @domIDs = $vmm->list_domain_ids($maxids)
179 Return a list of all domain IDs currently known to the VMM. The IDs
180 can be used with the "get_domain_by_id" method.
181 my @doms = $vmm->list_defined_domains()
183 Return a list of all domains defined, but not currently running, on
184 the VMM. The elements in the returned list are instances of the
185 Sys::Virt::Domain class.
186 my $nnames = $vmm->num_of_defined_domains()
188 Return the number of running domains known to the VMM. This can be
189 used as the "maxnames" parameter to "list_defined_domain_names".
190 my @names = $vmm->list_defined_domain_names($maxnames)
192 Return a list of names of all domains defined, but not currently
193 running, on the VMM. The names can be used with the
194 "get_domain_by_name" method.
195 my @nets = $vmm->list_networks()
197 Return a list of all networks currently known to the VMM. The
198 elements in the returned list are instances of the
199 Sys::Virt::Network class.
200 my $nnames = $vmm->num_of_networks()
202 Return the number of running networks known to the VMM. This can be
203 used as the "maxids" parameter to "list_network_ids".
204 my @netNames = $vmm->list_network_names($maxnames)
206 Return a list of all network names currently known to the VMM. The
207 names can be used with the "get_network_by_name" method.
208 my @nets = $vmm->list_defined_networks()
210 Return a list of all networks defined, but not currently running,
211 on the VMM. The elements in the returned list are instances of the
212 Sys::Virt::Network class.
213 my $nnamess = $vmm->num_of_defined_networks()
215 Return the number of running networks known to the host. This can
216 be used as the "maxnames" parameter to
217 "list_defined_network_names".
218 my @names = $vmm->list_defined_network_names($maxnames)
220 Return a list of names of all networks defined, but not currently
221 running, on the host. The names can be used with the
222 "get_network_by_name" method.
223 my @pools = $vmm->list_storage_pools()
225 Return a list of all storage pools currently known to the host. The
226 elements in the returned list are instances of the
227 Sys::Virt::StoragePool class.
228 my $nnames = $vmm->num_of_storage_pools()
230 Return the number of running storage pools known to the VMM. This
231 can be used as the "maxids" parameter to "list_storage_pool_names".
232 my @poolNames = $vmm->list_storage_pool_names($maxnames)
234 Return a list of all storage pool names currently known to the VMM.
235 The IDs can be used with the "get_network_by_id" method.
236 my @pools = $vmm->list_defined_storage_pools()
238 Return a list of all storage pools defined, but not currently
239 running, on the host. The elements in the returned list are
240 instances of the Sys::Virt::StoragePool class.
241 my $nnames = $vmm->num_of_defined_storage_pools()
243 Return the number of running networks known to the host. This can
244 be used as the "maxnames" parameter to
245 "list_defined_storage_pool_names".
246 my @names = $vmm->list_defined_storage_pool_names($maxnames)
248 Return a list of names of all storage pools defined, but not
249 currently running, on the host. The names can be used with the
250 "get_storage_pool_by_name" method.
251 my @devs = $vmm->list_node_devices($capability)
253 Return a list of all devices currently known to the host OS. The
254 elements in the returned list are instances of the
255 Sys::Virt::NodeDevice class. The optional "capability" parameter
256 allows the list to be restricted to only devices with a particular
257 capability type.
258 my $nnames = $vmm->num_of_node_devices($capability[, $flags])
260 Return the number of host devices known to the VMM. This can be
261 used as the "maxids" parameter to "list_node_device_names". The
262 "capability" parameter allows the list to be restricted to only
263 devices with a particular capability type, and should be left as
264 "undef" if the full list is required. The optional <flags>
265 parameter is currently unused and defaults to 0 if omitted.
266 my @netNames = $vmm->list_node_device_names($capability, $maxnames[,
268 $flags])
269 Return a list of all host device names currently known to the VMM.
270 The names can be used with the "get_node_device_by_name" method.
271 The "capability" parameter allows the list to be restricted to only
272 devices with a particular capability type, and should be left as
273 "undef" if the full list is required. The optional <flags>
274 parameter is currently unused and defaults to 0 if omitted.
275 my @ifaces = $vmm->list_interfaces()
277 Return a list of all network interfaces currently known to the VMM.
278 The elements in the returned list are instances of the
279 Sys::Virt::Interface class.
280 my $nnames = $vmm->num_of_interfaces()
282 Return the number of running interfaces known to the VMM. This can
283 be used as the "maxnames" parameter to "list_interface_names".
284 my @names = $vmm->list_interface_names($maxnames)
286 Return a list of all interface names currently known to the VMM.
287 The names can be used with the "get_interface_by_name" method.
288 my @ifaces = $vmm->list_defined_interfaces()
290 Return a list of all network interfaces currently known to the VMM.
291 The elements in the returned list are instances of the
292 Sys::Virt::Interface class.
293 my $nnames = $vmm->num_of_defined_interfaces()
295 Return the number of inactive interfaces known to the VMM. This can
296 be used as the "maxnames" parameter to
297 "list_defined_interface_names".
298 my @names = $vmm->list_defined_interface_names($maxnames)
300 Return a list of inactive interface names currently known to the
301 VMM. The names can be used with the "get_interface_by_name" method.
302 my @ifaces = $vmm->list_secrets()
304 Return a list of all secrets currently known to the VMM. The
305 elements in the returned list are instances of the
306 Sys::Virt::Secret class.
307 my $nuuids = $vmm->num_of_secrets()
309 Return the number of secrets known to the VMM. This can be used as
310 the "maxuuids" parameter to "list_secrets".
311 my @uuids = $vmm->list_secret_uuids($maxuuids)
313 Return a list of all secret uuids currently known to the VMM. The
314 uuids can be used with the "get_secret_by_uuid" method.
315 my @nets = $vmm->list_nwfilters()
317 Return a list of all nwfilters currently known to the VMM. The
318 elements in the returned list are instances of the
319 Sys::Virt::NWFilter class.
320 my $nnames = $vmm->num_of_nwfilters()
322 Return the number of running nwfilters known to the VMM. This can
323 be used as the "maxids" parameter to "list_nwfilter_names".
324 my @filterNames = $vmm->list_nwfilter_names($maxnames)
326 Return a list of all nwfilter names currently known to the VMM. The
327 names can be used with the "get_nwfilter_by_name" method.
328 my $dom = $vmm->get_domain_by_name($name)
330 Return the domain with a name of $name. The returned object is an
331 instance of the Sys::Virt::Domain class.
332 my $dom = $vmm->get_domain_by_id($id)
334 Return the domain with a local id of $id. The returned object is an
335 instance of the Sys::Virt::Domain class.
336 my $dom = $vmm->get_domain_by_uuid($uuid)
338 Return the domain with a globally unique id of $uuid. The returned
339 object is an instance of the Sys::Virt::Domain class.
340 my $net = $vmm->get_network_by_name($name)
342 Return the network with a name of $name. The returned object is an
343 instance of the Sys::Virt::Network class.
344 my $net = $vmm->get_network_by_uuid($uuid)
346 Return the network with a globally unique id of $uuid. The returned
347 object is an instance of the Sys::Virt::Network class.
348 my $pool = $vmm->get_storage_pool_by_name($name)
350 Return the storage pool with a name of $name. The returned object
351 is an instance of the Sys::Virt::StoragePool class.
352 my $pool = $vmm->get_storage_pool_by_uuid($uuid)
354 Return the storage pool with a globally unique id of $uuid. The
355 returned object is an instance of the Sys::Virt::StoragePool class.
356 my $vol = $vmm->get_storage_volume_by_path($path)
358 Return the storage volume with a location of $path. The returned
359 object is an instance of the Sys::Virt::StorageVol class.
360 my $vol = $vmm->get_storage_volume_by_key($key)
362 Return the storage volume with a globally unique id of $key. The
363 returned object is an instance of the Sys::Virt::StorageVol class.
364 my $dev = $vmm->get_node_device_by_name($name)
366 Return the node device with a name of $name. The returned object is
367 an instance of the Sys::Virt::NodeDevice class.
368 my $iface = $vmm->get_interface_by_name($name)
370 Return the interface with a name of $name. The returned object is
371 an instance of the Sys::Virt::Interface class.
372 my $iface = $vmm->get_interface_by_mac($mac)
374 Return the interface with a MAC address of $mac. The returned
375 object is an instance of the Sys::Virt::Interface class.
376 my $sec = $vmm->get_secret_by_uuid($uuid)
378 Return the secret with a globally unique id of $uuid. The returned
379 object is an instance of the Sys::Virt::Secret class.
380 my $sec = $vmm->get_secret_by_usage($usageType, $usageID)
382 Return the secret with a usage type of $usageType, identified by
383 $usageID. The returned object is an instance of the
384 Sys::Virt::Secret class.
385 my $dom = $vmm->get_nwfilter_by_name($name)
387 Return the domain with a name of $name. The returned object is an
388 instance of the Sys::Virt::NWFilter class.
389 my $dom = $vmm->get_nwfilter_by_uuid($uuid)
391 Return the nwfilter with a globally unique id of $uuid. The
392 returned object is an instance of the Sys::Virt::NWFilter class.
393 my $xml = $vmm->find_storage_pool_sources($type, $srcspec[, $flags])
395 Probe for available storage pool sources for the pool of type
396 $type. The $srcspec parameter can be "undef", or a parameter to
397 refine the discovery process, for example a server hostname for NFS
398 discovery. The $flags parameter is optional, and if omitted
399 defaults to zero. The returned scalar is an XML document describing
400 the discovered storage pool sources.
401 $vmm->restore_domain($savefile)
403 Recreate a domain from the saved state file given in the $savefile
404 parameter.
405 $vmm->get_max_vcpus($domtype)
407 Return the maximum number of vcpus that can be configured for a
408 domain of type $domtype
409 my $hostname = $vmm->get_hostname()
411 Return the name of the host with which this connection is
412 associated.
413 my $uri = $vmm->get_uri()
415 Return the URI associated with the open connection. This may be
416 different from the URI used when initially connecting to libvirt,
417 when 'auto-probing' or drivers occurrs.
418 my $type = $vmm->get_type()
420 Return the type of virtualization backend accessed by this VMM
421 object. Currently the only supported type is "Xen".
422 my $xml = $vmm->domain_xml_from_native($format, $config);
424 Convert the native hypervisor configuration $config which is in
425 format <$format> into libvirrt domain XML. Valid values of $format
426 vary between hypervisor drivers.
427 my $config = $vmm->domain_xml_to_native($format, $xml)
429 Convert the libvirt domain XML configuration $xml to a native
430 hypervisor configuration in format $format
431 my $ver = $vmm->get_version()
433 Return the complete version number as a string encoded in the
434 formula "(major * 1000000) + (minor * 1000) + micro".
435 my $ver = $vmm->get_major_version
437 Return the major version number of the libvirt library.
438 my $ver = $vmm->get_minor_version
440 Return the minor version number of the libvirt library.
441 my $ver = $vmm->get_micro_version
443 Return the micro version number of the libvirt library.
444 my $ver = $vmm->get_library_version
446 Return the version number of the API associated with the active
447 connection. This differs from "get_version" in that if the
448 connection is to a remote libvirtd daemon, it will return the API
449 version of the remote libvirt, rather than the local client.
450 $conn->is_secure()
452 Returns a true value if the current connection is secure against
453 network interception. This implies either use of UNIX sockets, or
454 encryption with a TCP stream.
455 $conn->is_encrypted()
457 Returns a true value if the current connection data stream is
458 encrypted.
459 my $info = $con->get_node_info()
461 Returns a hash reference summarising the capabilities of the host
462 node. The elements of the hash are as follows:
463 $conn->domain_event_register($callback)
465 Register a callback to received notificaitons of domain state
466 change events. Only a single callback can be registered with each
467 connection instance. The callback will be invoked with four
468 parameters, an instance of "Sys::Virt" for the connection, an
469 instance of "Sys::Virt::Domain" for the domain changing state, and
470 a "event" and "detail" arguments, corresponding to the event
471 constants defined in the "Sys::Virt::Domain" module. Before
472 discarding the connection object, the callback must be
473 deregistered, otherwise the connection object memory will never be
474 released in garbage collection.
475 $conn->domain_event_deregister()
477 Unregister a callback, allowing the connection object to be garbage
478 collected.
479 $callback = $conn->domain_event_register_any($dom, $eventID, $callback)
481 Register a callback to received notifications of domain events.
482 The $dom parameter can be "undef" to request events on all known
483 domains, or a specific "Sys::Virt::Domain" object to filter events.
484 The $eventID parameter is one of the EVENT ID constants described
485 later in this document. The $callback is a subroutine reference
486 that will receive the events.
487 All callbacks receive a "Sys::Virt" connection as the first
489 parameter and a "Sys::Virt::Domain" object indiciating the domain
490 on which the event occurred as the second parameter. Subsequent
491 parameters vary according to the event type
492 EVENT_ID_LIFECYCLE
494 Extra "event" and "detail" parameters defining the lifecycle
495 transition that occurred.
496 EVENT_ID_REBOOT
498 No extra parameters
499 EVENT_ID_RTC_CHANGE
501 The "utcoffset" gives the offset from UTC in seconds
502 EVENT_ID_WATCHDOG
504 The "action" defines the action that is taken as a result of
505 the watchdog triggering. One of the WATCHDOG constants
506 described later
507 EVENT_ID_IO_ERROR
509 The "srcPath" is the file on the host which had the error. The
510 "devAlias" is the unique device alias from the guest
511 configuration associated with "srcPath". The "action" is the
512 action taken as a result of the error, one of the IO ERROR
513 constants described later
514 EVENT_ID_GRAPHICS
516 The "phase" is the stage of the connection, one of the GRAPHICS
517 PHASE constants described later. The "local" and "remote"
518 parameters follow with the details of the local and remote
519 network addresses. The "authScheme" describes how the user was
520 authenticated (if at all). Finally "identities" is an array ref
521 containing authenticated identities for the user, if any.
522 The return value is a unique callback ID that must be used when
524 unregistering the event.
525 $conn->domain_event_deregister_any($callbackID)
527 Unregister a callback, associated with the $callbackID previously
528 obtained from "domain_event_register_any".
529 my $xml = $con->baseline_cpu(\@xml, $flags=0)
531 Given an array ref whose elements are XML documents describing host
532 CPUs, compute the baseline CPU model that is operable across all
533 hosts. The XML for the baseline CPU model is returned. The optional
534 $flags parameter is currently unused and defaults to 0.
535 memory
537 The amount of physical memory in the host
538 model
540 The model of the CPU, eg x86_64
541 cpus
543 The total number of logical CPUs
544 mhz The peak MHZ of the CPU
546 nodes
548 The number of NUMA cells
549 sockets
551 The number of CPU sockets
552 cores
554 The number of cores per socket
555 threads
557 The number of threads per core
558 my $info = $con->get_node_security_model()
560 Returns a hash reference summarising the security model of the host
561 node. There are two keys in the hash, "model" specifying the name
562 of the security model (eg 'selinux') and "doi" specifying the
563 'domain of interpretation' for security labels.
564 my $xml = $con->get_capabilities();
566 Returns an XML document describing the hypervisor capabilities
567 my $result = $con->compare_cpu($xml, $flags=0);
569 Checks whether the CPU definition in $xml is compatible with the
570 current hypervisor connection. This can be used to determine
571 whether it is safe to migrate a guest to this host. The returned
572 result is one of the constants listed later
573 $mem = $con->get_node_free_memory();
575 Returns the current free memory on the host
576 @mem = $con->get_node_cells_free_memory($start, $end);
578 Returns the free memory on each NUMA cell between $start and $end.
579
581 The following sets of constants are useful when dealing with APIs in
582 this package
583 CREDENTIAL TYPES
585 When providing authentication callbacks, the following constants
586 indicate the type of credential being requested
587 Sys::Virt::CRED_AUTHNAME
589 Identity to act as
590 Sys::Virt::CRED_USERNAME
592 Identity to authorize as
593 Sys::Virt::CRED_CNONCE
595 Client supplies a nonce
596 Sys::Virt::CRED_REALM
598 Authentication realm
599 Sys::Virt::CRED_ECHOPROMPT
601 Challenge response non-secret
602 Sys::Virt::CRED_NOECHOPROMPT
604 Challenge response secret
605 Sys::Virt::CRED_PASSPHRASE
607 Passphrase secret
608 Sys::Virt::CRED_LANGUAGE
610 RFC 1766 language code
611 Sys::Virt::CRED_EXTERNAL
613 Externally provided credential
614 CPU COMPARISON CONSTANTS
616 Sys::Virt::CPU_COMPARE_INCOMPATIBLE
617 This host is missing one or more CPU features in the CPU
618 description
619 Sys::Virt::CPU_COMPARE_IDENTICAL
621 The host has an identical CPU description
622 Sys::Virt::CPU_COMPARE_SUPERSET
624 The host offers a superset of the CPU descriptoon
625
627 Hopefully none, but the XS code needs to be audited to ensure it is not
628 leaking memory.
629
631 Daniel P. Berrange <berrange@redhat.com>
632
634 Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P.
635 Berrange
636
638 This program is free software; you can redistribute it and/or modify it
639 under the terms of either the GNU General Public License as published
640 by the Free Software Foundation (either version 2 of the License, or at
641 your option any later version), or, the Artistic License, as specified
642 in the Perl README file.
643
645 Sys::Virt::Domain, Sys::Virt::Network, Sys::Virt::StoragePool,
646 Sys::Virt::StorageVol, Sys::Virt::Error, "http://libvirt.org"
647perl v5.12.3 2010-05-19 Sys::Virt(3)