1Sys::Virt::Domain(3) User Contributed Perl Documentation Sys::Virt::Domain(3)
2
6 Sys::Virt::Domain - Represent & manage a libvirt guest domain
7
9 The "Sys::Virt::Domain" module represents a guest domain managed by the
10 virtual machine monitor.
11
13 my $id = $dom->get_id()
14 Returns an integer with a locally unique identifier for the domain.
15 my $uuid = $dom->get_uuid()
17 Returns a 16 byte long string containing the raw globally unique
18 identifier (UUID) for the domain.
19 my $uuid = $dom->get_uuid_string()
21 Returns a printable string representation of the raw UUID, in the
22 format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'.
23 my $name = $dom->get_name()
25 Returns a string with a locally unique name of the domain
26 my $hostname = $dom->get_hostname()
28 Returns a string representing the hostname of the guest
29 my $str = $dom->get_metadata($type, $uri, $flags =0)
31 Returns the metadata element of type $type associated with the
32 domain. If $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the
33 $uri parameter specifies the XML namespace to retrieve, otherwise
34 $uri should be "undef". The optional $flags parameter defaults to
35 zero.
36 $dom->set_metadata($type, $val, $key, $uri, $flags=0)
38 Sets the metadata element of type $type to hold the value $val. If
39 $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the $key and
40 $uri elements specify an XML namespace to use, otherwise they
41 should both be "undef". The optional $flags parameter defaults to
42 zero.
43 $dom->is_active()
45 Returns a true value if the domain is currently running
46 $dom->is_persistent()
48 Returns a true value if the domain has a persistent configuration
49 file defined
50 $dom->is_updated()
52 Returns a true value if the domain is running and has a persistent
53 configuration file defined that is out of date compared to the
54 current live config.
55 my $xml = $dom->get_xml_description($flags=0)
57 Returns an XML document containing a complete description of the
58 domain's configuration. The optional $flags parameter controls
59 generation of the XML document, defaulting to 0 if omitted. It can
60 be one or more of the XML DUMP constants listed later in this
61 document.
62 my $type = $dom->get_os_type()
64 Returns a string containing the name of the OS type running within
65 the domain.
66 $dom->create($flags)
68 Start a domain whose configuration was previously defined using the
69 "define_domain" method in Sys::Virt. The $flags parameter accepts
70 one of the DOMAIN CREATION constants documented later, and defaults
71 to 0 if omitted.
72 $dom->create_with_files($fds, $flags)
74 Start a domain whose configuration was previously defined using the
75 "define_domain" method in Sys::Virt. The $fds parameter is an array
76 of UNIX file descriptors which will be passed to the init process
77 of the container. This is only supported with container based
78 virtualization.The $flags parameter accepts one of the DOMAIN
79 CREATION constants documented later, and defaults to 0 if omitted.
80 $dom->undefine()
82 Remove the configuration associated with a domain previously
83 defined with the "define_domain" method in Sys::Virt. If the domain
84 is running, you probably want to use the "shutdown" or "destroy"
85 methods instead.
86 $dom->suspend()
88 Temporarily stop execution of the domain, allowing later
89 continuation by calling the "resume" method.
90 $dom->resume()
92 Resume execution of a domain previously halted with the "suspend"
93 method.
94 $dom->pm_wakeup()
96 Wakeup the guest from power management suspend state
97 $dom->pm_suspend_for_duration($target, $duration, $flags=0)
99 Tells the guest OS to enter the power management suspend state
100 identified by $target. The $target parameter should be one of the
101 NODE SUSPEND CONTANTS listed in "Sys::Virt". The $duration
102 specifies when the guest should automatically wakeup. The $flags
103 parameter is optional and defaults to zero.
104 $dom->save($filename)
106 Take a snapshot of the domain's state and save the information to
107 the file named in the $filename parameter. The domain can later be
108 restored from this file with the "restore_domain" method on the
109 Sys::Virt object.
110 $dom->managed_save($flags=0)
112 Take a snapshot of the domain's state and save the information to a
113 managed save location. The domain will be automatically restored
114 with this state when it is next started. The $flags parameter is
115 unused and defaults to zero.
116 $bool = $dom->has_managed_save_image($flags=0)
118 Return a non-zero value if the domain has a managed save image that
119 will be used at next start. The $flags parameter is unused and
120 defaults to zero.
121 $dom->managed_save_remove($flags=0)
123 Remove the current managed save image, causing the guest to perform
124 a full boot next time it is started. The $flags parameter is unused
125 and defaults to zero.
126 $dom->managed_save_define_xml($xml, $flags=0)
128 Update the XML of the managed save image to $xml. The $flags
129 parameter is unused and defaults to zero.
130 $xml = $dom->managed_save_get_xml_description($flags=0)
132 Get the XML in the managed save image. The $flags parameter is
133 unused and defaults to zero.
134 $dom->core_dump($filename[, $flags])
136 Trigger a core dump of the guest virtual machine, saving its memory
137 image to $filename so it can be analysed by tools such as "crash".
138 The optional $flags flags parameter is currently unused and if
139 omitted will default to 0.
140 $dom->core_dump_format($filename, $format, [, $flags])
142 Trigger a core dump of the guest virtual machine, saving its memory
143 image to $filename so it can be analysed by tools such as "crash".
144 The $format parameter is one of the core dump format constants.
145 The optional $flags flags parameter is currently unused and if
146 omitted will default to 0.
147 Sys::Virt::Domain::CORE_DUMP_FORMAT_RAW
149 The raw ELF format
150 Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_ZLIB
152 The zlib compressed ELF format
153 Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_SNAPPY
155 The snappy compressed ELF format
156 Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_LZO
158 The lzo compressed ELF format
159 $dom->destroy()
161 Immediately poweroff the machine. This is equivalent to removing
162 the power plug. The guest OS is given no time to cleanup / save
163 state. For a clean poweroff sequence, use the "shutdown" method
164 instead.
165 my $info = $dom->get_info()
167 Returns a hash reference summarising the execution state of the
168 domain. The elements of the hash are as follows:
169 maxMem
171 The maximum memory allowed for this domain, in kilobytes
172 memory
174 The current memory allocated to the domain in kilobytes
175 cpuTime
177 The amount of CPU time used by the domain
178 nrVirtCpu
180 The current number of virtual CPUs enabled in the domain
181 state
183 The execution state of the machine, which will be one of the
184 constants &Sys::Virt::Domain::STATE_*.
185 my ($state, $reason) = $dom->get_state()
187 Returns an array whose values specify the current state of the
188 guest, and the reason for it being in that state. The $state
189 values are the same as for the "get_info" API, and the $reason
190 values come from:
191 Sys::Virt::Domain::STATE_CRASHED_UNKNOWN
193 It is not known why the domain has crashed
194 Sys::Virt::Domain::STATE_CRASHED_PANICKED
196 The domain has crashed due to a kernel panic
197 Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN
199 It is not known why the domain has no state
200 Sys::Virt::Domain::STATE_PAUSED_DUMP
202 The guest is paused due to a core dump operation
203 Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT
205 The guest is paused due to a snapshot
206 Sys::Virt::Domain::STATE_PAUSED_IOERROR
208 The guest is paused due to an I/O error
209 Sys::Virt::Domain::STATE_PAUSED_MIGRATION
211 The guest is paused due to migration
212 Sys::Virt::Domain::STATE_PAUSED_SAVE
214 The guest is paused due to a save operation
215 Sys::Virt::Domain::STATE_PAUSED_UNKNOWN
217 It is not known why the domain has paused
218 Sys::Virt::Domain::STATE_PAUSED_USER
220 The guest is paused at admin request
221 Sys::Virt::Domain::STATE_PAUSED_WATCHDOG
223 The guest is paused due to the watchdog
224 Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN
226 The guest is paused while domain shutdown takes place
227 Sys::Virt::Domain::STATE_PAUSED_SNAPSHOT
229 The guest is paused while a snapshot takes place
230 Sys::Virt::Domain::STATE_PAUSED_CRASHED
232 The guest is paused due to a kernel panic
233 Sys::Virt::Domain::STATE_PAUSED_STARTING_UP
235 The guest is paused as it is being started up.
236 Sys::Virt::Domain::STATE_PAUSED_POSTCOPY
238 The guest is paused as post-copy migration is taking place
239 Sys::Virt::Domain::STATE_PAUSED_POSTCOPY_FAILED
241 The guest is paused as post-copy migration failed
242 Sys::Virt::Domain::STATE_RUNNING_BOOTED
244 The guest is running after being booted
245 Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT
247 The guest is running after restore from snapshot
248 Sys::Virt::Domain::STATE_RUNNING_MIGRATED
250 The guest is running after migration
251 Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED
253 The guest is running after migration abort
254 Sys::Virt::Domain::STATE_RUNNING_RESTORED
256 The guest is running after restore from file
257 Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED
259 The guest is running after save cancel
260 Sys::Virt::Domain::STATE_RUNNING_UNKNOWN
262 It is not known why the domain has started
263 Sys::Virt::Domain::STATE_RUNNING_UNPAUSED
265 The guest is running after a resume
266 Sys::Virt::Domain::STATE_RUNNING_WAKEUP
268 The guest is running after wakeup from power management suspend
269 Sys::Virt::Domain::STATE_RUNNING_CRASHED
271 The guest was restarted after crashing
272 Sys::Virt::Domain::STATE_RUNNING_POSTCOPY
274 The guest is running but post-copy is taking place
275 Sys::Virt::Domain::STATE_BLOCKED_UNKNOWN
277 The guest is blocked for an unknown reason
278 Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN
280 It is not known why the domain has shutdown
281 Sys::Virt::Domain::STATE_SHUTDOWN_USER
283 The guest is shutdown due to admin request
284 Sys::Virt::Domain::STATE_SHUTOFF_CRASHED
286 The guest is shutoff after a crash
287 Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED
289 The guest is shutoff after being destroyed
290 Sys::Virt::Domain::STATE_SHUTOFF_FAILED
292 The guest is shutoff due to a virtualization failure
293 Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT
295 The guest is shutoff after a snapshot
296 Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED
298 The guest is shutoff after migration
299 Sys::Virt::Domain::STATE_SHUTOFF_SAVED
301 The guest is shutoff after a save
302 Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN
304 The guest is shutoff due to controlled shutdown
305 Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN
307 It is not known why the domain has shutoff
308 Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN
310 It is not known why the domain was suspended to RAM
311 Sys::Virt::Domain::STATE_PMSUSPENDED_DISK_UNKNOWN
313 It is not known why the domain was suspended to disk
314 my $info = $dom->get_control_info($flags=0)
316 Returns a hash reference providing information about the control
317 channel. The returned keys in the hash are
318 "state"
320 One of the CONTROL INFO constants listed later
321 "details"
323 Currently unused, always 0.
324 "stateTime"
326 The elapsed time since the control channel entered the current
327 state.
328 my $time = $dom->get_time($flags=0);
330 Get the current time of the guest, in seconds and nanoseconds. The
331 $flags parameter is currently unused and defaults to zero. The
332 return value is an array ref with two elements, the first contains
333 the time in seconds, the second contains the remaining nanoseconds.
334 $dom->set_time($secs, $nsecs, $flags=0);
336 Set the current time of the guest, in seconds and nanoseconds. The
337 $flags parameter accepts one of
338 "Sys::Virt::Domain::TIME_SYNC"
340 Re-sync domain time from domain's RTC.
341 $dom->set_user_password($username, $password, $flags=0);
343 Update the password for account $username to be $password.
344 $password is the clear-text password string unless the
345 PASSWORD_ENCRYPTED flag is set.
346 "Sys::Virt::Domain::PASSWORD_ENCRYPTED"
348 The $password is encrypted with the password scheme required by
349 the guest OS.
350 $dom->rename($newname, $flags=0)
352 Change the name of an inactive guest to be $newname. The $flags
353 parameter is currently unused and defaults to zero.
354 my @errs = $dom->get_disk_errors($flags=0)
356 Returns a list of all disk errors that have occurred on the backing
357 store for the guest's virtual disks. The returned array elements
358 are hash references, containing two keys
359 "path"
361 The path of the disk with an error
362 "error"
364 The error type
365 $dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0)
367 Sends a sequence of keycodes to the guest domain. The $keycodeset
368 should be one of the constants listed later in the KEYCODE SET
369 section. $holdtiem is the duration, in milliseconds, to keep the
370 key pressed before releasing it and sending the next keycode.
371 @keycodes is an array reference containing the list of keycodes to
372 send to the guest. The elements in the array should be keycode
373 values from the specified keycode set. $flags is currently unused.
374 my $info = $dom->get_block_info($dev, $flags=0)
376 Returns a hash reference summarising the disk usage of the host
377 backing store for a guest block device. The $dev parameter should
378 be the path to the backing store on the host. $flags is currently
379 unused and defaults to 0 if omitted. The returned hash contains the
380 following elements
381 capacity
383 Logical size in bytes of the block device backing image *
384 allocation
386 Highest allocated extent in bytes of the block device backing
387 image
388 physical
390 Physical size in bytes of the container of the backing image
391 $dom->set_max_memory($mem)
393 Set the maximum memory for the domain to the value $mem. The value
394 of the $mem parameter is specified in kilobytes.
395 $mem = $dom->get_max_memory()
397 Returns the current maximum memory allowed for this domain in
398 kilobytes.
399 $dom->set_memory($mem, $flags)
401 Set the current memory for the domain to the value $mem. The value
402 of the $mem parameter is specified in kilobytes. This must be less
403 than, or equal to the domain's max memory limit. The $flags
404 parameter can control whether the update affects the live guest, or
405 inactive config, defaulting to modifying the current state.
406 $dom->set_memory_stats_period($period, $flags)
408 Set the period on which guests memory stats are refreshed, with
409 $period being a value in seconds. The $flags parameter is currently
410 unused.
411 $dom->shutdown()
413 Request that the guest OS perform a graceful shutdown and poweroff.
414 This usually requires some form of cooperation from the guest
415 operating system, such as responding to an ACPI signal, or a guest
416 agent process. For an immediate, forceful poweroff, use the
417 "destroy" method instead.
418 $dom->reboot([$flags])
420 Request that the guest OS perform a graceful shutdown and
421 optionally restart. The optional $flags parameter is currently
422 unused and if omitted defaults to zero.
423 $dom->reset([$flags])
425 Perform a hardware reset of the virtual machine. The guest OS is
426 given no opportunity to shutdown gracefully. The optional $flags
427 parameter is currently unused and if omitted defaults to zero.
428 $dom->get_max_vcpus()
430 Return the maximum number of vcpus that are configured for the
431 domain
432 $dom->attach_device($xml[, $flags])
434 Hotplug a new device whose configuration is given by $xml, to the
435 running guest. The optional <$flags> parameter defaults to 0, but
436 can accept one of the device hotplug flags described later.
437 $dom->detach_device($xml[, $flags])
439 Hotunplug an existing device whose configuration is given by $xml,
440 from the running guest. The optional <$flags> parameter defaults to
441 0, but can accept one of the device hotplug flags described later.
442 $dom->detach_device_alias($alias[, $flags])
444 Hotunplug an existing device which is identified by $alias. The
445 optional <$flags> parameter defaults to 0, but can accept one of
446 the device hotplug flags described later.
447 $dom->update_device($xml[, $flags])
449 Update the configuration of an existing device. The new
450 configuration is given by $xml. The optional <$flags> parameter
451 defaults to 0 but can accept one of the device hotplug flags
452 described later.
453 $data = $dom->block_peek($path, $offset, $size[, $flags])
455 Peek into the guest disk $path, at byte $offset capturing $size
456 bytes of data. The returned scalar may contain embedded NULLs. The
457 optional $flags parameter is currently unused and if omitted
458 defaults to zero.
459 $data = $dom->memory_peek($offset, $size[, $flags])
461 Peek into the guest memory at byte $offset virtual address,
462 capturing $size bytes of memory. The return scalar may contain
463 embedded NULLs. The optional $flags parameter is currently unused
464 and if omitted defaults to zero.
465 $flag = $dom->get_autostart();
467 Return a true value if the guest domain is configured to
468 automatically start upon boot. Return false, otherwise
469 $dom->set_autostart($flag)
471 Set the state of the autostart flag, which determines whether the
472 guest will automatically start upon boot of the host OS
473 $dom->set_vcpus($count, [$flags])
475 Set the number of virtual CPUs in the guest VM to $count. The
476 optional $flags parameter can be used to control whether the
477 setting changes the live config or inactive config.
478 $dom->set_vcpu($cpumap, $state, [$flags])
480 Set the state of the CPUs in $cpumap to $state. The $flags
481 parameter defaults to zero if not present.
482 $count = $dom->get_vcpus([$flags])
484 Get the number of virtual CPUs in the guest VM. The optional
485 $flags parameter can be used to control whether to query the
486 setting of the live config or inactive config.
487 $dom->set_guest_vcpus($cpumap, $state, [$flags=0])
489 Set the online status of the guest OS CPUs. The $cpumap parameter
490 describes the set of CPUs to modify (eg "0-3,^1"). $state is
491 either 1 to set the CPUs online, or 0 to set them offline. The
492 $flags parameter is currently unused and defaults to 0.
493 $info $dom->get_guest_vcpus([$flags=0])
495 Query information about the guest OS CPUs. The returned data is a
496 hash reference with the following keys.
497 vcpus
499 String containing bitmap representing CPU ids reported
500 currently known to the guest.
501 online
503 String containing bitmap representing CPU ids that are
504 currently online in the guest.
505 offlinable
507 String containing bitmap representing CPU ids that can be
508 offlined in the guest.
509 The $flags parameter is currently unused and defaults to 0.
511 $type = $dom->get_scheduler_type()
513 Return the scheduler type for the guest domain
514 $stats = $dom->block_stats($path)
516 Fetch the current I/O statistics for the block device given by
517 $path. The returned hash reference contains keys for
518 "rd_req"
520 Number of read requests
521 "rd_bytes"
523 Number of bytes read
524 "wr_req"
526 Number of write requests
527 "wr_bytes"
529 Number of bytes written
530 "errs"
532 Some kind of error count
533 my $params = $dom->get_scheduler_parameters($flags=0)
535 Return the set of scheduler tunable parameters for the guest, as a
536 hash reference. The precise set of keys in the hash are specific to
537 the hypervisor.
538 $dom->set_scheduler_parameters($params, $flags=0)
540 Update the set of scheduler tunable parameters. The value names for
541 tunables vary, and can be discovered using the
542 "get_scheduler_params" call
543 my $params = $dom->get_memory_parameters($flags=0)
545 Return a hash reference containing the set of memory tunable
546 parameters for the guest. The keys in the hash are one of the
547 constants MEMORY PARAMETERS described later. The $flags parameter
548 accepts one or more the CONFIG OPTION constants documented later,
549 and defaults to 0 if omitted.
550 $dom->set_memory_parameters($params, $flags=0)
552 Update the memory tunable parameters for the guest. The $params
553 should be a hash reference whose keys are one of the MEMORY
554 PARAMETERS constants. The $flags parameter accepts one or more the
555 CONFIG OPTION constants documented later, and defaults to 0 if
556 omitted.
557 my $params = $dom->get_blkio_parameters($flags=0)
559 Return a hash reference containing the set of blkio tunable
560 parameters for the guest. The keys in the hash are one of the
561 constants BLKIO PARAMETERS described later. The $flags parameter
562 accepts one or more the CONFIG OPTION constants documented later,
563 and defaults to 0 if omitted.
564 $dom->set_blkio_parameters($params, $flags=0)
566 Update the blkio tunable parameters for the guest. The $params
567 should be a hash reference whose keys are one of the BLKIO
568 PARAMETERS constants. The $flags parameter accepts one or more the
569 CONFIG OPTION constants documented later, and defaults to 0 if
570 omitted.
571 $stats = $dom->get_block_iotune($disk, $flags=0)
573 Return a hash reference containing the set of blkio tunable
574 parameters for the guest disk $disk. The keys in the hash are one
575 of the constants BLOCK IOTUNE PARAMETERS described later.
576 $dom->set_block_iotune($disk, $params, $flags=0);
578 Update the blkio tunable parameters for the guest disk $disk. The
579 $params should be a hash reference whose keys are one of the BLOCK
580 IOTUNE PARAMETERS constants.
581 my $params = $dom->get_interface_parameters($intf, $flags=0)
583 Return a hash reference containing the set of interface tunable
584 parameters for the guest. The keys in the hash are one of the
585 constants INTERFACE PARAMETERS described later.
586 $dom->set_interface_parameters($intf, $params, $flags=0)
588 Update the interface tunable parameters for the guest. The $params
589 should be a hash reference whose keys are one of the INTERFACE
590 PARAMETERS constants.
591 my $params = $dom->get_numa_parameters($flags=0)
593 Return a hash reference containing the set of numa tunable
594 parameters for the guest. The keys in the hash are one of the
595 constants NUMA PARAMETERS described later. The $flags parameter
596 accepts one or more the CONFIG OPTION constants documented later,
597 and defaults to 0 if omitted.
598 $dom->set_numa_parameters($params, $flags=0)
600 Update the numa tunable parameters for the guest. The $params
601 should be a hash reference whose keys are one of the NUMA
602 PARAMETERS constants. The $flags parameter accepts one or more the
603 CONFIG OPTION constants documented later, and defaults to 0 if
604 omitted.
605 my $params = $dom->get_perf_events($flags=0)
607 Return a hash reference containing the set of performance events
608 that are available for the guest. The keys in the hash are one of
609 the constants PERF EVENTS described later. The $flags parameter
610 accepts one or more the CONFIG OPTION constants documented later,
611 and defaults to 0 if omitted.
612 $dom->set_perf_events($params, $flags=0)
614 Update the enabled state for performance events for the guest. The
615 $params should be a hash reference whose keys are one of the PERF
616 EVENTS constants. The $flags parameter accepts one or more the
617 CONFIG OPTION constants documented later, and defaults to 0 if
618 omitted.
619 $dom->block_resize($disk, $newsize, $flags=0)
621 Resize the disk $disk to have new size $newsize KB. If the disk is
622 backed by a special image format, the actual resize is done by the
623 hypervisor. If the disk is backed by a raw file, or block device,
624 the resize must be done prior to invoking this API call, and it
625 merely updates the hypervisor's view of the disk size. The
626 following flags may be used
627 Sys::Virt::Domain::BLOCK_RESIZE_BYTES
629 Treat $newsize as if it were in bytes, rather than KB.
630 $dom->interface_stats($path)
632 Fetch the current I/O statistics for the block device given by
633 $path. The returned hash containins keys for
634 "rx_bytes"
636 Total bytes received
637 "rx_packets"
639 Total packets received
640 "rx_errs"
642 Total packets received with errors
643 "rx_drop"
645 Total packets drop at reception
646 "tx_bytes"
648 Total bytes transmitted
649 "tx_packets"
651 Total packets transmitted
652 "tx_errs"
654 Total packets transmitted with errors
655 "tx_drop"
657 Total packets dropped at transmission.
658 $dom->memory_stats($flags=0)
660 Fetch the current memory statistics for the guest domain. The
661 $flags parameter is currently unused and can be omitted. The
662 returned hash containins keys for
663 "swap_in"
665 Data read from swap space
666 "swap_out"
668 Data written to swap space
669 "major_fault"
671 Page fault involving disk I/O
672 "minor_fault"
674 Page fault not involving disk I/O
675 "unused"
677 Memory not used by the system
678 "available"
680 Total memory seen by guest
681 "rss"
683 Resident set size. Size of memory resident in host RAM.
684 $info = $dom->get_security_label()
686 Fetch information about the security label assigned to the guest
687 domain. The returned hash reference has two keys, "model" gives the
688 name of the security model in effect (eg "selinux"), while "label"
689 provides the name of the security label applied to the domain. This
690 method only returns information about the first security label. To
691 retrieve all labels, use "get_security_label_list".
692 @info = $dom->get_security_label_list()
694 Fetches information about all security labels assigned to the guest
695 domain. The elements in the returned array are all hash references,
696 whose keys are as described for "get_security_label".
697 $ddom = $dom->migrate(destcon, \%params, flags=0)
699 Migrate a domain to an alternative host. The "destcon" parameter
700 should be a "Sys::Virt" connection to the remote target host. The
701 "flags" parameter takes one or more of the
702 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
703 document. The %params parameter is a hash reference used to set
704 various parameters for the migration operation, with the following
705 valid keys.
706 "Sys::Virt::Domain::MIGRATE_PARAM_URI"
708 The URI to use for initializing the domain migration. It takes
709 a hypervisor specific format. The uri_transports element of the
710 hypervisor capabilities XML includes details of the supported
711 URI schemes. When omitted libvirt will auto-generate suitable
712 default URI. It is typically only necessary to specify this URI
713 if the destination host has multiple interfaces and a specific
714 interface is required to transmit migration data.
715 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_NAME"
717 The name to be used for the domain on the destination host.
718 Omitting this parameter keeps the domain name the same. This
719 field is only allowed to be used with hypervisors that support
720 domain renaming during migration.
721 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_XML"
723 The new configuration to be used for the domain on the
724 destination host. The configuration must include an identical
725 set of virtual devices, to ensure a stable guest ABI across
726 migration. Only parameters related to host side configuration
727 can be changed in the XML. Hypervisors which support this field
728 will forbid migration if the provided XML would cause a change
729 in the guest ABI. This field cannot be used to rename the
730 domain during migration (use VIR_MIGRATE_PARAM_DEST_NAME field
731 for that purpose). Domain name in the destination XML must
732 match the original domain name.
733 Omitting this parameter keeps the original domain
735 configuration. Using this field with hypervisors that do not
736 support changing domain configuration during migration will
737 result in a failure.
738 "Sys::Virt::Domain::MIGRATE_PARAM_GRAPHICS_URI"
740 URI to use for migrating client's connection to domain's
741 graphical console as VIR_TYPED_PARAM_STRING. If specified, the
742 client will be asked to automatically reconnect using these
743 parameters instead of the automatically computed ones. This can
744 be useful if, e.g., the client does not have a direct access to
745 the network virtualization hosts are connected to and needs to
746 connect through a proxy. The URI is formed as follows:
747 protocol://hostname[:port]/[?parameters]
749 where protocol is either "spice" or "vnc" and parameters is a
751 list of protocol specific parameters separated by '&'.
752 Currently recognized parameters are "tlsPort" and "tlsSubject".
753 For example,
754 spice://target.host.com:1234/?tlsPort=4567
756 "Sys::Virt::Domain::MIGRATE_PARAM_BANDWIDTH"
758 The maximum bandwidth (in MiB/s) that will be used for
759 migration. If set to 0 or omitted, libvirt will choose a
760 suitable default. Some hypervisors do not support this feature
761 and will return an error if this field is used and is not 0.
762 "Sys::Virt::Domain::MIGRATE_PARAM_LISTEN_ADDRESS"
764 The address on which to listen for incoming migration
765 connections. If omitted, libvirt will listen on the wildcard
766 address (0.0.0.0 or ::). This default may be a security risk if
767 guests, or other untrusted users have the ability to connect to
768 the virtualization host, thus use of an explicit restricted
769 listen address is recommended.
770 "Sys::Virt::Domain::MIGRATE_PARAM_DISK_PORT"
772 Port that destination server should use for incoming disks
773 migration. Type is VIR_TYPED_PARAM_INT. If set to 0 or omitted,
774 libvirt will choose a suitable default. At the moment this is
775 only supported by the QEMU driver.
776 "Sys::Virt::Domain::MIGRATE_PARAM_MIGRATE_DISKS"
778 The list of disks to migrate when doing block storage
779 migration. In constrast to other parameters whose values are
780 plain strings, the parameter value should be an array
781 reference, whose elements are in turn strings representing the
782 disk target names.
783 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION"
785 The type of compression method use use, either "xbzrle" or
786 "mt".
787 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_THREADS"
789 The number of compression threads to use
790 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_DTHREADS"
792 The number of decompression threads
793 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_LEVEL"
795 The compression level from 0 (no compression) to 9 (maximum
796 compression)
797 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_XBZRLE_CACHE"
799 The size of the cache for xbzrle compression
800 "Sys::Virt::Domain::MIGRATE_PARAM_PERSIST_XML"
802 The alternative persistent XML config to copy
803 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INITIAL"
805 The initial percentage to throttle guest vCPUs
806 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INCREMENT"
808 The additional percentage step size to throttle guest vCPUs if
809 progress is not made
810 $ddom = $dom->migrate(destcon, flags=0, dname=undef, uri=undef,
812 bandwidth=0)
813 Migrate a domain to an alternative host. Use of positional
814 parameters with "migrate" is deprecated in favour of passing a hash
815 reference as described above.
816 $ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)
818 Migrate a domain to an alternative host. This method is deprecated
819 in favour of passing a hash ref to "migrate".
820 $ddom = $dom->migrate_to_uri(desturi, \%params, flags=0)
822 Migrate a domain to an alternative host. The "desturi" parameter
823 should be a valid libvirt connection URI for the remote target
824 host. The "flags" parameter takes one or more of the
825 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
826 document. The %params parameter is a hash reference used to set
827 various parameters for the migration operation, with the same keys
828 described for the "migrate" API.
829 $dom->migrate_to_uri(desturi, flags, dname, bandwidth)
831 Migrate a domain to an alternative host. Use of positional
832 parameters with "migrate_to_uri" is deprecated in favour of passing
833 a hash reference as described above.
834 $dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)
836 Migrate a domain to an alternative host. This method is deprecated
837 in favour of passing a hash ref to "migrate_to_uri".
838 $dom->migrate_set_max_downtime($downtime, $flags=0)
840 Set the maximum allowed downtime during migration of the guest. A
841 longer downtime makes it more likely that migration will complete,
842 at the cost of longer time blackout for the guest OS at the switch
843 over point. The "downtime" parameter is measured in milliseconds.
844 The $flags parameter is currently unused and defaults to zero.
845 $downtime = $dom->migrate_get_max_downtime($flags=0) Get the current
847 value of the maximum downtime allowed during a migration of a guest.
848 The returned <downtime> value is measured in milliseconds. The $flags
849 parameter is currently unused and defaults to zero.
850 $dom->migrate_set_max_speed($bandwidth, $flags=0)
851 Set the maximum allowed bandwidth during migration of the guest.
852 The "bandwidth" parameter is measured in MB/second. The $flags
853 parameter is currently unused and defaults to zero.
854 $bandwidth = $dom->migrate_get_max_speed($flags=0)
856 Get the maximum allowed bandwidth during migration fo the guest.
857 The returned <bandwidth> value is measured in MB/second. The
858 $flags parameter is currently unused and defaults to zero.
859 $dom->migrate_set_compression_cache($cacheSize, $flags=0)
861 Set the maximum allowed compression cache size during migration of
862 the guest. The "cacheSize" parameter is measured in bytes. The
863 $flags parameter is currently unused and defaults to zero.
864 $cacheSize = $dom->migrate_get_compression_cache($flags=0)
866 Get the maximum allowed compression cache size during migration of
867 the guest. The returned <bandwidth> value is measured in bytes.
868 The $flags parameter is currently unused and defaults to zero.
869 $dom->migrate_start_post_copy($flags=0)
871 Switch the domain from pre-copy to post-copy mode. This requires
872 that the original migrate command had the
873 "Sys::Virt::Domain::MIGRATE_POST_COPY" flag specified.
874 $dom->inject_nmi($flags)
876 Trigger an NMI in the guest virtual machine. The $flags parameter
877 is currently unused and defaults to 0.
878 $dom->open_console($st, $devname, $flags)
880 Open the text console for a serial, parallel or paravirt console
881 device identified by $devname, connecting it to the stream $st. If
882 $devname is undefined, the default console will be opened. $st must
883 be a "Sys::Virt::Stream" object used for bi-directional
884 communication with the console. $flags is currently unused,
885 defaulting to 0.
886 $dom->open_channel($st, $devname, $flags)
888 Open the text console for a data channel device identified by
889 $devname, connecting it to the stream $st. $st must be a
890 "Sys::Virt::Stream" object used for bi-directional communication
891 with the channel. $flags is currently unused, defaulting to 0.
892 $dom->open_graphics($idx, $fd, $flags)
894 Open the graphics console for a guest, identified by $idx, counting
895 from 0. The $fd should be a file descriptor for an anoymous socket
896 pair. The $flags argument should be one of the constants listed at
897 the end of this document, and defaults to 0.
898 $fd = $dom->open_graphics_fd($idx, $flags)
900 Open the graphics console for a guest, identified by $idx, counting
901 from 0. The $flags argument should be one of the constants listed
902 at the end of this document, and defaults to 0. The return value
903 will be a file descriptor connected to the console which must be
904 closed when no longer needed. This method is preferred over
905 "open_graphics" since it will work correctly under sVirt mandatory
906 access control policies.
907 my $mimetype = $dom->screenshot($st, $screen, $flags)
909 Capture a screenshot of the virtual machine's monitor. The $screen
910 parameter controls which monitor is captured when using a multi-
911 head or multi-card configuration. $st must be a "Sys::Virt::Stream"
912 object from which the data can be read. $flags is currently unused
913 and defaults to 0. The mimetype of the screenshot is returned
914 @vcpuinfo = $dom->get_vcpu_info($flags=0)
916 Obtain information about the state of all virtual CPUs in a running
917 guest domain. The returned list will have one element for each
918 vCPU, where each elements contains a hash reference. The keys in
919 the hash are, "number" the vCPU number, "cpu" the physical CPU on
920 which the vCPU is currently scheduled, "cpuTime" the cummulative
921 execution time of the vCPU, "state" the running state and
922 "affinity" giving the allowed shedular placement. The value for
923 "affinity" is a string representing a bitmask against physical
924 CPUs, 8 cpus per character. To extract the bits use the "unpack"
925 function with the "b*" template. NB The "state", "cpuTime", "cpu"
926 values are only available if using $flags value of 0, and the
927 domain is currently running; otherwise they will all be set to
928 zero.
929 $dom->pin_vcpu($vcpu, $mask)
931 Pin the virtual CPU given by index $vcpu to physical CPUs given by
932 $mask. The $mask is a string representing a bitmask against
933 physical CPUs, 8 cpus per character.
934 $mask = $dom->get_emulator_pin_info()
936 Obtain information about the CPU affinity of the emulator process.
937 The returned $mask is a bitstring against physical CPUs, 8 cpus per
938 character. To extract the bits use the "unpack" function with the
939 "b*" template.
940 $dom->pin_emulator($newmask, $flags=0)
942 Pin the emulator threads to the physical CPUs identified by the
943 affinity in $newmask. The $newmask is a bitstring against the
944 physical CPUa, 8 cpus per character. To create a suitable
945 bitstring, use the "vec" function with a value of 1 for the "BITS"
946 parameter.
947 @iothreadinfo = $dom->get_iothread_info($flags=0)
949 Obtain information about the state of all IOThreads in a running
950 guest domain. The returned list will have one element for each
951 IOThread, where each elements contains a hash reference. The keys
952 in the hash are, "number" the IOThread number and "affinity" giving
953 the allowed schedular placement. The value for "affinity" is a
954 string representing a bitmask against physical CPUs, 8 cpus per
955 character. To extract the bits use the "unpack" function with the
956 "b*" template.
957 $dom->pin_iothread($iothread, $mask)
959 Pin the IOThread given by index $iothread to physical CPUs given by
960 $mask. The $mask is a string representing a bitmask against
961 physical CPUs, 8 cpus per character.
962 $dom->add_iothread($iothread, $flags=0)
964 Add a new IOThread by the $iothread value to the guest domain. The
965 $flags parameter accepts one or more the CONFIG OPTION constants
966 documented later, and defaults to 0 if omitted.
967 $dom->del_iothread($iothread, $flags=0)
969 Delete an existing IOThread by the $iothread value from the guest
970 domain. The $flags parameter accepts one or more the CONFIG OPTION
971 constants documented later, and defaults to 0 if omitted.
972 my @stats = $dom->get_cpu_stats($startCpu, $numCpus, $flags=0)
974 Requests the guests host physical CPU usage statistics, starting
975 from host CPU <$startCpu> counting upto $numCpus. If $startCpu is
976 -1 and $numCpus is 1, then the utilization across all CPUs is
977 returned. Returns an array of hash references, each element
978 containing stats for one CPU.
979 my $info = $dom->get_job_info()
981 Returns a hash reference summarising the execution state of the
982 background job. The elements of the hash are as follows:
983 type
985 The type of job, one of the JOB TYPE constants listed later in
986 this document.
987 timeElapsed
989 The elapsed time in milliseconds
990 timeRemaining
992 The expected remaining time in milliseconds. Only set if the
993 "type" is JOB_UNBOUNDED.
994 dataTotal
996 The total amount of data expected to be processed by the job,
997 in bytes.
998 dataProcessed
1000 The current amount of data processed by the job, in bytes.
1001 dataRemaining
1003 The expected amount of data remaining to be processed by the
1004 job, in bytes.
1005 memTotal
1007 The total amount of mem expected to be processed by the job, in
1008 bytes.
1009 memProcessed
1011 The current amount of mem processed by the job, in bytes.
1012 memRemaining
1014 The expected amount of mem remaining to be processed by the
1015 job, in bytes.
1016 fileTotal
1018 The total amount of file expected to be processed by the job,
1019 in bytes.
1020 fileProcessed
1022 The current amount of file processed by the job, in bytes.
1023 fileRemaining
1025 The expected amount of file remaining to be processed by the
1026 job, in bytes.
1027 my ($type, $stats) = $dom->get_job_stats($flags=0)
1029 Returns an array summarising the execution state of the background
1030 job. The $type value is one of the JOB TYPE constants listed later
1031 in this document. The $stats value is a hash reference, whose
1032 elements are one of the following constants.
1033 type
1035 The type of job, one of the JOB TYPE constants listed later in
1036 this document.
1037 The $flags parameter defaults to zero and can take one of the
1039 following constants.
1040 Sys::Virt::Domain::JOB_STATS_COMPLETED
1042 Return the stats of the most recently completed job.
1043 Sys::Virt::Domain::JOB_TIME_ELAPSED
1045 The elapsed time in milliseconds
1046 Sys::Virt::Domain::JOB_TIME_ELAPSED_NET
1048 Time in miliseconds since the beginning of the migration job
1049 NOT including the time required to transfer control flow from
1050 the source host to the destination host.
1051 Sys::Virt::Domain::JOB_TIME_REMAINING
1053 The expected remaining time in milliseconds. Only set if the
1054 "type" is JOB_UNBOUNDED.
1055 Sys::Virt::Domain::JOB_DATA_TOTAL
1057 The total amount of data expected to be processed by the job,
1058 in bytes.
1059 Sys::Virt::Domain::JOB_DATA_PROCESSED
1061 The current amount of data processed by the job, in bytes.
1062 Sys::Virt::Domain::JOB_DATA_REMAINING
1064 The expected amount of data remaining to be processed by the
1065 job, in bytes.
1066 Sys::Virt::Domain::JOB_MEMORY_TOTAL
1068 The total amount of mem expected to be processed by the job, in
1069 bytes.
1070 Sys::Virt::Domain::JOB_MEMORY_PROCESSED
1072 The current amount of mem processed by the job, in bytes.
1073 Sys::Virt::Domain::JOB_MEMORY_REMAINING
1075 The expected amount of mem remaining to be processed by the
1076 job, in bytes.
1077 Sys::Virt::Domain::JOB_MEMORY_CONSTANT
1079 The number of pages filled with a constant byte which have been
1080 transferred
1081 Sys::Virt::Domain::JOB_MEMORY_NORMAL
1083 The number of pages transferred without any compression
1084 Sys::Virt::Domain::JOB_MEMORY_NORMAL_BYTES
1086 The number of bytes transferred without any compression
1087 Sys::Virt::Domain::JOB_MEMORY_BPS
1089 The bytes per second transferred
1090 Sys::Virt::Domain::JOB_MEMORY_DIRTY_RATE
1092 The number of memory pages dirtied per second
1093 Sys::Virt::Domain::JOB_MEMORY_PAGE_SIZE
1095 The memory page size in bytes
1096 Sys::Virt::Domain::JOB_MEMORY_ITERATION
1098 The total number of iterations over guest memory
1099 Sys::Virt::Domain::JOB_DISK_TOTAL
1101 The total amount of file expected to be processed by the job,
1102 in bytes.
1103 Sys::Virt::Domain::JOB_DISK_PROCESSED
1105 The current amount of file processed by the job, in bytes.
1106 Sys::Virt::Domain::JOB_DISK_REMAINING
1108 The expected amount of file remaining to be processed by the
1109 job, in bytes.
1110 Sys::Virt::Domain::JOB_DISK_BPS
1112 The bytes per second transferred
1113 Sys::Virt::Domain::JOB_AUTO_CONVERGE_THROTTLE
1115 The percentage by which vCPUs are currently throttled
1116 Sys::Virt::Domain::JOB_COMPRESSION_CACHE
1118 The size of the compression cache in bytes
1119 Sys::Virt::Domain::JOB_COMPRESSION_BYTES
1121 The number of compressed bytes transferred
1122 Sys::Virt::Domain::JOB_COMPRESSION_PAGES
1124 The number of compressed pages transferred
1125 Sys::Virt::Domain::JOB_COMPRESSION_CACHE_MISSES
1127 The number of changing pages not in compression cache
1128 Sys::Virt::Domain::JOB_COMPRESSION_OVERFLOW
1130 The number of changing pages in the compression cache but sent
1131 uncompressed since the compressed page was larger than the non-
1132 compressed page.
1133 Sys::Virt::Domain::JOB_DOWNTIME
1135 The number of milliseconds of downtime expected during
1136 migration switchover.
1137 Sys::Virt::Domain::JOB_DOWNTIME_NET
1139 Real measured downtime (ms) NOT including the time required to
1140 transfer control flow from the source host to the destination
1141 host.
1142 Sys::Virt::Domain::JOB_SETUP_TIME
1144 The number of milliseconds of time doing setup of the job
1145 Sys::Virt::Domain::JOB_OPERATION
1147 The type of operation associated with the job
1148 The values for the Sys::Virt::Domain::JOB_OPERATION field are
1150 Sys::Virt::Domain::JOB_OPERATION_UNKNOWN
1152 No known job type
1153 Sys::Virt::Domain::JOB_OPERATION_START
1155 The guest is starting
1156 Sys::Virt::Domain::JOB_OPERATION_SAVE
1158 The guest is saving to disk
1159 Sys::Virt::Domain::JOB_OPERATION_RESTORE
1161 The guest is restoring from disk
1162 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_IN
1164 The guest is migrating in from another host
1165 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_OUT
1167 The guest is migrating out to another host
1168 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT
1170 The guest is saving a snapshot
1171 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT_REVERT
1173 The guest is reverting to a snapshot
1174 Sys::Virt::Domain::JOB_OPERATION_DUMP
1176 The guest is saving a crash dump
1177 $dom->abort_job()
1179 Aborts the currently executing job
1180 my $info = $dom->get_block_job_info($path, $flags=0)
1182 Returns a hash reference summarising the execution state of the
1183 block job. The $path parameter should be the fully qualified path
1184 of the block device being changed. Valid $flags include:
1185 Sys::Virt::Domain::BLOCK_JOB_INFO_BANDWIDTH_BYTES
1187 Treat bandwidth value as bytes instead of MiB.
1188 $dom->set_block_job_speed($path, $bandwidth, $flags=0)
1190 Change the maximum I/O bandwidth used by the block job that is
1191 currently executing for $path. The $bandwidth argument is specified
1192 in MB/s. The $flags parameter can take the bitwise union of the
1193 values:
1194 Sys::Virt::Domain::BLOCK_JOB_SPEED_BANDWIDTH_BYTES
1196 The $bandwidth parameter value is measured in bytes/s instead
1197 of MB/s.
1198 $dom->abort_block_job($path, $flags=0)
1200 Abort the current job that is executing for the block device
1201 associated with $path
1202 $dom->block_pull($path, $bandwidth, $flags=0)
1204 Merge the backing files associated with $path into the top level
1205 file. The $bandwidth parameter specifies the maximum I/O rate to
1206 allow in MB/s. The $flags parameter can take the bitwise union of
1207 the values:
1208 Sys::Virt::Domain::BLOCK_PULL_BANDWIDTH_BYTES
1210 The $bandwidth parameter value is measured in bytes/s instead
1211 of MB/s.
1212 $dom->block_rebase($path, $base, $bandwidth, $flags=0)
1214 Switch the backing path associated with $path to instead use $base.
1215 The $bandwidth parameter specifies the maximum I/O rate to allow in
1216 MB/s. The $flags parameter can take the bitwise union of the
1217 values:
1218 Sys::Virt::Domain::BLOCK_REBASE_BANDWIDTH_BYTES
1220 The $bandwidth parameter value is measured in bytes/s instead
1221 of MB/s.
1222 $dom->block_copy($path, $destxml, $params, $flags=0)
1224 Copy contents of a disk image <$path> into the target volume
1225 described by $destxml which follows the schema of the <disk>
1226 element in the domain XML. The $params parameter is a hash of
1227 optional parameters to control the process
1228 Sys::Virt::Domain::BLOCK_COPY_BANDWIDTH
1230 The maximum bandwidth in bytes per second.
1231 Sys::Virt::Domain::BLOCK_COPY_GRANULARITY
1233 The granularity in bytes of the copy process
1234 Sys::Virt::Domain::BLOCK_COPY_BUF_SIZE
1236 The maximum amount of data in flight in bytes.
1237 $dom->block_commit($path, $base, $top, $bandwidth, $flags=0)
1239 Commit changes there were made to the temporary top level file
1240 $top. Takes all the differences between $top and $base and merge
1241 them into $base. The $bandwidth parameter specifies the maximum I/O
1242 rate to allow in MB/s. The $flags parameter can take the bitwise
1243 union of the values:
1244 Sys::Virt::Domain::BLOCK_COMMIT_BANDWIDTH_BYTES
1246 The $bandwidth parameter value is measured in bytes instead of
1247 MB/s.
1248 $count = $dom->num_of_snapshots()
1250 Return the number of saved snapshots of the domain
1251 @names = $dom->list_snapshot_names()
1253 List the names of all saved snapshots. The names can be used with
1254 the "lookup_snapshot_by_name"
1255 @snapshots = $dom->list_snapshots()
1257 Return a list of all snapshots currently known to the domain. The
1258 elements in the returned list are instances of the
1259 Sys::Virt::DomainSnapshot class. This method requires O(n) RPC
1260 calls, so the "list_all_snapshots" method is recommended as a more
1261 efficient alternative.
1262 my @snapshots = $dom->list_all_snapshots($flags)
1264 Return a list of all domain snapshots associated with this domain.
1265 The elements in the returned list are instances of the
1266 Sys::Virt::DomainSnapshot class. The $flags parameter can be used
1267 to filter the list of return domain snapshots.
1268 my $snapshot = $dom->get_snapshot_by_name($name)
1270 Return the domain snapshot with a name of $name. The returned
1271 object is an instance of the Sys::Virt::DomainSnapshot class.
1272 $dom->has_current_snapshot()
1274 Returns a true value if the domain has a currently active snapshot
1275 $snapshot = $dom->current_snapshot()
1277 Returns the currently active snapshot for the domain.
1278 $snapshot = $dom->create_snapshot($xml[, $flags])
1280 Create a new snapshot from the $xml. The $flags parameter accepts
1281 the SNAPSHOT CREATION constants listed in
1282 "Sys::Virt::DomainSnapshots".
1283 $dom->fs_trim($mountPoint, $minimum, $flags=0);
1285 Issue an FS_TRIM command to the device at $mountPoint to remove
1286 chunks of unused space that are at least $minimum bytes in length.
1287 $flags is currently unused and defaults to zero.
1288 $dom->fs_freeze(\@mountPoints, $flags=0);
1290 Freeze all the filesystems associated with the @mountPoints array
1291 reference. If <@mountPoints> is an empty list, then all filesystems
1292 will be frozen. $flags is currently unused and defaults to zero.
1293 $dom->fs_thaw(\@mountPoints, $flags=0);
1295 Thaw all the filesystems associated with the @mountPoints array
1296 reference. If <@mountPoints> is an empty list, then all filesystems
1297 will be thawed. $flags is currently unused and defaults to zero.
1298 @fslist = $dom->get_fs_info($flags=0);
1300 Obtain a list of all guest filesystems. The returned list will
1301 contain one element for each filesystem, whose value will be a hash
1302 reference with the following keys
1303 name
1305 The name of the guest device that is mounted
1306 fstype
1308 The filesystem type (eg 'ext4', 'fat', 'ntfs', etc)
1309 mountpoint
1311 The location in the filesystem tree of the mount
1312 devalias
1314 An array reference containing list of device aliases associated
1315 with the guest device. The device aliases correspond to disk
1316 target names in the guest XML configuration
1317 @nics = $dom->get_interface_addresses($src, $flags=0);
1319 Obtain a list of all guest network interfaces. The $src parameter
1320 is one of the constants
1321 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_LEASE
1323 Extract the DHCP server lease information
1324 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_AGENT
1326 Query the guest OS via an agent
1327 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_ARP
1329 Extract from the local ARP tables
1330 The returned list will contain one element for each interface. The
1332 values in the list will be a hash reference with the following keys
1333 name
1335 The name of the guest interface that is mounted
1336 hwaddr
1338 The hardware address, aka MAC, if available.
1339 addrs
1341 An array reference containing list of IP addresses associated
1342 with the guest NIC. Each element in the array is a further hash
1343 containing
1344 addr
1346 The IP address string
1347 prefix
1349 The IP address network prefix
1350 type
1352 The IP address type (IPv4 vs IPv6)
1353 $dom->send_process_signal($pid, $signum, $flags=0);
1355 Send the process $pid the signal $signum. The $signum value must be
1356 one of the constants listed later, not a POSIX or Linux signal
1357 value. $flags is currently unused and defaults to zero.
1358 $dom->set_block_threshold($dev, $threshold, $flags=0);
1360 Set the threshold level for delivering the EVENT_ID_BLOCK_THRESHOLD
1361 if the device or backing chain element described by $dev is written
1362 beyond the set $threshold level. The threshold level is unset once
1363 the event fires. The event might not be delivered at all if
1364 libvirtd was not running at the moment when the threshold was
1365 reached.
1366 $dom->set_lifecycle_action($type, $action, $flags=0)
1368 Changes the actions of lifecycle events for domain represented as
1369 <on_$type>$action</on_$type> in the domain XML.
1370 $info = $dom->get_launch_security_info($flags=0)
1372 Get information about the domaim launch security policy. $flags is
1373 currently unused and defaults to zero. The returned hash may
1374 contain the following keys
1375 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_MEASUREMENT
1377 The AMD SEV launch measurement
1378
1380 A number of the APIs take a "flags" parameter. In most cases passing a
1381 value of zero will be satisfactory. Some APIs, however, accept named
1382 constants to alter their behaviour. This section documents the current
1383 known constants.
1384 DOMAIN STATE
1386 The domain state constants are useful in interpreting the "state" key
1387 in the hash returned by the "get_info" method.
1388 Sys::Virt::Domain::STATE_NOSTATE
1390 The domain is active, but is not running / blocked (eg idle)
1391 Sys::Virt::Domain::STATE_RUNNING
1393 The domain is active and running
1394 Sys::Virt::Domain::STATE_BLOCKED
1396 The domain is active, but execution is blocked
1397 Sys::Virt::Domain::STATE_PAUSED
1399 The domain is active, but execution has been paused
1400 Sys::Virt::Domain::STATE_SHUTDOWN
1402 The domain is active, but in the shutdown phase
1403 Sys::Virt::Domain::STATE_SHUTOFF
1405 The domain is inactive, and shut down.
1406 Sys::Virt::Domain::STATE_CRASHED
1408 The domain is inactive, and crashed.
1409 Sys::Virt::Domain::STATE_PMSUSPENDED
1411 The domain is active, but in power management suspend state
1412 CONTROL INFO
1414 The following constants can be used to determine what the guest domain
1415 control channel status is
1416 Sys::Virt::Domain::CONTROL_ERROR
1418 The control channel has a fatal error
1419 Sys::Virt::Domain::CONTROL_OK
1421 The control channel is ready for jobs
1422 Sys::Virt::Domain::CONTROL_OCCUPIED
1424 The control channel is busy
1425 Sys::Virt::Domain::CONTROL_JOB
1427 The control channel is busy with a job
1428 If the status is "Sys::Virt::Domain::CONTROL_ERROR", then one of the
1430 following constants describes the reason
1431 Sys::Virt::Domain::CONTROL_ERROR_REASON_NONE
1433 There is no reason for the error available
1434 Sys::Virt::Domain::CONTROL_ERROR_REASON_UNKNOWN
1436 The reason for the error is unknown
1437 Sys::Virt::Domain::CONTROL_ERROR_REASON_INTERNAL
1439 There was an internal error in libvirt
1440 Sys::Virt::Domain::CONTROL_ERROR_REASON_MONITOR
1442 There was an error speaking to the monitor
1443 DOMAIN CREATION
1445 The following constants can be used to control the behaviour of domain
1446 creation
1447 Sys::Virt::Domain::START_PAUSED
1449 Keep the guest vCPUs paused after starting the guest
1450 Sys::Virt::Domain::START_AUTODESTROY
1452 Automatically destroy the guest when the connection is closed (or
1453 fails)
1454 Sys::Virt::Domain::START_BYPASS_CACHE
1456 Do not use OS I/O cache if starting a domain with a saved state
1457 image
1458 Sys::Virt::Domain::START_FORCE_BOOT
1460 Boot the guest, even if there was a saved snapshot
1461 Sys::Virt::Domain::START_VALIDATE
1463 Validate the XML document against the XML schema
1464 DOMAIN DEFINE
1466 The following constants can be used to control the behaviour of domain
1467 define operations
1468 Sys::Virt::Domain::DEFINE_VALIDATE
1470 Validate the XML document against the XML schema
1471 KEYCODE SETS
1473 The following constants define the set of supported keycode sets
1474 Sys::Virt::Domain::KEYCODE_SET_LINUX
1476 The Linux event subsystem keycodes
1477 Sys::Virt::Domain::KEYCODE_SET_XT
1479 The original XT keycodes
1480 Sys::Virt::Domain::KEYCODE_SET_ATSET1
1482 The AT Set1 keycodes (aka XT)
1483 Sys::Virt::Domain::KEYCODE_SET_ATSET2
1485 The AT Set2 keycodes (aka AT)
1486 Sys::Virt::Domain::KEYCODE_SET_ATSET3
1488 The AT Set3 keycodes (aka PS2)
1489 Sys::Virt::Domain::KEYCODE_SET_OSX
1491 The OS-X keycodes
1492 Sys::Virt::Domain::KEYCODE_SET_XT_KBD
1494 The XT keycodes from the Linux Keyboard driver
1495 Sys::Virt::Domain::KEYCODE_SET_USB
1497 The USB HID keycode set
1498 Sys::Virt::Domain::KEYCODE_SET_WIN32
1500 The Windows keycode set
1501 Sys::Virt::Domain::KEYCODE_SET_QNUM
1503 The XT keycode set, with the extended scancodes using the high bit
1504 of the first byte, instead of the low bit of the second byte.
1505 Sys::Virt::Domain::KEYCODE_SET_RFB
1507 A deprecated alias for "Sys::Virt::Domain::KEYCODE_SET_QNUM"
1508 MEMORY PEEK
1510 The following constants can be used with the "memory_peek" method's
1511 flags parameter
1512 Sys::Virt::Domain::MEMORY_VIRTUAL
1514 Indicates that the offset is using virtual memory addressing.
1515 Sys::Virt::Domain::MEMORY_PHYSICAL
1517 Indicates that the offset is using physical memory addressing.
1518 VCPU STATE
1520 The following constants are useful when interpreting the virtual CPU
1521 run state
1522 Sys::Virt::Domain::VCPU_OFFLINE
1524 The virtual CPU is not online
1525 Sys::Virt::Domain::VCPU_RUNNING
1527 The virtual CPU is executing code
1528 Sys::Virt::Domain::VCPU_BLOCKED
1530 The virtual CPU is waiting to be scheduled
1531 OPEN GRAPHICS CONSTANTS
1533 The following constants are used when opening a connection to the guest
1534 graphics server
1535 Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH
1537 Skip authentication of the client
1538 OPEN CONSOLE CONSTANTS
1540 The following constants are used when opening a connection to the guest
1541 console
1542 Sys::Virt::Domain::OPEN_CONSOLE_FORCE
1544 Force opening of the console, disconnecting any other open session
1545 Sys::Virt::Domain::OPEN_CONSOLE_SAFE
1547 Check if the console driver supports safe operations
1548 OPEN CHANNEL CONSTANTS
1550 The following constants are used when opening a connection to the guest
1551 channel
1552 Sys::Virt::Domain::OPEN_CHANNEL_FORCE
1554 Force opening of the channel, disconnecting any other open session
1555 XML DUMP OPTIONS
1557 The following constants are used to control the information included in
1558 the XML configuration dump
1559 Sys::Virt::Domain::XML_INACTIVE
1561 Report the persistent inactive configuration for the guest, even if
1562 it is currently running.
1563 Sys::Virt::Domain::XML_SECURE
1565 Include security sensitive information in the XML dump, such as
1566 passwords.
1567 Sys::Virt::Domain::XML_UPDATE_CPU
1569 Update the CPU model definition to match the current executing
1570 state.
1571 Sys::Virt::Domain::XML_MIGRATABLE
1573 Update the XML to allow migration to older versions of libvirt
1574 DEVICE HOTPLUG OPTIONS
1576 The following constants are used to control device hotplug operations
1577 Sys::Virt::Domain::DEVICE_MODIFY_CURRENT
1579 Modify the domain in its current state
1580 Sys::Virt::Domain::DEVICE_MODIFY_LIVE
1582 Modify only the live state of the domain
1583 Sys::Virt::Domain::DEVICE_MODIFY_CONFIG
1585 Modify only the persistent config of the domain
1586 Sys::Virt::Domain::DEVICE_MODIFY_FORCE
1588 Force the device to be modified
1589 MEMORY OPTIONS
1591 The following constants are used to control memory change operations
1592 Sys::Virt::Domain::MEM_CURRENT
1594 Modify the current state
1595 Sys::Virt::Domain::MEM_LIVE
1597 Modify only the live state of the domain
1598 Sys::Virt::Domain::MEM_CONFIG
1600 Modify only the persistent config of the domain
1601 Sys::Virt::Domain::MEM_MAXIMUM
1603 Modify the maximum memory value
1604 CONFIG OPTIONS
1606 The following constants are used to control what configuration a domain
1607 update changes
1608 Sys::Virt::Domain::AFFECT_CURRENT
1610 Modify the current state
1611 Sys::Virt::Domain::AFFECT_LIVE
1613 Modify only the live state of the domain
1614 Sys::Virt::Domain::AFFECT_CONFIG
1616 Modify only the persistent config of the domain
1617 MIGRATE OPTIONS
1619 The following constants are used to control how migration is performed
1620 Sys::Virt::Domain::MIGRATE_LIVE
1622 Migrate the guest without interrupting its execution on the source
1623 host.
1624 Sys::Virt::Domain::MIGRATE_PEER2PEER
1626 Manage the migration process over a direct peer-2-peer connection
1627 between the source and destination host libvirtd daemons.
1628 Sys::Virt::Domain::MIGRATE_TUNNELLED
1630 Tunnel the migration data over the libvirt daemon connection,
1631 rather than the native hypervisor data transport. Requires
1632 PEER2PEER flag to be set.
1633 Sys::Virt::Domain::MIGRATE_PERSIST_DEST
1635 Make the domain persistent on the destination host, defining its
1636 configuration file upon completion of migration.
1637 Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE
1639 Remove the domain's persistent configuration after migration
1640 completes successfully.
1641 Sys::Virt::Domain::MIGRATE_PAUSED
1643 Do not re-start execution of the guest CPUs on the destination host
1644 after migration completes.
1645 Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK
1647 Copy the complete contents of the disk images during migration
1648 Sys::Virt::Domain::MIGRATE_NON_SHARED_INC
1650 Copy the incrementally changed contents of the disk images during
1651 migration
1652 Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION
1654 Do not allow changes to the virtual domain configuration while
1655 migration is taking place. This option is automatically implied if
1656 doing a peer-2-peer migration.
1657 Sys::Virt::Domain::MIGRATE_UNSAFE
1659 Migrate even if the compatibility check indicates the migration
1660 will be unsafe to the guest.
1661 Sys::Virt::Domain::MIGRATE_OFFLINE
1663 Migrate the guest config if the guest is not currently running
1664 Sys::Virt::Domain::MIGRATE_COMPRESSED
1666 Enable compression of the migration data stream
1667 Sys::Virt::Domain::MIGRATE_ABORT_ON_ERROR
1669 Abort if an I/O error occurrs on the disk
1670 Sys::Virt::Domain::MIGRATE_AUTO_CONVERGE
1672 Force convergance of the migration operation by throttling guest
1673 runtime
1674 Sys::Virt::Domain::MIGRATE_RDMA_PIN_ALL
1676 Pin memory for RDMA transfer
1677 Sys::Virt::Domain::MIGRATE_POSTCOPY
1679 Enable support for post-copy migration
1680 Sys::Virt::Domain::MIGRATE_TLS
1682 Setting this flag will cause the migration to attempt to use the
1683 TLS environment configured by the hypervisor in order to perform
1684 the migration. If incorrectly configured on either source or
1685 destination, the migration will fail.
1686 UNDEFINE CONSTANTS
1688 The following constants can be used when undefining virtual domain
1689 configurations
1690 Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE
1692 Also remove any managed save image when undefining the virtual
1693 domain
1694 Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA
1696 Also remove any snapshot metadata when undefining the virtual
1697 domain.
1698 Sys::Virt::Domain::UNDEFINE_NVRAM
1700 Also remove any NVRAM state file when undefining the virtual
1701 domain.
1702 Sys::Virt::Domain::UNDEFINE_KEEP_NVRAM
1704 keep NVRAM state file when undefining the virtual domain.
1705 JOB TYPES
1707 The following constants describe the different background job types.
1708 Sys::Virt::Domain::JOB_NONE
1710 No job is active
1711 Sys::Virt::Domain::JOB_BOUNDED
1713 A job with a finite completion time is active
1714 Sys::Virt::Domain::JOB_UNBOUNDED
1716 A job with an unbounded completion time is active
1717 Sys::Virt::Domain::JOB_COMPLETED
1719 The job has finished, but isn't cleaned up
1720 Sys::Virt::Domain::JOB_FAILED
1722 The job has hit an error, but isn't cleaned up
1723 Sys::Virt::Domain::JOB_CANCELLED
1725 The job was aborted at user request, but isn't cleaned up
1726 MEMORY PARAMETERS
1728 The following constants are useful when getting/setting memory
1729 parameters for guests
1730 Sys::Virt::Domain::MEMORY_HARD_LIMIT
1732 The maximum memory the guest can use.
1733 Sys::Virt::Domain::MEMORY_SOFT_LIMIT
1735 The memory upper limit enforced during memory contention.
1736 Sys::Virt::Domain::MEMORY_MIN_GUARANTEE
1738 The minimum memory guaranteed to be reserved for the guest.
1739 Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT
1741 The maximum swap the guest can use.
1742 Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED
1744 The value of an unlimited memory parameter
1745 BLKIO PARAMETERS
1747 The following parameters control I/O tuning for the domain as a whole
1748 Sys::Virt::Domain::BLKIO_WEIGHT
1750 The I/O weight parameter
1751 Sys::Virt::Domain::BLKIO_DEVICE_WEIGHT
1753 The per-device I/O weight parameter
1754 Sys::Virt::Domain::BLKIO_DEVICE_READ_BPS
1756 The per-device I/O bytes read per second
1757 Sys::Virt::Domain::BLKIO_DEVICE_READ_IOPS
1759 The per-device I/O operations read per second
1760 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_BPS
1762 The per-device I/O bytes write per second
1763 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_IOPS
1765 The per-device I/O operations write per second
1766 BLKIO TUNING PARAMETERS
1768 The following parameters control I/O tuning for an individual guest
1769 disk.
1770 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC
1772 The total bytes processed per second.
1773 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC
1775 The bytes read per second.
1776 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC
1778 The bytes written per second.
1779 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC
1781 The total I/O operations processed per second.
1782 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC
1784 The I/O operations read per second.
1785 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC
1787 The I/O operations written per second.
1788 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX
1790 The maximum total bytes processed per second.
1791 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX
1793 The maximum bytes read per second.
1794 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX
1796 The maximum bytes written per second.
1797 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX
1799 The maximum total I/O operations processed per second.
1800 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX
1802 The maximum I/O operations read per second.
1803 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX
1805 The maximum I/O operations written per second.
1806 Sys::Virt::Domain::BLOCK_IOTUNE_SIZE_IOPS_SEC
1808 The maximum I/O operations per second
1809 Sys::Virt::Domain::BLOCK_IOTUNE_GROUP_NAME
1811 A string representing a group name to allow sharing of I/O
1812 throttling quota between multiple drives
1813 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX_LENGTH
1815 The duration in seconds allowed for maximum total bytes processed
1816 per second.
1817 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX_LENGTH
1819 The duration in seconds allowed for maximum bytes read per second.
1820 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX_LENGTH
1822 The duration in seconds allowed for maximum bytes written per
1823 second.
1824 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX_LENGTH
1826 The duration in seconds allowed for maximum total I/O operations
1827 processed per second.
1828 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX_LENGTH
1830 The duration in seconds allowed for maximum I/O operations read per
1831 second.
1832 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX_LENGTH
1834 The duration in seconds allowed for maximum I/O operations written
1835 per second.
1836 SCHEDULER CONSTANTS
1838 Sys::Virt::Domain::SCHEDULER_CAP
1839 The VM cap tunable
1840 Sys::Virt::Domain::SCHEDULER_CPU_SHARES
1842 The CPU shares tunable
1843 Sys::Virt::Domain::SCHEDULER_LIMIT
1845 The VM limit tunable
1846 Sys::Virt::Domain::SCHEDULER_RESERVATION
1848 The VM reservation tunable
1849 Sys::Virt::Domain::SCHEDULER_SHARES
1851 The VM shares tunable
1852 Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD
1854 The VCPU period tunable
1855 Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA
1857 The VCPU quota tunable
1858 Sys::Virt::Domain::SCHEDULER_GLOBAL_PERIOD
1860 The VM global period tunable
1861 Sys::Virt::Domain::SCHEDULER_GLOBAL_QUOTA
1863 The VM global quota tunable
1864 Sys::Virt::Domain::SCHEDULER_WEIGHT
1866 The VM weight tunable
1867 NUMA PARAMETERS
1869 The following constants are useful when getting/setting the guest NUMA
1870 memory policy
1871 Sys::Virt::Domain::NUMA_MODE
1873 The NUMA policy mode
1874 Sys::Virt::Domain::NUMA_NODESET
1876 The NUMA nodeset mask
1877 The following constants are useful when interpreting the
1879 "Sys::Virt::Domain::NUMA_MODE" parameter value
1880 Sys::Virt::Domain::NUMATUNE_MEM_STRICT
1882 Allocation is mandatory from the mask nodes
1883 Sys::Virt::Domain::NUMATUNE_MEM_PREFERRED
1885 Allocation is preferred from the masked nodes
1886 Sys::Virt::Domain::NUMATUNE_MEM_INTERLEAVE
1888 Allocation is interleaved across all masked nods
1889 INTERFACE PARAMETERS
1891 The following constants are useful when getting/setting the per network
1892 interface tunable parameters
1893 Sys::Virt::Domain::BANDWIDTH_IN_AVERAGE
1895 The average inbound bandwidth
1896 Sys::Virt::Domain::BANDWIDTH_IN_PEAK
1898 The peak inbound bandwidth
1899 Sys::Virt::Domain::BANDWIDTH_IN_BURST
1901 The burstable inbound bandwidth
1902 Sys::Virt::Domain::BANDWIDTH_IN_FLOOR
1904 The minimum inbound bandwidth
1905 Sys::Virt::Domain::BANDWIDTH_OUT_AVERAGE
1907 The average outbound bandwidth
1908 Sys::Virt::Domain::BANDWIDTH_OUT_PEAK
1910 The peak outbound bandwidth
1911 Sys::Virt::Domain::BANDWIDTH_OUT_BURST
1913 The burstable outbound bandwidth
1914 PERF EVENTS
1916 The following constants defined performance events which can be
1917 monitored for a guest
1918 Sys::Virt::Domain::PERF_PARAM_CMT
1920 The CMT event counter which can be used to measure the usage of
1921 cache (bytes) by applications running on the platform. It
1922 corresponds to the "perf.cmt" field in the *Stats APIs.
1923 Sys::Virt::Domain::PERF_PARAM_MBML
1925 The MBML event counter which can be used to monitor the amount of
1926 data (bytes/s) sent through the memory controller on the socket.
1927 It corresponds to the "perf.mbml" field in the *Stats APIs.
1928 Sys::Virt::Domain::PERF_PARAM_MBMT
1930 The MBMT event counter which can be used to monitor total system
1931 bandwidth (bytes/s) from one level of cache to another. It
1932 corresponds to the "perf.mbmt" field in the *Stats APIs.
1933 Sys::Virt::Domain::PERF_PARAM_CACHE_MISSES
1935 The cache_misses perf event counter which can be used to measure
1936 the count of cache misses by applications running on the platform.
1937 It corresponds to the "perf.cache_misses" field in the *Stats APIs.
1938 Sys::Virt::Domain::PERF_PARAM_CACHE_REFERENCES
1940 The cache_references perf event counter which can be used to
1941 measure the count of cache hits by applications running on the
1942 platform. It corresponds to the "perf.cache_references" field in
1943 the *Stats APIs.
1944 Sys::Virt::Domain::PERF_PARAM_CPU_CYCLES
1946 The cpu_cycles perf event counter which can be used to measure how
1947 many cpu cycles one instruction needs. It corresponds to the
1948 "perf.cpu_cycles" field in the *Stats APIs.
1949 Sys::Virt::Domain::PERF_PARAM_INSTRUCTIONS
1951 The instructions perf event counter which can be used to measure
1952 the count of instructions by applications running on the platform.
1953 It corresponds to the "perf.instructions" field in the *Stats APIs.
1954 Sys::Virt::Domain::PERF_PARAM_BRANCH_INSTRUCTIONS
1956 The branch_instructions perf event counter which can be used to
1957 measure the count of instructions by applications running on the
1958 platform. It corresponds to the "perf.branch_instructions" field in
1959 the *Stats APIs.
1960 Sys::Virt::Domain::PERF_PARAM_BRANCH_MISSES
1962 The branch_misses perf event which can be used to measure the count
1963 of branch misses by applications running on the platform. It
1964 corresponds to the "perf.branch_misses" field in the *Stats APIs.
1965 Sys::Virt::Domain::PERF_PARAM_BUS_CYCLES The bus_cycles perf event
1967 counter which can be used to measure the count of bus cycles by
1968 applications running on the platform. It corresponds to the
1969 "perf.bus_cycles" field in the *Stats APIs.
1970 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_FRONTEND The
1971 stalled_cycles_frontend perf event counter which can be used to measure
1972 the count of stalled cpu cycles in the frontend of the instruction
1973 processor pipeline by applications running on the platform. It
1974 corresponds to the "perf.stalled_cycles_frontend" field in the *Stats
1975 APIs.
1976 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_BACKEND The
1977 stalled_cycles_backend perf event counter which can be used to measure
1978 the count of stalled cpu cycles in the backend of the instruction
1979 processor pipeline by application running on the platform. It
1980 corresponds to the "perf.stalled_cycles_backend" field in the *Stats
1981 APIs.
1982 Sys::Virt::Domain::PERF_PARAM_REF_CPU_CYCLES The ref_cpu_cycles perf
1983 event counter which can be used to measure the count of total cpu
1984 cycles not affected by CPU frequency scaling by applications running on
1985 the platform. It corresponds to the "perf.ref_cpu_cycles" field in the
1986 *Stats APIs.
1987 Sys::Virt::Domain::PERF_PARAM_CPU_CLOCK The cpu_clock perf event
1988 counter which can be used to measure the count of cpu clock time by
1989 applications running on the platform. It corresponds to the
1990 "perf.cpu_clock" field in the *Stats APIs.
1991 Sys::Virt::Domain::PERF_PARAM_TASK_CLOCK The task_clock perf event
1992 counter which can be used to measure the count of task clock time by
1993 applications running on the platform. It corresponds to the
1994 "perf.task_clock" field in the *Stats APIs.
1995 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS The page_faults perf event
1996 counter which can be used to measure the count of page faults by
1997 applications running on the platform. It corresponds to the
1998 "perf.page_faults" field in the *Stats APIs.
1999 Sys::Virt::Domain::PERF_PARAM_CONTEXT_SWITCHES The context_switches
2000 perf event counter which can be used to measure the count of context
2001 switches by applications running on the platform. It corresponds to the
2002 "perf.context_switches" field in the *Stats APIs.
2003 Sys::Virt::Domain::PERF_PARAM_CPU_MIGRATIONS The cpu_migrations perf
2004 event counter which can be used to measure the count of cpu migrations
2005 by applications running on the platform. It corresponds to the
2006 "perf.cpu_migrations" field in the *Stats APIs.
2007 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MIN The page_faults_min perf
2008 event counter which can be used to measure the count of minor page
2009 faults by applications running on the platform. It corresponds to the
2010 "perf.page_faults_min" field in the *Stats APIs.
2011 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MAJ The page_faults_maj perf
2012 event counter which can be used to measure the count of major page
2013 faults by applications running on the platform. It corresponds to the
2014 "perf.page_faults_maj" field in the *Stats APIs.
2015 Sys::Virt::Domain::PERF_PARAM_ALIGNMENT_FAULTS The alignment_faults
2016 perf event counter which can be used to measure the count of alignment
2017 faults by applications running on the platform. It corresponds to the
2018 "perf.alignment_faults" field in the *Stats APIs.
2019 Sys::Virt::Domain::PERF_PARAM_EMULATION_FAULTS The emulation_faults
2020 perf event counter which can be used to measure the count of emulation
2021 faults by applications running on the platform. It corresponds to the
2022 "perf.emulation_faults" field in the *Stats APIs.
2023 VCPU FLAGS
2025 The following constants are useful when getting/setting the VCPU count
2026 for a guest
2027 Sys::Virt::Domain::VCPU_LIVE
2029 Flag to request the live value
2030 Sys::Virt::Domain::VCPU_CONFIG
2032 Flag to request the persistent config value
2033 Sys::Virt::Domain::VCPU_CURRENT
2035 Flag to request the current config value
2036 Sys::Virt::Domain::VCPU_MAXIMUM
2038 Flag to request adjustment of the maximum vCPU value
2039 Sys::Virt::Domain::VCPU_GUEST
2041 Flag to request the guest VCPU mask
2042 Sys::Virt::Domain::VCPU_HOTPLUGGABLE
2044 Flag to make vcpus added hot(un)pluggable
2045 STATE CHANGE EVENTS
2047 The following constants allow domain state change events to be
2048 interpreted. The events contain both a state change, and a reason.
2049 Sys::Virt::Domain::EVENT_DEFINED
2051 Indicates that a persistent configuration has been defined for the
2052 domain.
2053 Sys::Virt::Domain::EVENT_DEFINED_ADDED
2055 The defined configuration is newly added
2056 Sys::Virt::Domain::EVENT_DEFINED_UPDATED
2058 The defined configuration is an update to an existing
2059 configuration
2060 Sys::Virt::Domain::EVENT_DEFINED_RENAMED
2062 The defined configuration is a rename of an existing
2063 configuration
2064 Sys::Virt::Domain::EVENT_DEFINED_FROM_SNAPSHOT
2066 The defined configuration was restored from a snapshot
2067 Sys::Virt::Domain::EVENT_RESUMED
2069 The domain has resumed execution
2070 Sys::Virt::Domain::EVENT_RESUMED_MIGRATED
2072 The domain resumed because migration has completed. This is
2073 emitted on the destination host.
2074 Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED
2076 The domain resumed because the admin unpaused it.
2077 Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT
2079 The domain resumed because it was restored from a snapshot
2080 Sys::Virt::Domain::EVENT_RESUMED_POSTCOPY
2082 The domain resumed but post-copy is running in background
2083 Sys::Virt::Domain::EVENT_STARTED
2085 The domain has started running
2086 Sys::Virt::Domain::EVENT_STARTED_BOOTED
2088 The domain was booted from shutoff state
2089 Sys::Virt::Domain::EVENT_STARTED_MIGRATED
2091 The domain started due to an incoming migration
2092 Sys::Virt::Domain::EVENT_STARTED_RESTORED
2094 The domain was restored from saved state file
2095 Sys::Virt::Domain::EVENT_STARTED_FROM_SNAPSHOT
2097 The domain was restored from a snapshot
2098 Sys::Virt::Domain::EVENT_STARTED_WAKEUP
2100 The domain was woken up from suspend
2101 Sys::Virt::Domain::EVENT_STOPPED
2103 The domain has stopped running
2104 Sys::Virt::Domain::EVENT_STOPPED_CRASHED
2106 The domain stopped because guest operating system has crashed
2107 Sys::Virt::Domain::EVENT_STOPPED_DESTROYED
2109 The domain stopped because administrator issued a destroy
2110 command.
2111 Sys::Virt::Domain::EVENT_STOPPED_FAILED
2113 The domain stopped because of a fault in the host
2114 virtualization environment.
2115 Sys::Virt::Domain::EVENT_STOPPED_MIGRATED
2117 The domain stopped because it was migrated to another machine.
2118 Sys::Virt::Domain::EVENT_STOPPED_SAVED
2120 The domain was saved to a state file
2121 Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN
2123 The domain stopped due to graceful shutdown of the guest.
2124 Sys::Virt::Domain::EVENT_STOPPED_FROM_SNAPSHOT
2126 The domain was stopped due to a snapshot
2127 Sys::Virt::Domain::EVENT_SHUTDOWN
2129 The domain has shutdown but is not yet stopped
2130 Sys::Virt::Domain::EVENT_SHUTDOWN_FINISHED
2132 The domain finished shutting down
2133 Sys::Virt::Domain::EVENT_SHUTDOWN_HOST
2135 The domain shutdown due to host trigger
2136 Sys::Virt::Domain::EVENT_SHUTDOWN_GUEST
2138 The domain shutdown due to guest trigger
2139 Sys::Virt::Domain::EVENT_SUSPENDED
2141 The domain has stopped executing, but still exists
2142 Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED
2144 The domain has been suspended due to offline migration
2145 Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED
2147 The domain has been suspended due to administrator pause
2148 request.
2149 Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR
2151 The domain has been suspended due to a block device I/O error.
2152 Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT
2154 The domain has been suspended due to resume from snapshot
2155 Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG
2157 The domain has been suspended due to the watchdog triggering
2158 Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED
2160 The domain has been suspended due to restore from saved state
2161 Sys::Virt::Domain::EVENT_SUSPENDED_API_ERROR
2163 The domain has been suspended due to an API error
2164 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY
2166 The domain has been suspended for post-copy migration
2167 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY_FAILED
2169 The domain has been suspended due post-copy migration failing
2170 Sys::Virt::Domain::EVENT_UNDEFINED
2172 The persistent configuration has gone away
2173 Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED
2175 The domain configuration has gone away due to it being removed
2176 by administrator.
2177 Sys::Virt::Domain::EVENT_UNDEFINED_RENAMED
2179 The undefined configuration is a rename of an existing
2180 configuration
2181 Sys::Virt::Domain::EVENT_PMSUSPENDED
2183 The domain has stopped running
2184 Sys::Virt::Domain::EVENT_PMSUSPENDED_MEMORY
2186 The domain has suspend to RAM.
2187 Sys::Virt::Domain::EVENT_PMSUSPENDED_DISK
2189 The domain has suspend to Disk.
2190 Sys::Virt::Domain::EVENT_CRASHED
2192 The domain has crashed
2193 Sys::Virt::Domain::EVENT_CRASHED_PANICKED
2195 The domain has crashed due to a kernel panic
2196 EVENT ID CONSTANTS
2198 Sys::Virt::Domain::EVENT_ID_LIFECYCLE
2199 Domain lifecycle events
2200 Sys::Virt::Domain::EVENT_ID_REBOOT
2202 Soft / warm reboot events
2203 Sys::Virt::Domain::EVENT_ID_RTC_CHANGE
2205 RTC clock adjustments
2206 Sys::Virt::Domain::EVENT_ID_IO_ERROR
2208 File IO errors, typically from disks
2209 Sys::Virt::Domain::EVENT_ID_WATCHDOG
2211 Watchdog device triggering
2212 Sys::Virt::Domain::EVENT_ID_GRAPHICS
2214 Graphics client connections.
2215 Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON
2217 File IO errors, typically from disks, with a root cause
2218 Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR
2220 Errors from the virtualization control channel
2221 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB
2223 Completion status of asynchronous block jobs, identified by source
2224 file name.
2225 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB_2
2227 Completion status of asynchronous block jobs, identified by target
2228 device name.
2229 Sys::Virt::Domain::EVENT_ID_DISK_CHANGE
2231 Changes in disk media
2232 Sys::Virt::Domain::EVENT_ID_TRAY_CHANGE
2234 CDROM media tray state
2235 Sys::Virt::Domain::EVENT_ID_PMSUSPEND
2237 Power management initiated suspend to RAM
2238 Sys::Virt::Domain::EVENT_ID_PMSUSPEND_DISK
2240 Power management initiated suspend to Disk
2241 Sys::Virt::Domain::EVENT_ID_PMWAKEUP
2243 Power management initiated wakeup
2244 Sys::Virt::Domain::EVENT_ID_BALLOON_CHANGE
2246 Balloon target changes
2247 Sys::Virt::Domain::EVENT_ID_DEVICE_ADDED
2249 Asynchronous guest device addition
2250 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVED
2252 Asynchronous guest device removal
2253 Sys::Virt::Domain::EVENT_ID_TUNABLE
2255 Changes of any domain tuning parameters. The callback will be
2256 provided with a hash listing all changed parameters. The later
2257 DOMAIN TUNABLE constants can be useful when accessing the hash keys
2258 Sys::Virt::Domain::EVENT_ID_AGENT_LIFECYCLE
2260 Domain guest agent lifecycle events. The "state" parameter to the
2261 callback will match one of the constants
2262 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_CONNECTED
2264 The agent is now connected
2265 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_DISCONNECTED
2267 The agent is now disconnected
2268 The second parameter, "reason", matches one of the following
2270 constants
2271 Sys::Virt::Domain::EVENT_ID_MIGRATION_ITERATION
2273 Domain migration progress iteration. The "iteration" parameter to
2274 the callback will specify the number of iterations migration has
2275 made over guest RAM.
2276 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_UNKNOWN
2278 The reason is unknown
2279 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_DOMAIN_STARTED
2281 The domain was initially booted
2282 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_CHANNEL
2284 The channel on a running guest changed state
2285 Sys::Virt::Domain::EVENT_ID_JOB_COMPLETED
2287 Domain background job completion notification. The callback
2288 provides a hash containing the job stats. The keyus in the hash are
2289 the same as those used with the
2290 "Sys::Virt::Domain::get_job_stats()" method.
2291 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVAL_FAILED
2293 Guest device removal has failed.
2294 Sys::Virt::Domain::EVENT_ID_METADATA_CHANGE
2296 The domain metadata has changed
2297 Sys::Virt::Domain::EVENT_ID_BLOCK_THRESHOLD
2299 The event occurs when the hypervisor detects that the given storage
2300 element was written beyond the point specified by threshold. The
2301 event is useful for thin-provisioned storage.
2302 IO ERROR EVENT CONSTANTS
2304 These constants describe what action was taken due to the IO error.
2305 Sys::Virt::Domain::EVENT_IO_ERROR_NONE
2307 No action was taken, the error was ignored & reported as success to
2308 guest
2309 Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE
2311 The guest is paused since the error occurred
2312 Sys::Virt::Domain::EVENT_IO_ERROR_REPORT
2314 The error has been reported to the guest OS
2315 WATCHDOG EVENT CONSTANTS
2317 These constants describe what action was taken due to the watchdog
2318 firing
2319 Sys::Virt::Domain::EVENT_WATCHDOG_NONE
2321 No action was taken, the watchdog was ignored
2322 Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE
2324 The guest is paused since the watchdog fired
2325 Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF
2327 The guest is powered off after the watchdog fired
2328 Sys::Virt::Domain::EVENT_WATCHDOG_RESET
2330 The guest is reset after the watchdog fired
2331 Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN
2333 The guest attempted to gracefully shutdown after the watchdog fired
2334 Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG
2336 No action was taken, the watchdog was logged
2337 Sys::Virt::Domain::EVENT_WATCHDOG_INJECTNMI
2339 An NMI was injected into the guest after the watchdog fired
2340 GRAPHICS EVENT PHASE CONSTANTS
2342 These constants describe the phase of the graphics connection
2343 Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT
2345 The initial client connection
2346 Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE
2348 The client has been authenticated & the connection is running
2349 Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT
2351 The client has disconnected
2352 GRAPHICS EVENT ADDRESS CONSTANTS
2354 These constants describe the format of the address
2355 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4
2357 An IPv4 address
2358 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6
2360 An IPv6 address
2361 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX
2363 An UNIX socket path address
2364 DISK CHANGE EVENT CONSTANTS
2366 These constants describe the reason for a disk change event
2367 Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START
2369 The disk media was cleared, as its source was missing when
2370 attempting to start the guest
2371 Sys::Virt::Domain::EVENT_DISK_DROP_MISSING_ON_START
2373 The disk device was dropped, as its source was missing whe
2374 attempting to start the guest
2375 TRAY CHANGE CONSTANTS
2377 These constants describe the reason for a tray change event
2378 Sys::Virt::Domain::EVENT_TRAY_CHANGE_CLOSE
2380 The tray was closed
2381 Sys::Virt::Domain::EVENT_TRAY_CHANGE_OPEN
2383 The tray was opened
2384 DOMAIN BLOCK JOB TYPE CONSTANTS
2386 The following constants identify the different types of domain block
2387 jobs
2388 Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN
2390 An unknown block job type
2391 Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL
2393 The block pull job type
2394 Sys::Virt::Domain::BLOCK_JOB_TYPE_COPY
2396 The block copy job type
2397 Sys::Virt::Domain::BLOCK_JOB_TYPE_COMMIT
2399 The block commit job type
2400 Sys::Virt::Domain::BLOCK_JOB_TYPE_ACTIVE_COMMIT
2402 The block active commit job type
2403 DOMAIN BLOCK JOB COMPLETION CONSTANTS
2405 The following constants can be used to determine the completion status
2406 of a block job
2407 Sys::Virt::Domain::BLOCK_JOB_COMPLETED
2409 A successfully completed block job
2410 Sys::Virt::Domain::BLOCK_JOB_FAILED
2412 An unsuccessful block job
2413 Sys::Virt::Domain::BLOCK_JOB_CANCELED
2415 A block job canceled byy the user
2416 Sys::Virt::Domain::BLOCK_JOB_READY
2418 A block job is running
2419 DOMAIN BLOCK REBASE CONSTANTS
2421 The following constants are useful when rebasing block devices
2422 Sys::Virt::Domain::BLOCK_REBASE_SHALLOW
2424 Limit copy to top of source backing chain
2425 Sys::Virt::Domain::BLOCK_REBASE_REUSE_EXT
2427 Reuse existing external file for copy
2428 Sys::Virt::Domain::BLOCK_REBASE_COPY_RAW
2430 Make destination file raw
2431 Sys::Virt::Domain::BLOCK_REBASE_COPY
2433 Start a copy job
2434 Sys::Virt::Domain::BLOCK_REBASE_COPY_DEV
2436 Treat destination as a block device instead of file
2437 Sys::Virt::Domain::BLOCK_REBASE_RELATIVE
2439 Keep backing chain referenced using relative names
2440 DOMAIN BLOCK COPY CONSTANTS
2442 The following constants are useful when copying block devices
2443 Sys::Virt::Domain::BLOCK_COPY_SHALLOW
2445 Limit copy to top of source backing chain
2446 Sys::Virt::Domain::BLOCK_COPY_REUSE_EXT
2448 Reuse existing external file for copy
2449 Sys::Virt::Domain::BLOCK_COPY_TRANSIENT_JOB
2451 Don't force usage of recoverable job for the copy operation
2452 DOMAIN BLOCK JOB ABORT CONSTANTS
2454 The following constants are useful when aborting job copy jobs
2455 Sys::Virt::Domain::BLOCK_JOB_ABORT_ASYNC
2457 Request only, do not wait for completion
2458 Sys::Virt::Domain::BLOCK_JOB_ABORT_PIVOT
2460 Pivot to mirror when ending a copy job
2461 DOMAIN BLOCK COMMIT JOB CONSTANTS
2463 The following constants are useful with block commit job types
2464 Sys::Virt::Domain::BLOCK_COMMIT_DELETE
2466 Delete any files that are invalid after commit
2467 Sys::Virt::Domain::BLOCK_COMMIT_SHALLOW
2469 NULL base means next backing file, not whole chain
2470 Sys::Virt::Domain::BLOCK_COMMIT_ACTIVE
2472 Allow two phase commit when top is active layer
2473 Sys::Virt::Domain::BLOCK_COMMIT_RELATIVE
2475 Keep backing chain referenced using relative names
2476 DOMAIN SAVE / RESTORE CONSTANTS
2478 The following constants can be used when saving or restoring virtual
2479 machines
2480 Sys::Virt::Domain::SAVE_BYPASS_CACHE
2482 Do not use OS I/O cache when saving state.
2483 Sys::Virt::Domain::SAVE_PAUSED
2485 Mark the saved state as paused to prevent the guest CPUs starting
2486 upon restore.
2487 Sys::Virt::Domain::SAVE_RUNNING
2489 Mark the saved state as running to allow the guest CPUs to start
2490 upon restore.
2491 DOMAIN CORE DUMP CONSTANTS
2493 The following constants can be used when triggering domain core dumps
2494 Sys::Virt::Domain::DUMP_LIVE
2496 Do not pause execution while dumping the guest
2497 Sys::Virt::Domain::DUMP_CRASH
2499 Crash the guest after completing the core dump
2500 Sys::Virt::Domain::DUMP_BYPASS_CACHE
2502 Do not use OS I/O cache when writing core dump
2503 Sys::Virt::Domain::DUMP_RESET
2505 Reset the virtual machine after finishing the dump
2506 Sys::Virt::Domain::DUMP_MEMORY_ONLY
2508 Only include guest RAM in the dump, not the device state
2509 DESTROY CONSTANTS
2511 The following constants are useful when terminating guests using the
2512 "destroy" API.
2513 Sys::Virt::Domain::DESTROY_DEFAULT
2515 Destroy the guest using the default approach
2516 Sys::Virt::Domain::DESTROY_GRACEFUL
2518 Destroy the guest in a graceful manner
2519 SHUTDOWN CONSTANTS
2521 The following constants are useful when requesting that a guest
2522 terminate using the "shutdown" API
2523 Sys::Virt::Domain::SHUTDOWN_DEFAULT
2525 Shutdown using the hypervisor's default mechanism
2526 Sys::Virt::Domain::SHUTDOWN_GUEST_AGENT
2528 Shutdown by issuing a command to a guest agent
2529 Sys::Virt::Domain::SHUTDOWN_ACPI_POWER_BTN
2531 Shutdown by injecting an ACPI power button press
2532 Sys::Virt::Domain::SHUTDOWN_INITCTL
2534 Shutdown by talking to initctl (containers only)
2535 Sys::Virt::Domain::SHUTDOWN_SIGNAL
2537 Shutdown by sending SIGTERM to the init process
2538 Sys::Virt::Domain::SHUTDOWN_PARAVIRT
2540 Shutdown by issuing a paravirt power control command
2541 REBOOT CONSTANTS
2543 The following constants are useful when requesting that a guest
2544 terminate using the "reboot" API
2545 Sys::Virt::Domain::REBOOT_DEFAULT
2547 Reboot using the hypervisor's default mechanism
2548 Sys::Virt::Domain::REBOOT_GUEST_AGENT
2550 Reboot by issuing a command to a guest agent
2551 Sys::Virt::Domain::REBOOT_ACPI_POWER_BTN
2553 Reboot by injecting an ACPI power button press
2554 Sys::Virt::Domain::REBOOT_INITCTL
2556 Reboot by talking to initctl (containers only)
2557 Sys::Virt::Domain::REBOOT_SIGNAL
2559 Reboot by sending SIGHUP to the init process
2560 Sys::Virt::Domain::REBOOT_PARAVIRT
2562 Reboot by issuing a paravirt power control command
2563 METADATA CONSTANTS
2565 The following constants are useful when reading/writing metadata about
2566 a guest
2567 Sys::Virt::Domain::METADATA_TITLE
2569 The short human friendly title of the guest
2570 Sys::Virt::Domain::METADATA_DESCRIPTION
2572 The long free text description of the guest
2573 Sys::Virt::Domain::METADATA_ELEMENT
2575 The structured metadata elements for the guest
2576 DISK ERROR CONSTANTS
2578 The following constants are useful when interpreting disk error codes
2579 Sys::Virt::Domain::DISK_ERROR_NONE
2581 No error
2582 Sys::Virt::Domain::DISK_ERROR_NO_SPACE
2584 The host storage has run out of free space
2585 Sys::Virt::Domain::DISK_ERROR_UNSPEC
2587 An unspecified error has occurred.
2588 MEMORY STATISTIC CONSTANTS
2590 Sys::Virt::Domain::MEMORY_STAT_SWAP_IN
2591 Swap in
2592 Sys::Virt::Domain::MEMORY_STAT_SWAP_OUT
2594 Swap out
2595 Sys::Virt::Domain::MEMORY_STAT_MINOR_FAULT
2597 Minor faults
2598 Sys::Virt::Domain::MEMORY_STAT_MAJOR_FAULT
2600 Major faults
2601 Sys::Virt::Domain::MEMORY_STAT_RSS
2603 Resident memory
2604 Sys::Virt::Domain::MEMORY_STAT_UNUSED
2606 Unused memory
2607 Sys::Virt::Domain::MEMORY_STAT_AVAILABLE
2609 Available memory
2610 Sys::Virt::Domain::MEMORY_STAT_ACTUAL_BALLOON
2612 Actual balloon limit
2613 Sys::Virt::Domain::MEMORY_STAT_USABLE
2615 Amount of usable memory
2616 Sys::Virt::Domain::MEMORY_STAT_LAST_UPDATE
2618 Time of last stats refresh from guest
2619 DOMAIN LIST CONSTANTS
2621 The following constants can be used when listing domains
2622 Sys::Virt::Domain::LIST_ACTIVE
2624 Only list domains that are currently active (running, or paused)
2625 Sys::Virt::Domain::LIST_AUTOSTART
2627 Only list domains that are set to automatically start on boot
2628 Sys::Virt::Domain::LIST_HAS_SNAPSHOT
2630 Only list domains that have a stored snapshot
2631 Sys::Virt::Domain::LIST_INACTIVE
2633 Only list domains that are currently inactive (shutoff, saved)
2634 Sys::Virt::Domain::LIST_MANAGEDSAVE
2636 Only list domains that have current managed save state
2637 Sys::Virt::Domain::LIST_NO_AUTOSTART
2639 Only list domains that are not set to automatically start on boto
2640 Sys::Virt::Domain::LIST_NO_MANAGEDSAVE
2642 Only list domains that do not have any managed save state
2643 Sys::Virt::Domain::LIST_NO_SNAPSHOT
2645 Only list domains that do not have a stored snapshot
2646 Sys::Virt::Domain::LIST_OTHER
2648 Only list domains that are not running, paused or shutoff
2649 Sys::Virt::Domain::LIST_PAUSED
2651 Only list domains that are paused
2652 Sys::Virt::Domain::LIST_PERSISTENT
2654 Only list domains which have a persistent config
2655 Sys::Virt::Domain::LIST_RUNNING
2657 Only list domains that are currently running
2658 Sys::Virt::Domain::LIST_SHUTOFF
2660 Only list domains that are currently shutoff
2661 Sys::Virt::Domain::LIST_TRANSIENT
2663 Only list domains that do not have a persistent config
2664 SEND KEY CONSTANTS
2666 The following constants are to be used with the "send_key" API
2667 Sys::Virt::Domain::SEND_KEY_MAX_KEYS
2669 The maximum number of keys that can be sent in a single call to
2670 "send_key"
2671 BLOCK STATS CONSTANTS
2673 The following constants provide the names of well known block stats
2674 fields
2675 Sys::Virt::Domain::BLOCK_STATS_ERRS
2677 The number of I/O errors
2678 Sys::Virt::Domain::BLOCK_STATS_FLUSH_REQ
2680 The number of flush requests
2681 Sys::Virt::Domain::BLOCK_STATS_FLUSH_TOTAL_TIMES
2683 The time spent processing flush requests
2684 Sys::Virt::Domain::BLOCK_STATS_READ_BYTES
2686 The amount of data read
2687 Sys::Virt::Domain::BLOCK_STATS_READ_REQ
2689 The number of read requests
2690 Sys::Virt::Domain::BLOCK_STATS_READ_TOTAL_TIMES
2692 The time spent processing read requests
2693 Sys::Virt::Domain::BLOCK_STATS_WRITE_BYTES
2695 The amount of data written
2696 Sys::Virt::Domain::BLOCK_STATS_WRITE_REQ
2698 The number of write requests
2699 Sys::Virt::Domain::BLOCK_STATS_WRITE_TOTAL_TIMES
2701 The time spent processing write requests
2702 CPU STATS CONSTANTS
2704 The following constants provide the names of well known cpu stats
2705 fields
2706 Sys::Virt::Domain::CPU_STATS_CPUTIME
2708 The total CPU time, including both hypervisor and vCPU time.
2709 Sys::Virt::Domain::CPU_STATS_USERTIME
2711 THe total time in kernel
2712 Sys::Virt::Domain::CPU_STATS_SYSTEMTIME
2714 The total time in userspace
2715 Sys::Virt::Domain::CPU_STATS_VCPUTIME
2717 The total vCPU time.
2718 CPU STATS CONSTANTS
2720 The following constants provide the names of well known schedular
2721 parameters
2722 Sys::Virt::SCHEDULER_EMULATOR_PERIOD
2724 The duration of the time period for scheduling the emulator
2725 Sys::Virt::SCHEDULER_EMULATOR_QUOTA
2727 The quota for the emulator in one schedular time period
2728 Sys::Virt::SCHEDULER_IOTHREAD_PERIOD
2730 The duration of the time period for scheduling the iothread
2731 Sys::Virt::SCHEDULER_IOTHREAD_QUOTA
2733 The quota for the iothread in one schedular time period
2734 DOMAIN STATS FLAG CONSTANTS
2736 The following constants are used as flags when requesting bulk domain
2737 stats from "Sys::Virt::get_all_domain_stats".
2738 Sys::Virt::Domain::GET_ALL_STATS_ACTIVE
2740 Include stats for active domains
2741 Sys::Virt::Domain::GET_ALL_STATS_INACTIVE
2743 Include stats for inactive domains
2744 Sys::Virt::Domain::GET_ALL_STATS_OTHER
2746 Include stats for other domains
2747 Sys::Virt::Domain::GET_ALL_STATS_PAUSED
2749 Include stats for paused domains
2750 Sys::Virt::Domain::GET_ALL_STATS_PERSISTENT
2752 Include stats for persistent domains
2753 Sys::Virt::Domain::GET_ALL_STATS_RUNNING
2755 Include stats for running domains
2756 Sys::Virt::Domain::GET_ALL_STATS_SHUTOFF
2758 Include stats for shutoff domains
2759 Sys::Virt::Domain::GET_ALL_STATS_TRANSIENT
2761 Include stats for transient domains
2762 Sys::Virt::Domain::GET_ALL_STATS_ENFORCE_STATS
2764 Require that all requested stats fields are returned
2765 Sys::Virt::Domain::GET_ALL_STATS_BACKING
2767 Get stats for image backing files too
2768 Sys::Virt::Domain::GET_ALL_STATS_NOWAIT
2770 Skip stats if they can't be acquired without waiting
2771 DOMAIN STATS FIELD CONSTANTS
2773 The following constants are used to control which fields are returned
2774 for stats queries.
2775 Sys::Virt::Domain::STATS_BALLOON
2777 Balloon statistics
2778 Sys::Virt::Domain::STATS_BLOCK
2780 Block device info
2781 Sys::Virt::Domain::STATS_CPU_TOTAL
2783 CPU usage info
2784 Sys::Virt::Domain::STATS_INTERFACE
2786 Network interface info
2787 Sys::Virt::Domain::STATS_STATE
2789 General lifecycle state
2790 Sys::Virt::Domain::STATS_VCPU
2792 Virtual CPU info
2793 Sys::Virt::Domain::STATS_PERF
2795 Performance event counter values
2796 PROCESS SIGNALS
2798 The following constants provide the names of signals which can be sent
2799 to guest processes. They mostly correspond to POSIX signal names.
2800 Sys::Virt::Domain::PROCESS_SIGNAL_NOP
2802 SIGNOP
2803 Sys::Virt::Domain::PROCESS_SIGNAL_HUP
2805 SIGHUP
2806 Sys::Virt::Domain::PROCESS_SIGNAL_INT
2808 SIGINT
2809 Sys::Virt::Domain::PROCESS_SIGNAL_QUIT
2811 SIGQUIT
2812 Sys::Virt::Domain::PROCESS_SIGNAL_ILL
2814 SIGILL
2815 Sys::Virt::Domain::PROCESS_SIGNAL_TRAP
2817 SIGTRAP
2818 Sys::Virt::Domain::PROCESS_SIGNAL_ABRT
2820 SIGABRT
2821 Sys::Virt::Domain::PROCESS_SIGNAL_BUS
2823 SIGBUS
2824 Sys::Virt::Domain::PROCESS_SIGNAL_FPE
2826 SIGFPE
2827 Sys::Virt::Domain::PROCESS_SIGNAL_KILL
2829 SIGKILL
2830 Sys::Virt::Domain::PROCESS_SIGNAL_USR1
2832 SIGUSR1
2833 Sys::Virt::Domain::PROCESS_SIGNAL_SEGV
2835 SIGSEGV
2836 Sys::Virt::Domain::PROCESS_SIGNAL_USR2
2838 SIGUSR2
2839 Sys::Virt::Domain::PROCESS_SIGNAL_PIPE
2841 SIGPIPE
2842 Sys::Virt::Domain::PROCESS_SIGNAL_ALRM
2844 SIGALRM
2845 Sys::Virt::Domain::PROCESS_SIGNAL_TERM
2847 SIGTERM
2848 Sys::Virt::Domain::PROCESS_SIGNAL_STKFLT
2850 SIGSTKFLT
2851 Sys::Virt::Domain::PROCESS_SIGNAL_CHLD
2853 SIGCHLD
2854 Sys::Virt::Domain::PROCESS_SIGNAL_CONT
2856 SIGCONT
2857 Sys::Virt::Domain::PROCESS_SIGNAL_STOP
2859 SIGSTOP
2860 Sys::Virt::Domain::PROCESS_SIGNAL_TSTP
2862 SIGTSTP
2863 Sys::Virt::Domain::PROCESS_SIGNAL_TTIN
2865 SIGTTIN
2866 Sys::Virt::Domain::PROCESS_SIGNAL_TTOU
2868 SIGTTOU
2869 Sys::Virt::Domain::PROCESS_SIGNAL_URG
2871 SIGURG
2872 Sys::Virt::Domain::PROCESS_SIGNAL_XCPU
2874 SIGXCPU
2875 Sys::Virt::Domain::PROCESS_SIGNAL_XFSZ
2877 SIGXFSZ
2878 Sys::Virt::Domain::PROCESS_SIGNAL_VTALRM
2880 SIGVTALRM
2881 Sys::Virt::Domain::PROCESS_SIGNAL_PROF
2883 SIGPROF
2884 Sys::Virt::Domain::PROCESS_SIGNAL_WINCH
2886 SIGWINCH
2887 Sys::Virt::Domain::PROCESS_SIGNAL_POLL
2889 SIGPOLL
2890 Sys::Virt::Domain::PROCESS_SIGNAL_PWR
2892 SIGPWR
2893 Sys::Virt::Domain::PROCESS_SIGNAL_SYS
2895 SIGSYS
2896 Sys::Virt::Domain::PROCESS_SIGNAL_RT0
2898 SIGRT0
2899 Sys::Virt::Domain::PROCESS_SIGNAL_RT1
2901 SIGRT1
2902 Sys::Virt::Domain::PROCESS_SIGNAL_RT2
2904 SIGRT2
2905 Sys::Virt::Domain::PROCESS_SIGNAL_RT3
2907 SIGRT3
2908 Sys::Virt::Domain::PROCESS_SIGNAL_RT4
2910 SIGRT4
2911 Sys::Virt::Domain::PROCESS_SIGNAL_RT5
2913 SIGRT5
2914 Sys::Virt::Domain::PROCESS_SIGNAL_RT6
2916 SIGRT6
2917 Sys::Virt::Domain::PROCESS_SIGNAL_RT7
2919 SIGRT7
2920 Sys::Virt::Domain::PROCESS_SIGNAL_RT8
2922 SIGRT8
2923 Sys::Virt::Domain::PROCESS_SIGNAL_RT9
2925 SIGRT9
2926 Sys::Virt::Domain::PROCESS_SIGNAL_RT10
2928 SIGRT10
2929 Sys::Virt::Domain::PROCESS_SIGNAL_RT11
2931 SIGRT11
2932 Sys::Virt::Domain::PROCESS_SIGNAL_RT12
2934 SIGRT12
2935 Sys::Virt::Domain::PROCESS_SIGNAL_RT13
2937 SIGRT13
2938 Sys::Virt::Domain::PROCESS_SIGNAL_RT14
2940 SIGRT14
2941 Sys::Virt::Domain::PROCESS_SIGNAL_RT15
2943 SIGRT15
2944 Sys::Virt::Domain::PROCESS_SIGNAL_RT16
2946 SIGRT16
2947 Sys::Virt::Domain::PROCESS_SIGNAL_RT17
2949 SIGRT17
2950 Sys::Virt::Domain::PROCESS_SIGNAL_RT18
2952 SIGRT18
2953 Sys::Virt::Domain::PROCESS_SIGNAL_RT19
2955 SIGRT19
2956 Sys::Virt::Domain::PROCESS_SIGNAL_RT20
2958 SIGRT20
2959 Sys::Virt::Domain::PROCESS_SIGNAL_RT21
2961 SIGRT21
2962 Sys::Virt::Domain::PROCESS_SIGNAL_RT22
2964 SIGRT22
2965 Sys::Virt::Domain::PROCESS_SIGNAL_RT23
2967 SIGRT23
2968 Sys::Virt::Domain::PROCESS_SIGNAL_RT24
2970 SIGRT24
2971 Sys::Virt::Domain::PROCESS_SIGNAL_RT25
2973 SIGRT25
2974 Sys::Virt::Domain::PROCESS_SIGNAL_RT26
2976 SIGRT26
2977 Sys::Virt::Domain::PROCESS_SIGNAL_RT27
2979 SIGRT27
2980 Sys::Virt::Domain::PROCESS_SIGNAL_RT28
2982 SIGRT28
2983 Sys::Virt::Domain::PROCESS_SIGNAL_RT29
2985 SIGRT29
2986 Sys::Virt::Domain::PROCESS_SIGNAL_RT30
2988 SIGRT30
2989 Sys::Virt::Domain::PROCESS_SIGNAL_RT31
2991 SIGRT31
2992 Sys::Virt::Domain::PROCESS_SIGNAL_RT32
2994 SIGRT32
2995 DOMAIN TUNABLE CONSTANTS
2997 The following constants are useful when accessing domain tuning
2998 parameters in APIs and events
2999 Sys::Virt::Domain::TUNABLE_CPU_CPU_SHARES
3001 Proportional CPU weight
3002 Sys::Virt::Domain::TUNABLE_CPU_EMULATORPIN
3004 Emulator thread CPU pinning mask
3005 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_PERIOD
3007 Emulator thread CPU period
3008 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_QUOTA
3010 Emulator thread CPU quota
3011 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_PERIOD
3013 Iothread thread CPU period
3014 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_QUOTA
3016 Iothread thread CPU quota
3017 Sys::Virt::Domain::TUNABLE_CPU_VCPUPIN
3019 VCPU thread pinning mask
3020 Sys::Virt::Domain::TUNABLE_CPU_VCPU_PERIOD
3022 VCPU thread period
3023 Sys::Virt::Domain::TUNABLE_CPU_VCPU_QUOTA
3025 VCPU thread quota
3026 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_PERIOD
3028 VM global period
3029 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_QUOTA
3031 VM global quota
3032 Sys::Virt::Domain::TUNABLE_BLKDEV_DISK
3034 The name of guest disks
3035 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC
3037 Read throughput in bytes per sec
3038 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC
3040 Read throughput in I/O operations per sec
3041 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC
3043 Total throughput in bytes per sec
3044 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC
3046 Total throughput in I/O operations per sec
3047 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC
3049 Write throughput in bytes per sec
3050 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC
3052 Write throughput in I/O operations per sec
3053 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX
3055 Maximum read throughput in bytes per sec
3056 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX
3058 Maximum read throughput in I/O operations per sec
3059 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX
3061 Maximum total throughput in bytes per sec
3062 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX
3064 Maximum total throughput in I/O operations per sec
3065 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX
3067 Maximum write throughput in bytes per sec
3068 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX
3070 Maximum write throughput in I/O operations per sec
3071 Sys::Virt::Domain::TUNABLE_BLKDEV_SIZE_IOPS_SEC
3073 The maximum I/O operations per second
3074 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX_LENGTH
3076 The duration in seconds allowed for maximum total bytes processed
3077 per second.
3078 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX_LENGTH
3080 The duration in seconds allowed for maximum bytes read per second.
3081 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX_LENGTH
3083 The duration in seconds allowed for maximum bytes written per
3084 second.
3085 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX_LENGTH
3087 The duration in seconds allowed for maximum total I/O operations
3088 processed per second.
3089 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX_LENGTH
3091 The duration in seconds allowed for maximum I/O operations read per
3092 second.
3093 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX_LENGTH
3095 The duration in seconds allowed for maximum I/O operations written
3096 per second.
3097 Sys::Virt::Domain::TUNABLE_BLKDEV_GROUP_NAME
3099 The name of the blkdev group
3100 Sys::Virt::Domain::TUNABLE_IOTHREADSPIN
3102 The I/O threads pinning
3103 DOMAIN LIFECYCLE CONSTANTS
3105 The following constants are useful when setting action for lifecycle
3106 events.
3107 Sys::Virt::Domain::LIFECYCLE_POWEROFF
3109 The poweroff lifecycle event type
3110 Sys::Virt::Domain::LIFECYCLE_REBOOT
3112 The reboot lifecycle event type
3113 Sys::Virt::Domain::LIFECYCLE_CRASH
3115 The crash lifecycle event type
3116 DOMAIN LIFECYCLE ACTION CONSTANTS
3118 Sys::Virt::Domain::LIFECYCLE_ACTION_DESTROY
3119 The destroy lifecycle action
3120 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART
3122 The restart lifecycle action
3123 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART_RENAME
3125 The restart-rename lifecycle action
3126 Sys::Virt::Domain::LIFECYCLE_ACTION_PRESERVE
3128 The preserve lifecycle action
3129 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_DESTROY
3131 The coredump-destroy lifecycle action
3132 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_RESTART
3134 The coredump-restart lifecycle action
3135
3137 Daniel P. Berrange <berrange@redhat.com>
3138
3140 Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
3141
3143 This program is free software; you can redistribute it and/or modify it
3144 under the terms of either the GNU General Public License as published
3145 by the Free Software Foundation (either version 2 of the License, or at
3146 your option any later version), or, the Artistic License, as specified
3147 in the Perl README file.
3148
3150 Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
3151perl v5.16.3 2018-11-02 Sys::Virt::Domain(3)