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:
26 eval { my $vmm = Sys::Virt->new(address => $addr); };
28 if ($@) {
29 print STDERR "Unable to open connection to $addr" . $@->message . "\n";
30 }
31 For details of the information contained in the error objects, consult
33 the Sys::Virt::Error manual page.
34
36 my $vmm = Sys::Virt->new(uri => $uri, readonly => $ro, flags =>
37 $flags);
38 Attach to the virtual machine monitor with the address of
39 "address". The uri parameter may be omitted, in which case the
40 default connection made will be to the local Xen hypervisor. Some
41 example URIs include:
42 xen:///
44 Xen on the local machine
45 test:///default
47 Dummy "in memory" driver for test suites
48 qemu:///system
50 System-wide driver for QEMU / KVM virtualization
51 qemu:///session
53 Per-user driver for QEMU virtualization
54 qemu+tls://somehost/system
56 System-wide QEMU driver on "somehost" using TLS security
57 xen+tcp://somehost/
59 Xen driver on "somehost" using TCP / SASL security
60 For further details consult "http://libvirt.org/uri.html"
62 If the optional "readonly" parameter is supplied, then an
64 unprivileged connection to the VMM will be attempted. If it is not
65 supplied, then it defaults to making a fully privileged connection
66 to the VMM. If the calling application is not running as root, it
67 may be necessary to provide authentication callbacks.
68 If the optional "auth" parameter is set to a non-zero value,
70 authentication will be enabled during connection, using the default
71 set of credential gathering callbacks. The default callbacks prompt
72 for credentials on the console, so are not suitable for graphical
73 applications. For such apps a custom implementation should be
74 supplied. The "credlist" parameter should be an array reference
75 listing the set of credential types that will be supported. The
76 credential constants in this module can be used as values in this
77 list. The "callback" parameter should be a subroutine reference
78 containing the code necessary to gather the credentials. When
79 invoked it will be supplied with a single parameter, a array
80 reference of requested credentials. The elements of the array are
81 hash references, with keys "type" giving the type of credential,
82 "prompt" giving a user descriptive user prompt, "challenge" giving
83 name of the credential required. The answer should be collected
84 from the user, and returned by setting the "result" key. This key
85 may already be set with a default result if applicable
86 As a simple example returning hardcoded credentials
88 my $address = "qemu+tcp://192.168.122.1/system";
90 my $username = "test";
91 my $password = "123456";
92 my $con = Sys::Virt->new(address => $address,
94 auth => 1,
95 credlist => [
96 Sys::Virt::CRED_AUTHNAME,
97 Sys::Virt::CRED_PASSPHRASE,
98 ],
99 callback =>
100 sub {
101 my $creds = shift;
102 foreach my $cred (@{$creds}) {
104 if ($cred->{type} == Sys::Virt::CRED_AUTHNAME) {
105 $cred->{result} = $username;
106 }
107 if ($cred->{type} == Sys::Virt::CRED_PASSPHRASE) {
108 $cred->{result} = $password;
109 }
110 }
111 return 0;
112 });
113 my $st = $vmm->new_stream($flags)
115 Create a new stream, with the given flags
116 my $dom = $vmm->create_domain($xml, $flags);
118 Create a new domain based on the XML description passed into the
119 $xml parameter. The returned object is an instance of the
120 Sys::Virt::Domain class. This method is not available with
121 unprivileged connections to the VMM. The $flags parameter accepts
122 one of the DOMAIN CREATION constants documented in
123 Sys::Virt::Domain, and defaults to 0 if omitted.
124 my $dom = $vmm->define_domain($xml);
126 Defines, but does not start, a new domain based on the XML
127 description passed into the $xml parameter. The returned object is
128 an instance of the Sys::Virt::Domain class. This method is not
129 available with unprivileged connections to the VMM. The defined
130 domain can be later started by calling the "create" method on the
131 returned "Sys::Virt::Domain" object.
132 my $dom = $vmm->create_network($xml);
134 Create a new network based on the XML description passed into the
135 $xml parameter. The returned object is an instance of the
136 Sys::Virt::Network class. This method is not available with
137 unprivileged connections to the VMM.
138 my $dom = $vmm->define_network($xml);
140 Defines, but does not start, a new network based on the XML
141 description passed into the $xml parameter. The returned object is
142 an instance of the Sys::Virt::Network class. This method is not
143 available with unprivileged connections to the VMM. The defined
144 network can be later started by calling the "create" method on the
145 returned "Sys::Virt::Network" object.
146 my $dom = $vmm->create_storage_pool($xml);
148 Create a new storage pool based on the XML description passed into
149 the $xml parameter. The returned object is an instance of the
150 Sys::Virt::StoragePool class. This method is not available with
151 unprivileged connections to the VMM.
152 my $dom = $vmm->define_storage_pool($xml);
154 Defines, but does not start, a new storage pol based on the XML
155 description passed into the $xml parameter. The returned object is
156 an instance of the Sys::Virt::StoragePool class. This method is not
157 available with unprivileged connections to the VMM. The defined
158 pool can be later started by calling the "create" method on the
159 returned "Sys::Virt::StoragePool" object.
160 my $dom = $vmm->create_interface($xml);
162 Create a new interface based on the XML description passed into the
163 $xml parameter. The returned object is an instance of the
164 Sys::Virt::Interface class. This method is not available with
165 unprivileged connections to the VMM.
166 my $dom = $vmm->define_interface($xml);
168 Defines, but does not start, a new interface based on the XML
169 description passed into the $xml parameter. The returned object is
170 an instance of the Sys::Virt::Interface class. This method is not
171 available with unprivileged connections to the VMM. The defined
172 interface can be later started by calling the "create" method on
173 the returned "Sys::Virt::Interface" object.
174 my $dom = $vmm->create_node_device($xml);
176 Create a new virtual node device based on the XML description
177 passed into the $xml parameter. The returned object is an instance
178 of the Sys::Virt::NodeDevice class. This method is not available
179 with unprivileged connections to the VMM.
180 my @doms = $vmm->list_domains()
182 Return a list of all running domains currently known to the VMM.
183 The elements in the returned list are instances of the
184 Sys::Virt::Domain class. This method requires O(n) RPC calls, so
185 the "list_all_domains" method is recommended as a more efficient
186 alternative.
187 my $nids = $vmm->num_of_domains()
189 Return the number of running domains known to the VMM. This can be
190 used as the "maxids" parameter to "list_domain_ids".
191 my @domIDs = $vmm->list_domain_ids($maxids)
193 Return a list of all domain IDs currently known to the VMM. The IDs
194 can be used with the "get_domain_by_id" method.
195 my @doms = $vmm->list_defined_domains()
197 Return a list of all domains defined, but not currently running, on
198 the VMM. The elements in the returned list are instances of the
199 Sys::Virt::Domain class. This method requires O(n) RPC calls, so
200 the "list_all_domains" method is recommended as a more efficient
201 alternative.
202 my $nnames = $vmm->num_of_defined_domains()
204 Return the number of running domains known to the VMM. This can be
205 used as the "maxnames" parameter to "list_defined_domain_names".
206 my @names = $vmm->list_defined_domain_names($maxnames)
208 Return a list of names of all domains defined, but not currently
209 running, on the VMM. The names can be used with the
210 "get_domain_by_name" method.
211 my @doms = $vmm->list_all_domains($flags)
213 Return a list of all domains currently known to the VMM, whether
214 running or shutoff. The elements in the returned list are instances
215 of the Sys::Virt::Domain class. The $flags parameter can be used to
216 filter the list of returned domains.
217 my @nets = $vmm->list_networks()
219 Return a list of all networks currently known to the VMM. The
220 elements in the returned list are instances of the
221 Sys::Virt::Network class. This method requires O(n) RPC calls, so
222 the "list_all_networks" method is recommended as a more efficient
223 alternative.
224 my $nnames = $vmm->num_of_networks()
226 Return the number of running networks known to the VMM. This can be
227 used as the "maxids" parameter to "list_network_ids".
228 my @netNames = $vmm->list_network_names($maxnames)
230 Return a list of all network names currently known to the VMM. The
231 names can be used with the "get_network_by_name" method.
232 my @nets = $vmm->list_defined_networks()
234 Return a list of all networks defined, but not currently running,
235 on the VMM. The elements in the returned list are instances of the
236 Sys::Virt::Network class. This method requires O(n) RPC calls, so
237 the "list_all_networks" method is recommended as a more efficient
238 alternative.
239 my $nnamess = $vmm->num_of_defined_networks()
241 Return the number of running networks known to the host. This can
242 be used as the "maxnames" parameter to
243 "list_defined_network_names".
244 my @names = $vmm->list_defined_network_names($maxnames)
246 Return a list of names of all networks defined, but not currently
247 running, on the host. The names can be used with the
248 "get_network_by_name" method.
249 my @nets = $vmm->list_all_networks($flags)
251 Return a list of all networks currently known to the VMM, whether
252 running or shutoff. The elements in the returned list are instances
253 of the Sys::Virt::Network class. The $flags parameter can be used
254 to filter the list of returned networks.
255 my @pools = $vmm->list_storage_pools()
257 Return a list of all storage pools currently known to the host. The
258 elements in the returned list are instances of the
259 Sys::Virt::StoragePool class. This method requires O(n) RPC calls,
260 so the "list_all_storage_pools" method is recommended as a more
261 efficient alternative.
262 my $nnames = $vmm->num_of_storage_pools()
264 Return the number of running storage pools known to the VMM. This
265 can be used as the "maxids" parameter to "list_storage_pool_names".
266 my @poolNames = $vmm->list_storage_pool_names($maxnames)
268 Return a list of all storage pool names currently known to the VMM.
269 The IDs can be used with the "get_network_by_id" method.
270 my @pools = $vmm->list_defined_storage_pools()
272 Return a list of all storage pools defined, but not currently
273 running, on the host. The elements in the returned list are
274 instances of the Sys::Virt::StoragePool class. This method requires
275 O(n) RPC calls, so the "list_all_storage_pools" method is
276 recommended as a more efficient alternative.
277 my $nnames = $vmm->num_of_defined_storage_pools()
279 Return the number of running networks known to the host. This can
280 be used as the "maxnames" parameter to
281 "list_defined_storage_pool_names".
282 my @names = $vmm->list_defined_storage_pool_names($maxnames)
284 Return a list of names of all storage pools defined, but not
285 currently running, on the host. The names can be used with the
286 "get_storage_pool_by_name" method.
287 my @pools = $vmm->list_all_storage_pools($flags)
289 Return a list of all storage pools currently known to the VMM,
290 whether running or shutoff. The elements in the returned list are
291 instances of the Sys::Virt::StoragePool class. The $flags parameter
292 can be used to filter the list of returned pools.
293 my @devs = $vmm->list_node_devices($capability)
295 Return a list of all devices currently known to the host OS. The
296 elements in the returned list are instances of the
297 Sys::Virt::NodeDevice class. The optional "capability" parameter
298 allows the list to be restricted to only devices with a particular
299 capability type. This method requires O(n) RPC calls, so the
300 "list_all_node_devices" method is recommended as a more efficient
301 alternative.
302 my $nnames = $vmm->num_of_node_devices($capability[, $flags])
304 Return the number of host devices known to the VMM. This can be
305 used as the "maxids" parameter to "list_node_device_names". The
306 "capability" parameter allows the list to be restricted to only
307 devices with a particular capability type, and should be left as
308 "undef" if the full list is required. The optional <flags>
309 parameter is currently unused and defaults to 0 if omitted.
310 my @netNames = $vmm->list_node_device_names($capability, $maxnames[,
312 $flags])
313 Return a list of all host device names currently known to the VMM.
314 The names can be used with the "get_node_device_by_name" method.
315 The "capability" parameter allows the list to be restricted to only
316 devices with a particular capability type, and should be left as
317 "undef" if the full list is required. The optional <flags>
318 parameter is currently unused and defaults to 0 if omitted.
319 my @devs = $vmm->list_all_node_devices($flags)
321 Return a list of all node devices currently known to the VMM. The
322 elements in the returned list are instances of the
323 Sys::Virt::NodeDevice class. The $flags parameter can be used to
324 filter the list of returned devices.
325 my @ifaces = $vmm->list_interfaces()
327 Return a list of all network interfaces currently known to the VMM.
328 The elements in the returned list are instances of the
329 Sys::Virt::Interface class. This method requires O(n) RPC calls,
330 so the "list_all_interfaces" method is recommended as a more
331 efficient alternative.
332 my $nnames = $vmm->num_of_interfaces()
334 Return the number of running interfaces known to the VMM. This can
335 be used as the "maxnames" parameter to "list_interface_names".
336 my @names = $vmm->list_interface_names($maxnames)
338 Return a list of all interface names currently known to the VMM.
339 The names can be used with the "get_interface_by_name" method.
340 my @ifaces = $vmm->list_defined_interfaces()
342 Return a list of all network interfaces currently known to the VMM.
343 The elements in the returned list are instances of the
344 Sys::Virt::Interface class. This method requires O(n) RPC calls,
345 so the "list_all_interfaces" method is recommended as a more
346 efficient alternative.
347 my $nnames = $vmm->num_of_defined_interfaces()
349 Return the number of inactive interfaces known to the VMM. This can
350 be used as the "maxnames" parameter to
351 "list_defined_interface_names".
352 my @names = $vmm->list_defined_interface_names($maxnames)
354 Return a list of inactive interface names currently known to the
355 VMM. The names can be used with the "get_interface_by_name" method.
356 my @ifaces = $vmm->list_all_interfaces($flags)
358 Return a list of all interfaces currently known to the VMM, whether
359 running or shutoff. The elements in the returned list are instances
360 of the Sys::Virt::Interface class. The $flags parameter can be used
361 to filter the list of returned interfaces.
362 my @ifaces = $vmm->list_secrets()
364 Return a list of all secrets currently known to the VMM. The
365 elements in the returned list are instances of the
366 Sys::Virt::Secret class. This method requires O(n) RPC calls, so
367 the "list_all_secrets" method is recommended as a more efficient
368 alternative.
369 my $nuuids = $vmm->num_of_secrets()
371 Return the number of secrets known to the VMM. This can be used as
372 the "maxuuids" parameter to "list_secrets".
373 my @uuids = $vmm->list_secret_uuids($maxuuids)
375 Return a list of all secret uuids currently known to the VMM. The
376 uuids can be used with the "get_secret_by_uuid" method.
377 my @secrets = $vmm->list_all_secrets($flags)
379 Return a list of all secrets currently known to the VMM. The
380 elements in the returned list are instances of the
381 Sys::Virt::Network class. The $flags parameter can be used to
382 filter the list of returned secrets.
383 my @nets = $vmm->list_nwfilters()
385 Return a list of all nwfilters currently known to the VMM. The
386 elements in the returned list are instances of the
387 Sys::Virt::NWFilter class. This method requires O(n) RPC calls, so
388 the "list_all_nwfilters" method is recommended as a more efficient
389 alternative.
390 my $nnames = $vmm->num_of_nwfilters()
392 Return the number of running nwfilters known to the VMM. This can
393 be used as the "maxids" parameter to "list_nwfilter_names".
394 my @filterNames = $vmm->list_nwfilter_names($maxnames)
396 Return a list of all nwfilter names currently known to the VMM. The
397 names can be used with the "get_nwfilter_by_name" method.
398 my @nwfilters = $vmm->list_all_nwfilters($flags)
400 Return a list of all nwfilters currently known to the VMM. The
401 elements in the returned list are instances of the
402 Sys::Virt::NWFilter class. The $flags parameter is currently
403 unused and defaults to zero.
404 $vmm->define_save_image_xml($file, $dxml, $flags=0)
406 Update the XML associated with a virtual machine's save image. The
407 $file parameter is the fully qualified path to the save image XML,
408 while $dxml is the new XML document to write. The $flags parameter
409 is currently unused and defaults to zero.
410 $xml = $vmm->get_save_image_xml_description($file, $flags=1)
412 Retrieve the current XML configuration associated with the virtual
413 machine's save image identified by $file. The $flags parameter is
414 currently unused and defaults to zero.
415 my $dom = $vmm->get_domain_by_name($name)
417 Return the domain with a name of $name. The returned object is an
418 instance of the Sys::Virt::Domain class.
419 my $dom = $vmm->get_domain_by_id($id)
421 Return the domain with a local id of $id. The returned object is an
422 instance of the Sys::Virt::Domain class.
423 my $dom = $vmm->get_domain_by_uuid($uuid)
425 Return the domain with a globally unique id of $uuid. The returned
426 object is an instance of the Sys::Virt::Domain class.
427 my $net = $vmm->get_network_by_name($name)
429 Return the network with a name of $name. The returned object is an
430 instance of the Sys::Virt::Network class.
431 my $net = $vmm->get_network_by_uuid($uuid)
433 Return the network with a globally unique id of $uuid. The returned
434 object is an instance of the Sys::Virt::Network class.
435 my $pool = $vmm->get_storage_pool_by_name($name)
437 Return the storage pool with a name of $name. The returned object
438 is an instance of the Sys::Virt::StoragePool class.
439 my $pool = $vmm->get_storage_pool_by_uuid($uuid)
441 Return the storage pool with a globally unique id of $uuid. The
442 returned object is an instance of the Sys::Virt::StoragePool class.
443 my $pool = $vmm->get_storage_pool_by_volume($vol)
445 Return the storage pool with a storage volume $vol. The $vol
446 parameter must be an instance of the Sys::Virt::StorageVol class.
447 The returned object is an instance of the Sys::Virt::StoragePool
448 class.
449 my $vol = $vmm->get_storage_volume_by_path($path)
451 Return the storage volume with a location of $path. The returned
452 object is an instance of the Sys::Virt::StorageVol class.
453 my $vol = $vmm->get_storage_volume_by_key($key)
455 Return the storage volume with a globally unique id of $key. The
456 returned object is an instance of the Sys::Virt::StorageVol class.
457 my $dev = $vmm->get_node_device_by_name($name)
459 Return the node device with a name of $name. The returned object is
460 an instance of the Sys::Virt::NodeDevice class.
461 my $iface = $vmm->get_interface_by_name($name)
463 Return the interface with a name of $name. The returned object is
464 an instance of the Sys::Virt::Interface class.
465 my $iface = $vmm->get_interface_by_mac($mac)
467 Return the interface with a MAC address of $mac. The returned
468 object is an instance of the Sys::Virt::Interface class.
469 my $sec = $vmm->get_secret_by_uuid($uuid)
471 Return the secret with a globally unique id of $uuid. The returned
472 object is an instance of the Sys::Virt::Secret class.
473 my $sec = $vmm->get_secret_by_usage($usageType, $usageID)
475 Return the secret with a usage type of $usageType, identified by
476 $usageID. The returned object is an instance of the
477 Sys::Virt::Secret class.
478 my $dom = $vmm->get_nwfilter_by_name($name)
480 Return the domain with a name of $name. The returned object is an
481 instance of the Sys::Virt::NWFilter class.
482 my $dom = $vmm->get_nwfilter_by_uuid($uuid)
484 Return the nwfilter with a globally unique id of $uuid. The
485 returned object is an instance of the Sys::Virt::NWFilter class.
486 my $xml = $vmm->find_storage_pool_sources($type, $srcspec[, $flags])
488 Probe for available storage pool sources for the pool of type
489 $type. The $srcspec parameter can be "undef", or a parameter to
490 refine the discovery process, for example a server hostname for NFS
491 discovery. The $flags parameter is optional, and if omitted
492 defaults to zero. The returned scalar is an XML document describing
493 the discovered storage pool sources.
494 $vmm->interface_change_begin($flags)
496 Begin a transaction for changing the configuration of one or more
497 network interfaces
498 $vmm->interface_change_commit($flags)
500 Complete a transaction for changing the configuration of one or
501 more network interfaces
502 $vmm->interface_change_rollback($flags)
504 Abort a transaction for changing the configuration of one or more
505 network interfaces
506 $vmm->restore_domain($savefile)
508 Recreate a domain from the saved state file given in the $savefile
509 parameter.
510 $vmm->get_max_vcpus($domtype)
512 Return the maximum number of vcpus that can be configured for a
513 domain of type $domtype
514 my $hostname = $vmm->get_hostname()
516 Return the name of the host with which this connection is
517 associated.
518 my $uri = $vmm->get_uri()
520 Return the URI associated with the open connection. This may be
521 different from the URI used when initially connecting to libvirt,
522 when 'auto-probing' or drivers occurrs.
523 my $xml = $vmm->get_sysinfo()
525 Return an XML documenting representing the host system information,
526 typically obtained from SMBIOS tables.
527 my $type = $vmm->get_type()
529 Return the type of virtualization backend accessed by this VMM
530 object. Currently the only supported type is "Xen".
531 my $xml = $vmm->domain_xml_from_native($format, $config);
533 Convert the native hypervisor configuration $config which is in
534 format <$format> into libvirrt domain XML. Valid values of $format
535 vary between hypervisor drivers.
536 my $config = $vmm->domain_xml_to_native($format, $xml)
538 Convert the libvirt domain XML configuration $xml to a native
539 hypervisor configuration in format $format
540 my $ver = $vmm->get_version()
542 Return the complete version number as a string encoded in the
543 formula "(major * 1000000) + (minor * 1000) + micro".
544 my $ver = $vmm->get_major_version
546 Return the major version number of the libvirt library.
547 my $ver = $vmm->get_minor_version
549 Return the minor version number of the libvirt library.
550 my $ver = $vmm->get_micro_version
552 Return the micro version number of the libvirt library.
553 my $ver = $vmm->get_library_version
555 Return the version number of the API associated with the active
556 connection. This differs from "get_version" in that if the
557 connection is to a remote libvirtd daemon, it will return the API
558 version of the remote libvirt, rather than the local client.
559 $conn->is_secure()
561 Returns a true value if the current connection is secure against
562 network interception. This implies either use of UNIX sockets, or
563 encryption with a TCP stream.
564 $conn->is_encrypted()
566 Returns a true value if the current connection data stream is
567 encrypted.
568 $conn->is_alive()
570 Returns a true value if the connection is alive, as determined by
571 keep-alive packets or other recent RPC traffic.
572 $conn->set_keep_alive($interval, $count)
574 Change the operation of the keep alive protocol to send $count
575 packets spaced $interval seconds apart before considering the
576 connection dead.
577 my $info = $con->get_node_info()
579 Returns a hash reference summarising the capabilities of the host
580 node. The elements of the hash are as follows:
581 memory
583 The amount of physical memory in the host
584 model
586 The model of the CPU, eg x86_64
587 cpus
589 The total number of logical CPUs
590 mhz The peak MHZ of the CPU
592 nodes
594 The number of NUMA cells
595 sockets
597 The number of CPU sockets
598 cores
600 The number of cores per socket
601 threads
603 The number of threads per core
604 my $info = $con->get_node_cpu_stats($cpuNum=-1, $flags=0)
606 Returns a hash reference providing information about the host CPU
607 statistics. If <$cpuNum> is omitted, it defaults to
608 "Sys::Virt::NODE_CPU_STATS_ALL_CPUS" which causes it to return
609 cummulative information for all CPUs in the host. If $cpuNum is
610 zero or larger, it returns information just for the specified
611 number. The $flags parameter is currently unused and defaults to
612 zero. The fields in the returned hash reference are
613 kernel
615 The time spent in kernelspace
616 user
618 The time spent in userspace
619 idle
621 The idle time
622 iowait
624 The I/O wait time
625 utilization
627 The overall percentage utilization.
628 my $info = $con->get_node_memory_stats($cellNum=-1, $flags=0)
630 Returns a hash reference providing information about the host
631 memory statistics. If <$cellNum> is omitted, it defaults to
632 "Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS" which causes it to return
633 cummulative information for all NUMA cells in the host. If $cellNum
634 is zero or larger, it returns information just for the specified
635 number. The $flags parameter is currently unused and defaults to
636 zero. The fields in the returned hash reference are
637 total
639 The total memory
640 free
642 The free memory
643 buffers
645 The memory consumed by buffers
646 cached
648 The memory consumed for cache
649 my $params = $conn->get_node_memory_parameters($flags=0)
651 Return a hash reference containing the set of memory tunable
652 parameters for the node. The keys in the hash are one of the
653 constants MEMORY PARAMETERS described later. The $flags parameter
654 is currently unused, and defaults to 0 if omitted.
655 $conn->set_node_memory_parameters($params, $flags=0)
657 Update the memory tunable parameters for the node. The $params
658 should be a hash reference whose keys are one of the MEMORY
659 PARAMETERS constants. The $flags parameter is currently unused, and
660 defaults to 0 if omitted.
661 $conn->node_suspend_for_duration($target, $duration, $flags=0)
663 Suspend the the host, using mode $target which is one of the NODE
664 SUSPEND constants listed later. The $duration parameter controls
665 how long the node is suspended for before waking up.
666 $conn->domain_event_register($callback)
668 Register a callback to received notificaitons of domain state
669 change events. Only a single callback can be registered with each
670 connection instance. The callback will be invoked with four
671 parameters, an instance of "Sys::Virt" for the connection, an
672 instance of "Sys::Virt::Domain" for the domain changing state, and
673 a "event" and "detail" arguments, corresponding to the event
674 constants defined in the "Sys::Virt::Domain" module. Before
675 discarding the connection object, the callback must be
676 deregistered, otherwise the connection object memory will never be
677 released in garbage collection.
678 $conn->domain_event_deregister()
680 Unregister a callback, allowing the connection object to be garbage
681 collected.
682 $callback = $conn->domain_event_register_any($dom, $eventID, $callback)
684 Register a callback to received notifications of domain events.
685 The $dom parameter can be "undef" to request events on all known
686 domains, or a specific "Sys::Virt::Domain" object to filter events.
687 The $eventID parameter is one of the EVENT ID constants described
688 later in this document. The $callback is a subroutine reference
689 that will receive the events.
690 All callbacks receive a "Sys::Virt" connection as the first
692 parameter and a "Sys::Virt::Domain" object indiciating the domain
693 on which the event occurred as the second parameter. Subsequent
694 parameters vary according to the event type
695 EVENT_ID_LIFECYCLE
697 Extra "event" and "detail" parameters defining the lifecycle
698 transition that occurred.
699 EVENT_ID_REBOOT
701 No extra parameters
702 EVENT_ID_RTC_CHANGE
704 The "utcoffset" gives the offset from UTC in seconds
705 EVENT_ID_WATCHDOG
707 The "action" defines the action that is taken as a result of
708 the watchdog triggering. One of the WATCHDOG constants
709 described later
710 EVENT_ID_IO_ERROR
712 The "srcPath" is the file on the host which had the error. The
713 "devAlias" is the unique device alias from the guest
714 configuration associated with "srcPath". The "action" is the
715 action taken as a result of the error, one of the IO ERROR
716 constants described later
717 EVENT_ID_GRAPHICS
719 The "phase" is the stage of the connection, one of the GRAPHICS
720 PHASE constants described later. The "local" and "remote"
721 parameters follow with the details of the local and remote
722 network addresses. The "authScheme" describes how the user was
723 authenticated (if at all). Finally "identities" is an array ref
724 containing authenticated identities for the user, if any.
725 The return value is a unique callback ID that must be used when
727 unregistering the event.
728 $conn->domain_event_deregister_any($callbackID)
730 Unregister a callback, associated with the $callbackID previously
731 obtained from "domain_event_register_any".
732 $conn->register_close_callback($coderef);
734 Register a callback to be invoked when the connection is closed.
735 The callback will be invoked with two parameters, the $conn it was
736 registered against, and the reason for the close event. The reason
737 value will be one of the "CLOSE REASON CONSTANTS" listed later in
738 this document.
739 $conn->unregister_close_callback();
741 Remove the previously registered close callback.
742 my $xml = $con->baseline_cpu(\@xml, $flags=0)
744 Given an array ref whose elements are XML documents describing host
745 CPUs, compute the baseline CPU model that is operable across all
746 hosts. The XML for the baseline CPU model is returned. The optional
747 $flags parameter is currently unused and defaults to 0.
748 my $info = $con->get_node_security_model()
750 Returns a hash reference summarising the security model of the host
751 node. There are two keys in the hash, "model" specifying the name
752 of the security model (eg 'selinux') and "doi" specifying the
753 'domain of interpretation' for security labels.
754 my $xml = $con->get_capabilities();
756 Returns an XML document describing the hypervisor capabilities
757 my $result = $con->compare_cpu($xml, $flags=0);
759 Checks whether the CPU definition in $xml is compatible with the
760 current hypervisor connection. This can be used to determine
761 whether it is safe to migrate a guest to this host. The returned
762 result is one of the constants listed later
763 $mem = $con->get_node_free_memory();
765 Returns the current free memory on the host
766 @mem = $con->get_node_cells_free_memory($start, $end);
768 Returns the free memory on each NUMA cell between $start and $end.
769
771 The following sets of constants are useful when dealing with APIs in
772 this package
773 CONNECTION
775 When opening a connection the following constants can be used:
776 Sys::Virt::CONNECT_RO
778 Request a read-only connection
779 Sys::Virt::CONNECT_NO_ALIASES
781 Prevent the resolution of URI aliases
782 CREDENTIAL TYPES
784 When providing authentication callbacks, the following constants
785 indicate the type of credential being requested
786 Sys::Virt::CRED_AUTHNAME
788 Identity to act as
789 Sys::Virt::CRED_USERNAME
791 Identity to authorize as
792 Sys::Virt::CRED_CNONCE
794 Client supplies a nonce
795 Sys::Virt::CRED_REALM
797 Authentication realm
798 Sys::Virt::CRED_ECHOPROMPT
800 Challenge response non-secret
801 Sys::Virt::CRED_NOECHOPROMPT
803 Challenge response secret
804 Sys::Virt::CRED_PASSPHRASE
806 Passphrase secret
807 Sys::Virt::CRED_LANGUAGE
809 RFC 1766 language code
810 Sys::Virt::CRED_EXTERNAL
812 Externally provided credential
813 CPU COMPARISON CONSTANTS
815 Sys::Virt::CPU_COMPARE_INCOMPATIBLE
816 This host is missing one or more CPU features in the CPU
817 description
818 Sys::Virt::CPU_COMPARE_IDENTICAL
820 The host has an identical CPU description
821 Sys::Virt::CPU_COMPARE_SUPERSET
823 The host offers a superset of the CPU descriptoon
824 NODE SUSPEND CONSTANTS
826 Sys::Virt::NODE_SUSPEND_TARGET_MEM
827 Suspends to memory (equivalent of S3 on x86 architectures)
828 Sys::Virt::NODE_SUSPEND_TARGET_DISK
830 Suspends to disk (equivalent of S5 on x86 architectures)
831 Sys::Virt::NODE_SUSPEND_TARGET_HYBRID
833 Suspends to memory and disk (equivalent of S3+S5 on x86
834 architectures)
835 NODE VCPU CONSTANTS
837 Sys::Virt::NODE_CPU_STATS_ALL_CPUS
838 Request statistics for all CPUs
839 NODE MEMORY CONSTANTS
841 Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS
842 Request statistics for all memory cells
843 MEMORY PARAMETERS
845 The following constants are used to name memory parameters of the node
846 Sys::Virt::NODE_MEMORY_SHARED_FULL_SCANS
848 How many times all mergeable areas have been scanned.
849 Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARED
851 How many the shared memory pages are being used.
852 Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARING
854 How many sites are sharing the pages
855 Sys::Virt::NODE_MEMORY_SHARED_PAGES_TO_SCAN
857 How many present pages to scan before the shared memory service
858 goes to sleep
859 Sys::Virt::NODE_MEMORY_SHARED_PAGES_UNSHARED
861 How many pages unique but repeatedly checked for merging.
862 Sys::Virt::NODE_MEMORY_SHARED_PAGES_VOLATILE
864 How many pages changing too fast to be placed in a tree.
865 Sys::Virt::NODE_MEMORY_SHARED_SLEEP_MILLISECS
867 How many milliseconds the shared memory service should sleep before
868 next scan.
869 CLOSE REASON CONSTANTS
871 The following constants related to the connection close callback,
872 describe the reason for the closing of the connection.
873 Sys::Virt::CLOSE_REASON_CLIENT
875 The client application requested the connection be closed
876 Sys::Virt::CLOSE_REASON_EOF
878 End-of-file was encountered reading data from the connection
879 Sys::Virt::CLOSE_REASON_ERROR
881 An I/O error was encountered reading/writing data from/to the
882 connection
883 Sys::Virt::CLOSE_REASON_KEEPALIVE
885 The connection keepalive timer triggered due to lack of response
886 from the server
887 CPU STATS CONSTANTS
889 The following constants provide the names of known CPU stats fields
890 Sys::Virt::NODE_CPU_STATS_IDLE
892 Time spent idle
893 Sys::Virt::NODE_CPU_STATS_IOWAIT
895 Time spent waiting for I/O to complete
896 Sys::Virt::NODE_CPU_STATS_KERNEL
898 Time spent executing kernel code
899 Sys::Virt::NODE_CPU_STATS_USER
901 Time spent executing user code
902 Sys::Virt::NODE_CPU_STATS_UTILIZATION
904 Percentage utilization of the CPU.
905 MEMORY STAS CONSTANTS
907 The following constants provide the names of known memory stats fields
908 Sys::Virt::NODE_MEMORY_STATS_BUFFERS
910 The amount of memory consumed by I/O buffers
911 Sys::Virt::NODE_MEMORY_STATS_CACHED
913 The amount of memory consumed by disk cache
914 Sys::Virt::NODE_MEMORY_STATS_FREE
916 The amount of free memory
917 Sys::Virt::NODE_MEMORY_STATS_TOTAL
919 The total amount of memory
920
922 Hopefully none, but the XS code needs to be audited to ensure it is not
923 leaking memory.
924
926 Daniel P. Berrange <berrange@redhat.com>
927
929 Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P.
930 Berrange
931
933 This program is free software; you can redistribute it and/or modify it
934 under the terms of either the GNU General Public License as published
935 by the Free Software Foundation (either version 2 of the License, or at
936 your option any later version), or, the Artistic License, as specified
937 in the Perl README file.
938
940 Sys::Virt::Domain, Sys::Virt::Network, Sys::Virt::StoragePool,
941 Sys::Virt::StorageVol, Sys::Virt::Error, "http://libvirt.org"
942perl v5.10.1 2015-07-23 Sys::Virt(3)