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($flags=0)
28 Returns a string representing the hostname of the guest. $flags
29 can be zero or more of
30 Sys::Virt::Domain::GET_HOSTNAME_AGENT
32 Report the guest agent hostname
33 Sys::Virt::Domain::GET_HOSTNAME_LEASE
35 Report the DHCP lease hostname
36 my $str = $dom->get_metadata($type, $uri, $flags =0)
38 Returns the metadata element of type $type associated with the
39 domain. If $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the
40 $uri parameter specifies the XML namespace to retrieve, otherwise
41 $uri should be "undef". The optional $flags parameter defaults to
42 zero.
43 $dom->set_metadata($type, $val, $key, $uri, $flags=0)
45 Sets the metadata element of type $type to hold the value $val. If
46 $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the $key and
47 $uri elements specify an XML namespace to use, otherwise they
48 should both be "undef". The optional $flags parameter defaults to
49 zero.
50 $dom->is_active()
52 Returns a true value if the domain is currently running
53 $dom->is_persistent()
55 Returns a true value if the domain has a persistent configuration
56 file defined
57 $dom->is_updated()
59 Returns a true value if the domain is running and has a persistent
60 configuration file defined that is out of date compared to the
61 current live config.
62 my $xml = $dom->get_xml_description($flags=0)
64 Returns an XML document containing a complete description of the
65 domain's configuration. The optional $flags parameter controls
66 generation of the XML document, defaulting to 0 if omitted. It can
67 be one or more of the XML DUMP constants listed later in this
68 document.
69 my $type = $dom->get_os_type()
71 Returns a string containing the name of the OS type running within
72 the domain.
73 $dom->create($flags)
75 Start a domain whose configuration was previously defined using the
76 "define_domain" method in Sys::Virt. The $flags parameter accepts
77 one of the DOMAIN CREATION constants documented later, and defaults
78 to 0 if omitted.
79 $dom->create_with_files($fds, $flags)
81 Start a domain whose configuration was previously defined using the
82 "define_domain" method in Sys::Virt. The $fds parameter is an array
83 of UNIX file descriptors which will be passed to the init process
84 of the container. This is only supported with container based
85 virtualization.The $flags parameter accepts one of the DOMAIN
86 CREATION constants documented later, and defaults to 0 if omitted.
87 $dom->undefine()
89 Remove the configuration associated with a domain previously
90 defined with the "define_domain" method in Sys::Virt. If the domain
91 is running, you probably want to use the "shutdown" or "destroy"
92 methods instead.
93 $dom->suspend()
95 Temporarily stop execution of the domain, allowing later
96 continuation by calling the "resume" method.
97 $dom->resume()
99 Resume execution of a domain previously halted with the "suspend"
100 method.
101 $dom->pm_wakeup()
103 Wakeup the guest from power management suspend state
104 $dom->pm_suspend_for_duration($target, $duration, $flags=0)
106 Tells the guest OS to enter the power management suspend state
107 identified by $target. The $target parameter should be one of the
108 NODE SUSPEND CONTANTS listed in "Sys::Virt". The $duration
109 specifies when the guest should automatically wakeup. The $flags
110 parameter is optional and defaults to zero.
111 $dom->save($filename, $dxml=undef, $params=undef, $flags=0)
113 Take a snapshot of the domain's state and save the information to
114 the file named in the $filename parameter. The domain can later be
115 restored from this file with the "restore_domain" method on the
116 Sys::Virt object. The optional $dxml parameter can be used to alter
117 portions of the domain XML that will be used when performing
118 restore. The $params parameter is a hash reference whose keys is a
119 subset of the SAVE / RESTORE PARAMETER CONSTANTS. The $flags
120 parameter accepts one of the SAVE / RESTORE FLAG CONSTANTS
121 described later and defaults to zero.
122 $dom->managed_save($flags=0)
124 Take a snapshot of the domain's state and save the information to a
125 managed save location. The domain will be automatically restored
126 with this state when it is next started. The $flags parameter is
127 unused and defaults to zero.
128 $bool = $dom->has_managed_save_image($flags=0)
130 Return a non-zero value if the domain has a managed save image that
131 will be used at next start. The $flags parameter is unused and
132 defaults to zero.
133 $dom->managed_save_remove($flags=0)
135 Remove the current managed save image, causing the guest to perform
136 a full boot next time it is started. The $flags parameter is unused
137 and defaults to zero.
138 $dom->managed_save_define_xml($xml, $flags=0)
140 Update the XML of the managed save image to $xml. The $flags
141 parameter is unused and defaults to zero.
142 $xml = $dom->managed_save_get_xml_description($flags=0)
144 Get the XML in the managed save image. The $flags parameter accepts
145 the following constants
146 Sys::Virt::Domain::SAVE_IMAGE_XML_SECURE
148 Include security sensitive information in the XML dump, such as
149 passwords.
150 $dom->core_dump($filename[, $flags])
152 Trigger a core dump of the guest virtual machine, saving its memory
153 image to $filename so it can be analysed by tools such as "crash".
154 The optional $flags flags parameter is currently unused and if
155 omitted will default to 0.
156 $dom->core_dump_format($filename, $format, [, $flags])
158 Trigger a core dump of the guest virtual machine, saving its memory
159 image to $filename so it can be analysed by tools such as "crash".
160 The $format parameter is one of the core dump format constants.
161 The optional $flags flags parameter is currently unused and if
162 omitted will default to 0.
163 Sys::Virt::Domain::CORE_DUMP_FORMAT_RAW
165 The raw ELF format
166 Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_ZLIB
168 The zlib compressed ELF format
169 Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_SNAPPY
171 The snappy compressed ELF format
172 Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_LZO
174 The lzo compressed ELF format
175 Sys::Virt::Domain::CORE_DUMP_FORMAT_WIN_DMP
177 The Windows dump format
178 $dom->destroy()
180 Immediately poweroff the machine. This is equivalent to removing
181 the power plug. The guest OS is given no time to cleanup / save
182 state. For a clean poweroff sequence, use the "shutdown" method
183 instead.
184 my $info = $dom->get_info()
186 Returns a hash reference summarising the execution state of the
187 domain. The elements of the hash are as follows:
188 maxMem
190 The maximum memory allowed for this domain, in kilobytes
191 memory
193 The current memory allocated to the domain in kilobytes
194 cpuTime
196 The amount of CPU time used by the domain
197 nrVirtCpu
199 The current number of virtual CPUs enabled in the domain
200 state
202 The execution state of the machine, which will be one of the
203 constants &Sys::Virt::Domain::STATE_*.
204 my ($state, $reason) = $dom->get_state()
206 Returns an array whose values specify the current state of the
207 guest, and the reason for it being in that state. The $state
208 values are the same as for the "get_info" API, and the $reason
209 values come from:
210 Sys::Virt::Domain::STATE_CRASHED_UNKNOWN
212 It is not known why the domain has crashed
213 Sys::Virt::Domain::STATE_CRASHED_PANICKED
215 The domain has crashed due to a kernel panic
216 Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN
218 It is not known why the domain has no state
219 Sys::Virt::Domain::STATE_PAUSED_DUMP
221 The guest is paused due to a core dump operation
222 Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT
224 The guest is paused due to a snapshot
225 Sys::Virt::Domain::STATE_PAUSED_IOERROR
227 The guest is paused due to an I/O error
228 Sys::Virt::Domain::STATE_PAUSED_MIGRATION
230 The guest is paused due to migration
231 Sys::Virt::Domain::STATE_PAUSED_SAVE
233 The guest is paused due to a save operation
234 Sys::Virt::Domain::STATE_PAUSED_UNKNOWN
236 It is not known why the domain has paused
237 Sys::Virt::Domain::STATE_PAUSED_USER
239 The guest is paused at admin request
240 Sys::Virt::Domain::STATE_PAUSED_WATCHDOG
242 The guest is paused due to the watchdog
243 Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN
245 The guest is paused while domain shutdown takes place
246 Sys::Virt::Domain::STATE_PAUSED_SNAPSHOT
248 The guest is paused while a snapshot takes place
249 Sys::Virt::Domain::STATE_PAUSED_CRASHED
251 The guest is paused due to a kernel panic
252 Sys::Virt::Domain::STATE_PAUSED_STARTING_UP
254 The guest is paused as it is being started up.
255 Sys::Virt::Domain::STATE_PAUSED_POSTCOPY
257 The guest is paused as post-copy migration is taking place
258 Sys::Virt::Domain::STATE_PAUSED_POSTCOPY_FAILED
260 The guest is paused as post-copy migration failed
261 Sys::Virt::Domain::STATE_RUNNING_BOOTED
263 The guest is running after being booted
264 Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT
266 The guest is running after restore from snapshot
267 Sys::Virt::Domain::STATE_RUNNING_MIGRATED
269 The guest is running after migration
270 Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED
272 The guest is running after migration abort
273 Sys::Virt::Domain::STATE_RUNNING_RESTORED
275 The guest is running after restore from file
276 Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED
278 The guest is running after save cancel
279 Sys::Virt::Domain::STATE_RUNNING_UNKNOWN
281 It is not known why the domain has started
282 Sys::Virt::Domain::STATE_RUNNING_UNPAUSED
284 The guest is running after a resume
285 Sys::Virt::Domain::STATE_RUNNING_WAKEUP
287 The guest is running after wakeup from power management suspend
288 Sys::Virt::Domain::STATE_RUNNING_CRASHED
290 The guest was restarted after crashing
291 Sys::Virt::Domain::STATE_RUNNING_POSTCOPY
293 The guest is running but post-copy is taking place
294 Sys::Virt::Domain::STATE_RUNNING_POSTCOPY_FAILED
296 The guest is running, but migration failed in post-copy
297 Sys::Virt::Domain::STATE_BLOCKED_UNKNOWN
299 The guest is blocked for an unknown reason
300 Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN
302 It is not known why the domain has shutdown
303 Sys::Virt::Domain::STATE_SHUTDOWN_USER
305 The guest is shutdown due to admin request
306 Sys::Virt::Domain::STATE_SHUTOFF_CRASHED
308 The guest is shutoff after a crash
309 Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED
311 The guest is shutoff after being destroyed
312 Sys::Virt::Domain::STATE_SHUTOFF_FAILED
314 The guest is shutoff due to a virtualization failure
315 Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT
317 The guest is shutoff after a snapshot
318 Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED
320 The guest is shutoff after migration
321 Sys::Virt::Domain::STATE_SHUTOFF_SAVED
323 The guest is shutoff after a save
324 Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN
326 The guest is shutoff due to controlled shutdown
327 Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN
329 It is not known why the domain has shutoff
330 Sys::Virt::Domain::STATE_SHUTOFF_DAEMON
332 The daemon stopped the guest due to a failure
333 Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN
335 It is not known why the domain was suspended to RAM
336 Sys::Virt::Domain::STATE_PMSUSPENDED_DISK_UNKNOWN
338 It is not known why the domain was suspended to disk
339 my $info = $dom->get_control_info($flags=0)
341 Returns a hash reference providing information about the control
342 channel. The returned keys in the hash are
343 "state"
345 One of the CONTROL INFO constants listed later
346 "details"
348 Currently unused, always 0.
349 "stateTime"
351 The elapsed time since the control channel entered the current
352 state.
353 my $time = $dom->get_time($flags=0);
355 Get the current time of the guest, in seconds and nanoseconds. The
356 $flags parameter is currently unused and defaults to zero. The
357 return value is an array ref with two elements, the first contains
358 the time in seconds, the second contains the remaining nanoseconds.
359 $dom->set_time($secs, $nsecs, $flags=0);
361 Set the current time of the guest, in seconds and nanoseconds. The
362 $flags parameter accepts one of
363 "Sys::Virt::Domain::TIME_SYNC"
365 Re-sync domain time from domain's RTC.
366 $dom->set_user_password($username, $password, $flags=0);
368 Update the password for account $username to be $password.
369 $password is the clear-text password string unless the
370 PASSWORD_ENCRYPTED flag is set.
371 "Sys::Virt::Domain::PASSWORD_ENCRYPTED"
373 The $password is encrypted with the password scheme required by
374 the guest OS.
375 $dom->rename($newname, $flags=0)
377 Change the name of an inactive guest to be $newname. The $flags
378 parameter is currently unused and defaults to zero.
379 my @errs = $dom->get_disk_errors($flags=0)
381 Returns a list of all disk errors that have occurred on the backing
382 store for the guest's virtual disks. The returned array elements
383 are hash references, containing two keys
384 "path"
386 The path of the disk with an error
387 "error"
389 The error type
390 $dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0)
392 Sends a sequence of keycodes to the guest domain. The $keycodeset
393 should be one of the constants listed later in the KEYCODE SET
394 section. $holdtiem is the duration, in milliseconds, to keep the
395 key pressed before releasing it and sending the next keycode.
396 @keycodes is an array reference containing the list of keycodes to
397 send to the guest. The elements in the array should be keycode
398 values from the specified keycode set. $flags is currently unused.
399 my $info = $dom->get_block_info($dev, $flags=0)
401 Returns a hash reference summarising the disk usage of the host
402 backing store for a guest block device. The $dev parameter should
403 be the path to the backing store on the host. $flags is currently
404 unused and defaults to 0 if omitted. The returned hash contains the
405 following elements
406 capacity
408 Logical size in bytes of the block device backing image *
409 allocation
411 Highest allocated extent in bytes of the block device backing
412 image
413 physical
415 Physical size in bytes of the container of the backing image
416 $dom->set_max_memory($mem)
418 Set the maximum memory for the domain to the value $mem. The value
419 of the $mem parameter is specified in kilobytes.
420 $mem = $dom->get_max_memory()
422 Returns the current maximum memory allowed for this domain in
423 kilobytes.
424 $dom->set_memory($mem, $flags)
426 Set the current memory for the domain to the value $mem. The value
427 of the $mem parameter is specified in kilobytes. This must be less
428 than, or equal to the domain's max memory limit. The $flags
429 parameter can control whether the update affects the live guest, or
430 inactive config, defaulting to modifying the current state.
431 $dom->set_memory_stats_period($period, $flags)
433 Set the period on which guests memory stats are refreshed, with
434 $period being a value in seconds. The $flags parameter is currently
435 unused.
436 $dom->shutdown()
438 Request that the guest OS perform a graceful shutdown and poweroff.
439 This usually requires some form of cooperation from the guest
440 operating system, such as responding to an ACPI signal, or a guest
441 agent process. For an immediate, forceful poweroff, use the
442 "destroy" method instead.
443 $dom->reboot([$flags])
445 Request that the guest OS perform a graceful shutdown and
446 optionally restart. The optional $flags parameter is currently
447 unused and if omitted defaults to zero.
448 $dom->reset([$flags])
450 Perform a hardware reset of the virtual machine. The guest OS is
451 given no opportunity to shutdown gracefully. The optional $flags
452 parameter is currently unused and if omitted defaults to zero.
453 $dom->get_max_vcpus()
455 Return the maximum number of vcpus that are configured for the
456 domain
457 $dom->attach_device($xml[, $flags])
459 Hotplug a new device whose configuration is given by $xml, to the
460 running guest. The optional <$flags> parameter defaults to 0, but
461 can accept one of the device hotplug flags described later.
462 $dom->detach_device($xml[, $flags])
464 Hotunplug an existing device whose configuration is given by $xml,
465 from the running guest. The optional <$flags> parameter defaults to
466 0, but can accept one of the device hotplug flags described later.
467 $dom->detach_device_alias($alias[, $flags])
469 Hotunplug an existing device which is identified by $alias. The
470 optional <$flags> parameter defaults to 0, but can accept one of
471 the device hotplug flags described later.
472 $dom->update_device($xml[, $flags])
474 Update the configuration of an existing device. The new
475 configuration is given by $xml. The optional <$flags> parameter
476 defaults to 0 but can accept one of the device hotplug flags
477 described later.
478 $data = $dom->block_peek($path, $offset, $size[, $flags])
480 Peek into the guest disk $path, at byte $offset capturing $size
481 bytes of data. The returned scalar may contain embedded NULLs. The
482 optional $flags parameter is currently unused and if omitted
483 defaults to zero.
484 $data = $dom->memory_peek($offset, $size[, $flags])
486 Peek into the guest memory at byte $offset virtual address,
487 capturing $size bytes of memory. The return scalar may contain
488 embedded NULLs. The optional $flags parameter is currently unused
489 and if omitted defaults to zero.
490 $flag = $dom->get_autostart();
492 Return a true value if the guest domain is configured to
493 automatically start upon boot. Return false, otherwise
494 $dom->set_autostart($flag)
496 Set the state of the autostart flag, which determines whether the
497 guest will automatically start upon boot of the host OS
498 $dom->set_vcpus($count, [$flags])
500 Set the number of virtual CPUs in the guest VM to $count. The
501 optional $flags parameter can be used to control whether the
502 setting changes the live config or inactive config.
503 $dom->set_vcpu($cpumap, $state, [$flags])
505 Set the state of the CPUs in $cpumap to $state. The $flags
506 parameter defaults to zero if not present.
507 $count = $dom->get_vcpus([$flags])
509 Get the number of virtual CPUs in the guest VM. The optional
510 $flags parameter can be used to control whether to query the
511 setting of the live config or inactive config.
512 $dom->set_guest_vcpus($cpumap, $state, [$flags=0])
514 Set the online status of the guest OS CPUs. The $cpumap parameter
515 describes the set of CPUs to modify (eg "0-3,^1"). $state is
516 either 1 to set the CPUs online, or 0 to set them offline. The
517 $flags parameter is currently unused and defaults to 0.
518 $info $dom->get_guest_vcpus([$flags=0])
520 Query information about the guest OS CPUs. The returned data is a
521 hash reference with the following keys.
522 vcpus
524 String containing bitmap representing CPU ids reported
525 currently known to the guest.
526 online
528 String containing bitmap representing CPU ids that are
529 currently online in the guest.
530 offlinable
532 String containing bitmap representing CPU ids that can be
533 offlined in the guest.
534 The $flags parameter is currently unused and defaults to 0.
536 $type = $dom->get_scheduler_type()
538 Return the scheduler type for the guest domain
539 $stats = $dom->block_stats($path)
541 Fetch the current I/O statistics for the block device given by
542 $path. The returned hash reference contains keys for
543 "rd_req"
545 Number of read requests
546 "rd_bytes"
548 Number of bytes read
549 "wr_req"
551 Number of write requests
552 "wr_bytes"
554 Number of bytes written
555 "errs"
557 Some kind of error count
558 my $params = $dom->get_scheduler_parameters($flags=0)
560 Return the set of scheduler tunable parameters for the guest, as a
561 hash reference. The precise set of keys in the hash are specific to
562 the hypervisor.
563 $dom->set_scheduler_parameters($params, $flags=0)
565 Update the set of scheduler tunable parameters. The value names for
566 tunables vary, and can be discovered using the
567 "get_scheduler_params" call
568 my $params = $dom->get_memory_parameters($flags=0)
570 Return a hash reference containing the set of memory tunable
571 parameters for the guest. The keys in the hash are one of the
572 constants MEMORY PARAMETERS described later. The $flags parameter
573 accepts one or more the CONFIG OPTION constants documented later,
574 and defaults to 0 if omitted.
575 $dom->set_memory_parameters($params, $flags=0)
577 Update the memory tunable parameters for the guest. The $params
578 should be a hash reference whose keys are one of the MEMORY
579 PARAMETERS constants. The $flags parameter accepts one or more the
580 CONFIG OPTION constants documented later, and defaults to 0 if
581 omitted.
582 my $params = $dom->get_blkio_parameters($flags=0)
584 Return a hash reference containing the set of blkio tunable
585 parameters for the guest. The keys in the hash are one of the
586 constants BLKIO PARAMETERS described later. The $flags parameter
587 accepts one or more the CONFIG OPTION constants documented later,
588 and defaults to 0 if omitted.
589 $dom->set_blkio_parameters($params, $flags=0)
591 Update the blkio tunable parameters for the guest. The $params
592 should be a hash reference whose keys are one of the BLKIO
593 PARAMETERS constants. The $flags parameter accepts one or more the
594 CONFIG OPTION constants documented later, and defaults to 0 if
595 omitted.
596 $stats = $dom->get_block_iotune($disk, $flags=0)
598 Return a hash reference containing the set of blkio tunable
599 parameters for the guest disk $disk. The keys in the hash are one
600 of the constants BLOCK IOTUNE PARAMETERS described later.
601 $dom->set_block_iotune($disk, $params, $flags=0);
603 Update the blkio tunable parameters for the guest disk $disk. The
604 $params should be a hash reference whose keys are one of the BLOCK
605 IOTUNE PARAMETERS constants.
606 my $params = $dom->get_interface_parameters($intf, $flags=0)
608 Return a hash reference containing the set of interface tunable
609 parameters for the guest. The keys in the hash are one of the
610 constants INTERFACE PARAMETERS described later.
611 $dom->set_interface_parameters($intf, $params, $flags=0)
613 Update the interface tunable parameters for the guest. The $params
614 should be a hash reference whose keys are one of the INTERFACE
615 PARAMETERS constants.
616 my $params = $dom->get_numa_parameters($flags=0)
618 Return a hash reference containing the set of numa tunable
619 parameters for the guest. The keys in the hash are one of the
620 constants NUMA PARAMETERS described later. The $flags parameter
621 accepts one or more the CONFIG OPTION constants documented later,
622 and defaults to 0 if omitted.
623 $dom->set_numa_parameters($params, $flags=0)
625 Update the numa tunable parameters for the guest. The $params
626 should be a hash reference whose keys are one of the NUMA
627 PARAMETERS constants. The $flags parameter accepts one or more the
628 CONFIG OPTION constants documented later, and defaults to 0 if
629 omitted.
630 my $params = $dom->get_perf_events($flags=0)
632 Return a hash reference containing the set of performance events
633 that are available for the guest. The keys in the hash are one of
634 the constants PERF EVENTS described later. The $flags parameter
635 accepts one or more the CONFIG OPTION constants documented later,
636 and defaults to 0 if omitted.
637 $dom->set_perf_events($params, $flags=0)
639 Update the enabled state for performance events for the guest. The
640 $params should be a hash reference whose keys are one of the PERF
641 EVENTS constants. The $flags parameter accepts one or more the
642 CONFIG OPTION constants documented later, and defaults to 0 if
643 omitted.
644 $dom->block_resize($disk, $newsize, $flags=0)
646 Resize the disk $disk to have new size $newsize KB. If the disk is
647 backed by a special image format, the actual resize is done by the
648 hypervisor. If the disk is backed by a raw file, or block device,
649 the resize must be done prior to invoking this API call, and it
650 merely updates the hypervisor's view of the disk size. The
651 following flags may be used
652 Sys::Virt::Domain::BLOCK_RESIZE_BYTES
654 Treat $newsize as if it were in bytes, rather than KB.
655 $dom->interface_stats($path)
657 Fetch the current I/O statistics for the block device given by
658 $path. The returned hash containins keys for
659 "rx_bytes"
661 Total bytes received
662 "rx_packets"
664 Total packets received
665 "rx_errs"
667 Total packets received with errors
668 "rx_drop"
670 Total packets drop at reception
671 "tx_bytes"
673 Total bytes transmitted
674 "tx_packets"
676 Total packets transmitted
677 "tx_errs"
679 Total packets transmitted with errors
680 "tx_drop"
682 Total packets dropped at transmission.
683 $dom->memory_stats($flags=0)
685 Fetch the current memory statistics for the guest domain. The
686 $flags parameter is currently unused and can be omitted. The
687 returned hash containins keys for
688 "swap_in"
690 Data read from swap space
691 "swap_out"
693 Data written to swap space
694 "major_fault"
696 Page fault involving disk I/O
697 "minor_fault"
699 Page fault not involving disk I/O
700 "unused"
702 Memory not used by the system
703 "available"
705 Total memory seen by guest
706 "rss"
708 Resident set size. Size of memory resident in host RAM.
709 $info = $dom->get_security_label()
711 Fetch information about the security label assigned to the guest
712 domain. The returned hash reference has two keys, "model" gives the
713 name of the security model in effect (eg "selinux"), while "label"
714 provides the name of the security label applied to the domain. This
715 method only returns information about the first security label. To
716 retrieve all labels, use "get_security_label_list".
717 @info = $dom->get_security_label_list()
719 Fetches information about all security labels assigned to the guest
720 domain. The elements in the returned array are all hash references,
721 whose keys are as described for "get_security_label".
722 $ddom = $dom->migrate(destcon, \%params, flags=0)
724 Migrate a domain to an alternative host. The "destcon" parameter
725 should be a "Sys::Virt" connection to the remote target host. The
726 "flags" parameter takes one or more of the
727 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
728 document. The %params parameter is a hash reference used to set
729 various parameters for the migration operation, with the following
730 valid keys.
731 "Sys::Virt::Domain::MIGRATE_PARAM_URI"
733 The URI to use for initializing the domain migration. It takes
734 a hypervisor specific format. The uri_transports element of the
735 hypervisor capabilities XML includes details of the supported
736 URI schemes. When omitted libvirt will auto-generate suitable
737 default URI. It is typically only necessary to specify this URI
738 if the destination host has multiple interfaces and a specific
739 interface is required to transmit migration data.
740 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_NAME"
742 The name to be used for the domain on the destination host.
743 Omitting this parameter keeps the domain name the same. This
744 field is only allowed to be used with hypervisors that support
745 domain renaming during migration.
746 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_XML"
748 The new configuration to be used for the domain on the
749 destination host. The configuration must include an identical
750 set of virtual devices, to ensure a stable guest ABI across
751 migration. Only parameters related to host side configuration
752 can be changed in the XML. Hypervisors which support this field
753 will forbid migration if the provided XML would cause a change
754 in the guest ABI. This field cannot be used to rename the
755 domain during migration (use VIR_MIGRATE_PARAM_DEST_NAME field
756 for that purpose). Domain name in the destination XML must
757 match the original domain name.
758 Omitting this parameter keeps the original domain
760 configuration. Using this field with hypervisors that do not
761 support changing domain configuration during migration will
762 result in a failure.
763 "Sys::Virt::Domain::MIGRATE_PARAM_GRAPHICS_URI"
765 URI to use for migrating client's connection to domain's
766 graphical console as VIR_TYPED_PARAM_STRING. If specified, the
767 client will be asked to automatically reconnect using these
768 parameters instead of the automatically computed ones. This can
769 be useful if, e.g., the client does not have a direct access to
770 the network virtualization hosts are connected to and needs to
771 connect through a proxy. The URI is formed as follows:
772 protocol://hostname[:port]/[?parameters]
774 where protocol is either "spice" or "vnc" and parameters is a
776 list of protocol specific parameters separated by '&'.
777 Currently recognized parameters are "tlsPort" and "tlsSubject".
778 For example,
779 spice://target.host.com:1234/?tlsPort=4567
781 "Sys::Virt::Domain::MIGRATE_PARAM_BANDWIDTH"
783 The maximum bandwidth (in MiB/s) that will be used for
784 migration. If set to 0 or omitted, libvirt will choose a
785 suitable default. Some hypervisors do not support this feature
786 and will return an error if this field is used and is not 0.
787 "Sys::Virt::Domain::MIGRATE_PARAM_BANDWIDTH_POSTCOPY"
789 The maximum bandwidth (in MiB/s) that will be used for
790 migration during post-copy phase. If set to 0 or omitted,
791 libvirt will choose a suitable default. Some hypervisors do not
792 support this feature and return an error if this field is used
793 and is not 0.
794 "Sys::Virt::Domain::MIGRATE_PARAM_LISTEN_ADDRESS"
796 The address on which to listen for incoming migration
797 connections. If omitted, libvirt will listen on the wildcard
798 address (0.0.0.0 or ::). This default may be a security risk if
799 guests, or other untrusted users have the ability to connect to
800 the virtualization host, thus use of an explicit restricted
801 listen address is recommended.
802 "Sys::Virt::Domain::MIGRATE_PARAM_DISK_PORT"
804 Port that destination server should use for incoming disks
805 migration. Type is VIR_TYPED_PARAM_INT. If set to 0 or omitted,
806 libvirt will choose a suitable default. At the moment this is
807 only supported by the QEMU driver.
808 "Sys::Virt::Domain::MIGRATE_PARAM_MIGRATE_DISKS"
810 The list of disks to migrate when doing block storage
811 migration. In contrast to other parameters whose values are
812 plain strings, the parameter value should be an array
813 reference, whose elements are in turn strings representing the
814 disk target names.
815 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION"
817 The type of compression method use use, either "xbzrle" or
818 "mt".
819 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_THREADS"
821 The number of compression threads to use
822 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_DTHREADS"
824 The number of decompression threads
825 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_LEVEL"
827 The compression level from 0 (no compression) to 9 (maximum
828 compression)
829 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_XBZRLE_CACHE"
831 The size of the cache for xbzrle compression
832 "Sys::Virt::Domain::MIGRATE_PARAM_PERSIST_XML"
834 The alternative persistent XML config to copy
835 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INITIAL"
837 The initial percentage to throttle guest vCPUs
838 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INCREMENT"
840 The additional percentage step size to throttle guest vCPUs if
841 progress is not made
842 "Sys::Virt::Domain::MIGRATE_PARAM_PARALLEL_CONNECTIONS"
844 The number of connections used during parallel migration.
845 "Sys::Virt::Domain::MIGRATE_PARAM_TLS_DESTINATION"
847 Override the destination host name used for TLS verification.
848 Normally the TLS certificate from the destination host must
849 match the host's name for TLS verification to succeed. When the
850 certificate does not match the destination hostname and the
851 expected cetificate's hostname is known, this parameter can be
852 used to pass this expected hostname when starting the
853 migration.
854 "Sys::Virt::Domain::MIGRATE_PARAM_DISKS_URI"
856 The URI to use for initializing the domain migration for
857 storage. It takes a hypervisor specific format. The
858 uri_transports element of the hypervisor capabilities XML
859 includes details of the supported URI schemes. When omitted
860 libvirt will auto-generate suitable default URI. It is
861 typically only necessary to specify this URI if the destination
862 host has multiple interfaces and a specific interface is
863 required to transmit storage data.
864 $ddom = $dom->migrate(destcon, flags=0, dname=undef, uri=undef,
866 bandwidth=0)
867 Migrate a domain to an alternative host. Use of positional
868 parameters with "migrate" is deprecated in favour of passing a hash
869 reference as described above.
870 $ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)
872 Migrate a domain to an alternative host. This method is deprecated
873 in favour of passing a hash ref to "migrate".
874 $ddom = $dom->migrate_to_uri(desturi, \%params, flags=0)
876 Migrate a domain to an alternative host. The "desturi" parameter
877 should be a valid libvirt connection URI for the remote target
878 host. The "flags" parameter takes one or more of the
879 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
880 document. The %params parameter is a hash reference used to set
881 various parameters for the migration operation, with the same keys
882 described for the "migrate" API.
883 $dom->migrate_to_uri(desturi, flags, dname, bandwidth)
885 Migrate a domain to an alternative host. Use of positional
886 parameters with "migrate_to_uri" is deprecated in favour of passing
887 a hash reference as described above.
888 $dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)
890 Migrate a domain to an alternative host. This method is deprecated
891 in favour of passing a hash ref to "migrate_to_uri".
892 $dom->migrate_set_max_downtime($downtime, $flags=0)
894 Set the maximum allowed downtime during migration of the guest. A
895 longer downtime makes it more likely that migration will complete,
896 at the cost of longer time blackout for the guest OS at the switch
897 over point. The "downtime" parameter is measured in milliseconds.
898 The $flags parameter is currently unused and defaults to zero.
899 $downtime = $dom->migrate_get_max_downtime($flags=0) Get the current
901 value of the maximum downtime allowed during a migration of a guest.
902 The returned <downtime> value is measured in milliseconds. The $flags
903 parameter is currently unused and defaults to zero.
904 $dom->migrate_set_max_speed($bandwidth, $flags=0)
905 Set the maximum allowed bandwidth during migration of the guest.
906 The "bandwidth" parameter is measured in MB/second. The $flags
907 parameter takes zero or more of the constants:
908 $Sys::Virt::Domain::MIGRATE_MAX_SPEED_POSTCOPY
910 Set the post-copy speed instead of the pre-copy speed.
911 $bandwidth = $dom->migrate_get_max_speed($flags=0)
913 Get the maximum allowed bandwidth during migration fo the guest.
914 The returned <bandwidth> value is measured in MB/second. The
915 $flags parameter is accepts the same constants as
916 "migrate_set_max_speed".
917 $dom->migrate_set_compression_cache($cacheSize, $flags=0)
919 Set the maximum allowed compression cache size during migration of
920 the guest. The "cacheSize" parameter is measured in bytes. The
921 $flags parameter is currently unused and defaults to zero.
922 $cacheSize = $dom->migrate_get_compression_cache($flags=0)
924 Get the maximum allowed compression cache size during migration of
925 the guest. The returned <bandwidth> value is measured in bytes.
926 The $flags parameter is currently unused and defaults to zero.
927 $dom->migrate_start_post_copy($flags=0)
929 Switch the domain from pre-copy to post-copy mode. This requires
930 that the original migrate command had the
931 "Sys::Virt::Domain::MIGRATE_POST_COPY" flag specified.
932 $dom->inject_nmi($flags)
934 Trigger an NMI in the guest virtual machine. The $flags parameter
935 is currently unused and defaults to 0.
936 $dom->open_console($st, $devname, $flags)
938 Open the text console for a serial, parallel or paravirt console
939 device identified by $devname, connecting it to the stream $st. If
940 $devname is undefined, the default console will be opened. $st must
941 be a "Sys::Virt::Stream" object used for bi-directional
942 communication with the console. $flags is currently unused,
943 defaulting to 0.
944 $dom->open_channel($st, $devname, $flags)
946 Open the text console for a data channel device identified by
947 $devname, connecting it to the stream $st. $st must be a
948 "Sys::Virt::Stream" object used for bi-directional communication
949 with the channel. $flags is currently unused, defaulting to 0.
950 $dom->open_graphics($idx, $fd, $flags)
952 Open the graphics console for a guest, identified by $idx, counting
953 from 0. The $fd should be a file descriptor for an anoymous socket
954 pair. The $flags argument should be one of the constants listed at
955 the end of this document, and defaults to 0.
956 $fd = $dom->open_graphics_fd($idx, $flags)
958 Open the graphics console for a guest, identified by $idx, counting
959 from 0. The $flags argument should be one of the constants listed
960 at the end of this document, and defaults to 0. The return value
961 will be a file descriptor connected to the console which must be
962 closed when no longer needed. This method is preferred over
963 "open_graphics" since it will work correctly under sVirt mandatory
964 access control policies.
965 my $mimetype = $dom->screenshot($st, $screen, $flags)
967 Capture a screenshot of the virtual machine's monitor. The $screen
968 parameter controls which monitor is captured when using a multi-
969 head or multi-card configuration. $st must be a "Sys::Virt::Stream"
970 object from which the data can be read. $flags is currently unused
971 and defaults to 0. The mimetype of the screenshot is returned
972 @vcpuinfo = $dom->get_vcpu_info($flags=0)
974 Obtain information about the state of all virtual CPUs in a running
975 guest domain. The returned list will have one element for each
976 vCPU, where each elements contains a hash reference. The keys in
977 the hash are, "number" the vCPU number, "cpu" the physical CPU on
978 which the vCPU is currently scheduled, "cpuTime" the cumulative
979 execution time of the vCPU, "state" the running state and
980 "affinity" giving the allowed shedular placement. The value for
981 "affinity" is a string representing a bitmask against physical
982 CPUs, 8 cpus per character. To extract the bits use the "unpack"
983 function with the "b*" template. NB The "state", "cpuTime", "cpu"
984 values are only available if using $flags value of 0, and the
985 domain is currently running; otherwise they will all be set to
986 zero.
987 $dom->pin_vcpu($vcpu, $mask)
989 Pin the virtual CPU given by index $vcpu to physical CPUs given by
990 $mask. The $mask is a string representing a bitmask against
991 physical CPUs, 8 cpus per character.
992 $mask = $dom->get_emulator_pin_info()
994 Obtain information about the CPU affinity of the emulator process.
995 The returned $mask is a bitstring against physical CPUs, 8 cpus per
996 character. To extract the bits use the "unpack" function with the
997 "b*" template.
998 $dom->pin_emulator($newmask, $flags=0)
1000 Pin the emulator threads to the physical CPUs identified by the
1001 affinity in $newmask. The $newmask is a bitstring against the
1002 physical CPUa, 8 cpus per character. To create a suitable
1003 bitstring, use the "vec" function with a value of 1 for the "BITS"
1004 parameter.
1005 @iothreadinfo = $dom->get_iothread_info($flags=0)
1007 Obtain information about the state of all IOThreads in a running
1008 guest domain. The returned list will have one element for each
1009 IOThread, where each elements contains a hash reference. The keys
1010 in the hash are, "number" the IOThread number and "affinity" giving
1011 the allowed schedular placement. The value for "affinity" is a
1012 string representing a bitmask against physical CPUs, 8 cpus per
1013 character. To extract the bits use the "unpack" function with the
1014 "b*" template.
1015 $dom->pin_iothread($iothread, $mask)
1017 Pin the IOThread given by index $iothread to physical CPUs given by
1018 $mask. The $mask is a string representing a bitmask against
1019 physical CPUs, 8 cpus per character.
1020 $dom->add_iothread($iothread, $flags=0)
1022 Add a new IOThread by the $iothread value to the guest domain. The
1023 $flags parameter accepts one or more the CONFIG OPTION constants
1024 documented later, and defaults to 0 if omitted.
1025 $dom->del_iothread($iothread, $flags=0)
1027 Delete an existing IOThread by the $iothread value from the guest
1028 domain. The $flags parameter accepts one or more the CONFIG OPTION
1029 constants documented later, and defaults to 0 if omitted.
1030 $dom->set_iothread($iothread, $params, $flags=0)
1032 Set parameters for the IOThread by the $iothread value on the guest
1033 domain. The $params parameter is a hash reference whose keys are
1034 the "IOTHREAD STATS" constants documented later. The $flags
1035 parameter accepts one or more the CONFIG OPTION constants
1036 documented later, and defaults to 0 if omitted.
1037 my @stats = $dom->get_cpu_stats($startCpu, $numCpus, $flags=0)
1039 Requests the guests host physical CPU usage statistics, starting
1040 from host CPU <$startCpu> counting up to $numCpus. If $startCpu is
1041 -1 and $numCpus is 1, then the utilization across all CPUs is
1042 returned. Returns an array of hash references, each element
1043 containing stats for one CPU.
1044 my $info = $dom->get_job_info()
1046 Returns a hash reference summarising the execution state of the
1047 background job. The elements of the hash are as follows:
1048 type
1050 The type of job, one of the JOB TYPE constants listed later in
1051 this document.
1052 timeElapsed
1054 The elapsed time in milliseconds
1055 timeRemaining
1057 The expected remaining time in milliseconds. Only set if the
1058 "type" is JOB_UNBOUNDED.
1059 dataTotal
1061 The total amount of data expected to be processed by the job,
1062 in bytes.
1063 dataProcessed
1065 The current amount of data processed by the job, in bytes.
1066 dataRemaining
1068 The expected amount of data remaining to be processed by the
1069 job, in bytes.
1070 memTotal
1072 The total amount of mem expected to be processed by the job, in
1073 bytes.
1074 memProcessed
1076 The current amount of mem processed by the job, in bytes.
1077 memRemaining
1079 The expected amount of mem remaining to be processed by the
1080 job, in bytes.
1081 fileTotal
1083 The total amount of file expected to be processed by the job,
1084 in bytes.
1085 fileProcessed
1087 The current amount of file processed by the job, in bytes.
1088 fileRemaining
1090 The expected amount of file remaining to be processed by the
1091 job, in bytes.
1092 my ($type, $stats) = $dom->get_job_stats($flags=0)
1094 Returns an array summarising the execution state of the background
1095 job. The $type value is one of the JOB TYPE constants listed later
1096 in this document. The $stats value is a hash reference, whose
1097 elements are one of the following constants.
1098 type
1100 The type of job, one of the JOB TYPE constants listed later in
1101 this document.
1102 The $flags parameter defaults to zero and can take one of the
1104 following constants.
1105 Sys::Virt::Domain::JOB_STATS_COMPLETED
1107 Return the stats of the most recently completed job.
1108 Sys::Virt::Domain::JOB_STATS_KEEP_COMPLETED
1110 Don't clear the completed stats after reading them.
1111 Sys::Virt::Domain::JOB_TIME_ELAPSED
1113 The elapsed time in milliseconds
1114 Sys::Virt::Domain::JOB_TIME_ELAPSED_NET
1116 Time in milliseconds since the beginning of the migration job
1117 NOT including the time required to transfer control flow from
1118 the source host to the destination host.
1119 Sys::Virt::Domain::JOB_TIME_REMAINING
1121 The expected remaining time in milliseconds. Only set if the
1122 "type" is JOB_UNBOUNDED.
1123 Sys::Virt::Domain::JOB_DATA_TOTAL
1125 The total amount of data expected to be processed by the job,
1126 in bytes.
1127 Sys::Virt::Domain::JOB_DATA_PROCESSED
1129 The current amount of data processed by the job, in bytes.
1130 Sys::Virt::Domain::JOB_DATA_REMAINING
1132 The expected amount of data remaining to be processed by the
1133 job, in bytes.
1134 Sys::Virt::Domain::JOB_MEMORY_TOTAL
1136 The total amount of mem expected to be processed by the job, in
1137 bytes.
1138 Sys::Virt::Domain::JOB_MEMORY_PROCESSED
1140 The current amount of mem processed by the job, in bytes.
1141 Sys::Virt::Domain::JOB_MEMORY_REMAINING
1143 The expected amount of mem remaining to be processed by the
1144 job, in bytes.
1145 Sys::Virt::Domain::JOB_MEMORY_CONSTANT
1147 The number of pages filled with a constant byte which have been
1148 transferred
1149 Sys::Virt::Domain::JOB_MEMORY_NORMAL
1151 The number of pages transferred without any compression
1152 Sys::Virt::Domain::JOB_MEMORY_NORMAL_BYTES
1154 The number of bytes transferred without any compression
1155 Sys::Virt::Domain::JOB_MEMORY_BPS
1157 The bytes per second transferred
1158 Sys::Virt::Domain::JOB_MEMORY_DIRTY_RATE
1160 The number of memory pages dirtied per second
1161 Sys::Virt::Domain::JOB_MEMORY_PAGE_SIZE
1163 The memory page size in bytes
1164 Sys::Virt::Domain::JOB_MEMORY_ITERATION
1166 The total number of iterations over guest memory
1167 Sys::Virt::Domain::JOB_MEMORY_POSTCOPY_REQS
1169 The number of page requests received from the destination host
1170 during post-copy migration.
1171 Sys::Virt::Domain::JOB_DISK_TOTAL
1173 The total amount of file expected to be processed by the job,
1174 in bytes.
1175 Sys::Virt::Domain::JOB_DISK_PROCESSED
1177 The current amount of file processed by the job, in bytes.
1178 Sys::Virt::Domain::JOB_DISK_REMAINING
1180 The expected amount of file remaining to be processed by the
1181 job, in bytes.
1182 Sys::Virt::Domain::JOB_DISK_BPS
1184 The bytes per second transferred
1185 Sys::Virt::Domain::JOB_AUTO_CONVERGE_THROTTLE
1187 The percentage by which vCPUs are currently throttled
1188 Sys::Virt::Domain::JOB_COMPRESSION_CACHE
1190 The size of the compression cache in bytes
1191 Sys::Virt::Domain::JOB_COMPRESSION_BYTES
1193 The number of compressed bytes transferred
1194 Sys::Virt::Domain::JOB_COMPRESSION_PAGES
1196 The number of compressed pages transferred
1197 Sys::Virt::Domain::JOB_COMPRESSION_CACHE_MISSES
1199 The number of changing pages not in compression cache
1200 Sys::Virt::Domain::JOB_COMPRESSION_OVERFLOW
1202 The number of changing pages in the compression cache but sent
1203 uncompressed since the compressed page was larger than the non-
1204 compressed page.
1205 Sys::Virt::Domain::JOB_DOWNTIME
1207 The number of milliseconds of downtime expected during
1208 migration switchover.
1209 Sys::Virt::Domain::JOB_DOWNTIME_NET
1211 Real measured downtime (ms) NOT including the time required to
1212 transfer control flow from the source host to the destination
1213 host.
1214 Sys::Virt::Domain::JOB_SETUP_TIME
1216 The number of milliseconds of time doing setup of the job
1217 Sys::Virt::Domain::JOB_OPERATION
1219 The type of operation associated with the job
1220 Sys::Virt::Domain::JOB_SUCCESS
1222 Whether the job was successfully completed.
1223 Sys::Virt::Domain::JOB_DISK_TEMP_TOTAL
1225 Possible total temporary disk space for the job in bytes
1226 Sys::Virt::Domain::JOB_DISK_TEMP_USED
1228 Current total temporary disk space for the job in bytes
1229 Sys::Virt::Domain::JOB_ERRMSG
1231 The error message from a failed job
1232 The values for the Sys::Virt::Domain::JOB_OPERATION field are
1234 Sys::Virt::Domain::JOB_OPERATION_UNKNOWN
1236 No known job type
1237 Sys::Virt::Domain::JOB_OPERATION_START
1239 The guest is starting
1240 Sys::Virt::Domain::JOB_OPERATION_SAVE
1242 The guest is saving to disk
1243 Sys::Virt::Domain::JOB_OPERATION_RESTORE
1245 The guest is restoring from disk
1246 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_IN
1248 The guest is migrating in from another host
1249 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_OUT
1251 The guest is migrating out to another host
1252 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT
1254 The guest is saving a snapshot
1255 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT_REVERT
1257 The guest is reverting to a snapshot
1258 Sys::Virt::Domain::JOB_OPERATION_DUMP
1260 The guest is saving a crash dump
1261 Sys::Virt::Domain::JOB_OPERATION_BACKUP
1263 The guest is performing a block backup
1264 $dom->abort_job($flags=0)
1266 Aborts the currently executing job. Valid $flags incude:
1267 Sys::Virt::Domain::DOMAIN_ABORT_JOB_POSTCOPY
1269 Interrupt post-copy migration. It can later be resumed using
1270 migrate APIs with "MIGRATE_POSTCOPY_RESUME" flag.
1271 my $info = $dom->get_block_job_info($path, $flags=0)
1273 Returns a hash reference summarising the execution state of the
1274 block job. The $path parameter should be the fully qualified path
1275 of the block device being changed. Valid $flags include:
1276 Sys::Virt::Domain::BLOCK_JOB_INFO_BANDWIDTH_BYTES
1278 Treat bandwidth value as bytes instead of MiB.
1279 $dom->set_block_job_speed($path, $bandwidth, $flags=0)
1281 Change the maximum I/O bandwidth used by the block job that is
1282 currently executing for $path. The $bandwidth argument is specified
1283 in MB/s. The $flags parameter can take the bitwise union of the
1284 values:
1285 Sys::Virt::Domain::BLOCK_JOB_SPEED_BANDWIDTH_BYTES
1287 The $bandwidth parameter value is measured in bytes/s instead
1288 of MB/s.
1289 $dom->abort_block_job($path, $flags=0)
1291 Abort the current job that is executing for the block device
1292 associated with $path
1293 $dom->block_pull($path, $bandwidth, $flags=0)
1295 Merge the backing files associated with $path into the top level
1296 file. The $bandwidth parameter specifies the maximum I/O rate to
1297 allow in MB/s. The $flags parameter can take the bitwise union of
1298 the values:
1299 Sys::Virt::Domain::BLOCK_PULL_BANDWIDTH_BYTES
1301 The $bandwidth parameter value is measured in bytes/s instead
1302 of MB/s.
1303 $dom->block_rebase($path, $base, $bandwidth, $flags=0)
1305 Switch the backing path associated with $path to instead use $base.
1306 The $bandwidth parameter specifies the maximum I/O rate to allow in
1307 MB/s. The $flags parameter can take the bitwise union of the
1308 values:
1309 Sys::Virt::Domain::BLOCK_REBASE_BANDWIDTH_BYTES
1311 The $bandwidth parameter value is measured in bytes/s instead
1312 of MB/s.
1313 $dom->block_copy($path, $destxml, $params, $flags=0)
1315 Copy contents of a disk image <$path> into the target volume
1316 described by $destxml which follows the schema of the <disk>
1317 element in the domain XML. The $params parameter is a hash of
1318 optional parameters to control the process
1319 Sys::Virt::Domain::BLOCK_COPY_BANDWIDTH
1321 The maximum bandwidth in bytes per second.
1322 Sys::Virt::Domain::BLOCK_COPY_GRANULARITY
1324 The granularity in bytes of the copy process
1325 Sys::Virt::Domain::BLOCK_COPY_BUF_SIZE
1327 The maximum amount of data in flight in bytes.
1328 $dom->block_commit($path, $base, $top, $bandwidth, $flags=0)
1330 Commit changes there were made to the temporary top level file
1331 $top. Takes all the differences between $top and $base and merge
1332 them into $base. The $bandwidth parameter specifies the maximum I/O
1333 rate to allow in MB/s. The $flags parameter can take the bitwise
1334 union of the values:
1335 Sys::Virt::Domain::BLOCK_COMMIT_BANDWIDTH_BYTES
1337 The $bandwidth parameter value is measured in bytes instead of
1338 MB/s.
1339 $count = $dom->num_of_snapshots()
1341 Return the number of saved snapshots of the domain
1342 @names = $dom->list_snapshot_names()
1344 List the names of all saved snapshots. The names can be used with
1345 the "lookup_snapshot_by_name"
1346 @snapshots = $dom->list_snapshots()
1348 Return a list of all snapshots currently known to the domain. The
1349 elements in the returned list are instances of the
1350 Sys::Virt::DomainSnapshot class. This method requires O(n) RPC
1351 calls, so the "list_all_snapshots" method is recommended as a more
1352 efficient alternative.
1353 my @snapshots = $dom->list_all_snapshots($flags)
1355 Return a list of all domain snapshots associated with this domain.
1356 The elements in the returned list are instances of the
1357 Sys::Virt::DomainSnapshot class. The $flags parameter can be used
1358 to filter the list of return domain snapshots.
1359 my $snapshot = $dom->get_snapshot_by_name($name)
1361 Return the domain snapshot with a name of $name. The returned
1362 object is an instance of the Sys::Virt::DomainSnapshot class.
1363 $dom->has_current_snapshot()
1365 Returns a true value if the domain has a currently active snapshot
1366 $snapshot = $dom->current_snapshot()
1368 Returns the currently active snapshot for the domain.
1369 $snapshot = $dom->create_snapshot($xml[, $flags])
1371 Create a new snapshot from the $xml. The $flags parameter accepts
1372 the SNAPSHOT CREATION constants listed in
1373 "Sys::Virt::DomainSnapshots".
1374 my @checkpoints = $dom->list_all_checkpoints($flags)
1376 Return a list of all domain checkpoints associated with this
1377 domain. The elements in the returned list are instances of the
1378 Sys::Virt::DomainCheckpoint class. The $flags parameter can be used
1379 to filter the list of return domain checkpoints.
1380 my $checkpoint = $dom->get_checkpoint_by_name($name)
1382 Return the domain checkpoint with a name of $name. The returned
1383 object is an instance of the Sys::Virt::DomainCheckpoint class.
1384 $checkpoint = $dom->create_checkpoint($xml[, $flags])
1386 Create a new checkpoint from the $xml. The $flags parameter accepts
1387 the CHECKPOINT CREATION constants listed in
1388 "Sys::Virt::DomainCheckpoints".
1389 $dom->backup_begin($backupxml, $checkpointxml=undef, $flags=0);
1391 Start a point-in-time backup job for the specified disks of a
1392 running domain. The $backupxml parameter describes the backup
1393 operation, including which disks to use. The optional
1394 $checkpointxml parameter can be used to create a checkpoint
1395 covering to the same point in time as the backup. The optional
1396 $flags parameter can be one of the following constants:
1397 Sys::Virt::Domain::BACKUP_BEGIN_REUSE_EXTERNAL
1399 Assume that the output/temporary files for the backup have been
1400 precreated by the caller with the correct size and format.
1401 $xml = $dom->backup_get_xml_description($flags=0);
1403 Get the XML description of the currently executing backup job. If
1404 there is no backup job then an error is raised.
1405 $dom->fs_trim($mountPoint, $minimum, $flags=0);
1407 Issue an FS_TRIM command to the device at $mountPoint to remove
1408 chunks of unused space that are at least $minimum bytes in length.
1409 $flags is currently unused and defaults to zero.
1410 $dom->fs_freeze(\@mountPoints, $flags=0);
1412 Freeze all the filesystems associated with the @mountPoints array
1413 reference. If <@mountPoints> is an empty list, then all filesystems
1414 will be frozen. $flags is currently unused and defaults to zero.
1415 $dom->fs_thaw(\@mountPoints, $flags=0);
1417 Thaw all the filesystems associated with the @mountPoints array
1418 reference. If <@mountPoints> is an empty list, then all filesystems
1419 will be thawed. $flags is currently unused and defaults to zero.
1420 @fslist = $dom->get_fs_info($flags=0);
1422 Obtain a list of all guest filesystems. The returned list will
1423 contain one element for each filesystem, whose value will be a hash
1424 reference with the following keys
1425 name
1427 The name of the guest device that is mounted
1428 fstype
1430 The filesystem type (eg 'ext4', 'fat', 'ntfs', etc)
1431 mountpoint
1433 The location in the filesystem tree of the mount
1434 devalias
1436 An array reference containing list of device aliases associated
1437 with the guest device. The device aliases correspond to disk
1438 target names in the guest XML configuration
1439 @nics = $dom->get_interface_addresses($src, $flags=0);
1441 Obtain a list of all guest network interfaces. The $src parameter
1442 is one of the constants
1443 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_LEASE
1445 Extract the DHCP server lease information
1446 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_AGENT
1448 Query the guest OS via an agent
1449 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_ARP
1451 Extract from the local ARP tables
1452 The returned list will contain one element for each interface. The
1454 values in the list will be a hash reference with the following keys
1455 name
1457 The name of the guest interface that is mounted
1458 hwaddr
1460 The hardware address, aka MAC, if available.
1461 addrs
1463 An array reference containing list of IP addresses associated
1464 with the guest NIC. Each element in the array is a further hash
1465 containing
1466 addr
1468 The IP address string
1469 prefix
1471 The IP address network prefix
1472 type
1474 The IP address type (IPv4 vs IPv6)
1475 $dom->send_process_signal($pid, $signum, $flags=0);
1477 Send the process $pid the signal $signum. The $signum value must be
1478 one of the constants listed later, not a POSIX or Linux signal
1479 value. $flags is currently unused and defaults to zero.
1480 $dom->set_block_threshold($dev, $threshold, $flags=0);
1482 Set the threshold level for delivering the EVENT_ID_BLOCK_THRESHOLD
1483 if the device or backing chain element described by $dev is written
1484 beyond the set $threshold level. The threshold level is unset once
1485 the event fires. The event might not be delivered at all if
1486 libvirtd was not running at the moment when the threshold was
1487 reached.
1488 $dom->set_lifecycle_action($type, $action, $flags=0)
1490 Changes the actions of lifecycle events for domain represented as
1491 <on_$type>$action</on_$type> in the domain XML.
1492 $info = $dom->get_launch_security_info($flags=0)
1494 Get information about the domain launch security policy. $flags is
1495 currently unused and defaults to zero. The returned hash may
1496 contain the following keys
1497 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_MEASUREMENT
1499 The AMD SEV launch measurement
1500 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_API_MAJOR
1502 The host SEV API major version
1503 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_API_MINOR
1505 The host SEV API minor version
1506 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_BUILD_ID
1508 The host SEV firmware build ID
1509 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_POLICY
1511 The guest SEV policy
1512 $dom->set_launch_security_state(\%params, $flags=0)
1514 Set information about the domain launch security state. $flags is
1515 currently unused and defaults to zero. The provided hash may
1516 contain the following keys
1517 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET
1519 The SEV secret string to inject
1520 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET_HEADER
1522 The SEV secret header string to inject
1523 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET_SET_ADDRESS
1525 The address at which to inject the SEV secret. If omitted it
1526 can be automatically determined from the firmware
1527 $info = $dom->get_guest_info($types, $flags=0)
1529 Get information about the domain guest configuration. The $types
1530 parameter determines what pieces of information are returned and
1531 should be the bitwise or of the following constants:
1532 Sys::Virt::Domain::GUEST_INFO_USERS
1534 Active user information
1535 Sys::Virt::Domain::GUEST_INFO_OS
1537 Misc operating system information
1538 Sys::Virt::Domain::GUEST_INFO_TIMEZONE
1540 The guest timezone
1541 Sys::Virt::Domain::GUEST_INFO_HOSTNAME
1543 The guest hostname
1544 Sys::Virt::Domain::GUEST_INFO_FILESYSTEM
1546 Filesystem mount information
1547 Sys::Virt::Domain::GUEST_INFO_DISKS
1549 Block device information
1550 Sys::Virt::Domain::GUEST_INFO_INTERFACES
1552 Network interfaces information
1553 $flags is currently unused and defaults to zero.
1555 $dom->set_agent_response_timeout($timeout, $flags=0)
1557 Set the amount of time to wait for the agent to respond to a
1558 command. $timeout is a positive integer representing the number of
1559 seconds to wait, or one of the constants:
1560 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_BLOCK
1562 Wait forever with no timeout
1563 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_NOWAIT
1565 Don't want at all, return immediately
1566 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_DEFAULT
1568 Use the hypervisor driver's default timeout
1569 The $flags parameter is currently unused and defaults to zero.
1571 my @keys = $dom->authorized_ssh_keys_get($user, $flags=0)
1573 Retrieve the list of authorized SSH keys for the user account
1574 $user. The $flags parameter is currently unused and defaults to
1575 zero.
1576 $dom->authorized_ssh_keys_set($user, \@keys, $flags=0)
1578 Update the list of authorized SSH keys for the user account $user.
1579 The @keys parameter should be an array reference containing the new
1580 keys, if any. The default behaviour is to set the authorized SSH
1581 keys to the exact set specified in @keys. This can be modified via
1582 the $flags parameter which takes the following constants
1583 Sys::Virt::Domain::AUTHORIZED_SSH_KEYS_SET_APPEND
1585 Append @keys to the current set of keys, rather than replacing
1586 the existing keys.
1587 Sys::Virt::Domain::AUTHORIZED_SSH_KEYS_SET_REMOVE
1589 Remove @keys from the current set of keys, rather than
1590 replacing the existing keys. It is not an error if the keys do
1591 not exist.
1592 my @msgs = $dom->get_messages($flags=0)
1594 Retrieve a list of messages associated with the domain. The
1595 optional $flags parameter can accept zero or more of
1596 Sys::Virt::Domain::MESSAGE_DEPRECATION
1598 Warnings about use of deprecated features
1599 Sys::Virt::Domain::MESSAGE_TAINTING
1601 Warnings about actions that have tainting the domain
1602 $dom->start_dirty_rate_calc($dom, $secs, $flags=0)
1604 Request calculation of the domain's memory dirty rate over the next
1605 $secs seconds. $flags accepts one or more of
1606 Sys::Virt::Domain::DIRTYRATE_MODE_PAGE_SAMPLING
1608 Page sampling mode
1609 Sys::Virt::Domain::DIRTYRATE_MODE_DIRTY_BITMAP
1611 Dirty bitmap mode
1612 Sys::Virt::Domain::DIRTYRATE_MODE_DIRTY_RING
1614 Dirty ring mode
1615
1617 A number of the APIs take a "flags" parameter. In most cases passing a
1618 value of zero will be satisfactory. Some APIs, however, accept named
1619 constants to alter their behaviour. This section documents the current
1620 known constants.
1621 DOMAIN STATE
1623 The domain state constants are useful in interpreting the "state" key
1624 in the hash returned by the "get_info" method.
1625 Sys::Virt::Domain::STATE_NOSTATE
1627 The domain is active, but is not running / blocked (eg idle)
1628 Sys::Virt::Domain::STATE_RUNNING
1630 The domain is active and running
1631 Sys::Virt::Domain::STATE_BLOCKED
1633 The domain is active, but execution is blocked
1634 Sys::Virt::Domain::STATE_PAUSED
1636 The domain is active, but execution has been paused
1637 Sys::Virt::Domain::STATE_SHUTDOWN
1639 The domain is active, but in the shutdown phase
1640 Sys::Virt::Domain::STATE_SHUTOFF
1642 The domain is inactive, and shut down.
1643 Sys::Virt::Domain::STATE_CRASHED
1645 The domain is inactive, and crashed.
1646 Sys::Virt::Domain::STATE_PMSUSPENDED
1648 The domain is active, but in power management suspend state
1649 CONTROL INFO
1651 The following constants can be used to determine what the guest domain
1652 control channel status is
1653 Sys::Virt::Domain::CONTROL_ERROR
1655 The control channel has a fatal error
1656 Sys::Virt::Domain::CONTROL_OK
1658 The control channel is ready for jobs
1659 Sys::Virt::Domain::CONTROL_OCCUPIED
1661 The control channel is busy
1662 Sys::Virt::Domain::CONTROL_JOB
1664 The control channel is busy with a job
1665 If the status is "Sys::Virt::Domain::CONTROL_ERROR", then one of the
1667 following constants describes the reason
1668 Sys::Virt::Domain::CONTROL_ERROR_REASON_NONE
1670 There is no reason for the error available
1671 Sys::Virt::Domain::CONTROL_ERROR_REASON_UNKNOWN
1673 The reason for the error is unknown
1674 Sys::Virt::Domain::CONTROL_ERROR_REASON_INTERNAL
1676 There was an internal error in libvirt
1677 Sys::Virt::Domain::CONTROL_ERROR_REASON_MONITOR
1679 There was an error speaking to the monitor
1680 DOMAIN CREATION
1682 The following constants can be used to control the behaviour of domain
1683 creation
1684 Sys::Virt::Domain::START_PAUSED
1686 Keep the guest vCPUs paused after starting the guest
1687 Sys::Virt::Domain::START_AUTODESTROY
1689 Automatically destroy the guest when the connection is closed (or
1690 fails)
1691 Sys::Virt::Domain::START_BYPASS_CACHE
1693 Do not use OS I/O cache if starting a domain with a saved state
1694 image
1695 Sys::Virt::Domain::START_FORCE_BOOT
1697 Boot the guest, even if there was a saved snapshot
1698 Sys::Virt::Domain::START_VALIDATE
1700 Validate the XML document against the XML schema
1701 Sys::Virt::Domain::START_RESET_NVRAM
1703 Reset the firmware NVRAM state from its original template
1704 DOMAIN DEFINE
1706 The following constants can be used to control the behaviour of domain
1707 define operations
1708 Sys::Virt::Domain::DEFINE_VALIDATE
1710 Validate the XML document against the XML schema
1711 KEYCODE SETS
1713 The following constants define the set of supported keycode sets
1714 Sys::Virt::Domain::KEYCODE_SET_LINUX
1716 The Linux event subsystem keycodes
1717 Sys::Virt::Domain::KEYCODE_SET_XT
1719 The original XT keycodes
1720 Sys::Virt::Domain::KEYCODE_SET_ATSET1
1722 The AT Set1 keycodes (aka XT)
1723 Sys::Virt::Domain::KEYCODE_SET_ATSET2
1725 The AT Set2 keycodes (aka AT)
1726 Sys::Virt::Domain::KEYCODE_SET_ATSET3
1728 The AT Set3 keycodes (aka PS2)
1729 Sys::Virt::Domain::KEYCODE_SET_OSX
1731 The OS-X keycodes
1732 Sys::Virt::Domain::KEYCODE_SET_XT_KBD
1734 The XT keycodes from the Linux Keyboard driver
1735 Sys::Virt::Domain::KEYCODE_SET_USB
1737 The USB HID keycode set
1738 Sys::Virt::Domain::KEYCODE_SET_WIN32
1740 The Windows keycode set
1741 Sys::Virt::Domain::KEYCODE_SET_QNUM
1743 The XT keycode set, with the extended scancodes using the high bit
1744 of the first byte, instead of the low bit of the second byte.
1745 Sys::Virt::Domain::KEYCODE_SET_RFB
1747 A deprecated alias for "Sys::Virt::Domain::KEYCODE_SET_QNUM"
1748 MEMORY PEEK
1750 The following constants can be used with the "memory_peek" method's
1751 flags parameter
1752 Sys::Virt::Domain::MEMORY_VIRTUAL
1754 Indicates that the offset is using virtual memory addressing.
1755 Sys::Virt::Domain::MEMORY_PHYSICAL
1757 Indicates that the offset is using physical memory addressing.
1758 VCPU STATE
1760 The following constants are useful when interpreting the virtual CPU
1761 run state
1762 Sys::Virt::Domain::VCPU_OFFLINE
1764 The virtual CPU is not online
1765 Sys::Virt::Domain::VCPU_RUNNING
1767 The virtual CPU is executing code
1768 Sys::Virt::Domain::VCPU_BLOCKED
1770 The virtual CPU is waiting to be scheduled
1771 VCPU HOST PLACEMENT STATE
1773 The following constants are useful when interpreting the virtual CPU
1774 host placement
1775 Sys::Virt::Domain::VCPU_INFO_CPU_OFFLINE
1777 The virtual CPU is not online
1778 Sys::Virt::Domain::VCPU_INFO_CPU_UNAVAILABLE
1780 The virtual CPU placement is not available from this hypervisor
1781 OPEN GRAPHICS CONSTANTS
1783 The following constants are used when opening a connection to the guest
1784 graphics server
1785 Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH
1787 Skip authentication of the client
1788 OPEN CONSOLE CONSTANTS
1790 The following constants are used when opening a connection to the guest
1791 console
1792 Sys::Virt::Domain::OPEN_CONSOLE_FORCE
1794 Force opening of the console, disconnecting any other open session
1795 Sys::Virt::Domain::OPEN_CONSOLE_SAFE
1797 Check if the console driver supports safe operations
1798 OPEN CHANNEL CONSTANTS
1800 The following constants are used when opening a connection to the guest
1801 channel
1802 Sys::Virt::Domain::OPEN_CHANNEL_FORCE
1804 Force opening of the channel, disconnecting any other open session
1805 XML DUMP OPTIONS
1807 The following constants are used to control the information included in
1808 the XML configuration dump
1809 Sys::Virt::Domain::XML_INACTIVE
1811 Report the persistent inactive configuration for the guest, even if
1812 it is currently running.
1813 Sys::Virt::Domain::XML_SECURE
1815 Include security sensitive information in the XML dump, such as
1816 passwords.
1817 Sys::Virt::Domain::XML_UPDATE_CPU
1819 Update the CPU model definition to match the current executing
1820 state.
1821 Sys::Virt::Domain::XML_MIGRATABLE
1823 Update the XML to allow migration to older versions of libvirt
1824 DEVICE HOTPLUG OPTIONS
1826 The following constants are used to control device hotplug operations
1827 Sys::Virt::Domain::DEVICE_MODIFY_CURRENT
1829 Modify the domain in its current state
1830 Sys::Virt::Domain::DEVICE_MODIFY_LIVE
1832 Modify only the live state of the domain
1833 Sys::Virt::Domain::DEVICE_MODIFY_CONFIG
1835 Modify only the persistent config of the domain
1836 Sys::Virt::Domain::DEVICE_MODIFY_FORCE
1838 Force the device to be modified
1839 MEMORY OPTIONS
1841 The following constants are used to control memory change operations
1842 Sys::Virt::Domain::MEM_CURRENT
1844 Modify the current state
1845 Sys::Virt::Domain::MEM_LIVE
1847 Modify only the live state of the domain
1848 Sys::Virt::Domain::MEM_CONFIG
1850 Modify only the persistent config of the domain
1851 Sys::Virt::Domain::MEM_MAXIMUM
1853 Modify the maximum memory value
1854 CONFIG OPTIONS
1856 The following constants are used to control what configuration a domain
1857 update changes
1858 Sys::Virt::Domain::AFFECT_CURRENT
1860 Modify the current state
1861 Sys::Virt::Domain::AFFECT_LIVE
1863 Modify only the live state of the domain
1864 Sys::Virt::Domain::AFFECT_CONFIG
1866 Modify only the persistent config of the domain
1867 MIGRATE OPTIONS
1869 The following constants are used to control how migration is performed
1870 Sys::Virt::Domain::MIGRATE_LIVE
1872 Migrate the guest without interrupting its execution on the source
1873 host.
1874 Sys::Virt::Domain::MIGRATE_PEER2PEER
1876 Manage the migration process over a direct peer-2-peer connection
1877 between the source and destination host libvirtd daemons.
1878 Sys::Virt::Domain::MIGRATE_TUNNELLED
1880 Tunnel the migration data over the libvirt daemon connection,
1881 rather than the native hypervisor data transport. Requires
1882 PEER2PEER flag to be set.
1883 Sys::Virt::Domain::MIGRATE_PERSIST_DEST
1885 Make the domain persistent on the destination host, defining its
1886 configuration file upon completion of migration.
1887 Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE
1889 Remove the domain's persistent configuration after migration
1890 completes successfully.
1891 Sys::Virt::Domain::MIGRATE_PAUSED
1893 Do not re-start execution of the guest CPUs on the destination host
1894 after migration completes.
1895 Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK
1897 Copy the complete contents of the disk images during migration
1898 Sys::Virt::Domain::MIGRATE_NON_SHARED_INC
1900 Copy the incrementally changed contents of the disk images during
1901 migration
1902 Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION
1904 Do not allow changes to the virtual domain configuration while
1905 migration is taking place. This option is automatically implied if
1906 doing a peer-2-peer migration.
1907 Sys::Virt::Domain::MIGRATE_UNSAFE
1909 Migrate even if the compatibility check indicates the migration
1910 will be unsafe to the guest.
1911 Sys::Virt::Domain::MIGRATE_OFFLINE
1913 Migrate the guest config if the guest is not currently running
1914 Sys::Virt::Domain::MIGRATE_COMPRESSED
1916 Enable compression of the migration data stream
1917 Sys::Virt::Domain::MIGRATE_ABORT_ON_ERROR
1919 Abort if an I/O error occurrs on the disk
1920 Sys::Virt::Domain::MIGRATE_AUTO_CONVERGE
1922 Force convergance of the migration operation by throttling guest
1923 runtime
1924 Sys::Virt::Domain::MIGRATE_RDMA_PIN_ALL
1926 Pin memory for RDMA transfer
1927 Sys::Virt::Domain::MIGRATE_POSTCOPY
1929 Enable support for post-copy migration
1930 Sys::Virt::Domain::MIGRATE_TLS
1932 Setting this flag will cause the migration to attempt to use the
1933 TLS environment configured by the hypervisor in order to perform
1934 the migration. If incorrectly configured on either source or
1935 destination, the migration will fail.
1936 Sys::Virt::Domain::MIGRATE_PARALLEL
1938 Send memory pages to the destination host through several network
1939 connections. See "Sys::Virt::Domain::MIGRATE_PARAM_PARALLEL_*"
1940 parameters for configuring the parallel migration.
1941 Sys::Virt::Domain::MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES
1943 Force the guest writes which happen when copying disk images for
1944 non-shared storage migration to be synchronously written to the
1945 destination. This ensures the storage migration converges for VMs
1946 doing heavy I/O on fast local storage and slow mirror.
1947 Sys::Virt::Domain::MIGRATE_POSTCOPY_RESUME
1949 Resume migration which failed in post-copy phase.
1950 Sys::Virt::Domain::MIGRATE_ZEROCOPY
1952 Attempt to avoid copying data. This is a request, not a guarantee
1953 and may apply to either one or both directions of data transfer at
1954 discretion of the hypervisor implementation.
1955 UNDEFINE CONSTANTS
1957 The following constants can be used when undefining virtual domain
1958 configurations
1959 Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE
1961 Also remove any managed save image when undefining the virtual
1962 domain
1963 Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA
1965 Also remove any snapshot metadata when undefining the virtual
1966 domain.
1967 Sys::Virt::Domain::UNDEFINE_NVRAM
1969 Also remove any NVRAM state file when undefining the virtual
1970 domain.
1971 Sys::Virt::Domain::UNDEFINE_KEEP_NVRAM
1973 keep NVRAM state file when undefining the virtual domain.
1974 Sys::Virt::Domain::UNDEFINE_CHECKPOINTS_METADATA
1976 Also remove any checkpoint metadata when undefining the virtual
1977 domain.
1978 JOB TYPES
1980 The following constants describe the different background job types.
1981 Sys::Virt::Domain::JOB_NONE
1983 No job is active
1984 Sys::Virt::Domain::JOB_BOUNDED
1986 A job with a finite completion time is active
1987 Sys::Virt::Domain::JOB_UNBOUNDED
1989 A job with an unbounded completion time is active
1990 Sys::Virt::Domain::JOB_COMPLETED
1992 The job has finished, but isn't cleaned up
1993 Sys::Virt::Domain::JOB_FAILED
1995 The job has hit an error, but isn't cleaned up
1996 Sys::Virt::Domain::JOB_CANCELLED
1998 The job was aborted at user request, but isn't cleaned up
1999 MEMORY PARAMETERS
2001 The following constants are useful when getting/setting memory
2002 parameters for guests
2003 Sys::Virt::Domain::MEMORY_HARD_LIMIT
2005 The maximum memory the guest can use.
2006 Sys::Virt::Domain::MEMORY_SOFT_LIMIT
2008 The memory upper limit enforced during memory contention.
2009 Sys::Virt::Domain::MEMORY_MIN_GUARANTEE
2011 The minimum memory guaranteed to be reserved for the guest.
2012 Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT
2014 The maximum swap the guest can use.
2015 Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED
2017 The value of an unlimited memory parameter
2018 BLKIO PARAMETERS
2020 The following parameters control I/O tuning for the domain as a whole
2021 Sys::Virt::Domain::BLKIO_WEIGHT
2023 The I/O weight parameter
2024 Sys::Virt::Domain::BLKIO_DEVICE_WEIGHT
2026 The per-device I/O weight parameter
2027 Sys::Virt::Domain::BLKIO_DEVICE_READ_BPS
2029 The per-device I/O bytes read per second
2030 Sys::Virt::Domain::BLKIO_DEVICE_READ_IOPS
2032 The per-device I/O operations read per second
2033 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_BPS
2035 The per-device I/O bytes write per second
2036 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_IOPS
2038 The per-device I/O operations write per second
2039 BLKIO TUNING PARAMETERS
2041 The following parameters control I/O tuning for an individual guest
2042 disk.
2043 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC
2045 The total bytes processed per second.
2046 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC
2048 The bytes read per second.
2049 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC
2051 The bytes written per second.
2052 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC
2054 The total I/O operations processed per second.
2055 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC
2057 The I/O operations read per second.
2058 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC
2060 The I/O operations written per second.
2061 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX
2063 The maximum total bytes processed per second.
2064 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX
2066 The maximum bytes read per second.
2067 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX
2069 The maximum bytes written per second.
2070 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX
2072 The maximum total I/O operations processed per second.
2073 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX
2075 The maximum I/O operations read per second.
2076 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX
2078 The maximum I/O operations written per second.
2079 Sys::Virt::Domain::BLOCK_IOTUNE_SIZE_IOPS_SEC
2081 The maximum I/O operations per second
2082 Sys::Virt::Domain::BLOCK_IOTUNE_GROUP_NAME
2084 A string representing a group name to allow sharing of I/O
2085 throttling quota between multiple drives
2086 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX_LENGTH
2088 The duration in seconds allowed for maximum total bytes processed
2089 per second.
2090 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX_LENGTH
2092 The duration in seconds allowed for maximum bytes read per second.
2093 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX_LENGTH
2095 The duration in seconds allowed for maximum bytes written per
2096 second.
2097 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX_LENGTH
2099 The duration in seconds allowed for maximum total I/O operations
2100 processed per second.
2101 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX_LENGTH
2103 The duration in seconds allowed for maximum I/O operations read per
2104 second.
2105 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX_LENGTH
2107 The duration in seconds allowed for maximum I/O operations written
2108 per second.
2109 SCHEDULER CONSTANTS
2111 Sys::Virt::Domain::SCHEDULER_CAP
2112 The VM cap tunable
2113 Sys::Virt::Domain::SCHEDULER_CPU_SHARES
2115 The CPU shares tunable
2116 Sys::Virt::Domain::SCHEDULER_LIMIT
2118 The VM limit tunable
2119 Sys::Virt::Domain::SCHEDULER_RESERVATION
2121 The VM reservation tunable
2122 Sys::Virt::Domain::SCHEDULER_SHARES
2124 The VM shares tunable
2125 Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD
2127 The VCPU period tunable
2128 Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA
2130 The VCPU quota tunable
2131 Sys::Virt::Domain::SCHEDULER_GLOBAL_PERIOD
2133 The VM global period tunable
2134 Sys::Virt::Domain::SCHEDULER_GLOBAL_QUOTA
2136 The VM global quota tunable
2137 Sys::Virt::Domain::SCHEDULER_WEIGHT
2139 The VM weight tunable
2140 NUMA PARAMETERS
2142 The following constants are useful when getting/setting the guest NUMA
2143 memory policy
2144 Sys::Virt::Domain::NUMA_MODE
2146 The NUMA policy mode
2147 Sys::Virt::Domain::NUMA_NODESET
2149 The NUMA nodeset mask
2150 The following constants are useful when interpreting the
2152 "Sys::Virt::Domain::NUMA_MODE" parameter value
2153 Sys::Virt::Domain::NUMATUNE_MEM_STRICT
2155 Allocation is mandatory from the mask nodes
2156 Sys::Virt::Domain::NUMATUNE_MEM_PREFERRED
2158 Allocation is preferred from the masked nodes
2159 Sys::Virt::Domain::NUMATUNE_MEM_INTERLEAVE
2161 Allocation is interleaved across all masked nodes
2162 Sys::Virt::Domain::NUMATUNE_MEM_RESTRICTIVE
2164 Allocation is determined by the host using the masked nodes.
2165 INTERFACE PARAMETERS
2167 The following constants are useful when getting/setting the per network
2168 interface tunable parameters
2169 Sys::Virt::Domain::BANDWIDTH_IN_AVERAGE
2171 The average inbound bandwidth
2172 Sys::Virt::Domain::BANDWIDTH_IN_PEAK
2174 The peak inbound bandwidth
2175 Sys::Virt::Domain::BANDWIDTH_IN_BURST
2177 The burstable inbound bandwidth
2178 Sys::Virt::Domain::BANDWIDTH_IN_FLOOR
2180 The minimum inbound bandwidth
2181 Sys::Virt::Domain::BANDWIDTH_OUT_AVERAGE
2183 The average outbound bandwidth
2184 Sys::Virt::Domain::BANDWIDTH_OUT_PEAK
2186 The peak outbound bandwidth
2187 Sys::Virt::Domain::BANDWIDTH_OUT_BURST
2189 The burstable outbound bandwidth
2190 PERF EVENTS
2192 The following constants defined performance events which can be
2193 monitored for a guest
2194 Sys::Virt::Domain::PERF_PARAM_CMT
2196 The CMT event counter which can be used to measure the usage of
2197 cache (bytes) by applications running on the platform. It
2198 corresponds to the "perf.cmt" field in the *Stats APIs.
2199 Sys::Virt::Domain::PERF_PARAM_MBML
2201 The MBML event counter which can be used to monitor the amount of
2202 data (bytes/s) sent through the memory controller on the socket.
2203 It corresponds to the "perf.mbml" field in the *Stats APIs.
2204 Sys::Virt::Domain::PERF_PARAM_MBMT
2206 The MBMT event counter which can be used to monitor total system
2207 bandwidth (bytes/s) from one level of cache to another. It
2208 corresponds to the "perf.mbmt" field in the *Stats APIs.
2209 Sys::Virt::Domain::PERF_PARAM_CACHE_MISSES
2211 The cache_misses perf event counter which can be used to measure
2212 the count of cache misses by applications running on the platform.
2213 It corresponds to the "perf.cache_misses" field in the *Stats APIs.
2214 Sys::Virt::Domain::PERF_PARAM_CACHE_REFERENCES
2216 The cache_references perf event counter which can be used to
2217 measure the count of cache hits by applications running on the
2218 platform. It corresponds to the "perf.cache_references" field in
2219 the *Stats APIs.
2220 Sys::Virt::Domain::PERF_PARAM_CPU_CYCLES
2222 The cpu_cycles perf event counter which can be used to measure how
2223 many cpu cycles one instruction needs. It corresponds to the
2224 "perf.cpu_cycles" field in the *Stats APIs.
2225 Sys::Virt::Domain::PERF_PARAM_INSTRUCTIONS
2227 The instructions perf event counter which can be used to measure
2228 the count of instructions by applications running on the platform.
2229 It corresponds to the "perf.instructions" field in the *Stats APIs.
2230 Sys::Virt::Domain::PERF_PARAM_BRANCH_INSTRUCTIONS
2232 The branch_instructions perf event counter which can be used to
2233 measure the count of instructions by applications running on the
2234 platform. It corresponds to the "perf.branch_instructions" field in
2235 the *Stats APIs.
2236 Sys::Virt::Domain::PERF_PARAM_BRANCH_MISSES
2238 The branch_misses perf event which can be used to measure the count
2239 of branch misses by applications running on the platform. It
2240 corresponds to the "perf.branch_misses" field in the *Stats APIs.
2241 Sys::Virt::Domain::PERF_PARAM_BUS_CYCLES The bus_cycles perf event
2243 counter which can be used to measure the count of bus cycles by
2244 applications running on the platform. It corresponds to the
2245 "perf.bus_cycles" field in the *Stats APIs.
2246 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_FRONTEND The
2247 stalled_cycles_frontend perf event counter which can be used to measure
2248 the count of stalled cpu cycles in the frontend of the instruction
2249 processor pipeline by applications running on the platform. It
2250 corresponds to the "perf.stalled_cycles_frontend" field in the *Stats
2251 APIs.
2252 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_BACKEND The
2253 stalled_cycles_backend perf event counter which can be used to measure
2254 the count of stalled cpu cycles in the backend of the instruction
2255 processor pipeline by application running on the platform. It
2256 corresponds to the "perf.stalled_cycles_backend" field in the *Stats
2257 APIs.
2258 Sys::Virt::Domain::PERF_PARAM_REF_CPU_CYCLES The ref_cpu_cycles perf
2259 event counter which can be used to measure the count of total cpu
2260 cycles not affected by CPU frequency scaling by applications running on
2261 the platform. It corresponds to the "perf.ref_cpu_cycles" field in the
2262 *Stats APIs.
2263 Sys::Virt::Domain::PERF_PARAM_CPU_CLOCK The cpu_clock perf event
2264 counter which can be used to measure the count of cpu clock time by
2265 applications running on the platform. It corresponds to the
2266 "perf.cpu_clock" field in the *Stats APIs.
2267 Sys::Virt::Domain::PERF_PARAM_TASK_CLOCK The task_clock perf event
2268 counter which can be used to measure the count of task clock time by
2269 applications running on the platform. It corresponds to the
2270 "perf.task_clock" field in the *Stats APIs.
2271 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS The page_faults perf event
2272 counter which can be used to measure the count of page faults by
2273 applications running on the platform. It corresponds to the
2274 "perf.page_faults" field in the *Stats APIs.
2275 Sys::Virt::Domain::PERF_PARAM_CONTEXT_SWITCHES The context_switches
2276 perf event counter which can be used to measure the count of context
2277 switches by applications running on the platform. It corresponds to the
2278 "perf.context_switches" field in the *Stats APIs.
2279 Sys::Virt::Domain::PERF_PARAM_CPU_MIGRATIONS The cpu_migrations perf
2280 event counter which can be used to measure the count of cpu migrations
2281 by applications running on the platform. It corresponds to the
2282 "perf.cpu_migrations" field in the *Stats APIs.
2283 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MIN The page_faults_min perf
2284 event counter which can be used to measure the count of minor page
2285 faults by applications running on the platform. It corresponds to the
2286 "perf.page_faults_min" field in the *Stats APIs.
2287 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MAJ The page_faults_maj perf
2288 event counter which can be used to measure the count of major page
2289 faults by applications running on the platform. It corresponds to the
2290 "perf.page_faults_maj" field in the *Stats APIs.
2291 Sys::Virt::Domain::PERF_PARAM_ALIGNMENT_FAULTS The alignment_faults
2292 perf event counter which can be used to measure the count of alignment
2293 faults by applications running on the platform. It corresponds to the
2294 "perf.alignment_faults" field in the *Stats APIs.
2295 Sys::Virt::Domain::PERF_PARAM_EMULATION_FAULTS The emulation_faults
2296 perf event counter which can be used to measure the count of emulation
2297 faults by applications running on the platform. It corresponds to the
2298 "perf.emulation_faults" field in the *Stats APIs.
2299 IOTHREAD STATS
2301 The following constants defined IOThread statistics which can be
2302 monitored for a guest
2303 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_MAX_NS
2305 The maximum polling time that can be used by polling algorithm in
2306 ns. The polling time starts at 0 (zero) and is the time spent by
2307 the guest to process IOThread data before returning the CPU to the
2308 host. The polling time will be dynamically modified over time based
2309 on the poll_grow and poll_shrink parameters provided.
2310 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_GROW
2312 This provides a value for the dynamic polling adjustment algorithm
2313 to use to grow its polling interval up to the poll_max_ns value.
2314 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_SHRINK
2316 This provides a value for the dynamic polling adjustment algorithm
2317 to use to shrink its polling interval when the polling interval
2318 exceeds the poll_max_ns value.
2319 Sys::Virt::Domain::IOTHREAD_PARAM_THREAD_POOL_MIN
2321 Sets the lower bound for thread pool size. A value of -1 disables
2322 this bound leaving hypervisor use its default value, though this
2323 value is not accepted for running domains. Due to internal
2324 implementation it's recommended to set lower and upper bounds
2325 separately.
2326 Sys::Virt::Domain::IOTHREAD_PARAM_THREAD_POOL_MAX
2328 Sets the upper bound for thread pool size. A value of -1 disables
2329 this bound leaving hypervisor use its default value, though this
2330 value is not accepted for running domains. Since the upper band has
2331 to be equal to or greater than lower bound value of 0 is not
2332 accepted. Due to internal implementation it's recommended to set
2333 lower and upper bounds separately.
2334 VCPU FLAGS
2336 The following constants are useful when getting/setting the VCPU count
2337 for a guest
2338 Sys::Virt::Domain::VCPU_LIVE
2340 Flag to request the live value
2341 Sys::Virt::Domain::VCPU_CONFIG
2343 Flag to request the persistent config value
2344 Sys::Virt::Domain::VCPU_CURRENT
2346 Flag to request the current config value
2347 Sys::Virt::Domain::VCPU_MAXIMUM
2349 Flag to request adjustment of the maximum vCPU value
2350 Sys::Virt::Domain::VCPU_GUEST
2352 Flag to request the guest VCPU mask
2353 Sys::Virt::Domain::VCPU_HOTPLUGGABLE
2355 Flag to make vcpus added hot(un)pluggable
2356 STATE CHANGE EVENTS
2358 The following constants allow domain state change events to be
2359 interpreted. The events contain both a state change, and a reason.
2360 Sys::Virt::Domain::EVENT_DEFINED
2362 Indicates that a persistent configuration has been defined for the
2363 domain.
2364 Sys::Virt::Domain::EVENT_DEFINED_ADDED
2366 The defined configuration is newly added
2367 Sys::Virt::Domain::EVENT_DEFINED_UPDATED
2369 The defined configuration is an update to an existing
2370 configuration
2371 Sys::Virt::Domain::EVENT_DEFINED_RENAMED
2373 The defined configuration is a rename of an existing
2374 configuration
2375 Sys::Virt::Domain::EVENT_DEFINED_FROM_SNAPSHOT
2377 The defined configuration was restored from a snapshot
2378 Sys::Virt::Domain::EVENT_RESUMED
2380 The domain has resumed execution
2381 Sys::Virt::Domain::EVENT_RESUMED_MIGRATED
2383 The domain resumed because migration has completed. This is
2384 emitted on the destination host.
2385 Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED
2387 The domain resumed because the admin unpaused it.
2388 Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT
2390 The domain resumed because it was restored from a snapshot
2391 Sys::Virt::Domain::EVENT_RESUMED_POSTCOPY
2393 The domain resumed but post-copy is running in background
2394 Sys::Virt::Domain::EVENT_RESUMED_POSTCOPY_FAILED
2396 The domain is running, but migration failed in post-copy.
2397 Sys::Virt::Domain::EVENT_STARTED
2399 The domain has started running
2400 Sys::Virt::Domain::EVENT_STARTED_BOOTED
2402 The domain was booted from shutoff state
2403 Sys::Virt::Domain::EVENT_STARTED_MIGRATED
2405 The domain started due to an incoming migration
2406 Sys::Virt::Domain::EVENT_STARTED_RESTORED
2408 The domain was restored from saved state file
2409 Sys::Virt::Domain::EVENT_STARTED_FROM_SNAPSHOT
2411 The domain was restored from a snapshot
2412 Sys::Virt::Domain::EVENT_STARTED_WAKEUP
2414 The domain was woken up from suspend
2415 Sys::Virt::Domain::EVENT_STOPPED
2417 The domain has stopped running
2418 Sys::Virt::Domain::EVENT_STOPPED_CRASHED
2420 The domain stopped because guest operating system has crashed
2421 Sys::Virt::Domain::EVENT_STOPPED_DESTROYED
2423 The domain stopped because administrator issued a destroy
2424 command.
2425 Sys::Virt::Domain::EVENT_STOPPED_FAILED
2427 The domain stopped because of a fault in the host
2428 virtualization environment.
2429 Sys::Virt::Domain::EVENT_STOPPED_MIGRATED
2431 The domain stopped because it was migrated to another machine.
2432 Sys::Virt::Domain::EVENT_STOPPED_SAVED
2434 The domain was saved to a state file
2435 Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN
2437 The domain stopped due to graceful shutdown of the guest.
2438 Sys::Virt::Domain::EVENT_STOPPED_FROM_SNAPSHOT
2440 The domain was stopped due to a snapshot
2441 Sys::Virt::Domain::EVENT_SHUTDOWN
2443 The domain has shutdown but is not yet stopped
2444 Sys::Virt::Domain::EVENT_SHUTDOWN_FINISHED
2446 The domain finished shutting down
2447 Sys::Virt::Domain::EVENT_SHUTDOWN_HOST
2449 The domain shutdown due to host trigger
2450 Sys::Virt::Domain::EVENT_SHUTDOWN_GUEST
2452 The domain shutdown due to guest trigger
2453 Sys::Virt::Domain::EVENT_SUSPENDED
2455 The domain has stopped executing, but still exists
2456 Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED
2458 The domain has been suspended due to offline migration
2459 Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED
2461 The domain has been suspended due to administrator pause
2462 request.
2463 Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR
2465 The domain has been suspended due to a block device I/O error.
2466 Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT
2468 The domain has been suspended due to resume from snapshot
2469 Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG
2471 The domain has been suspended due to the watchdog triggering
2472 Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED
2474 The domain has been suspended due to restore from saved state
2475 Sys::Virt::Domain::EVENT_SUSPENDED_API_ERROR
2477 The domain has been suspended due to an API error
2478 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY
2480 The domain has been suspended for post-copy migration
2481 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY_FAILED
2483 The domain has been suspended due post-copy migration failing
2484 Sys::Virt::Domain::EVENT_UNDEFINED
2486 The persistent configuration has gone away
2487 Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED
2489 The domain configuration has gone away due to it being removed
2490 by administrator.
2491 Sys::Virt::Domain::EVENT_UNDEFINED_RENAMED
2493 The undefined configuration is a rename of an existing
2494 configuration
2495 Sys::Virt::Domain::EVENT_PMSUSPENDED
2497 The domain has stopped running
2498 Sys::Virt::Domain::EVENT_PMSUSPENDED_MEMORY
2500 The domain has suspend to RAM.
2501 Sys::Virt::Domain::EVENT_PMSUSPENDED_DISK
2503 The domain has suspend to Disk.
2504 Sys::Virt::Domain::EVENT_CRASHED
2506 The domain has crashed
2507 Sys::Virt::Domain::EVENT_CRASHED_PANICKED
2509 The domain has crashed due to a kernel panic
2510 Sys::Virt::Domain::EVENT_CRASHED_CRASHLOADED
2512 The domain has crashed and reloaded itself
2513 EVENT ID CONSTANTS
2515 Sys::Virt::Domain::EVENT_ID_LIFECYCLE
2516 Domain lifecycle events
2517 Sys::Virt::Domain::EVENT_ID_REBOOT
2519 Soft / warm reboot events
2520 Sys::Virt::Domain::EVENT_ID_RTC_CHANGE
2522 RTC clock adjustments
2523 Sys::Virt::Domain::EVENT_ID_IO_ERROR
2525 File IO errors, typically from disks
2526 Sys::Virt::Domain::EVENT_ID_WATCHDOG
2528 Watchdog device triggering
2529 Sys::Virt::Domain::EVENT_ID_GRAPHICS
2531 Graphics client connections.
2532 Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON
2534 File IO errors, typically from disks, with a root cause
2535 Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR
2537 Errors from the virtualization control channel
2538 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB
2540 Completion status of asynchronous block jobs, identified by source
2541 file name.
2542 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB_2
2544 Completion status of asynchronous block jobs, identified by target
2545 device name.
2546 Sys::Virt::Domain::EVENT_ID_DISK_CHANGE
2548 Changes in disk media
2549 Sys::Virt::Domain::EVENT_ID_TRAY_CHANGE
2551 CDROM media tray state
2552 Sys::Virt::Domain::EVENT_ID_PMSUSPEND
2554 Power management initiated suspend to RAM
2555 Sys::Virt::Domain::EVENT_ID_PMSUSPEND_DISK
2557 Power management initiated suspend to Disk
2558 Sys::Virt::Domain::EVENT_ID_PMWAKEUP
2560 Power management initiated wakeup
2561 Sys::Virt::Domain::EVENT_ID_BALLOON_CHANGE
2563 Balloon target changes
2564 Sys::Virt::Domain::EVENT_ID_DEVICE_ADDED
2566 Asynchronous guest device addition
2567 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVED
2569 Asynchronous guest device removal
2570 Sys::Virt::Domain::EVENT_ID_TUNABLE
2572 Changes of any domain tuning parameters. The callback will be
2573 provided with a hash listing all changed parameters. The later
2574 DOMAIN TUNABLE constants can be useful when accessing the hash keys
2575 Sys::Virt::Domain::EVENT_ID_AGENT_LIFECYCLE
2577 Domain guest agent lifecycle events. The "state" parameter to the
2578 callback will match one of the constants
2579 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_CONNECTED
2581 The agent is now connected
2582 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_DISCONNECTED
2584 The agent is now disconnected
2585 The second parameter, "reason", matches one of the following
2587 constants
2588 Sys::Virt::Domain::EVENT_ID_MIGRATION_ITERATION
2590 Domain migration progress iteration. The "iteration" parameter to
2591 the callback will specify the number of iterations migration has
2592 made over guest RAM.
2593 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_UNKNOWN
2595 The reason is unknown
2596 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_DOMAIN_STARTED
2598 The domain was initially booted
2599 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_CHANNEL
2601 The channel on a running guest changed state
2602 Sys::Virt::Domain::EVENT_ID_JOB_COMPLETED
2604 Domain background job completion notification. The callback
2605 provides a hash containing the job stats. The keyus in the hash are
2606 the same as those used with the
2607 "Sys::Virt::Domain::get_job_stats()" method.
2608 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVAL_FAILED
2610 Guest device removal has failed.
2611 Sys::Virt::Domain::EVENT_ID_METADATA_CHANGE
2613 The domain metadata has changed
2614 Sys::Virt::Domain::EVENT_ID_BLOCK_THRESHOLD
2616 The event occurs when the hypervisor detects that the given storage
2617 element was written beyond the point specified by threshold. The
2618 event is useful for thin-provisioned storage.
2619 Sys::Virt::Domain::EVENT_ID_MEMORY_FAILURE
2621 The event occurs when the hypervisor detects hardware memory
2622 corruption.
2623 Sys::Virt::Domain::EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE
2625 The event occurs when the guest accepts a request to change the
2626 memory device size.
2627 IO ERROR EVENT CONSTANTS
2629 These constants describe what action was taken due to the IO error.
2630 Sys::Virt::Domain::EVENT_IO_ERROR_NONE
2632 No action was taken, the error was ignored & reported as success to
2633 guest
2634 Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE
2636 The guest is paused since the error occurred
2637 Sys::Virt::Domain::EVENT_IO_ERROR_REPORT
2639 The error has been reported to the guest OS
2640 WATCHDOG EVENT CONSTANTS
2642 These constants describe what action was taken due to the watchdog
2643 firing
2644 Sys::Virt::Domain::EVENT_WATCHDOG_NONE
2646 No action was taken, the watchdog was ignored
2647 Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE
2649 The guest is paused since the watchdog fired
2650 Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF
2652 The guest is powered off after the watchdog fired
2653 Sys::Virt::Domain::EVENT_WATCHDOG_RESET
2655 The guest is reset after the watchdog fired
2656 Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN
2658 The guest attempted to gracefully shutdown after the watchdog fired
2659 Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG
2661 No action was taken, the watchdog was logged
2662 Sys::Virt::Domain::EVENT_WATCHDOG_INJECTNMI
2664 An NMI was injected into the guest after the watchdog fired
2665 GRAPHICS EVENT PHASE CONSTANTS
2667 These constants describe the phase of the graphics connection
2668 Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT
2670 The initial client connection
2671 Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE
2673 The client has been authenticated & the connection is running
2674 Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT
2676 The client has disconnected
2677 GRAPHICS EVENT ADDRESS CONSTANTS
2679 These constants describe the format of the address
2680 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4
2682 An IPv4 address
2683 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6
2685 An IPv6 address
2686 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX
2688 An UNIX socket path address
2689 DISK CHANGE EVENT CONSTANTS
2691 These constants describe the reason for a disk change event
2692 Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START
2694 The disk media was cleared, as its source was missing when
2695 attempting to start the guest
2696 Sys::Virt::Domain::EVENT_DISK_DROP_MISSING_ON_START
2698 The disk device was dropped, as its source was missing when
2699 attempting to start the guest
2700 TRAY CHANGE CONSTANTS
2702 These constants describe the reason for a tray change event
2703 Sys::Virt::Domain::EVENT_TRAY_CHANGE_CLOSE
2705 The tray was closed
2706 Sys::Virt::Domain::EVENT_TRAY_CHANGE_OPEN
2708 The tray was opened
2709 DOMAIN BLOCK JOB TYPE CONSTANTS
2711 The following constants identify the different types of domain block
2712 jobs
2713 Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN
2715 An unknown block job type
2716 Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL
2718 The block pull job type
2719 Sys::Virt::Domain::BLOCK_JOB_TYPE_COPY
2721 The block copy job type
2722 Sys::Virt::Domain::BLOCK_JOB_TYPE_COMMIT
2724 The block commit job type
2725 Sys::Virt::Domain::BLOCK_JOB_TYPE_ACTIVE_COMMIT
2727 The block active commit job type
2728 Sys::Virt::Domain::BLOCK_JOB_TYPE_BACKUP
2730 The block backup job type
2731 DOMAIN BLOCK JOB COMPLETION CONSTANTS
2733 The following constants can be used to determine the completion status
2734 of a block job
2735 Sys::Virt::Domain::BLOCK_JOB_COMPLETED
2737 A successfully completed block job
2738 Sys::Virt::Domain::BLOCK_JOB_FAILED
2740 An unsuccessful block job
2741 Sys::Virt::Domain::BLOCK_JOB_CANCELED
2743 A block job canceled byy the user
2744 Sys::Virt::Domain::BLOCK_JOB_READY
2746 A block job is running
2747 DOMAIN BLOCK REBASE CONSTANTS
2749 The following constants are useful when rebasing block devices
2750 Sys::Virt::Domain::BLOCK_REBASE_SHALLOW
2752 Limit copy to top of source backing chain
2753 Sys::Virt::Domain::BLOCK_REBASE_REUSE_EXT
2755 Reuse existing external file for copy
2756 Sys::Virt::Domain::BLOCK_REBASE_COPY_RAW
2758 Make destination file raw
2759 Sys::Virt::Domain::BLOCK_REBASE_COPY
2761 Start a copy job
2762 Sys::Virt::Domain::BLOCK_REBASE_COPY_DEV
2764 Treat destination as a block device instead of file
2765 Sys::Virt::Domain::BLOCK_REBASE_RELATIVE
2767 Keep backing chain referenced using relative names
2768 DOMAIN BLOCK COPY CONSTANTS
2770 The following constants are useful when copying block devices
2771 Sys::Virt::Domain::BLOCK_COPY_SHALLOW
2773 Limit copy to top of source backing chain
2774 Sys::Virt::Domain::BLOCK_COPY_REUSE_EXT
2776 Reuse existing external file for copy
2777 Sys::Virt::Domain::BLOCK_COPY_TRANSIENT_JOB
2779 Don't force usage of recoverable job for the copy operation
2780 Sys::Virt::Domain::BLOCK_COPY_SYNCHRONOUS_WRITES
2782 Force the copy job to synchronously propagate guest writes into the
2783 destination image, so that the copy is guaranteed to converge
2784 DOMAIN BLOCK JOB ABORT CONSTANTS
2786 The following constants are useful when aborting job copy jobs
2787 Sys::Virt::Domain::BLOCK_JOB_ABORT_ASYNC
2789 Request only, do not wait for completion
2790 Sys::Virt::Domain::BLOCK_JOB_ABORT_PIVOT
2792 Pivot to mirror when ending a copy job
2793 DOMAIN BLOCK COMMIT JOB CONSTANTS
2795 The following constants are useful with block commit job types
2796 Sys::Virt::Domain::BLOCK_COMMIT_DELETE
2798 Delete any files that are invalid after commit
2799 Sys::Virt::Domain::BLOCK_COMMIT_SHALLOW
2801 NULL base means next backing file, not whole chain
2802 Sys::Virt::Domain::BLOCK_COMMIT_ACTIVE
2804 Allow two phase commit when top is active layer
2805 Sys::Virt::Domain::BLOCK_COMMIT_RELATIVE
2807 Keep backing chain referenced using relative names
2808 DOMAIN SAVE / RESTORE FLAG CONSTANTS
2810 The following constants can be used when saving or restoring virtual
2811 machines
2812 Sys::Virt::Domain::SAVE_BYPASS_CACHE
2814 Do not use OS I/O cache when saving state.
2815 Sys::Virt::Domain::SAVE_PAUSED
2817 Mark the saved state as paused to prevent the guest CPUs starting
2818 upon restore.
2819 Sys::Virt::Domain::SAVE_RUNNING
2821 Mark the saved state as running to allow the guest CPUs to start
2822 upon restore.
2823 Sys::Virt::Domain::SAVE_RESET_NVRAM
2825 Reset the firmware NVRAM state from its original template
2826 SAVE / RESTORE PARAMETER CONSTANTS
2828 Sys::Virt::Domain::SAVE_PARAM_FILE
2829 Specify the save state file to save to or restore from.
2830 Sys::Virt::Domain::SAVE_PARAM_DXML
2832 Used to adjust guest xml on restore, e.g. to alter a device while
2833 domain is stopped.
2834 DOMAIN CORE DUMP CONSTANTS
2836 The following constants can be used when triggering domain core dumps
2837 Sys::Virt::Domain::DUMP_LIVE
2839 Do not pause execution while dumping the guest
2840 Sys::Virt::Domain::DUMP_CRASH
2842 Crash the guest after completing the core dump
2843 Sys::Virt::Domain::DUMP_BYPASS_CACHE
2845 Do not use OS I/O cache when writing core dump
2846 Sys::Virt::Domain::DUMP_RESET
2848 Reset the virtual machine after finishing the dump
2849 Sys::Virt::Domain::DUMP_MEMORY_ONLY
2851 Only include guest RAM in the dump, not the device state
2852 DESTROY CONSTANTS
2854 The following constants are useful when terminating guests using the
2855 "destroy" API.
2856 Sys::Virt::Domain::DESTROY_DEFAULT
2858 Destroy the guest using the default approach
2859 Sys::Virt::Domain::DESTROY_GRACEFUL
2861 Destroy the guest in a graceful manner
2862 Sys::Virt::Domain::DESTROY_REMOVE_LOGS
2864 Delete log files associated with the guest
2865 SHUTDOWN CONSTANTS
2867 The following constants are useful when requesting that a guest
2868 terminate using the "shutdown" API
2869 Sys::Virt::Domain::SHUTDOWN_DEFAULT
2871 Shutdown using the hypervisor's default mechanism
2872 Sys::Virt::Domain::SHUTDOWN_GUEST_AGENT
2874 Shutdown by issuing a command to a guest agent
2875 Sys::Virt::Domain::SHUTDOWN_ACPI_POWER_BTN
2877 Shutdown by injecting an ACPI power button press
2878 Sys::Virt::Domain::SHUTDOWN_INITCTL
2880 Shutdown by talking to initctl (containers only)
2881 Sys::Virt::Domain::SHUTDOWN_SIGNAL
2883 Shutdown by sending SIGTERM to the init process
2884 Sys::Virt::Domain::SHUTDOWN_PARAVIRT
2886 Shutdown by issuing a paravirt power control command
2887 REBOOT CONSTANTS
2889 The following constants are useful when requesting that a guest
2890 terminate using the "reboot" API
2891 Sys::Virt::Domain::REBOOT_DEFAULT
2893 Reboot using the hypervisor's default mechanism
2894 Sys::Virt::Domain::REBOOT_GUEST_AGENT
2896 Reboot by issuing a command to a guest agent
2897 Sys::Virt::Domain::REBOOT_ACPI_POWER_BTN
2899 Reboot by injecting an ACPI power button press
2900 Sys::Virt::Domain::REBOOT_INITCTL
2902 Reboot by talking to initctl (containers only)
2903 Sys::Virt::Domain::REBOOT_SIGNAL
2905 Reboot by sending SIGHUP to the init process
2906 Sys::Virt::Domain::REBOOT_PARAVIRT
2908 Reboot by issuing a paravirt power control command
2909 METADATA CONSTANTS
2911 The following constants are useful when reading/writing metadata about
2912 a guest
2913 Sys::Virt::Domain::METADATA_TITLE
2915 The short human friendly title of the guest
2916 Sys::Virt::Domain::METADATA_DESCRIPTION
2918 The long free text description of the guest
2919 Sys::Virt::Domain::METADATA_ELEMENT
2921 The structured metadata elements for the guest
2922 DISK ERROR CONSTANTS
2924 The following constants are useful when interpreting disk error codes
2925 Sys::Virt::Domain::DISK_ERROR_NONE
2927 No error
2928 Sys::Virt::Domain::DISK_ERROR_NO_SPACE
2930 The host storage has run out of free space
2931 Sys::Virt::Domain::DISK_ERROR_UNSPEC
2933 An unspecified error has occurred.
2934 MEMORY STATISTIC CONSTANTS
2936 Sys::Virt::Domain::MEMORY_STAT_SWAP_IN
2937 Swap in
2938 Sys::Virt::Domain::MEMORY_STAT_SWAP_OUT
2940 Swap out
2941 Sys::Virt::Domain::MEMORY_STAT_MINOR_FAULT
2943 Minor faults
2944 Sys::Virt::Domain::MEMORY_STAT_MAJOR_FAULT
2946 Major faults
2947 Sys::Virt::Domain::MEMORY_STAT_RSS
2949 Resident memory
2950 Sys::Virt::Domain::MEMORY_STAT_UNUSED
2952 Unused memory
2953 Sys::Virt::Domain::MEMORY_STAT_AVAILABLE
2955 Available memory
2956 Sys::Virt::Domain::MEMORY_STAT_ACTUAL_BALLOON
2958 Actual balloon limit
2959 Sys::Virt::Domain::MEMORY_STAT_USABLE
2961 Amount of usable memory
2962 Sys::Virt::Domain::MEMORY_STAT_LAST_UPDATE
2964 Time of last stats refresh from guest
2965 Sys::Virt::Domain::MEMORY_STAT_DISK_CACHES
2967 Disk cache size
2968 Sys::Virt::Domain::MEMORY_STAT_HUGETLB_PGALLOC
2970 The amount of successful huge page allocations
2971 Sys::Virt::Domain::MEMORY_STAT_HUGETLB_PGFAIL
2973 The amount of failed huge page allocations
2974 DOMAIN LIST CONSTANTS
2976 The following constants can be used when listing domains
2977 Sys::Virt::Domain::LIST_ACTIVE
2979 Only list domains that are currently active (running, or paused)
2980 Sys::Virt::Domain::LIST_AUTOSTART
2982 Only list domains that are set to automatically start on boot
2983 Sys::Virt::Domain::LIST_HAS_SNAPSHOT
2985 Only list domains that have a stored snapshot
2986 Sys::Virt::Domain::LIST_INACTIVE
2988 Only list domains that are currently inactive (shutoff, saved)
2989 Sys::Virt::Domain::LIST_MANAGEDSAVE
2991 Only list domains that have current managed save state
2992 Sys::Virt::Domain::LIST_NO_AUTOSTART
2994 Only list domains that are not set to automatically start on boto
2995 Sys::Virt::Domain::LIST_NO_MANAGEDSAVE
2997 Only list domains that do not have any managed save state
2998 Sys::Virt::Domain::LIST_NO_SNAPSHOT
3000 Only list domains that do not have a stored snapshot
3001 Sys::Virt::Domain::LIST_OTHER
3003 Only list domains that are not running, paused or shutoff
3004 Sys::Virt::Domain::LIST_PAUSED
3006 Only list domains that are paused
3007 Sys::Virt::Domain::LIST_PERSISTENT
3009 Only list domains which have a persistent config
3010 Sys::Virt::Domain::LIST_RUNNING
3012 Only list domains that are currently running
3013 Sys::Virt::Domain::LIST_SHUTOFF
3015 Only list domains that are currently shutoff
3016 Sys::Virt::Domain::LIST_TRANSIENT
3018 Only list domains that do not have a persistent config
3019 Sys::Virt::Domain::LIST_HAS_CHECKPOINT
3021 Only list domains that have a stored checkpoint
3022 Sys::Virt::Domain::LIST_NO_CHECKPOINT
3024 Only list domains that do not have a stored checkpoint
3025 SEND KEY CONSTANTS
3027 The following constants are to be used with the "send_key" API
3028 Sys::Virt::Domain::SEND_KEY_MAX_KEYS
3030 The maximum number of keys that can be sent in a single call to
3031 "send_key"
3032 BLOCK STATS CONSTANTS
3034 The following constants provide the names of well known block stats
3035 fields
3036 Sys::Virt::Domain::BLOCK_STATS_ERRS
3038 The number of I/O errors
3039 Sys::Virt::Domain::BLOCK_STATS_FLUSH_REQ
3041 The number of flush requests
3042 Sys::Virt::Domain::BLOCK_STATS_FLUSH_TOTAL_TIMES
3044 The time spent processing flush requests
3045 Sys::Virt::Domain::BLOCK_STATS_READ_BYTES
3047 The amount of data read
3048 Sys::Virt::Domain::BLOCK_STATS_READ_REQ
3050 The number of read requests
3051 Sys::Virt::Domain::BLOCK_STATS_READ_TOTAL_TIMES
3053 The time spent processing read requests
3054 Sys::Virt::Domain::BLOCK_STATS_WRITE_BYTES
3056 The amount of data written
3057 Sys::Virt::Domain::BLOCK_STATS_WRITE_REQ
3059 The number of write requests
3060 Sys::Virt::Domain::BLOCK_STATS_WRITE_TOTAL_TIMES
3062 The time spent processing write requests
3063 CPU STATS CONSTANTS
3065 The following constants provide the names of well known cpu stats
3066 fields
3067 Sys::Virt::Domain::CPU_STATS_CPUTIME
3069 The total CPU time, including both hypervisor and vCPU time.
3070 Sys::Virt::Domain::CPU_STATS_USERTIME
3072 THe total time in kernel
3073 Sys::Virt::Domain::CPU_STATS_SYSTEMTIME
3075 The total time in userspace
3076 Sys::Virt::Domain::CPU_STATS_VCPUTIME
3078 The total vCPU time.
3079 CPU STATS CONSTANTS
3081 The following constants provide the names of well known schedular
3082 parameters
3083 Sys::Virt::SCHEDULER_EMULATOR_PERIOD
3085 The duration of the time period for scheduling the emulator
3086 Sys::Virt::SCHEDULER_EMULATOR_QUOTA
3088 The quota for the emulator in one schedular time period
3089 Sys::Virt::SCHEDULER_IOTHREAD_PERIOD
3091 The duration of the time period for scheduling the iothread
3092 Sys::Virt::SCHEDULER_IOTHREAD_QUOTA
3094 The quota for the iothread in one schedular time period
3095 DOMAIN STATS FLAG CONSTANTS
3097 The following constants are used as flags when requesting bulk domain
3098 stats from "Sys::Virt::get_all_domain_stats".
3099 Sys::Virt::Domain::GET_ALL_STATS_ACTIVE
3101 Include stats for active domains
3102 Sys::Virt::Domain::GET_ALL_STATS_INACTIVE
3104 Include stats for inactive domains
3105 Sys::Virt::Domain::GET_ALL_STATS_OTHER
3107 Include stats for other domains
3108 Sys::Virt::Domain::GET_ALL_STATS_PAUSED
3110 Include stats for paused domains
3111 Sys::Virt::Domain::GET_ALL_STATS_PERSISTENT
3113 Include stats for persistent domains
3114 Sys::Virt::Domain::GET_ALL_STATS_RUNNING
3116 Include stats for running domains
3117 Sys::Virt::Domain::GET_ALL_STATS_SHUTOFF
3119 Include stats for shutoff domains
3120 Sys::Virt::Domain::GET_ALL_STATS_TRANSIENT
3122 Include stats for transient domains
3123 Sys::Virt::Domain::GET_ALL_STATS_ENFORCE_STATS
3125 Require that all requested stats fields are returned
3126 Sys::Virt::Domain::GET_ALL_STATS_BACKING
3128 Get stats for image backing files too
3129 Sys::Virt::Domain::GET_ALL_STATS_NOWAIT
3131 Skip stats if they can't be acquired without waiting
3132 DOMAIN STATS FIELD CONSTANTS
3134 The following constants are used to control which fields are returned
3135 for stats queries.
3136 Sys::Virt::Domain::STATS_BALLOON
3138 Balloon statistics
3139 Sys::Virt::Domain::STATS_BLOCK
3141 Block device info
3142 Sys::Virt::Domain::STATS_CPU_TOTAL
3144 CPU usage info
3145 Sys::Virt::Domain::STATS_INTERFACE
3147 Network interface info
3148 Sys::Virt::Domain::STATS_STATE
3150 General lifecycle state
3151 Sys::Virt::Domain::STATS_VCPU
3153 Virtual CPU info
3154 Sys::Virt::Domain::STATS_PERF
3156 Performance event counter values
3157 Sys::Virt::Domain::STATS_IOTHREAD
3159 IOThread performance statistics values
3160 Sys::Virt::Domain::STATS_MEMORY
3162 Memory bandwidth statistics values
3163 Sys::Virt::Domain::STATS_DIRTYRATE
3165 Memory dirty rate statistics
3166 PROCESS SIGNALS
3168 The following constants provide the names of signals which can be sent
3169 to guest processes. They mostly correspond to POSIX signal names.
3170 Sys::Virt::Domain::PROCESS_SIGNAL_NOP
3172 SIGNOP
3173 Sys::Virt::Domain::PROCESS_SIGNAL_HUP
3175 SIGHUP
3176 Sys::Virt::Domain::PROCESS_SIGNAL_INT
3178 SIGINT
3179 Sys::Virt::Domain::PROCESS_SIGNAL_QUIT
3181 SIGQUIT
3182 Sys::Virt::Domain::PROCESS_SIGNAL_ILL
3184 SIGILL
3185 Sys::Virt::Domain::PROCESS_SIGNAL_TRAP
3187 SIGTRAP
3188 Sys::Virt::Domain::PROCESS_SIGNAL_ABRT
3190 SIGABRT
3191 Sys::Virt::Domain::PROCESS_SIGNAL_BUS
3193 SIGBUS
3194 Sys::Virt::Domain::PROCESS_SIGNAL_FPE
3196 SIGFPE
3197 Sys::Virt::Domain::PROCESS_SIGNAL_KILL
3199 SIGKILL
3200 Sys::Virt::Domain::PROCESS_SIGNAL_USR1
3202 SIGUSR1
3203 Sys::Virt::Domain::PROCESS_SIGNAL_SEGV
3205 SIGSEGV
3206 Sys::Virt::Domain::PROCESS_SIGNAL_USR2
3208 SIGUSR2
3209 Sys::Virt::Domain::PROCESS_SIGNAL_PIPE
3211 SIGPIPE
3212 Sys::Virt::Domain::PROCESS_SIGNAL_ALRM
3214 SIGALRM
3215 Sys::Virt::Domain::PROCESS_SIGNAL_TERM
3217 SIGTERM
3218 Sys::Virt::Domain::PROCESS_SIGNAL_STKFLT
3220 SIGSTKFLT
3221 Sys::Virt::Domain::PROCESS_SIGNAL_CHLD
3223 SIGCHLD
3224 Sys::Virt::Domain::PROCESS_SIGNAL_CONT
3226 SIGCONT
3227 Sys::Virt::Domain::PROCESS_SIGNAL_STOP
3229 SIGSTOP
3230 Sys::Virt::Domain::PROCESS_SIGNAL_TSTP
3232 SIGTSTP
3233 Sys::Virt::Domain::PROCESS_SIGNAL_TTIN
3235 SIGTTIN
3236 Sys::Virt::Domain::PROCESS_SIGNAL_TTOU
3238 SIGTTOU
3239 Sys::Virt::Domain::PROCESS_SIGNAL_URG
3241 SIGURG
3242 Sys::Virt::Domain::PROCESS_SIGNAL_XCPU
3244 SIGXCPU
3245 Sys::Virt::Domain::PROCESS_SIGNAL_XFSZ
3247 SIGXFSZ
3248 Sys::Virt::Domain::PROCESS_SIGNAL_VTALRM
3250 SIGVTALRM
3251 Sys::Virt::Domain::PROCESS_SIGNAL_PROF
3253 SIGPROF
3254 Sys::Virt::Domain::PROCESS_SIGNAL_WINCH
3256 SIGWINCH
3257 Sys::Virt::Domain::PROCESS_SIGNAL_POLL
3259 SIGPOLL
3260 Sys::Virt::Domain::PROCESS_SIGNAL_PWR
3262 SIGPWR
3263 Sys::Virt::Domain::PROCESS_SIGNAL_SYS
3265 SIGSYS
3266 Sys::Virt::Domain::PROCESS_SIGNAL_RT0
3268 SIGRT0
3269 Sys::Virt::Domain::PROCESS_SIGNAL_RT1
3271 SIGRT1
3272 Sys::Virt::Domain::PROCESS_SIGNAL_RT2
3274 SIGRT2
3275 Sys::Virt::Domain::PROCESS_SIGNAL_RT3
3277 SIGRT3
3278 Sys::Virt::Domain::PROCESS_SIGNAL_RT4
3280 SIGRT4
3281 Sys::Virt::Domain::PROCESS_SIGNAL_RT5
3283 SIGRT5
3284 Sys::Virt::Domain::PROCESS_SIGNAL_RT6
3286 SIGRT6
3287 Sys::Virt::Domain::PROCESS_SIGNAL_RT7
3289 SIGRT7
3290 Sys::Virt::Domain::PROCESS_SIGNAL_RT8
3292 SIGRT8
3293 Sys::Virt::Domain::PROCESS_SIGNAL_RT9
3295 SIGRT9
3296 Sys::Virt::Domain::PROCESS_SIGNAL_RT10
3298 SIGRT10
3299 Sys::Virt::Domain::PROCESS_SIGNAL_RT11
3301 SIGRT11
3302 Sys::Virt::Domain::PROCESS_SIGNAL_RT12
3304 SIGRT12
3305 Sys::Virt::Domain::PROCESS_SIGNAL_RT13
3307 SIGRT13
3308 Sys::Virt::Domain::PROCESS_SIGNAL_RT14
3310 SIGRT14
3311 Sys::Virt::Domain::PROCESS_SIGNAL_RT15
3313 SIGRT15
3314 Sys::Virt::Domain::PROCESS_SIGNAL_RT16
3316 SIGRT16
3317 Sys::Virt::Domain::PROCESS_SIGNAL_RT17
3319 SIGRT17
3320 Sys::Virt::Domain::PROCESS_SIGNAL_RT18
3322 SIGRT18
3323 Sys::Virt::Domain::PROCESS_SIGNAL_RT19
3325 SIGRT19
3326 Sys::Virt::Domain::PROCESS_SIGNAL_RT20
3328 SIGRT20
3329 Sys::Virt::Domain::PROCESS_SIGNAL_RT21
3331 SIGRT21
3332 Sys::Virt::Domain::PROCESS_SIGNAL_RT22
3334 SIGRT22
3335 Sys::Virt::Domain::PROCESS_SIGNAL_RT23
3337 SIGRT23
3338 Sys::Virt::Domain::PROCESS_SIGNAL_RT24
3340 SIGRT24
3341 Sys::Virt::Domain::PROCESS_SIGNAL_RT25
3343 SIGRT25
3344 Sys::Virt::Domain::PROCESS_SIGNAL_RT26
3346 SIGRT26
3347 Sys::Virt::Domain::PROCESS_SIGNAL_RT27
3349 SIGRT27
3350 Sys::Virt::Domain::PROCESS_SIGNAL_RT28
3352 SIGRT28
3353 Sys::Virt::Domain::PROCESS_SIGNAL_RT29
3355 SIGRT29
3356 Sys::Virt::Domain::PROCESS_SIGNAL_RT30
3358 SIGRT30
3359 Sys::Virt::Domain::PROCESS_SIGNAL_RT31
3361 SIGRT31
3362 Sys::Virt::Domain::PROCESS_SIGNAL_RT32
3364 SIGRT32
3365 DOMAIN TUNABLE CONSTANTS
3367 The following constants are useful when accessing domain tuning
3368 parameters in APIs and events
3369 Sys::Virt::Domain::TUNABLE_CPU_CPU_SHARES
3371 Proportional CPU weight
3372 Sys::Virt::Domain::TUNABLE_CPU_EMULATORPIN
3374 Emulator thread CPU pinning mask
3375 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_PERIOD
3377 Emulator thread CPU period
3378 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_QUOTA
3380 Emulator thread CPU quota
3381 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_PERIOD
3383 Iothread thread CPU period
3384 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_QUOTA
3386 Iothread thread CPU quota
3387 Sys::Virt::Domain::TUNABLE_CPU_VCPUPIN
3389 VCPU thread pinning mask
3390 Sys::Virt::Domain::TUNABLE_CPU_VCPU_PERIOD
3392 VCPU thread period
3393 Sys::Virt::Domain::TUNABLE_CPU_VCPU_QUOTA
3395 VCPU thread quota
3396 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_PERIOD
3398 VM global period
3399 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_QUOTA
3401 VM global quota
3402 Sys::Virt::Domain::TUNABLE_BLKDEV_DISK
3404 The name of guest disks
3405 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC
3407 Read throughput in bytes per sec
3408 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC
3410 Read throughput in I/O operations per sec
3411 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC
3413 Total throughput in bytes per sec
3414 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC
3416 Total throughput in I/O operations per sec
3417 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC
3419 Write throughput in bytes per sec
3420 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC
3422 Write throughput in I/O operations per sec
3423 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX
3425 Maximum read throughput in bytes per sec
3426 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX
3428 Maximum read throughput in I/O operations per sec
3429 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX
3431 Maximum total throughput in bytes per sec
3432 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX
3434 Maximum total throughput in I/O operations per sec
3435 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX
3437 Maximum write throughput in bytes per sec
3438 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX
3440 Maximum write throughput in I/O operations per sec
3441 Sys::Virt::Domain::TUNABLE_BLKDEV_SIZE_IOPS_SEC
3443 The maximum I/O operations per second
3444 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX_LENGTH
3446 The duration in seconds allowed for maximum total bytes processed
3447 per second.
3448 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX_LENGTH
3450 The duration in seconds allowed for maximum bytes read per second.
3451 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX_LENGTH
3453 The duration in seconds allowed for maximum bytes written per
3454 second.
3455 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX_LENGTH
3457 The duration in seconds allowed for maximum total I/O operations
3458 processed per second.
3459 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX_LENGTH
3461 The duration in seconds allowed for maximum I/O operations read per
3462 second.
3463 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX_LENGTH
3465 The duration in seconds allowed for maximum I/O operations written
3466 per second.
3467 Sys::Virt::Domain::TUNABLE_BLKDEV_GROUP_NAME
3469 The name of the blkdev group
3470 Sys::Virt::Domain::TUNABLE_IOTHREADSPIN
3472 The I/O threads pinning
3473 DOMAIN LIFECYCLE CONSTANTS
3475 The following constants are useful when setting action for lifecycle
3476 events.
3477 Sys::Virt::Domain::LIFECYCLE_POWEROFF
3479 The poweroff lifecycle event type
3480 Sys::Virt::Domain::LIFECYCLE_REBOOT
3482 The reboot lifecycle event type
3483 Sys::Virt::Domain::LIFECYCLE_CRASH
3485 The crash lifecycle event type
3486 DOMAIN LIFECYCLE ACTION CONSTANTS
3488 Sys::Virt::Domain::LIFECYCLE_ACTION_DESTROY
3489 The destroy lifecycle action
3490 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART
3492 The restart lifecycle action
3493 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART_RENAME
3495 The restart-rename lifecycle action
3496 Sys::Virt::Domain::LIFECYCLE_ACTION_PRESERVE
3498 The preserve lifecycle action
3499 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_DESTROY
3501 The coredump-destroy lifecycle action
3502 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_RESTART
3504 The coredump-restart lifecycle action
3505 MEMORY FAILURE ACTION CONSTANTS
3507 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_IGNORE
3508 The failure could be ignored
3509 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_INJECT
3511 An MCE was injected to the guest
3512 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_FATAL
3514 The failure is non-recoverable and the hypervisor was not able to
3515 handle it
3516 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_RESET
3518 The failure is non-recoverable and the guest was not able to handle
3519 it.
3520 MEMORY FAILURE RECIPIENT CONSTANTS
3522 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_RECIPIENT_HYPERVISOR
3523 The memory failure was in hypervisor address space
3524 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_RECIPIENT_GUEST
3526 The memory failure was in guest address space
3527 MEMORY FAILURE FLAG CONSTANTS
3529 Sys::Virt::Domain::MEMORY_FAILURE_ACTION_REQUIRED
3530 Whether the flag is action-required or action-optional
3531 Sys::Virt::Domain::MEMORY_FAILURE_RECURSIVE
3533 The failure occurred while the previous fault was being handled.
3534 MEMORY DIRTY RATE STATUS CONSTANTS
3536 Sys::Virt::Domain::DIRTYRATE_UNSTARTED
3537 The dirty rate is not being measured currently.
3538 Sys::Virt::Domain::DIRTYRATE_MEASURING
3540 The dity rate is in the process of being measured
3541 Sys::Virt::Domain::DIRTYRATE_MEASURED
3543 The dirty rate has been measured
3544
3546 Daniel P. Berrange <berrange@redhat.com>
3547
3549 Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
3550
3552 This program is free software; you can redistribute it and/or modify it
3553 under the terms of either the GNU General Public License as published
3554 by the Free Software Foundation (either version 2 of the License, or at
3555 your option any later version), or, the Artistic License, as specified
3556 in the Perl README file.
3557
3559 Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
3560perl v5.36.0 2022-07-25 Sys::Virt::Domain(3)