1Sys::Virt(3) User Contributed Perl Documentation Sys::Virt(3)
2
6 Sys::Virt - Represent and manage a libvirt hypervisor connection
7
9 my $conn = Sys::Virt->new(uri => $uri);
10 my @domains = $conn->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 $conn = Sys::Virt->new(uri => $uri); };
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 $conn = Sys::Virt->new(uri => $uri, readonly => $ro, flags =>
37 $flags);
38 Attach to the virtualization host identified by "uri". The "uri"
39 parameter may be omitted, in which case the default connection made
40 will be to the local Xen hypervisor. Some example URIs include:
41 xen:///
43 Xen on the local machine
44 test:///default
46 Dummy "in memory" driver for test suites
47 qemu:///system
49 System-wide driver for QEMU / KVM virtualization
50 qemu:///session
52 Per-user driver for QEMU virtualization
53 qemu+tls://somehost/system
55 System-wide QEMU driver on "somehost" using TLS security
56 xen+tcp://somehost/
58 Xen driver on "somehost" using TCP / SASL security
59 For further details consult "http://libvirt.org/uri.html"
61 If the optional "readonly" parameter is supplied, then an
63 unprivileged connection to the hypervisor will be attempted. If it
64 is not supplied, then it defaults to making a fully privileged
65 connection to the hypervisor. If the calling application is not
66 running as root, it may be necessary to provide authentication
67 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, an 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 $uri = "qemu+tcp://192.168.122.1/system";
90 my $username = "test";
91 my $password = "123456";
92 my $con = Sys::Virt->new(uri => $uri,
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 For backwards compatibility with earlier releases, the "address"
115 parameter is accepted as a synonym for the "uri" parameter. The use
116 of "uri" is recommended for all newly written code.
117 my $st = $conn->new_stream($flags)
119 Create a new stream, with the given flags
120 my $dom = $conn->create_domain($xml, $flags);
122 Create a new domain based on the XML description passed into the
123 $xml parameter. The returned object is an instance of the
124 Sys::Virt::Domain class. This method is not available with
125 unprivileged connections to the hypervisor. The $flags parameter
126 accepts one of the DOMAIN CREATION constants documented in
127 Sys::Virt::Domain, and defaults to 0 if omitted.
128 my $dom = $conn->create_domain_with_files($xml, $fds, $flags);
130 Create a new domain based on the XML description passed into the
131 $xml parameter. The returned object is an instance of the
132 Sys::Virt::Domain class. This method is not available with
133 unprivileged connections to the hypervisor. The $fds parameter is
134 an array of UNIX file descriptors which will be passed to the init
135 process of the container. This is only supported with container
136 based virtualization. The $flags parameter accepts one of the
137 DOMAIN CREATION constants documented in Sys::Virt::Domain, and
138 defaults to 0 if omitted.
139 my $dom = $conn->define_domain($xml, $flags=0);
141 Defines, but does not start, a new domain based on the XML
142 description passed into the $xml parameter. The returned object is
143 an instance of the Sys::Virt::Domain class. This method is not
144 available with unprivileged connections to the hypervisor. The
145 defined domain can be later started by calling the "create" method
146 on the returned "Sys::Virt::Domain" object.
147 my $net = $conn->create_network($xml);
149 Create a new network based on the XML description passed into the
150 $xml parameter. The returned object is an instance of the
151 Sys::Virt::Network class. This method is not available with
152 unprivileged connections to the hypervisor.
153 my $net = $conn->define_network($xml);
155 Defines, but does not start, a new network based on the XML
156 description passed into the $xml parameter. The returned object is
157 an instance of the Sys::Virt::Network class. This method is not
158 available with unprivileged connections to the hypervisor. The
159 defined network can be later started by calling the "create" method
160 on the returned "Sys::Virt::Network" object.
161 my $nwfilter = $conn->define_nwfilter($xml);
163 Defines a new network filter based on the XML description passed
164 into the $xml parameter. The returned object is an instance of the
165 Sys::Virt::NWFilter class. This method is not available with
166 unprivileged connections to the hypervisor.
167 my $secret = $conn->define_secret($xml);
169 Defines a new secret based on the XML description passed into the
170 $xml parameter. The returned object is an instance of the
171 Sys::Virt::Secret class. This method is not available with
172 unprivileged connections to the hypervisor.
173 my $pool = $conn->create_storage_pool($xml);
175 Create a new storage pool based on the XML description passed into
176 the $xml parameter. The returned object is an instance of the
177 Sys::Virt::StoragePool class. This method is not available with
178 unprivileged connections to the hypervisor.
179 my $pool = $conn->define_storage_pool($xml);
181 Defines, but does not start, a new storage pol based on the XML
182 description passed into the $xml parameter. The returned object is
183 an instance of the Sys::Virt::StoragePool class. This method is not
184 available with unprivileged connections to the hypervisor. The
185 defined pool can be later started by calling the "create" method on
186 the returned "Sys::Virt::StoragePool" object.
187 my $pool = $conn->create_interface($xml);
189 Create a new interface based on the XML description passed into the
190 $xml parameter. The returned object is an instance of the
191 Sys::Virt::Interface class. This method is not available with
192 unprivileged connections to the hypervisor.
193 my $binding = $conn->create_nwfilter_binding($xml);
195 Create a new network filter binding based on the XML description
196 passed into the $xml parameter. The returned object is an instance
197 of the Sys::Virt::NWFilterBinding class.
198 my $iface = $conn->define_interface($xml);
200 Defines, but does not start, a new interface based on the XML
201 description passed into the $xml parameter. The returned object is
202 an instance of the Sys::Virt::Interface class. This method is not
203 available with unprivileged connections to the hypervisor. The
204 defined interface can be later started by calling the "create"
205 method on the returned "Sys::Virt::Interface" object.
206 my $dev = $conn->create_node_device($xml);
208 Create a new virtual node device based on the XML description
209 passed into the $xml parameter. The returned object is an instance
210 of the Sys::Virt::NodeDevice class. This method is not available
211 with unprivileged connections to the hypervisor.
212 my @doms = $conn->list_domains()
214 Return a list of all running domains currently known to the
215 hypervisor. The elements in the returned list are instances of the
216 Sys::Virt::Domain class. This method requires O(n) RPC calls, so
217 the "list_all_domains" method is recommended as a more efficient
218 alternative.
219 my $nids = $conn->num_of_domains()
221 Return the number of running domains known to the hypervisor. This
222 can be used as the "maxids" parameter to "list_domain_ids".
223 my @domIDs = $conn->list_domain_ids($maxids)
225 Return a list of all domain IDs currently known to the hypervisor.
226 The IDs can be used with the "get_domain_by_id" method.
227 my @doms = $conn->list_defined_domains()
229 Return a list of all domains defined, but not currently running, on
230 the hypervisor. The elements in the returned list are instances of
231 the Sys::Virt::Domain class. This method requires O(n) RPC calls,
232 so the "list_all_domains" method is recommended as a more efficient
233 alternative.
234 my $ndoms = $conn->num_of_defined_domains()
236 Return the number of running domains known to the hypervisor. This
237 can be used as the "maxnames" parameter to
238 "list_defined_domain_names".
239 my @names = $conn->list_defined_domain_names($maxnames)
241 Return a list of names of all domains defined, but not currently
242 running, on the hypervisor. The names can be used with the
243 "get_domain_by_name" method.
244 my @doms = $conn->list_all_domains($flags)
246 Return a list of all domains currently known to the hypervisor,
247 whether running or shutoff. The elements in the returned list are
248 instances of the Sys::Virt::Domain class. The $flags parameter can
249 be used to filter the list of returned domains.
250 my @nets = $conn->list_networks()
252 Return a list of all networks currently known to the hypervisor.
253 The elements in the returned list are instances of the
254 Sys::Virt::Network class. This method requires O(n) RPC calls, so
255 the "list_all_networks" method is recommended as a more efficient
256 alternative.
257 my $nnets = $conn->num_of_networks()
259 Return the number of running networks known to the hypervisor. This
260 can be used as the "maxids" parameter to "list_network_ids".
261 my @netNames = $conn->list_network_names($maxnames)
263 Return a list of all network names currently known to the
264 hypervisor. The names can be used with the "get_network_by_name"
265 method.
266 my @nets = $conn->list_defined_networks()
268 Return a list of all networks defined, but not currently running,
269 on the hypervisor. The elements in the returned list are instances
270 of the Sys::Virt::Network class. This method requires O(n) RPC
271 calls, so the "list_all_networks" method is recommended as a more
272 efficient alternative.
273 my $nnets = $conn->num_of_defined_networks()
275 Return the number of running networks known to the host. This can
276 be used as the "maxnames" parameter to
277 "list_defined_network_names".
278 my @names = $conn->list_defined_network_names($maxnames)
280 Return a list of names of all networks defined, but not currently
281 running, on the host. The names can be used with the
282 "get_network_by_name" method.
283 my @nets = $conn->list_all_networks($flags)
285 Return a list of all networks currently known to the hypervisor,
286 whether running or shutoff. The elements in the returned list are
287 instances of the Sys::Virt::Network class. The $flags parameter can
288 be used to filter the list of returned networks.
289 my @pools = $conn->list_storage_pools()
291 Return a list of all storage pools currently known to the host. The
292 elements in the returned list are instances of the
293 Sys::Virt::StoragePool class. This method requires O(n) RPC calls,
294 so the "list_all_storage_pools" method is recommended as a more
295 efficient alternative.
296 my $npools = $conn->num_of_storage_pools()
298 Return the number of running storage pools known to the hypervisor.
299 This can be used as the "maxids" parameter to
300 "list_storage_pool_names".
301 my @poolNames = $conn->list_storage_pool_names($maxnames)
303 Return a list of all storage pool names currently known to the
304 hypervisor. The IDs can be used with the "get_network_by_id"
305 method.
306 my @pools = $conn->list_defined_storage_pools()
308 Return a list of all storage pools defined, but not currently
309 running, on the host. The elements in the returned list are
310 instances of the Sys::Virt::StoragePool class. This method requires
311 O(n) RPC calls, so the "list_all_storage_pools" method is
312 recommended as a more efficient alternative.
313 my $npools = $conn->num_of_defined_storage_pools()
315 Return the number of running networks known to the host. This can
316 be used as the "maxnames" parameter to
317 "list_defined_storage_pool_names".
318 my @names = $conn->list_defined_storage_pool_names($maxnames)
320 Return a list of names of all storage pools defined, but not
321 currently running, on the host. The names can be used with the
322 "get_storage_pool_by_name" method.
323 my @pools = $conn->list_all_storage_pools($flags)
325 Return a list of all storage pools currently known to the
326 hypervisor, whether running or shutoff. The elements in the
327 returned list are instances of the Sys::Virt::StoragePool class.
328 The $flags parameter can be used to filter the list of returned
329 pools.
330 my @devs = $conn->list_node_devices($capability)
332 Return a list of all devices currently known to the host OS. The
333 elements in the returned list are instances of the
334 Sys::Virt::NodeDevice class. The optional "capability" parameter
335 allows the list to be restricted to only devices with a particular
336 capability type. This method requires O(n) RPC calls, so the
337 "list_all_node_devices" method is recommended as a more efficient
338 alternative.
339 my $ndevs = $conn->num_of_node_devices($capability[, $flags])
341 Return the number of host devices known to the hypervisor. This can
342 be used as the "maxids" parameter to "list_node_device_names". The
343 "capability" parameter allows the list to be restricted to only
344 devices with a particular capability type, and should be left as
345 "undef" if the full list is required. The optional <flags>
346 parameter is currently unused and defaults to 0 if omitted.
347 my @devNames = $conn->list_node_device_names($capability, $maxnames[,
349 $flags])
350 Return a list of all host device names currently known to the
351 hypervisor. The names can be used with the
352 "get_node_device_by_name" method. The "capability" parameter
353 allows the list to be restricted to only devices with a particular
354 capability type, and should be left as "undef" if the full list is
355 required. The optional <flags> parameter is currently unused and
356 defaults to 0 if omitted.
357 my @devs = $conn->list_all_node_devices($flags)
359 Return a list of all node devices currently known to the
360 hypervisor. The elements in the returned list are instances of the
361 Sys::Virt::NodeDevice class. The $flags parameter can be used to
362 filter the list of returned devices.
363 my @ifaces = $conn->list_interfaces()
365 Return a list of all network interfaces currently known to the
366 hypervisor. The elements in the returned list are instances of the
367 Sys::Virt::Interface class. This method requires O(n) RPC calls,
368 so the "list_all_interfaces" method is recommended as a more
369 efficient alternative.
370 my $nifaces = $conn->num_of_interfaces()
372 Return the number of running interfaces known to the hypervisor.
373 This can be used as the "maxnames" parameter to
374 "list_interface_names".
375 my @names = $conn->list_interface_names($maxnames)
377 Return a list of all interface names currently known to the
378 hypervisor. The names can be used with the "get_interface_by_name"
379 method.
380 my @ifaces = $conn->list_defined_interfaces()
382 Return a list of all network interfaces currently known to the
383 hypervisor. The elements in the returned list are instances of the
384 Sys::Virt::Interface class. This method requires O(n) RPC calls,
385 so the "list_all_interfaces" method is recommended as a more
386 efficient alternative.
387 my $nifaces = $conn->num_of_defined_interfaces()
389 Return the number of inactive interfaces known to the hypervisor.
390 This can be used as the "maxnames" parameter to
391 "list_defined_interface_names".
392 my @names = $conn->list_defined_interface_names($maxnames)
394 Return a list of inactive interface names currently known to the
395 hypervisor. The names can be used with the "get_interface_by_name"
396 method.
397 my @ifaces = $conn->list_all_interfaces($flags)
399 Return a list of all interfaces currently known to the hypervisor,
400 whether running or shutoff. The elements in the returned list are
401 instances of the Sys::Virt::Interface class. The $flags parameter
402 can be used to filter the list of returned interfaces.
403 my @ifaces = $conn->list_secrets()
405 Return a list of all secrets currently known to the hypervisor. The
406 elements in the returned list are instances of the
407 Sys::Virt::Secret class. This method requires O(n) RPC calls, so
408 the "list_all_secrets" method is recommended as a more efficient
409 alternative.
410 my $nuuids = $conn->num_of_secrets()
412 Return the number of secrets known to the hypervisor. This can be
413 used as the "maxuuids" parameter to "list_secrets".
414 my @uuids = $conn->list_secret_uuids($maxuuids)
416 Return a list of all secret uuids currently known to the
417 hypervisor. The uuids can be used with the "get_secret_by_uuid"
418 method.
419 my @secrets = $conn->list_all_secrets($flags)
421 Return a list of all secrets currently known to the hypervisor. The
422 elements in the returned list are instances of the
423 Sys::Virt::Network class. The $flags parameter can be used to
424 filter the list of returned secrets.
425 my @nwfilters = $conn->list_nwfilters()
427 Return a list of all nwfilters currently known to the hypervisor.
428 The elements in the returned list are instances of the
429 Sys::Virt::NWFilter class. This method requires O(n) RPC calls, so
430 the "list_all_nwfilters" method is recommended as a more efficient
431 alternative.
432 my $nnwfilters = $conn->num_of_nwfilters()
434 Return the number of running nwfilters known to the hypervisor.
435 This can be used as the "maxids" parameter to
436 "list_nwfilter_names".
437 my @filterNames = $conn->list_nwfilter_names($maxnames)
439 Return a list of all nwfilter names currently known to the
440 hypervisor. The names can be used with the "get_nwfilter_by_name"
441 method.
442 my @nwfilters = $conn->list_all_nwfilters($flags)
444 Return a list of all nwfilters currently known to the hypervisor.
445 The elements in the returned list are instances of the
446 Sys::Virt::NWFilter class. The $flags parameter is currently
447 unused and defaults to zero.
448 my @bindings = $conn->list_all_nwfilter_bindings($flags)
450 Return a list of all nwfilter bindings currently known to the
451 hypervisor. The elements in the returned list are instances of the
452 Sys::Virt::NWFilterBinding class. The $flags parameter is currently
453 unused and defaults to zero.
454 $conn->define_save_image_xml($file, $dxml, $flags=0)
456 Update the XML associated with a virtual machine's save image. The
457 $file parameter is the fully qualified path to the save image XML,
458 while $dxml is the new XML document to write. The $flags parameter
459 is currently unused and defaults to zero.
460 $xml = $conn->get_save_image_xml_description($file, $flags=1)
462 Retrieve the current XML configuration associated with the virtual
463 machine's save image identified by $file. The $flags parameter
464 accepts the same constants as
465 "Sys::Virt::Domain::managed_save_get_xml_description".
466 my $dom = $conn->get_domain_by_name($name)
468 Return the domain with a name of $name. The returned object is an
469 instance of the Sys::Virt::Domain class.
470 my $dom = $conn->get_domain_by_id($id)
472 Return the domain with a local id of $id. The returned object is an
473 instance of the Sys::Virt::Domain class.
474 my $dom = $conn->get_domain_by_uuid($uuid)
476 Return the domain with a globally unique id of $uuid. The returned
477 object is an instance of the Sys::Virt::Domain class.
478 my $net = $conn->get_network_by_name($name)
480 Return the network with a name of $name. The returned object is an
481 instance of the Sys::Virt::Network class.
482 my $net = $conn->get_network_by_uuid($uuid)
484 Return the network with a globally unique id of $uuid. The returned
485 object is an instance of the Sys::Virt::Network class.
486 my $pool = $conn->get_storage_pool_by_name($name)
488 Return the storage pool with a name of $name. The returned object
489 is an instance of the Sys::Virt::StoragePool class.
490 my $pool = $conn->get_storage_pool_by_uuid($uuid)
492 Return the storage pool with a globally unique id of $uuid. The
493 returned object is an instance of the Sys::Virt::StoragePool class.
494 my $pool = $conn->get_storage_pool_by_volume($vol)
496 Return the storage pool with a storage volume $vol. The $vol
497 parameter must be an instance of the Sys::Virt::StorageVol class.
498 The returned object is an instance of the Sys::Virt::StoragePool
499 class.
500 my $pool = $conn->get_storage_pool_by_target_path($path)
502 Return the storage pool with a target path of $path. The returned
503 object is an instance of the Sys::Virt::StoragePool class.
504 my $vol = $conn->get_storage_volume_by_path($path)
506 Return the storage volume with a location of $path. The returned
507 object is an instance of the Sys::Virt::StorageVol class.
508 my $vol = $conn->get_storage_volume_by_key($key)
510 Return the storage volume with a globally unique id of $key. The
511 returned object is an instance of the Sys::Virt::StorageVol class.
512 my $dev = $conn->get_node_device_by_name($name)
514 Return the node device with a name of $name. The returned object is
515 an instance of the Sys::Virt::NodeDevice class.
516 my $dev = $conn->get_node_device_scsihost_by_wwn($wwnn, $wwpn,
518 $flags=0)
519 Return the node device which is a SCSI host identified by $wwnn and
520 $wwpn. The $flags parameter is unused and defaults to zero. The
521 returned object is an instance of the Sys::Virt::NodeDevice class.
522 my $iface = $conn->get_interface_by_name($name)
524 Return the interface with a name of $name. The returned object is
525 an instance of the Sys::Virt::Interface class.
526 my $iface = $conn->get_interface_by_mac($mac)
528 Return the interface with a MAC address of $mac. The returned
529 object is an instance of the Sys::Virt::Interface class.
530 my $sec = $conn->get_secret_by_uuid($uuid)
532 Return the secret with a globally unique id of $uuid. The returned
533 object is an instance of the Sys::Virt::Secret class.
534 my $sec = $conn->get_secret_by_usage($usageType, $usageID)
536 Return the secret with a usage type of $usageType, identified by
537 $usageID. The returned object is an instance of the
538 Sys::Virt::Secret class.
539 my $nwfilter = $conn->get_nwfilter_by_name($name)
541 Return the domain with a name of $name. The returned object is an
542 instance of the Sys::Virt::NWFilter class.
543 my $nwfilter = $conn->get_nwfilter_by_uuid($uuid)
545 Return the nwfilter with a globally unique id of $uuid. The
546 returned object is an instance of the Sys::Virt::NWFilter class.
547 my $binding = $conn->get_nwfilter_binding_by_port_dev($name)
549 Return the network filter binding for the port device $name. The
550 returned object is an instance of the Sys::Virt::NWFilterBinding
551 class.
552 my $xml = $conn->find_storage_pool_sources($type, $srcspec[, $flags])
554 Probe for available storage pool sources for the pool of type
555 $type. The $srcspec parameter can be "undef", or a parameter to
556 refine the discovery process, for example a server hostname for NFS
557 discovery. The $flags parameter is optional, and if omitted
558 defaults to zero. The returned scalar is an XML document describing
559 the discovered storage pool sources.
560 my @stats = $conn->get_all_domain_stats($stats, \@doms=undef,
562 $flags=0);
563 Get a list of all statistics for domains known to the hypervisor.
564 The $stats parameter controls which data fields to return and
565 should be a combination of the DOMAIN STATS FIELD CONSTANTS.
566 The optional @doms parameter is a list of Sys::Virt::Domain objects
568 to return stats for. If this is undefined, then all domains will be
569 returned. The $flags method can be used to filter the list of
570 returned domains.
571 The return data for the method is a list, one element for each
573 domain. The element will be a hash with two keys, "dom" pointing
574 to an instance of "Sys::Virt::Domain" and "data" pointing to
575 another hash reference containing the actual statistics.
576 $conn->interface_change_begin($flags)
578 Begin a transaction for changing the configuration of one or more
579 network interfaces
580 $conn->interface_change_commit($flags)
582 Complete a transaction for changing the configuration of one or
583 more network interfaces
584 $conn->interface_change_rollback($flags)
586 Abort a transaction for changing the configuration of one or more
587 network interfaces
588 $conn->restore_domain($savefile)
590 Recreate a domain from the saved state file given in the $savefile
591 parameter.
592 $conn->get_max_vcpus($domtype)
594 Return the maximum number of vcpus that can be configured for a
595 domain of type $domtype
596 my $hostname = $conn->get_hostname()
598 Return the name of the host with which this connection is
599 associated.
600 my $uri = $conn->get_uri()
602 Return the URI associated with the open connection. This may be
603 different from the URI used when initially connecting to libvirt,
604 when 'auto-probing' or drivers occurrs.
605 my $xml = $conn->get_sysinfo()
607 Return an XML documenting representing the host system information,
608 typically obtained from SMBIOS tables.
609 my $type = $conn->get_type()
611 Return the type of virtualization backend accessed by this
612 hypervisor object. Currently the only supported type is "Xen".
613 my $xml = $conn->domain_xml_from_native($format, $config);
615 Convert the native hypervisor configuration $config which is in
616 format <$format> into libvirrt domain XML. Valid values of $format
617 vary between hypervisor drivers.
618 my $config = $conn->domain_xml_to_native($format, $xml)
620 Convert the libvirt domain XML configuration $xml to a native
621 hypervisor configuration in format $format
622 my $ver = $conn->get_version()
624 Return the complete version number as a string encoded in the
625 formula "(major * 1000000) + (minor * 1000) + micro".
626 my $ver = $conn->get_major_version
628 Return the major version number of the libvirt library.
629 my $ver = $conn->get_minor_version
631 Return the minor version number of the libvirt library.
632 my $ver = $conn->get_micro_version
634 Return the micro version number of the libvirt library.
635 my $ver = $conn->get_library_version
637 Return the version number of the API associated with the active
638 connection. This differs from "get_version" in that if the
639 connection is to a remote libvirtd daemon, it will return the API
640 version of the remote libvirt, rather than the local client.
641 $conn->is_secure()
643 Returns a true value if the current connection is secure against
644 network interception. This implies either use of UNIX sockets, or
645 encryption with a TCP stream.
646 $conn->is_encrypted()
648 Returns a true value if the current connection data stream is
649 encrypted.
650 $conn->is_alive()
652 Returns a true value if the connection is alive, as determined by
653 keep-alive packets or other recent RPC traffic.
654 $conn->set_keep_alive($interval, $count)
656 Change the operation of the keep alive protocol to send $count
657 packets spaced $interval seconds apart before considering the
658 connection dead.
659 my $info = $con->get_node_info()
661 Returns a hash reference summarising the capabilities of the host
662 node. The elements of the hash are as follows:
663 memory
665 The amount of physical memory in the host
666 model
668 The model of the CPU, eg x86_64
669 cpus
671 The total number of logical CPUs.
672 mhz The peak MHZ of the CPU
674 nodes
676 The number of NUMA cells
677 sockets
679 The number of CPU sockets
680 cores
682 The number of cores per socket
683 threads
685 The number of threads per core
686 NB, more accurate information about the total number of CPUs and
688 those online can be obtained using the "get_node_cpu_map" method.
689 my ($totcpus, $onlinemap, $totonline) = $con->get_node_cpu_map();
691 Returns an array containing information about the CPUs available on
692 the host. The first element, "totcpus", specifies the total number
693 of CPUs available to the host regardles of their online stat. The
694 second element, "onlinemap", provides a bitmap detailing which CPUs
695 are currently online. The third element, "totonline", specifies the
696 total number of online CPUs. The values in the bitmap can be
697 extracted using the "unpack" method as follows:
698 my @onlinemap = split(//, unpack("b*", $onlinemap));
700 my $info = $con->get_node_cpu_stats($cpuNum=-1, $flags=0)
702 Returns a hash reference providing information about the host CPU
703 statistics. If <$cpuNum> is omitted, it defaults to
704 "Sys::Virt::NODE_CPU_STATS_ALL_CPUS" which causes it to return
705 cumulative information for all CPUs in the host. If $cpuNum is zero
706 or larger, it returns information just for the specified number.
707 The $flags parameter is currently unused and defaults to zero. The
708 fields in the returned hash reference are
709 kernel
711 The time spent in kernelspace
712 user
714 The time spent in userspace
715 idle
717 The idle time
718 iowait
720 The I/O wait time
721 utilization
723 The overall percentage utilization.
724 my $info = $con->get_node_memory_stats($cellNum=-1, $flags=0)
726 Returns a hash reference providing information about the host
727 memory statistics. If <$cellNum> is omitted, it defaults to
728 "Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS" which causes it to return
729 cumulative information for all NUMA cells in the host. If $cellNum
730 is zero or larger, it returns information just for the specified
731 number. The $flags parameter is currently unused and defaults to
732 zero. The fields in the returned hash reference are
733 total
735 The total memory
736 free
738 The free memory
739 buffers
741 The memory consumed by buffers
742 cached
744 The memory consumed for cache
745 my $params = $conn->get_node_memory_parameters($flags=0)
747 Return a hash reference containing the set of memory tunable
748 parameters for the node. The keys in the hash are one of the
749 constants MEMORY PARAMETERS described later. The $flags parameter
750 is currently unused, and defaults to 0 if omitted.
751 $conn->set_node_memory_parameters($params, $flags=0)
753 Update the memory tunable parameters for the node. The $params
754 should be a hash reference whose keys are one of the MEMORY
755 PARAMETERS constants. The $flags parameter is currently unused, and
756 defaults to 0 if omitted.
757 $info = $conn->get_node_sev_info($flags=0)
759 Get the AMD SEV information for the host. $flags is currently
760 unused and defaults to 0 if omitted. The returned hash contains the
761 following keys:
762 Sys::Virt::SEV_CBITPOS
764 The CBit position
765 Sys::Virt::SEV_CERT_CHAIN
767 The certificate chain
768 Sys::Virt::SEV_PDH
770 Platform diffie-hellman key
771 Sys::Virt::SEV_REDUCED_PHYS_BITS
773 The number of physical address bits used by SEV
774 $conn->node_suspend_for_duration($target, $duration, $flags=0)
776 Suspend the the host, using mode $target which is one of the NODE
777 SUSPEND constants listed later. The $duration parameter controls
778 how long the node is suspended for before waking up.
779 $conn->domain_event_register($callback)
781 Register a callback to received notifications of domain state
782 change events. Only a single callback can be registered with each
783 connection instance. The callback will be invoked with four
784 parameters, an instance of "Sys::Virt" for the connection, an
785 instance of "Sys::Virt::Domain" for the domain changing state, and
786 a "event" and "detail" arguments, corresponding to the event
787 constants defined in the "Sys::Virt::Domain" module. Before
788 discarding the connection object, the callback must be
789 deregistered, otherwise the connection object memory will never be
790 released in garbage collection.
791 $conn->domain_event_deregister()
793 Unregister a callback, allowing the connection object to be garbage
794 collected.
795 $callback = $conn->domain_event_register_any($dom, $eventID, $callback)
797 Register a callback to received notifications of domain events.
798 The $dom parameter can be "undef" to request events on all known
799 domains, or a specific "Sys::Virt::Domain" object to filter events.
800 The $eventID parameter is one of the EVENT ID constants described
801 later in this document. The $callback is a subroutine reference
802 that will receive the events.
803 All callbacks receive a "Sys::Virt" connection as the first
805 parameter and a "Sys::Virt::Domain" object indicating the domain on
806 which the event occurred as the second parameter. Subsequent
807 parameters vary according to the event type
808 EVENT_ID_LIFECYCLE
810 Extra "event" and "detail" parameters defining the lifecycle
811 transition that occurred.
812 EVENT_ID_REBOOT
814 No extra parameters
815 EVENT_ID_RTC_CHANGE
817 The "utcoffset" gives the offset from UTC in seconds
818 EVENT_ID_WATCHDOG
820 The "action" defines the action that is taken as a result of
821 the watchdog triggering. One of the WATCHDOG constants
822 described later
823 EVENT_ID_IO_ERROR
825 The "srcPath" is the file on the host which had the error. The
826 "devAlias" is the unique device alias from the guest
827 configuration associated with "srcPath". The "action" is the
828 action taken as a result of the error, one of the IO ERROR
829 constants described later
830 EVENT_ID_GRAPHICS
832 The "phase" is the stage of the connection, one of the GRAPHICS
833 PHASE constants described later. The "local" and "remote"
834 parameters follow with the details of the local and remote
835 network addresses. The "authScheme" describes how the user was
836 authenticated (if at all). Finally "identities" is an array ref
837 containing authenticated identities for the user, if any.
838 The return value is a unique callback ID that must be used when
840 unregistering the event.
841 $conn->domain_event_deregister_any($callbackID)
843 Unregister a callback, associated with the $callbackID previously
844 obtained from "domain_event_register_any".
845 $callback = $conn->network_event_register_any($net, $eventID,
847 $callback)
848 Register a callback to received notifications of network events.
849 The $net parameter can be "undef" to request events on all known
850 networks, or a specific "Sys::Virt::Network" object to filter
851 events. The $eventID parameter is one of the EVENT ID constants
852 described later in this document. The $callback is a subroutine
853 reference that will receive the events.
854 All callbacks receive a "Sys::Virt" connection as the first
856 parameter and a "Sys::Virt::Network" object indicating the network
857 on which the event occurred as the second parameter. Subsequent
858 parameters vary according to the event type
859 EVENT_ID_LIFECYCLE
861 Extra "event" and "detail" parameters defining the lifecycle
862 transition that occurred.
863 The return value is a unique callback ID that must be used when
865 unregistering the event.
866 $conn->network_event_deregister_any($callbackID)
868 Unregister a callback, associated with the $callbackID previously
869 obtained from "network_event_register_any".
870 $callback = $conn->storage_pool_event_register_any($pool, $eventID,
872 $callback)
873 Register a callback to received notifications of storage pool
874 events. The $pool parameter can be "undef" to request events on
875 all known storage pools, or a specific "Sys::Virt::StoragePool"
876 object to filter events. The $eventID parameter is one of the EVENT
877 ID constants described later in this document. The $callback is a
878 subroutine reference that will receive the events.
879 All callbacks receive a "Sys::Virt" connection as the first
881 parameter and a "Sys::Virt::StoragePool" object indicating the
882 storage pool on which the event occurred as the second parameter.
883 Subsequent parameters vary according to the event type
884 EVENT_ID_LIFECYCLE
886 Extra "event" and "detail" parameters defining the lifecycle
887 transition that occurred.
888 EVENT_ID_REFRESH
890 No extra parameters.
891 The return value is a unique callback ID that must be used when
893 unregistering the event.
894 $conn->storage_pool_event_deregister_any($callbackID)
896 Unregister a callback, associated with the $callbackID previously
897 obtained from "storage_pool_event_register_any".
898 $callback = $conn->node_device_event_register_any($dev, $eventID,
900 $callback)
901 Register a callback to received notifications of node device
902 events. The $dev parameter can be "undef" to request events on all
903 known node devices, or a specific "Sys::Virt::NodeDevice" object to
904 filter events. The $eventID parameter is one of the EVENT ID
905 constants described later in this document. The $callback is a
906 subroutine reference that will receive the events.
907 All callbacks receive a "Sys::Virt" connection as the first
909 parameter and a "Sys::Virt::NodeDevice" object indicating the node
910 device on which the event occurred as the second parameter.
911 Subsequent parameters vary according to the event type
912 EVENT_ID_LIFECYCLE
914 Extra "event" and "detail" parameters defining the lifecycle
915 transition that occurred.
916 The return value is a unique callback ID that must be used when
918 unregistering the event.
919 $conn->node_device_event_deregister_any($callbackID)
921 Unregister a callback, associated with the $callbackID previously
922 obtained from "node_device_event_register_any".
923 $callback = $conn->secret_event_register_any($secret, $eventID,
925 $callback)
926 Register a callback to received notifications of secret events.
927 The $secret parameter can be "undef" to request events on all known
928 secrets, or a specific "Sys::Virt::Secret" object to filter events.
929 The $eventID parameter is one of the EVENT ID constants described
930 later in this document. The $callback is a subroutine reference
931 that will receive the events.
932 All callbacks receive a "Sys::Virt" connection as the first
934 parameter and a "Sys::Virt::Secret" object indicating the secret on
935 which the event occurred as the second parameter. Subsequent
936 parameters vary according to the event type
937 EVENT_ID_LIFECYCLE
939 Extra "event" and "detail" parameters defining the lifecycle
940 transition that occurred.
941 EVENT_ID_VALUE_CHANGED
943 No extra parameters.
944 The return value is a unique callback ID that must be used when
946 unregistering the event.
947 $conn->secret_event_deregister_any($callbackID)
949 Unregister a callback, associated with the $callbackID previously
950 obtained from "secret_event_register_any".
951 $conn->register_close_callback($coderef);
953 Register a callback to be invoked when the connection is closed.
954 The callback will be invoked with two parameters, the $conn it was
955 registered against, and the reason for the close event. The reason
956 value will be one of the "CLOSE REASON CONSTANTS" listed later in
957 this document.
958 $conn->unregister_close_callback();
960 Remove the previously registered close callback.
961 my $xml = $con->baseline_cpu(\@xml, $flags=0)
963 Given an array ref whose elements are XML documents describing host
964 CPUs, compute the baseline CPU model that is operable across all
965 hosts. The XML for the baseline CPU model is returned. The optional
966 $flags parameter can take one of
967 Sys::Virt::BASELINE_CPU_EXPAND_FEATURES
969 Expand the CPU definition to list all feature flags, even those
970 implied by the model name.
971 Sys::Virt::BASELINE_CPU_MIGRATABLE
973 Only include features which can be live migrated.
974 my $xml = $con->baseline_hypervisor_cpu($emulator, $arch, $machine,
976 $virttype, \@xml, $flags=0)
977 Given an array ref whose elements are XML documents describing host
978 CPUs, compute the baseline CPU model that is operable across all
979 hosts. The XML for the baseline CPU model is returned. Either
980 $emulator or $arch must be a valid string referring to an emulator
981 binary or an architecture name respectively. The $machine parameter
982 is an optional name of a guest machine, and $virttype is an
983 optional name of the virtualization type. The optional $flags
984 parameter accepts the same values as "baseline_cpu".
985 @names = $con->get_cpu_model_names($arch, $flags=0)
987 Get a list of valid CPU models names for the architecture given by
988 $arch. The $arch value should be one of the architectures listed in
989 the capabilities XML document. The $flags parameter is currently
990 unused and defaults to 0.
991 my $info = $con->get_node_security_model()
993 Returns a hash reference summarising the security model of the host
994 node. There are two keys in the hash, "model" specifying the name
995 of the security model (eg 'selinux') and "doi" specifying the
996 'domain of interpretation' for security labels.
997 my $xml = $con->get_capabilities();
999 Returns an XML document describing the hypervisor capabilities
1000 my $xml = $con->get_domain_capabilities($emulator, $arch, $machine,
1002 $virttype, flags=0);
1003 Returns an XML document describing the capabilities of the
1004 requested guest configuration. Either $emulator or $arch must be a
1005 valid string referring to an emulator binary or an architecture
1006 name respectively. The $machine parameter is an optional name of a
1007 guest machine, and $virttype is an optional name of the
1008 virtualization type. $flags is unused and defaults to zero.
1009 my $xml = $con->get_storage_pool_capabilities($flags=0);
1011 Returns an XML document describing the storage pool driver
1012 capabilities (e.g. which storage pool types are supported and so
1013 on). $flags is currently unused and defaults to zero.
1014 my $result = $con->compare_cpu($xml, $flags=0);
1016 Checks whether the CPU definition in $xml is compatible with the
1017 current hypervisor connection. This can be used to determine
1018 whether it is safe to migrate a guest to this host. The returned
1019 result is one of the constants listed later The optional $flags
1020 parameter can take one of the following constants
1021 Sys::Virt::COMPARE_CPU_FAIL_INCOMPATIBLE
1023 Raise a fatal error if the CPUs are not compatible, instead of
1024 just returning a special error code.
1025 my $result = $con->compare_hypervisor_cpu($emulator, $arch, $machine,
1027 $virttype, $xml, $flags=0);
1028 Checks whether the CPU definition in $xml is compatible with the
1029 current hypervisor connection. This can be used to determine
1030 whether it is safe to migrate a guest to this host. Either
1031 $emulator or $arch must be a valid string referring to an emulator
1032 binary or an architecture name respectively. The $machine parameter
1033 is an optional name of a guest machine, and $virttype is an
1034 optional name of the virtualization type. The returned result is
1035 one of the constants listed later The optional $flags parameter can
1036 take the same values as the "compare_cpu" method.
1037 $mem = $con->get_node_free_memory();
1039 Returns the current free memory on the host
1040 @mem = $con->get_node_cells_free_memory($start, $end);
1042 Returns the free memory on each NUMA cell between $start and $end.
1043 @pages = $con->get_node_free_pages(\@pagesizes, $start, $end);
1045 Returns information about the number of pages free on each NUMA
1046 cell between $start and $end inclusive. The @pagesizes parameter
1047 should be an arrayref specifying which pages sizes information
1048 should be returned for. Information about supported page sizes is
1049 available in the capabilities XML. The returned array has an
1050 element for each NUMA cell requested. The elements are hash
1051 references with two keys, 'cell' specifies the NUMA cell number and
1052 'pages' specifies the free page information for that cell. The
1053 'pages' value is another hash reference where the keys are the page
1054 sizes and the values are the free count for that size.
1055 $con->node_alloc_pages(\@pages, $start, $end, $flags=0)
1057 Allocate further huge pages for the reserved dev. The <\@pages>
1058 parameter is an array reference with one entry per page size to
1059 allocate for. Each entry is a further array reference where the
1060 first element is the page size and the second element is the page
1061 count. The same number of pages will be allocated on each NUMA node
1062 in the range $start to $end inclusive. The $flags parameter accepts
1063 two contants
1064 Sys::Virt::NODE_ALLOC_PAGES_ADD
1066 The requested number of pages will be added to the existing
1067 huge page reservation.
1068 Sys::Virt::NODE_ALLOC_PAGES_SET
1070 The huge page reservation will be set to exactly the requested
1071 number
1072
1074 The following sets of constants are useful when dealing with APIs in
1075 this package
1076 CONNECTION
1078 When opening a connection the following constants can be used:
1079 Sys::Virt::CONNECT_RO
1081 Request a read-only connection
1082 Sys::Virt::CONNECT_NO_ALIASES
1084 Prevent the resolution of URI aliases
1085 CREDENTIAL TYPES
1087 When providing authentication callbacks, the following constants
1088 indicate the type of credential being requested
1089 Sys::Virt::CRED_AUTHNAME
1091 Identity to act as
1092 Sys::Virt::CRED_USERNAME
1094 Identity to authorize as
1095 Sys::Virt::CRED_CNONCE
1097 Client supplies a nonce
1098 Sys::Virt::CRED_REALM
1100 Authentication realm
1101 Sys::Virt::CRED_ECHOPROMPT
1103 Challenge response non-secret
1104 Sys::Virt::CRED_NOECHOPROMPT
1106 Challenge response secret
1107 Sys::Virt::CRED_PASSPHRASE
1109 Passphrase secret
1110 Sys::Virt::CRED_LANGUAGE
1112 RFC 1766 language code
1113 Sys::Virt::CRED_EXTERNAL
1115 Externally provided credential
1116 CPU COMPARISON CONSTANTS
1118 Sys::Virt::CPU_COMPARE_INCOMPATIBLE
1119 This host is missing one or more CPU features in the CPU
1120 description
1121 Sys::Virt::CPU_COMPARE_IDENTICAL
1123 The host has an identical CPU description
1124 Sys::Virt::CPU_COMPARE_SUPERSET
1126 The host offers a superset of the CPU descriptoon
1127 NODE SUSPEND CONSTANTS
1129 Sys::Virt::NODE_SUSPEND_TARGET_MEM
1130 Suspends to memory (equivalent of S3 on x86 architectures)
1131 Sys::Virt::NODE_SUSPEND_TARGET_DISK
1133 Suspends to disk (equivalent of S5 on x86 architectures)
1134 Sys::Virt::NODE_SUSPEND_TARGET_HYBRID
1136 Suspends to memory and disk (equivalent of S3+S5 on x86
1137 architectures)
1138 NODE VCPU CONSTANTS
1140 Sys::Virt::NODE_CPU_STATS_ALL_CPUS
1141 Request statistics for all CPUs
1142 NODE MEMORY CONSTANTS
1144 Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS
1145 Request statistics for all memory cells
1146 MEMORY PARAMETERS
1148 The following constants are used to name memory parameters of the node
1149 Sys::Virt::NODE_MEMORY_SHARED_FULL_SCANS
1151 How many times all mergeable areas have been scanned.
1152 Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARED
1154 How many the shared memory pages are being used.
1155 Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARING
1157 How many sites are sharing the pages
1158 Sys::Virt::NODE_MEMORY_SHARED_PAGES_TO_SCAN
1160 How many present pages to scan before the shared memory service
1161 goes to sleep
1162 Sys::Virt::NODE_MEMORY_SHARED_PAGES_UNSHARED
1164 How many pages unique but repeatedly checked for merging.
1165 Sys::Virt::NODE_MEMORY_SHARED_PAGES_VOLATILE
1167 How many pages changing too fast to be placed in a tree.
1168 Sys::Virt::NODE_MEMORY_SHARED_SLEEP_MILLISECS
1170 How many milliseconds the shared memory service should sleep before
1171 next scan.
1172 Sys::Virt::NODE_MEMORY_SHARED_MERGE_ACROSS_NODES
1174 Whether pages can be merged across NUMA nodes
1175 CLOSE REASON CONSTANTS
1177 The following constants related to the connection close callback,
1178 describe the reason for the closing of the connection.
1179 Sys::Virt::CLOSE_REASON_CLIENT
1181 The client application requested the connection be closed
1182 Sys::Virt::CLOSE_REASON_EOF
1184 End-of-file was encountered reading data from the connection
1185 Sys::Virt::CLOSE_REASON_ERROR
1187 An I/O error was encountered reading/writing data from/to the
1188 connection
1189 Sys::Virt::CLOSE_REASON_KEEPALIVE
1191 The connection keepalive timer triggered due to lack of response
1192 from the server
1193 CPU STATS CONSTANTS
1195 The following constants provide the names of known CPU stats fields
1196 Sys::Virt::NODE_CPU_STATS_IDLE
1198 Time spent idle
1199 Sys::Virt::NODE_CPU_STATS_IOWAIT
1201 Time spent waiting for I/O to complete
1202 Sys::Virt::NODE_CPU_STATS_KERNEL
1204 Time spent executing kernel code
1205 Sys::Virt::NODE_CPU_STATS_USER
1207 Time spent executing user code
1208 Sys::Virt::NODE_CPU_STATS_INTR
1210 Time spent processing interrupts
1211 Sys::Virt::NODE_CPU_STATS_UTILIZATION
1213 Percentage utilization of the CPU.
1214 MEMORY STAS CONSTANTS
1216 The following constants provide the names of known memory stats fields
1217 Sys::Virt::NODE_MEMORY_STATS_BUFFERS
1219 The amount of memory consumed by I/O buffers
1220 Sys::Virt::NODE_MEMORY_STATS_CACHED
1222 The amount of memory consumed by disk cache
1223 Sys::Virt::NODE_MEMORY_STATS_FREE
1225 The amount of free memory
1226 Sys::Virt::NODE_MEMORY_STATS_TOTAL
1228 The total amount of memory
1229 IP address constants
1231 The following constants are used to interpret IP address types
1232 Sys::Virt::IP_ADDR_TYPE_IPV4
1234 An IPv4 address type
1235 Sys::Virt::IP_ADDR_TYPE_IPV6
1237 An IPv6 address type
1238
1240 Hopefully none, but the XS code needs to be audited to ensure it is not
1241 leaking memory.
1242
1244 Daniel P. Berrange <berrange@redhat.com>
1245
1247 Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P.
1248 Berrange
1249
1251 This program is free software; you can redistribute it and/or modify it
1252 under the terms of either the GNU General Public License as published
1253 by the Free Software Foundation (either version 2 of the License, or at
1254 your option any later version), or, the Artistic License, as specified
1255 in the Perl README file.
1256
1258 Sys::Virt::Domain, Sys::Virt::Network, Sys::Virt::StoragePool,
1259 Sys::Virt::StorageVol, Sys::Virt::Error, "http://libvirt.org"
1260perl v5.30.0 2019-08-06 Sys::Virt(3)