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 CONSTANTS 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 (e.g. "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 contains 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 contains 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 (e.g. "selinux"), while
714 "label" provides the name of the security label applied to the
715 domain. This method only returns information about the first
716 security label. To retrieve all labels, use
717 "get_security_label_list".
718 @info = $dom->get_security_label_list()
720 Fetches information about all security labels assigned to the guest
721 domain. The elements in the returned array are all hash references,
722 whose keys are as described for "get_security_label".
723 $ddom = $dom->migrate(destcon, \%params, flags=0)
725 Migrate a domain to an alternative host. The "destcon" parameter
726 should be a "Sys::Virt" connection to the remote target host. The
727 "flags" parameter takes one or more of the
728 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
729 document. The %params parameter is a hash reference used to set
730 various parameters for the migration operation, with the following
731 valid keys.
732 "Sys::Virt::Domain::MIGRATE_PARAM_URI"
734 The URI to use for initializing the domain migration. It takes
735 a hypervisor specific format. The uri_transports element of the
736 hypervisor capabilities XML includes details of the supported
737 URI schemes. When omitted libvirt will auto-generate suitable
738 default URI. It is typically only necessary to specify this URI
739 if the destination host has multiple interfaces and a specific
740 interface is required to transmit migration data.
741 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_NAME"
743 The name to be used for the domain on the destination host.
744 Omitting this parameter keeps the domain name the same. This
745 field is only allowed to be used with hypervisors that support
746 domain renaming during migration.
747 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_XML"
749 The new configuration to be used for the domain on the
750 destination host. The configuration must include an identical
751 set of virtual devices, to ensure a stable guest ABI across
752 migration. Only parameters related to host side configuration
753 can be changed in the XML. Hypervisors which support this field
754 will forbid migration if the provided XML would cause a change
755 in the guest ABI. This field cannot be used to rename the
756 domain during migration (use VIR_MIGRATE_PARAM_DEST_NAME field
757 for that purpose). Domain name in the destination XML must
758 match the original domain name.
759 Omitting this parameter keeps the original domain
761 configuration. Using this field with hypervisors that do not
762 support changing domain configuration during migration will
763 result in a failure.
764 "Sys::Virt::Domain::MIGRATE_PARAM_GRAPHICS_URI"
766 URI to use for migrating client's connection to domain's
767 graphical console as VIR_TYPED_PARAM_STRING. If specified, the
768 client will be asked to automatically reconnect using these
769 parameters instead of the automatically computed ones. This can
770 be useful if, e.g., the client does not have a direct access to
771 the network virtualization hosts are connected to and needs to
772 connect through a proxy. The URI is formed as follows:
773 protocol://hostname[:port]/[?parameters]
775 where protocol is either "spice" or "vnc" and parameters is a
777 list of protocol specific parameters separated by '&'.
778 Currently recognized parameters are "tlsPort" and "tlsSubject".
779 For example,
780 spice://target.host.com:1234/?tlsPort=4567
782 "Sys::Virt::Domain::MIGRATE_PARAM_BANDWIDTH"
784 The maximum bandwidth (in MiB/s) that will be used for
785 migration. If set to 0 or omitted, libvirt will choose a
786 suitable default. Some hypervisors do not support this feature
787 and will return an error if this field is used and is not 0.
788 "Sys::Virt::Domain::MIGRATE_PARAM_BANDWIDTH_POSTCOPY"
790 The maximum bandwidth (in MiB/s) that will be used for
791 migration during post-copy phase. If set to 0 or omitted,
792 libvirt will choose a suitable default. Some hypervisors do not
793 support this feature and return an error if this field is used
794 and is not 0.
795 "Sys::Virt::Domain::MIGRATE_PARAM_LISTEN_ADDRESS"
797 The address on which to listen for incoming migration
798 connections. If omitted, libvirt will listen on the wildcard
799 address (0.0.0.0 or ::). This default may be a security risk if
800 guests, or other untrusted users have the ability to connect to
801 the virtualization host, thus use of an explicit restricted
802 listen address is recommended.
803 "Sys::Virt::Domain::MIGRATE_PARAM_DISK_PORT"
805 Port that destination server should use for incoming disks
806 migration. Type is VIR_TYPED_PARAM_INT. If set to 0 or omitted,
807 libvirt will choose a suitable default. At the moment this is
808 only supported by the QEMU driver.
809 "Sys::Virt::Domain::MIGRATE_PARAM_MIGRATE_DISKS"
811 The list of disks to migrate when doing block storage
812 migration. In contrast to other parameters whose values are
813 plain strings, the parameter value should be an array
814 reference, whose elements are in turn strings representing the
815 disk target names.
816 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION"
818 The type of compression method use use, either "xbzrle" or
819 "mt".
820 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_THREADS"
822 The number of compression threads to use
823 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_DTHREADS"
825 The number of decompression threads
826 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_LEVEL"
828 The compression level from 0 (no compression) to 9 (maximum
829 compression)
830 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_XBZRLE_CACHE"
832 The size of the cache for xbzrle compression
833 "Sys::Virt::Domain::MIGRATE_PARAM_PERSIST_XML"
835 The alternative persistent XML config to copy
836 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INITIAL"
838 The initial percentage to throttle guest vCPUs
839 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INCREMENT"
841 The additional percentage step size to throttle guest vCPUs if
842 progress is not made
843 "Sys::Virt::Domain::MIGRATE_PARAM_PARALLEL_CONNECTIONS"
845 The number of connections used during parallel migration.
846 "Sys::Virt::Domain::MIGRATE_PARAM_TLS_DESTINATION"
848 Override the destination host name used for TLS verification.
849 Normally the TLS certificate from the destination host must
850 match the host's name for TLS verification to succeed. When the
851 certificate does not match the destination hostname and the
852 expected certificate's hostname is known, this parameter can be
853 used to pass this expected hostname when starting the
854 migration.
855 "Sys::Virt::Domain::MIGRATE_PARAM_DISKS_URI"
857 The URI to use for initializing the domain migration for
858 storage. It takes a hypervisor specific format. The
859 uri_transports element of the hypervisor capabilities XML
860 includes details of the supported URI schemes. When omitted
861 libvirt will auto-generate suitable default URI. It is
862 typically only necessary to specify this URI if the destination
863 host has multiple interfaces and a specific interface is
864 required to transmit storage data.
865 $ddom = $dom->migrate(destcon, flags=0, dname=undef, uri=undef,
867 bandwidth=0)
868 Migrate a domain to an alternative host. Use of positional
869 parameters with "migrate" is deprecated in favour of passing a hash
870 reference as described above.
871 $ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)
873 Migrate a domain to an alternative host. This method is deprecated
874 in favour of passing a hash ref to "migrate".
875 $ddom = $dom->migrate_to_uri(desturi, \%params, flags=0)
877 Migrate a domain to an alternative host. The "desturi" parameter
878 should be a valid libvirt connection URI for the remote target
879 host. The "flags" parameter takes one or more of the
880 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
881 document. The %params parameter is a hash reference used to set
882 various parameters for the migration operation, with the same keys
883 described for the "migrate" API.
884 $dom->migrate_to_uri(desturi, flags, dname, bandwidth)
886 Migrate a domain to an alternative host. Use of positional
887 parameters with "migrate_to_uri" is deprecated in favour of passing
888 a hash reference as described above.
889 $dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)
891 Migrate a domain to an alternative host. This method is deprecated
892 in favour of passing a hash ref to "migrate_to_uri".
893 $dom->migrate_set_max_downtime($downtime, $flags=0)
895 Set the maximum allowed downtime during migration of the guest. A
896 longer downtime makes it more likely that migration will complete,
897 at the cost of longer time blackout for the guest OS at the switch
898 over point. The "downtime" parameter is measured in milliseconds.
899 The $flags parameter is currently unused and defaults to zero.
900 $downtime = $dom->migrate_get_max_downtime($flags=0) Get the current
902 value of the maximum downtime allowed during a migration of a guest.
903 The returned <downtime> value is measured in milliseconds. The $flags
904 parameter is currently unused and defaults to zero.
905 $dom->migrate_set_max_speed($bandwidth, $flags=0)
906 Set the maximum allowed bandwidth during migration of the guest.
907 The "bandwidth" parameter is measured in MB/second. The $flags
908 parameter takes zero or more of the constants:
909 $Sys::Virt::Domain::MIGRATE_MAX_SPEED_POSTCOPY
911 Set the post-copy speed instead of the pre-copy speed.
912 $bandwidth = $dom->migrate_get_max_speed($flags=0)
914 Get the maximum allowed bandwidth during migration fo the guest.
915 The returned <bandwidth> value is measured in MB/second. The
916 $flags parameter is accepts the same constants as
917 "migrate_set_max_speed".
918 $dom->migrate_set_compression_cache($cacheSize, $flags=0)
920 Set the maximum allowed compression cache size during migration of
921 the guest. The "cacheSize" parameter is measured in bytes. The
922 $flags parameter is currently unused and defaults to zero.
923 $cacheSize = $dom->migrate_get_compression_cache($flags=0)
925 Get the maximum allowed compression cache size during migration of
926 the guest. The returned <bandwidth> value is measured in bytes.
927 The $flags parameter is currently unused and defaults to zero.
928 $dom->migrate_start_post_copy($flags=0)
930 Switch the domain from pre-copy to post-copy mode. This requires
931 that the original migrate command had the
932 "Sys::Virt::Domain::MIGRATE_POST_COPY" flag specified.
933 $dom->inject_nmi($flags)
935 Trigger an NMI in the guest virtual machine. The $flags parameter
936 is currently unused and defaults to 0.
937 $dom->open_console($st, $devname, $flags)
939 Open the text console for a serial, parallel or paravirt console
940 device identified by $devname, connecting it to the stream $st. If
941 $devname is undefined, the default console will be opened. $st must
942 be a "Sys::Virt::Stream" object used for bi-directional
943 communication with the console. $flags is currently unused,
944 defaulting to 0.
945 $dom->open_channel($st, $devname, $flags)
947 Open the text console for a data channel device identified by
948 $devname, connecting it to the stream $st. $st must be a
949 "Sys::Virt::Stream" object used for bi-directional communication
950 with the channel. $flags is currently unused, defaulting to 0.
951 $dom->open_graphics($idx, $fd, $flags)
953 Open the graphics console for a guest, identified by $idx, counting
954 from 0. The $fd should be a file descriptor for an anonymous socket
955 pair. The $flags argument should be one of the constants listed at
956 the end of this document, and defaults to 0.
957 $fd = $dom->open_graphics_fd($idx, $flags)
959 Open the graphics console for a guest, identified by $idx, counting
960 from 0. The $flags argument should be one of the constants listed
961 at the end of this document, and defaults to 0. The return value
962 will be a file descriptor connected to the console which must be
963 closed when no longer needed. This method is preferred over
964 "open_graphics" since it will work correctly under sVirt mandatory
965 access control policies.
966 my $mimetype = $dom->screenshot($st, $screen, $flags)
968 Capture a screenshot of the virtual machine's monitor. The $screen
969 parameter controls which monitor is captured when using a multi-
970 head or multi-card configuration. $st must be a "Sys::Virt::Stream"
971 object from which the data can be read. $flags is currently unused
972 and defaults to 0. The mimetype of the screenshot is returned
973 @vcpuinfo = $dom->get_vcpu_info($flags=0)
975 Obtain information about the state of all virtual CPUs in a running
976 guest domain. The returned list will have one element for each
977 vCPU, where each elements contains a hash reference. The keys in
978 the hash are, "number" the vCPU number, "cpu" the physical CPU on
979 which the vCPU is currently scheduled, "cpuTime" the cumulative
980 execution time of the vCPU, "state" the running state and
981 "affinity" giving the allowed scheduler placement. The value for
982 "affinity" is a string representing a bitmask against physical
983 CPUs, 8 cpus per character. To extract the bits use the "unpack"
984 function with the "b*" template. NB The "state", "cpuTime", "cpu"
985 values are only available if using $flags value of 0, and the
986 domain is currently running; otherwise they will all be set to
987 zero.
988 $dom->pin_vcpu($vcpu, $mask)
990 Pin the virtual CPU given by index $vcpu to physical CPUs given by
991 $mask. The $mask is a string representing a bitmask against
992 physical CPUs, 8 cpus per character.
993 $mask = $dom->get_emulator_pin_info()
995 Obtain information about the CPU affinity of the emulator process.
996 The returned $mask is a bitstring against physical CPUs, 8 cpus per
997 character. To extract the bits use the "unpack" function with the
998 "b*" template.
999 $dom->pin_emulator($newmask, $flags=0)
1001 Pin the emulator threads to the physical CPUs identified by the
1002 affinity in $newmask. The $newmask is a bitstring against the
1003 physical CPUa, 8 cpus per character. To create a suitable
1004 bitstring, use the "vec" function with a value of 1 for the "BITS"
1005 parameter.
1006 @iothreadinfo = $dom->get_iothread_info($flags=0)
1008 Obtain information about the state of all IOThreads in a running
1009 guest domain. The returned list will have one element for each
1010 IOThread, where each elements contains a hash reference. The keys
1011 in the hash are, "number" the IOThread number and "affinity" giving
1012 the allowed scheduler placement. The value for "affinity" is a
1013 string representing a bitmask against physical CPUs, 8 cpus per
1014 character. To extract the bits use the "unpack" function with the
1015 "b*" template.
1016 $dom->pin_iothread($iothread, $mask)
1018 Pin the IOThread given by index $iothread to physical CPUs given by
1019 $mask. The $mask is a string representing a bitmask against
1020 physical CPUs, 8 cpus per character.
1021 $dom->add_iothread($iothread, $flags=0)
1023 Add a new IOThread by the $iothread value to the guest domain. The
1024 $flags parameter accepts one or more the CONFIG OPTION constants
1025 documented later, and defaults to 0 if omitted.
1026 $dom->del_iothread($iothread, $flags=0)
1028 Delete an existing IOThread by the $iothread value from the guest
1029 domain. The $flags parameter accepts one or more the CONFIG OPTION
1030 constants documented later, and defaults to 0 if omitted.
1031 $dom->set_iothread($iothread, $params, $flags=0)
1033 Set parameters for the IOThread by the $iothread value on the guest
1034 domain. The $params parameter is a hash reference whose keys are
1035 the "IOTHREAD STATS" constants documented later. The $flags
1036 parameter accepts one or more the CONFIG OPTION constants
1037 documented later, and defaults to 0 if omitted.
1038 my @stats = $dom->get_cpu_stats($startCpu, $numCpus, $flags=0)
1040 Requests the guests host physical CPU usage statistics, starting
1041 from host CPU <$startCpu> counting up to $numCpus. If $startCpu is
1042 -1 and $numCpus is 1, then the utilization across all CPUs is
1043 returned. Returns an array of hash references, each element
1044 containing stats for one CPU.
1045 my $info = $dom->get_job_info()
1047 Returns a hash reference summarising the execution state of the
1048 background job. The elements of the hash are as follows:
1049 type
1051 The type of job, one of the JOB TYPE constants listed later in
1052 this document.
1053 timeElapsed
1055 The elapsed time in milliseconds
1056 timeRemaining
1058 The expected remaining time in milliseconds. Only set if the
1059 "type" is JOB_UNBOUNDED.
1060 dataTotal
1062 The total amount of data expected to be processed by the job,
1063 in bytes.
1064 dataProcessed
1066 The current amount of data processed by the job, in bytes.
1067 dataRemaining
1069 The expected amount of data remaining to be processed by the
1070 job, in bytes.
1071 memTotal
1073 The total amount of memory expected to be processed by the job,
1074 in bytes.
1075 memProcessed
1077 The current amount of memory processed by the job, in bytes.
1078 memRemaining
1080 The expected amount of memory remaining to be processed by the
1081 job, in bytes.
1082 fileTotal
1084 The total amount of file expected to be processed by the job,
1085 in bytes.
1086 fileProcessed
1088 The current amount of file processed by the job, in bytes.
1089 fileRemaining
1091 The expected amount of file remaining to be processed by the
1092 job, in bytes.
1093 my ($type, $stats) = $dom->get_job_stats($flags=0)
1095 Returns an array summarising the execution state of the background
1096 job. The $type value is one of the JOB TYPE constants listed later
1097 in this document. The $stats value is a hash reference, whose
1098 elements are one of the following constants.
1099 type
1101 The type of job, one of the JOB TYPE constants listed later in
1102 this document.
1103 The $flags parameter defaults to zero and can take one of the
1105 following constants.
1106 Sys::Virt::Domain::JOB_STATS_COMPLETED
1108 Return the stats of the most recently completed job.
1109 Sys::Virt::Domain::JOB_STATS_KEEP_COMPLETED
1111 Don't clear the completed stats after reading them.
1112 Sys::Virt::Domain::JOB_TIME_ELAPSED
1114 The elapsed time in milliseconds
1115 Sys::Virt::Domain::JOB_TIME_ELAPSED_NET
1117 Time in milliseconds since the beginning of the migration job
1118 NOT including the time required to transfer control flow from
1119 the source host to the destination host.
1120 Sys::Virt::Domain::JOB_TIME_REMAINING
1122 The expected remaining time in milliseconds. Only set if the
1123 "type" is JOB_UNBOUNDED.
1124 Sys::Virt::Domain::JOB_DATA_TOTAL
1126 The total amount of data expected to be processed by the job,
1127 in bytes.
1128 Sys::Virt::Domain::JOB_DATA_PROCESSED
1130 The current amount of data processed by the job, in bytes.
1131 Sys::Virt::Domain::JOB_DATA_REMAINING
1133 The expected amount of data remaining to be processed by the
1134 job, in bytes.
1135 Sys::Virt::Domain::JOB_MEMORY_TOTAL
1137 The total amount of memory expected to be processed by the job,
1138 in bytes.
1139 Sys::Virt::Domain::JOB_MEMORY_PROCESSED
1141 The current amount of memory processed by the job, in bytes.
1142 Sys::Virt::Domain::JOB_MEMORY_REMAINING
1144 The expected amount of memory remaining to be processed by the
1145 job, in bytes.
1146 Sys::Virt::Domain::JOB_MEMORY_CONSTANT
1148 The number of pages filled with a constant byte which have been
1149 transferred
1150 Sys::Virt::Domain::JOB_MEMORY_NORMAL
1152 The number of pages transferred without any compression
1153 Sys::Virt::Domain::JOB_MEMORY_NORMAL_BYTES
1155 The number of bytes transferred without any compression
1156 Sys::Virt::Domain::JOB_MEMORY_BPS
1158 The bytes per second transferred
1159 Sys::Virt::Domain::JOB_MEMORY_DIRTY_RATE
1161 The number of memory pages dirtied per second
1162 Sys::Virt::Domain::JOB_MEMORY_PAGE_SIZE
1164 The memory page size in bytes
1165 Sys::Virt::Domain::JOB_MEMORY_ITERATION
1167 The total number of iterations over guest memory
1168 Sys::Virt::Domain::JOB_MEMORY_POSTCOPY_REQS
1170 The number of page requests received from the destination host
1171 during post-copy migration.
1172 Sys::Virt::Domain::JOB_DISK_TOTAL
1174 The total amount of file expected to be processed by the job,
1175 in bytes.
1176 Sys::Virt::Domain::JOB_DISK_PROCESSED
1178 The current amount of file processed by the job, in bytes.
1179 Sys::Virt::Domain::JOB_DISK_REMAINING
1181 The expected amount of file remaining to be processed by the
1182 job, in bytes.
1183 Sys::Virt::Domain::JOB_DISK_BPS
1185 The bytes per second transferred
1186 Sys::Virt::Domain::JOB_AUTO_CONVERGE_THROTTLE
1188 The percentage by which vCPUs are currently throttled
1189 Sys::Virt::Domain::JOB_COMPRESSION_CACHE
1191 The size of the compression cache in bytes
1192 Sys::Virt::Domain::JOB_COMPRESSION_BYTES
1194 The number of compressed bytes transferred
1195 Sys::Virt::Domain::JOB_COMPRESSION_PAGES
1197 The number of compressed pages transferred
1198 Sys::Virt::Domain::JOB_COMPRESSION_CACHE_MISSES
1200 The number of changing pages not in compression cache
1201 Sys::Virt::Domain::JOB_COMPRESSION_OVERFLOW
1203 The number of changing pages in the compression cache but sent
1204 uncompressed since the compressed page was larger than the non-
1205 compressed page.
1206 Sys::Virt::Domain::JOB_DOWNTIME
1208 The number of milliseconds of downtime expected during
1209 migration switchover.
1210 Sys::Virt::Domain::JOB_DOWNTIME_NET
1212 Real measured downtime (ms) NOT including the time required to
1213 transfer control flow from the source host to the destination
1214 host.
1215 Sys::Virt::Domain::JOB_SETUP_TIME
1217 The number of milliseconds of time doing setup of the job
1218 Sys::Virt::Domain::JOB_OPERATION
1220 The type of operation associated with the job
1221 Sys::Virt::Domain::JOB_SUCCESS
1223 Whether the job was successfully completed.
1224 Sys::Virt::Domain::JOB_DISK_TEMP_TOTAL
1226 Possible total temporary disk space for the job in bytes
1227 Sys::Virt::Domain::JOB_DISK_TEMP_USED
1229 Current total temporary disk space for the job in bytes
1230 Sys::Virt::Domain::JOB_ERRMSG
1232 The error message from a failed job
1233 The values for the Sys::Virt::Domain::JOB_OPERATION field are
1235 Sys::Virt::Domain::JOB_OPERATION_UNKNOWN
1237 No known job type
1238 Sys::Virt::Domain::JOB_OPERATION_START
1240 The guest is starting
1241 Sys::Virt::Domain::JOB_OPERATION_SAVE
1243 The guest is saving to disk
1244 Sys::Virt::Domain::JOB_OPERATION_RESTORE
1246 The guest is restoring from disk
1247 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_IN
1249 The guest is migrating in from another host
1250 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_OUT
1252 The guest is migrating out to another host
1253 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT
1255 The guest is saving a snapshot
1256 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT_REVERT
1258 The guest is reverting to a snapshot
1259 Sys::Virt::Domain::JOB_OPERATION_DUMP
1261 The guest is saving a crash dump
1262 Sys::Virt::Domain::JOB_OPERATION_BACKUP
1264 The guest is performing a block backup
1265 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT_DELETE
1267 The guest is deleting a snapshot
1268 $dom->abort_job($flags=0)
1270 Aborts the currently executing job. Valid $flags include:
1271 Sys::Virt::Domain::DOMAIN_ABORT_JOB_POSTCOPY
1273 Interrupt post-copy migration. It can later be resumed using
1274 migrate APIs with "MIGRATE_POSTCOPY_RESUME" flag.
1275 my $info = $dom->get_block_job_info($path, $flags=0)
1277 Returns a hash reference summarising the execution state of the
1278 block job. The $path parameter should be the fully qualified path
1279 of the block device being changed. Valid $flags include:
1280 Sys::Virt::Domain::BLOCK_JOB_INFO_BANDWIDTH_BYTES
1282 Treat bandwidth value as bytes instead of MiB.
1283 $dom->set_block_job_speed($path, $bandwidth, $flags=0)
1285 Change the maximum I/O bandwidth used by the block job that is
1286 currently executing for $path. The $bandwidth argument is specified
1287 in MB/s. The $flags parameter can take the bitwise union of the
1288 values:
1289 Sys::Virt::Domain::BLOCK_JOB_SPEED_BANDWIDTH_BYTES
1291 The $bandwidth parameter value is measured in bytes/s instead
1292 of MB/s.
1293 $dom->abort_block_job($path, $flags=0)
1295 Abort the current job that is executing for the block device
1296 associated with $path
1297 $dom->block_pull($path, $bandwidth, $flags=0)
1299 Merge the backing files associated with $path into the top level
1300 file. The $bandwidth parameter specifies the maximum I/O rate to
1301 allow in MB/s. The $flags parameter can take the bitwise union of
1302 the values:
1303 Sys::Virt::Domain::BLOCK_PULL_BANDWIDTH_BYTES
1305 The $bandwidth parameter value is measured in bytes/s instead
1306 of MB/s.
1307 $dom->block_rebase($path, $base, $bandwidth, $flags=0)
1309 Switch the backing path associated with $path to instead use $base.
1310 The $bandwidth parameter specifies the maximum I/O rate to allow in
1311 MB/s. The $flags parameter can take the bitwise union of the
1312 values:
1313 Sys::Virt::Domain::BLOCK_REBASE_BANDWIDTH_BYTES
1315 The $bandwidth parameter value is measured in bytes/s instead
1316 of MB/s.
1317 $dom->block_copy($path, $destxml, $params, $flags=0)
1319 Copy contents of a disk image <$path> into the target volume
1320 described by $destxml which follows the schema of the <disk>
1321 element in the domain XML. The $params parameter is a hash of
1322 optional parameters to control the process
1323 Sys::Virt::Domain::BLOCK_COPY_BANDWIDTH
1325 The maximum bandwidth in bytes per second.
1326 Sys::Virt::Domain::BLOCK_COPY_GRANULARITY
1328 The granularity in bytes of the copy process
1329 Sys::Virt::Domain::BLOCK_COPY_BUF_SIZE
1331 The maximum amount of data in flight in bytes.
1332 $dom->block_commit($path, $base, $top, $bandwidth, $flags=0)
1334 Commit changes there were made to the temporary top level file
1335 $top. Takes all the differences between $top and $base and merge
1336 them into $base. The $bandwidth parameter specifies the maximum I/O
1337 rate to allow in MB/s. The $flags parameter can take the bitwise
1338 union of the values:
1339 Sys::Virt::Domain::BLOCK_COMMIT_BANDWIDTH_BYTES
1341 The $bandwidth parameter value is measured in bytes instead of
1342 MB/s.
1343 $count = $dom->num_of_snapshots()
1345 Return the number of saved snapshots of the domain
1346 @names = $dom->list_snapshot_names()
1348 List the names of all saved snapshots. The names can be used with
1349 the "lookup_snapshot_by_name"
1350 @snapshots = $dom->list_snapshots()
1352 Return a list of all snapshots currently known to the domain. The
1353 elements in the returned list are instances of the
1354 Sys::Virt::DomainSnapshot class. This method requires O(n) RPC
1355 calls, so the "list_all_snapshots" method is recommended as a more
1356 efficient alternative.
1357 my @snapshots = $dom->list_all_snapshots($flags)
1359 Return a list of all domain snapshots associated with this domain.
1360 The elements in the returned list are instances of the
1361 Sys::Virt::DomainSnapshot class. The $flags parameter can be used
1362 to filter the list of return domain snapshots.
1363 my $snapshot = $dom->get_snapshot_by_name($name)
1365 Return the domain snapshot with a name of $name. The returned
1366 object is an instance of the Sys::Virt::DomainSnapshot class.
1367 $dom->has_current_snapshot()
1369 Returns a true value if the domain has a currently active snapshot
1370 $snapshot = $dom->current_snapshot()
1372 Returns the currently active snapshot for the domain.
1373 $snapshot = $dom->create_snapshot($xml[, $flags])
1375 Create a new snapshot from the $xml. The $flags parameter accepts
1376 the SNAPSHOT CREATION constants listed in
1377 "Sys::Virt::DomainSnapshots".
1378 my @checkpoints = $dom->list_all_checkpoints($flags)
1380 Return a list of all domain checkpoints associated with this
1381 domain. The elements in the returned list are instances of the
1382 Sys::Virt::DomainCheckpoint class. The $flags parameter can be used
1383 to filter the list of return domain checkpoints.
1384 my $checkpoint = $dom->get_checkpoint_by_name($name)
1386 Return the domain checkpoint with a name of $name. The returned
1387 object is an instance of the Sys::Virt::DomainCheckpoint class.
1388 $checkpoint = $dom->create_checkpoint($xml[, $flags])
1390 Create a new checkpoint from the $xml. The $flags parameter accepts
1391 the CHECKPOINT CREATION constants listed in
1392 "Sys::Virt::DomainCheckpoints".
1393 $dom->backup_begin($backupxml, $checkpointxml=undef, $flags=0);
1395 Start a point-in-time backup job for the specified disks of a
1396 running domain. The $backupxml parameter describes the backup
1397 operation, including which disks to use. The optional
1398 $checkpointxml parameter can be used to create a checkpoint
1399 covering to the same point in time as the backup. The optional
1400 $flags parameter can be one of the following constants:
1401 Sys::Virt::Domain::BACKUP_BEGIN_REUSE_EXTERNAL
1403 Assume that the output/temporary files for the backup have been
1404 precreated by the caller with the correct size and format.
1405 $xml = $dom->backup_get_xml_description($flags=0);
1407 Get the XML description of the currently executing backup job. If
1408 there is no backup job then an error is raised.
1409 $dom->fs_trim($mountPoint, $minimum, $flags=0);
1411 Issue an FS_TRIM command to the device at $mountPoint to remove
1412 chunks of unused space that are at least $minimum bytes in length.
1413 $flags is currently unused and defaults to zero.
1414 $dom->fs_freeze(\@mountPoints, $flags=0);
1416 Freeze all the filesystems associated with the @mountPoints array
1417 reference. If <@mountPoints> is an empty list, then all filesystems
1418 will be frozen. $flags is currently unused and defaults to zero.
1419 $dom->fs_thaw(\@mountPoints, $flags=0);
1421 Thaw all the filesystems associated with the @mountPoints array
1422 reference. If <@mountPoints> is an empty list, then all filesystems
1423 will be thawed. $flags is currently unused and defaults to zero.
1424 @fslist = $dom->get_fs_info($flags=0);
1426 Obtain a list of all guest filesystems. The returned list will
1427 contain one element for each filesystem, whose value will be a hash
1428 reference with the following keys
1429 name
1431 The name of the guest device that is mounted
1432 fstype
1434 The filesystem type (e.g. 'ext4', 'fat', 'ntfs', etc)
1435 mountpoint
1437 The location in the filesystem tree of the mount
1438 devalias
1440 An array reference containing list of device aliases associated
1441 with the guest device. The device aliases correspond to disk
1442 target names in the guest XML configuration
1443 @nics = $dom->get_interface_addresses($src, $flags=0);
1445 Obtain a list of all guest network interfaces. The $src parameter
1446 is one of the constants
1447 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_LEASE
1449 Extract the DHCP server lease information
1450 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_AGENT
1452 Query the guest OS via an agent
1453 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_ARP
1455 Extract from the local ARP tables
1456 The returned list will contain one element for each interface. The
1458 values in the list will be a hash reference with the following keys
1459 name
1461 The name of the guest interface that is mounted
1462 hwaddr
1464 The hardware address, aka MAC, if available.
1465 addrs
1467 An array reference containing list of IP addresses associated
1468 with the guest NIC. Each element in the array is a further hash
1469 containing
1470 addr
1472 The IP address string
1473 prefix
1475 The IP address network prefix
1476 type
1478 The IP address type (IPv4 vs IPv6)
1479 $dom->send_process_signal($pid, $signum, $flags=0);
1481 Send the process $pid the signal $signum. The $signum value must be
1482 one of the constants listed later, not a POSIX or Linux signal
1483 value. $flags is currently unused and defaults to zero.
1484 $dom->set_block_threshold($dev, $threshold, $flags=0);
1486 Set the threshold level for delivering the EVENT_ID_BLOCK_THRESHOLD
1487 if the device or backing chain element described by $dev is written
1488 beyond the set $threshold level. The threshold level is unset once
1489 the event fires. The event might not be delivered at all if
1490 libvirtd was not running at the moment when the threshold was
1491 reached.
1492 $dom->set_lifecycle_action($type, $action, $flags=0)
1494 Changes the actions of lifecycle events for domain represented as
1495 <on_$type>$action</on_$type> in the domain XML.
1496 $info = $dom->get_launch_security_info($flags=0)
1498 Get information about the domain launch security policy. $flags is
1499 currently unused and defaults to zero. The returned hash may
1500 contain the following keys
1501 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_MEASUREMENT
1503 The AMD SEV launch measurement
1504 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_API_MAJOR
1506 The host SEV API major version
1507 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_API_MINOR
1509 The host SEV API minor version
1510 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_BUILD_ID
1512 The host SEV firmware build ID
1513 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_POLICY
1515 The guest SEV policy
1516 $dom->set_launch_security_state(\%params, $flags=0)
1518 Set information about the domain launch security state. $flags is
1519 currently unused and defaults to zero. The provided hash may
1520 contain the following keys
1521 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET
1523 The SEV secret string to inject
1524 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET_HEADER
1526 The SEV secret header string to inject
1527 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET_SET_ADDRESS
1529 The address at which to inject the SEV secret. If omitted it
1530 can be automatically determined from the firmware
1531 $info = $dom->get_guest_info($types, $flags=0)
1533 Get information about the domain guest configuration. The $types
1534 parameter determines what pieces of information are returned and
1535 should be the bitwise or of the following constants:
1536 Sys::Virt::Domain::GUEST_INFO_USERS
1538 Active user information
1539 Sys::Virt::Domain::GUEST_INFO_OS
1541 Misc operating system information
1542 Sys::Virt::Domain::GUEST_INFO_TIMEZONE
1544 The guest timezone
1545 Sys::Virt::Domain::GUEST_INFO_HOSTNAME
1547 The guest hostname
1548 Sys::Virt::Domain::GUEST_INFO_FILESYSTEM
1550 Filesystem mount information
1551 Sys::Virt::Domain::GUEST_INFO_DISKS
1553 Block device information
1554 Sys::Virt::Domain::GUEST_INFO_INTERFACES
1556 Network interfaces information
1557 $flags is currently unused and defaults to zero.
1559 $dom->set_agent_response_timeout($timeout, $flags=0)
1561 Set the amount of time to wait for the agent to respond to a
1562 command. $timeout is a positive integer representing the number of
1563 seconds to wait, or one of the constants:
1564 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_BLOCK
1566 Wait forever with no timeout
1567 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_NOWAIT
1569 Don't want at all, return immediately
1570 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_DEFAULT
1572 Use the hypervisor driver's default timeout
1573 The $flags parameter is currently unused and defaults to zero.
1575 my @keys = $dom->authorized_ssh_keys_get($user, $flags=0)
1577 Retrieve the list of authorized SSH keys for the user account
1578 $user. The $flags parameter is currently unused and defaults to
1579 zero.
1580 $dom->authorized_ssh_keys_set($user, \@keys, $flags=0)
1582 Update the list of authorized SSH keys for the user account $user.
1583 The @keys parameter should be an array reference containing the new
1584 keys, if any. The default behaviour is to set the authorized SSH
1585 keys to the exact set specified in @keys. This can be modified via
1586 the $flags parameter which takes the following constants
1587 Sys::Virt::Domain::AUTHORIZED_SSH_KEYS_SET_APPEND
1589 Append @keys to the current set of keys, rather than replacing
1590 the existing keys.
1591 Sys::Virt::Domain::AUTHORIZED_SSH_KEYS_SET_REMOVE
1593 Remove @keys from the current set of keys, rather than
1594 replacing the existing keys. It is not an error if the keys do
1595 not exist.
1596 my @msgs = $dom->get_messages($flags=0)
1598 Retrieve a list of messages associated with the domain. The
1599 optional $flags parameter can accept zero or more of
1600 Sys::Virt::Domain::MESSAGE_DEPRECATION
1602 Warnings about use of deprecated features
1603 Sys::Virt::Domain::MESSAGE_TAINTING
1605 Warnings about actions that have tainting the domain
1606 $dom->start_dirty_rate_calc($dom, $secs, $flags=0)
1608 Request calculation of the domain's memory dirty rate over the next
1609 $secs seconds. $flags accepts one or more of
1610 Sys::Virt::Domain::DIRTYRATE_MODE_PAGE_SAMPLING
1612 Page sampling mode
1613 Sys::Virt::Domain::DIRTYRATE_MODE_DIRTY_BITMAP
1615 Dirty bitmap mode
1616 Sys::Virt::Domain::DIRTYRATE_MODE_DIRTY_RING
1618 Dirty ring mode
1619 $dom->fd_associate($name, \@fds, $flags=0)
1621 Associate a set of file descriptors in @fds with the domain, giving
1622 them the name $name. If $flags is non-zero, it can take one or
1623 more of:
1624 Sys::Virt::Domain::FD_ASSOCIATE_SECLABEL_RESTORE
1626 Attempt to restore the label when shutting down
1627 Sys::Virt::Domain::FD_ASSOCIATE_SECLABEL_WRITABLE
1629 Label the FD to permit the guest to write to it.
1630
1632 A number of the APIs take a "flags" parameter. In most cases passing a
1633 value of zero will be satisfactory. Some APIs, however, accept named
1634 constants to alter their behaviour. This section documents the current
1635 known constants.
1636 DOMAIN STATE
1638 The domain state constants are useful in interpreting the "state" key
1639 in the hash returned by the "get_info" method.
1640 Sys::Virt::Domain::STATE_NOSTATE
1642 The domain is active, but is not running / blocked (e.g. idle)
1643 Sys::Virt::Domain::STATE_RUNNING
1645 The domain is active and running
1646 Sys::Virt::Domain::STATE_BLOCKED
1648 The domain is active, but execution is blocked
1649 Sys::Virt::Domain::STATE_PAUSED
1651 The domain is active, but execution has been paused
1652 Sys::Virt::Domain::STATE_SHUTDOWN
1654 The domain is active, but in the shutdown phase
1655 Sys::Virt::Domain::STATE_SHUTOFF
1657 The domain is inactive, and shut down.
1658 Sys::Virt::Domain::STATE_CRASHED
1660 The domain is inactive, and crashed.
1661 Sys::Virt::Domain::STATE_PMSUSPENDED
1663 The domain is active, but in power management suspend state
1664 CONTROL INFO
1666 The following constants can be used to determine what the guest domain
1667 control channel status is
1668 Sys::Virt::Domain::CONTROL_ERROR
1670 The control channel has a fatal error
1671 Sys::Virt::Domain::CONTROL_OK
1673 The control channel is ready for jobs
1674 Sys::Virt::Domain::CONTROL_OCCUPIED
1676 The control channel is busy
1677 Sys::Virt::Domain::CONTROL_JOB
1679 The control channel is busy with a job
1680 If the status is "Sys::Virt::Domain::CONTROL_ERROR", then one of the
1682 following constants describes the reason
1683 Sys::Virt::Domain::CONTROL_ERROR_REASON_NONE
1685 There is no reason for the error available
1686 Sys::Virt::Domain::CONTROL_ERROR_REASON_UNKNOWN
1688 The reason for the error is unknown
1689 Sys::Virt::Domain::CONTROL_ERROR_REASON_INTERNAL
1691 There was an internal error in libvirt
1692 Sys::Virt::Domain::CONTROL_ERROR_REASON_MONITOR
1694 There was an error speaking to the monitor
1695 DOMAIN CREATION
1697 The following constants can be used to control the behaviour of domain
1698 creation
1699 Sys::Virt::Domain::START_PAUSED
1701 Keep the guest vCPUs paused after starting the guest
1702 Sys::Virt::Domain::START_AUTODESTROY
1704 Automatically destroy the guest when the connection is closed (or
1705 fails)
1706 Sys::Virt::Domain::START_BYPASS_CACHE
1708 Do not use OS I/O cache if starting a domain with a saved state
1709 image
1710 Sys::Virt::Domain::START_FORCE_BOOT
1712 Boot the guest, even if there was a saved snapshot
1713 Sys::Virt::Domain::START_VALIDATE
1715 Validate the XML document against the XML schema
1716 Sys::Virt::Domain::START_RESET_NVRAM
1718 Reset the firmware NVRAM state from its original template
1719 DOMAIN DEFINE
1721 The following constants can be used to control the behaviour of domain
1722 define operations
1723 Sys::Virt::Domain::DEFINE_VALIDATE
1725 Validate the XML document against the XML schema
1726 KEYCODE SETS
1728 The following constants define the set of supported keycode sets
1729 Sys::Virt::Domain::KEYCODE_SET_LINUX
1731 The Linux event subsystem keycodes
1732 Sys::Virt::Domain::KEYCODE_SET_XT
1734 The original XT keycodes
1735 Sys::Virt::Domain::KEYCODE_SET_ATSET1
1737 The AT Set1 keycodes (aka XT)
1738 Sys::Virt::Domain::KEYCODE_SET_ATSET2
1740 The AT Set2 keycodes (aka AT)
1741 Sys::Virt::Domain::KEYCODE_SET_ATSET3
1743 The AT Set3 keycodes (aka PS2)
1744 Sys::Virt::Domain::KEYCODE_SET_OSX
1746 The OS-X keycodes
1747 Sys::Virt::Domain::KEYCODE_SET_XT_KBD
1749 The XT keycodes from the Linux Keyboard driver
1750 Sys::Virt::Domain::KEYCODE_SET_USB
1752 The USB HID keycode set
1753 Sys::Virt::Domain::KEYCODE_SET_WIN32
1755 The Windows keycode set
1756 Sys::Virt::Domain::KEYCODE_SET_QNUM
1758 The XT keycode set, with the extended scancodes using the high bit
1759 of the first byte, instead of the low bit of the second byte.
1760 Sys::Virt::Domain::KEYCODE_SET_RFB
1762 A deprecated alias for "Sys::Virt::Domain::KEYCODE_SET_QNUM"
1763 MEMORY PEEK
1765 The following constants can be used with the "memory_peek" method's
1766 flags parameter
1767 Sys::Virt::Domain::MEMORY_VIRTUAL
1769 Indicates that the offset is using virtual memory addressing.
1770 Sys::Virt::Domain::MEMORY_PHYSICAL
1772 Indicates that the offset is using physical memory addressing.
1773 VCPU STATE
1775 The following constants are useful when interpreting the virtual CPU
1776 run state
1777 Sys::Virt::Domain::VCPU_OFFLINE
1779 The virtual CPU is not online
1780 Sys::Virt::Domain::VCPU_RUNNING
1782 The virtual CPU is executing code
1783 Sys::Virt::Domain::VCPU_BLOCKED
1785 The virtual CPU is waiting to be scheduled
1786 VCPU HOST PLACEMENT STATE
1788 The following constants are useful when interpreting the virtual CPU
1789 host placement
1790 Sys::Virt::Domain::VCPU_INFO_CPU_OFFLINE
1792 The virtual CPU is not online
1793 Sys::Virt::Domain::VCPU_INFO_CPU_UNAVAILABLE
1795 The virtual CPU placement is not available from this hypervisor
1796 OPEN GRAPHICS CONSTANTS
1798 The following constants are used when opening a connection to the guest
1799 graphics server
1800 Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH
1802 Skip authentication of the client
1803 OPEN CONSOLE CONSTANTS
1805 The following constants are used when opening a connection to the guest
1806 console
1807 Sys::Virt::Domain::OPEN_CONSOLE_FORCE
1809 Force opening of the console, disconnecting any other open session
1810 Sys::Virt::Domain::OPEN_CONSOLE_SAFE
1812 Check if the console driver supports safe operations
1813 OPEN CHANNEL CONSTANTS
1815 The following constants are used when opening a connection to the guest
1816 channel
1817 Sys::Virt::Domain::OPEN_CHANNEL_FORCE
1819 Force opening of the channel, disconnecting any other open session
1820 XML DUMP OPTIONS
1822 The following constants are used to control the information included in
1823 the XML configuration dump
1824 Sys::Virt::Domain::XML_INACTIVE
1826 Report the persistent inactive configuration for the guest, even if
1827 it is currently running.
1828 Sys::Virt::Domain::XML_SECURE
1830 Include security sensitive information in the XML dump, such as
1831 passwords.
1832 Sys::Virt::Domain::XML_UPDATE_CPU
1834 Update the CPU model definition to match the current executing
1835 state.
1836 Sys::Virt::Domain::XML_MIGRATABLE
1838 Update the XML to allow migration to older versions of libvirt
1839 DEVICE HOTPLUG OPTIONS
1841 The following constants are used to control device hotplug operations
1842 Sys::Virt::Domain::DEVICE_MODIFY_CURRENT
1844 Modify the domain in its current state
1845 Sys::Virt::Domain::DEVICE_MODIFY_LIVE
1847 Modify only the live state of the domain
1848 Sys::Virt::Domain::DEVICE_MODIFY_CONFIG
1850 Modify only the persistent config of the domain
1851 Sys::Virt::Domain::DEVICE_MODIFY_FORCE
1853 Force the device to be modified
1854 MEMORY OPTIONS
1856 The following constants are used to control memory change operations
1857 Sys::Virt::Domain::MEM_CURRENT
1859 Modify the current state
1860 Sys::Virt::Domain::MEM_LIVE
1862 Modify only the live state of the domain
1863 Sys::Virt::Domain::MEM_CONFIG
1865 Modify only the persistent config of the domain
1866 Sys::Virt::Domain::MEM_MAXIMUM
1868 Modify the maximum memory value
1869 CONFIG OPTIONS
1871 The following constants are used to control what configuration a domain
1872 update changes
1873 Sys::Virt::Domain::AFFECT_CURRENT
1875 Modify the current state
1876 Sys::Virt::Domain::AFFECT_LIVE
1878 Modify only the live state of the domain
1879 Sys::Virt::Domain::AFFECT_CONFIG
1881 Modify only the persistent config of the domain
1882 MIGRATE OPTIONS
1884 The following constants are used to control how migration is performed
1885 Sys::Virt::Domain::MIGRATE_LIVE
1887 Migrate the guest without interrupting its execution on the source
1888 host.
1889 Sys::Virt::Domain::MIGRATE_PEER2PEER
1891 Manage the migration process over a direct peer-2-peer connection
1892 between the source and destination host libvirtd daemons.
1893 Sys::Virt::Domain::MIGRATE_TUNNELLED
1895 Tunnel the migration data over the libvirt daemon connection,
1896 rather than the native hypervisor data transport. Requires
1897 PEER2PEER flag to be set.
1898 Sys::Virt::Domain::MIGRATE_PERSIST_DEST
1900 Make the domain persistent on the destination host, defining its
1901 configuration file upon completion of migration.
1902 Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE
1904 Remove the domain's persistent configuration after migration
1905 completes successfully.
1906 Sys::Virt::Domain::MIGRATE_PAUSED
1908 Do not re-start execution of the guest CPUs on the destination host
1909 after migration completes.
1910 Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK
1912 Copy the complete contents of the disk images during migration
1913 Sys::Virt::Domain::MIGRATE_NON_SHARED_INC
1915 Copy the incrementally changed contents of the disk images during
1916 migration
1917 Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION
1919 Do not allow changes to the virtual domain configuration while
1920 migration is taking place. This option is automatically implied if
1921 doing a peer-2-peer migration.
1922 Sys::Virt::Domain::MIGRATE_UNSAFE
1924 Migrate even if the compatibility check indicates the migration
1925 will be unsafe to the guest.
1926 Sys::Virt::Domain::MIGRATE_OFFLINE
1928 Migrate the guest config if the guest is not currently running
1929 Sys::Virt::Domain::MIGRATE_COMPRESSED
1931 Enable compression of the migration data stream
1932 Sys::Virt::Domain::MIGRATE_ABORT_ON_ERROR
1934 Abort if an I/O error occurs on the disk
1935 Sys::Virt::Domain::MIGRATE_AUTO_CONVERGE
1937 Force convergence of the migration operation by throttling guest
1938 runtime
1939 Sys::Virt::Domain::MIGRATE_RDMA_PIN_ALL
1941 Pin memory for RDMA transfer
1942 Sys::Virt::Domain::MIGRATE_POSTCOPY
1944 Enable support for post-copy migration
1945 Sys::Virt::Domain::MIGRATE_TLS
1947 Setting this flag will cause the migration to attempt to use the
1948 TLS environment configured by the hypervisor in order to perform
1949 the migration. If incorrectly configured on either source or
1950 destination, the migration will fail.
1951 Sys::Virt::Domain::MIGRATE_PARALLEL
1953 Send memory pages to the destination host through several network
1954 connections. See "Sys::Virt::Domain::MIGRATE_PARAM_PARALLEL_*"
1955 parameters for configuring the parallel migration.
1956 Sys::Virt::Domain::MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES
1958 Force the guest writes which happen when copying disk images for
1959 non-shared storage migration to be synchronously written to the
1960 destination. This ensures the storage migration converges for VMs
1961 doing heavy I/O on fast local storage and slow mirror.
1962 Sys::Virt::Domain::MIGRATE_POSTCOPY_RESUME
1964 Resume migration which failed in post-copy phase.
1965 Sys::Virt::Domain::MIGRATE_ZEROCOPY
1967 Attempt to avoid copying data. This is a request, not a guarantee
1968 and may apply to either one or both directions of data transfer at
1969 discretion of the hypervisor implementation.
1970 UNDEFINE CONSTANTS
1972 The following constants can be used when undefining virtual domain
1973 configurations
1974 Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE
1976 Also remove any managed save image when undefining the virtual
1977 domain
1978 Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA
1980 Also remove any snapshot metadata when undefining the virtual
1981 domain.
1982 Sys::Virt::Domain::UNDEFINE_NVRAM
1984 Also remove any NVRAM state file when undefining the virtual
1985 domain.
1986 Sys::Virt::Domain::UNDEFINE_KEEP_NVRAM
1988 keep NVRAM state file when undefining the virtual domain.
1989 Sys::Virt::Domain::UNDEFINE_CHECKPOINTS_METADATA
1991 Also remove any checkpoint metadata when undefining the virtual
1992 domain.
1993 Sys::Virt::Domain::UNDEFINE_TPM
1995 Also remove any TPM state when undefining the virtual domain.
1996 Sys::Virt::Domain::UNDEFINE_KEEP_TPM
1998 Keep TPM state when undefining the virtual domain.
1999 JOB TYPES
2001 The following constants describe the different background job types.
2002 Sys::Virt::Domain::JOB_NONE
2004 No job is active
2005 Sys::Virt::Domain::JOB_BOUNDED
2007 A job with a finite completion time is active
2008 Sys::Virt::Domain::JOB_UNBOUNDED
2010 A job with an unbounded completion time is active
2011 Sys::Virt::Domain::JOB_COMPLETED
2013 The job has finished, but isn't cleaned up
2014 Sys::Virt::Domain::JOB_FAILED
2016 The job has hit an error, but isn't cleaned up
2017 Sys::Virt::Domain::JOB_CANCELLED
2019 The job was aborted at user request, but isn't cleaned up
2020 MEMORY PARAMETERS
2022 The following constants are useful when getting/setting memory
2023 parameters for guests
2024 Sys::Virt::Domain::MEMORY_HARD_LIMIT
2026 The maximum memory the guest can use.
2027 Sys::Virt::Domain::MEMORY_SOFT_LIMIT
2029 The memory upper limit enforced during memory contention.
2030 Sys::Virt::Domain::MEMORY_MIN_GUARANTEE
2032 The minimum memory guaranteed to be reserved for the guest.
2033 Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT
2035 The maximum swap the guest can use.
2036 Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED
2038 The value of an unlimited memory parameter
2039 BLKIO PARAMETERS
2041 The following parameters control I/O tuning for the domain as a whole
2042 Sys::Virt::Domain::BLKIO_WEIGHT
2044 The I/O weight parameter
2045 Sys::Virt::Domain::BLKIO_DEVICE_WEIGHT
2047 The per-device I/O weight parameter
2048 Sys::Virt::Domain::BLKIO_DEVICE_READ_BPS
2050 The per-device I/O bytes read per second
2051 Sys::Virt::Domain::BLKIO_DEVICE_READ_IOPS
2053 The per-device I/O operations read per second
2054 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_BPS
2056 The per-device I/O bytes write per second
2057 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_IOPS
2059 The per-device I/O operations write per second
2060 BLKIO TUNING PARAMETERS
2062 The following parameters control I/O tuning for an individual guest
2063 disk.
2064 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC
2066 The total bytes processed per second.
2067 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC
2069 The bytes read per second.
2070 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC
2072 The bytes written per second.
2073 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC
2075 The total I/O operations processed per second.
2076 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC
2078 The I/O operations read per second.
2079 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC
2081 The I/O operations written per second.
2082 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX
2084 The maximum total bytes processed per second.
2085 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX
2087 The maximum bytes read per second.
2088 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX
2090 The maximum bytes written per second.
2091 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX
2093 The maximum total I/O operations processed per second.
2094 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX
2096 The maximum I/O operations read per second.
2097 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX
2099 The maximum I/O operations written per second.
2100 Sys::Virt::Domain::BLOCK_IOTUNE_SIZE_IOPS_SEC
2102 The maximum I/O operations per second
2103 Sys::Virt::Domain::BLOCK_IOTUNE_GROUP_NAME
2105 A string representing a group name to allow sharing of I/O
2106 throttling quota between multiple drives
2107 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX_LENGTH
2109 The duration in seconds allowed for maximum total bytes processed
2110 per second.
2111 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX_LENGTH
2113 The duration in seconds allowed for maximum bytes read per second.
2114 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX_LENGTH
2116 The duration in seconds allowed for maximum bytes written per
2117 second.
2118 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX_LENGTH
2120 The duration in seconds allowed for maximum total I/O operations
2121 processed per second.
2122 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX_LENGTH
2124 The duration in seconds allowed for maximum I/O operations read per
2125 second.
2126 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX_LENGTH
2128 The duration in seconds allowed for maximum I/O operations written
2129 per second.
2130 SCHEDULER CONSTANTS
2132 Sys::Virt::Domain::SCHEDULER_CAP
2133 The VM cap tunable
2134 Sys::Virt::Domain::SCHEDULER_CPU_SHARES
2136 The CPU shares tunable
2137 Sys::Virt::Domain::SCHEDULER_LIMIT
2139 The VM limit tunable
2140 Sys::Virt::Domain::SCHEDULER_RESERVATION
2142 The VM reservation tunable
2143 Sys::Virt::Domain::SCHEDULER_SHARES
2145 The VM shares tunable
2146 Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD
2148 The VCPU period tunable
2149 Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA
2151 The VCPU quota tunable
2152 Sys::Virt::Domain::SCHEDULER_GLOBAL_PERIOD
2154 The VM global period tunable
2155 Sys::Virt::Domain::SCHEDULER_GLOBAL_QUOTA
2157 The VM global quota tunable
2158 Sys::Virt::Domain::SCHEDULER_WEIGHT
2160 The VM weight tunable
2161 NUMA PARAMETERS
2163 The following constants are useful when getting/setting the guest NUMA
2164 memory policy
2165 Sys::Virt::Domain::NUMA_MODE
2167 The NUMA policy mode
2168 Sys::Virt::Domain::NUMA_NODESET
2170 The NUMA nodeset mask
2171 The following constants are useful when interpreting the
2173 "Sys::Virt::Domain::NUMA_MODE" parameter value
2174 Sys::Virt::Domain::NUMATUNE_MEM_STRICT
2176 Allocation is mandatory from the mask nodes
2177 Sys::Virt::Domain::NUMATUNE_MEM_PREFERRED
2179 Allocation is preferred from the masked nodes
2180 Sys::Virt::Domain::NUMATUNE_MEM_INTERLEAVE
2182 Allocation is interleaved across all masked nodes
2183 Sys::Virt::Domain::NUMATUNE_MEM_RESTRICTIVE
2185 Allocation is determined by the host using the masked nodes.
2186 INTERFACE PARAMETERS
2188 The following constants are useful when getting/setting the per network
2189 interface tunable parameters
2190 Sys::Virt::Domain::BANDWIDTH_IN_AVERAGE
2192 The average inbound bandwidth
2193 Sys::Virt::Domain::BANDWIDTH_IN_PEAK
2195 The peak inbound bandwidth
2196 Sys::Virt::Domain::BANDWIDTH_IN_BURST
2198 The burstable inbound bandwidth
2199 Sys::Virt::Domain::BANDWIDTH_IN_FLOOR
2201 The minimum inbound bandwidth
2202 Sys::Virt::Domain::BANDWIDTH_OUT_AVERAGE
2204 The average outbound bandwidth
2205 Sys::Virt::Domain::BANDWIDTH_OUT_PEAK
2207 The peak outbound bandwidth
2208 Sys::Virt::Domain::BANDWIDTH_OUT_BURST
2210 The burstable outbound bandwidth
2211 PERF EVENTS
2213 The following constants defined performance events which can be
2214 monitored for a guest
2215 Sys::Virt::Domain::PERF_PARAM_CMT
2217 The CMT event counter which can be used to measure the usage of
2218 cache (bytes) by applications running on the platform. It
2219 corresponds to the "perf.cmt" field in the *Stats APIs.
2220 Sys::Virt::Domain::PERF_PARAM_MBML
2222 The MBML event counter which can be used to monitor the amount of
2223 data (bytes/s) sent through the memory controller on the socket.
2224 It corresponds to the "perf.mbml" field in the *Stats APIs.
2225 Sys::Virt::Domain::PERF_PARAM_MBMT
2227 The MBMT event counter which can be used to monitor total system
2228 bandwidth (bytes/s) from one level of cache to another. It
2229 corresponds to the "perf.mbmt" field in the *Stats APIs.
2230 Sys::Virt::Domain::PERF_PARAM_CACHE_MISSES
2232 The cache_misses perf event counter which can be used to measure
2233 the count of cache misses by applications running on the platform.
2234 It corresponds to the "perf.cache_misses" field in the *Stats APIs.
2235 Sys::Virt::Domain::PERF_PARAM_CACHE_REFERENCES
2237 The cache_references perf event counter which can be used to
2238 measure the count of cache hits by applications running on the
2239 platform. It corresponds to the "perf.cache_references" field in
2240 the *Stats APIs.
2241 Sys::Virt::Domain::PERF_PARAM_CPU_CYCLES
2243 The cpu_cycles perf event counter which can be used to measure how
2244 many cpu cycles one instruction needs. It corresponds to the
2245 "perf.cpu_cycles" field in the *Stats APIs.
2246 Sys::Virt::Domain::PERF_PARAM_INSTRUCTIONS
2248 The instructions perf event counter which can be used to measure
2249 the count of instructions by applications running on the platform.
2250 It corresponds to the "perf.instructions" field in the *Stats APIs.
2251 Sys::Virt::Domain::PERF_PARAM_BRANCH_INSTRUCTIONS
2253 The branch_instructions perf event counter which can be used to
2254 measure the count of instructions by applications running on the
2255 platform. It corresponds to the "perf.branch_instructions" field in
2256 the *Stats APIs.
2257 Sys::Virt::Domain::PERF_PARAM_BRANCH_MISSES
2259 The branch_misses perf event which can be used to measure the count
2260 of branch misses by applications running on the platform. It
2261 corresponds to the "perf.branch_misses" field in the *Stats APIs.
2262 Sys::Virt::Domain::PERF_PARAM_BUS_CYCLES The bus_cycles perf event
2264 counter which can be used to measure the count of bus cycles by
2265 applications running on the platform. It corresponds to the
2266 "perf.bus_cycles" field in the *Stats APIs.
2267 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_FRONTEND The
2268 stalled_cycles_frontend perf event counter which can be used to measure
2269 the count of stalled cpu cycles in the frontend of the instruction
2270 processor pipeline by applications running on the platform. It
2271 corresponds to the "perf.stalled_cycles_frontend" field in the *Stats
2272 APIs.
2273 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_BACKEND The
2274 stalled_cycles_backend perf event counter which can be used to measure
2275 the count of stalled cpu cycles in the backend of the instruction
2276 processor pipeline by application running on the platform. It
2277 corresponds to the "perf.stalled_cycles_backend" field in the *Stats
2278 APIs.
2279 Sys::Virt::Domain::PERF_PARAM_REF_CPU_CYCLES The ref_cpu_cycles perf
2280 event counter which can be used to measure the count of total cpu
2281 cycles not affected by CPU frequency scaling by applications running on
2282 the platform. It corresponds to the "perf.ref_cpu_cycles" field in the
2283 *Stats APIs.
2284 Sys::Virt::Domain::PERF_PARAM_CPU_CLOCK The cpu_clock perf event
2285 counter which can be used to measure the count of cpu clock time by
2286 applications running on the platform. It corresponds to the
2287 "perf.cpu_clock" field in the *Stats APIs.
2288 Sys::Virt::Domain::PERF_PARAM_TASK_CLOCK The task_clock perf event
2289 counter which can be used to measure the count of task clock time by
2290 applications running on the platform. It corresponds to the
2291 "perf.task_clock" field in the *Stats APIs.
2292 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS The page_faults perf event
2293 counter which can be used to measure the count of page faults by
2294 applications running on the platform. It corresponds to the
2295 "perf.page_faults" field in the *Stats APIs.
2296 Sys::Virt::Domain::PERF_PARAM_CONTEXT_SWITCHES The context_switches
2297 perf event counter which can be used to measure the count of context
2298 switches by applications running on the platform. It corresponds to the
2299 "perf.context_switches" field in the *Stats APIs.
2300 Sys::Virt::Domain::PERF_PARAM_CPU_MIGRATIONS The cpu_migrations perf
2301 event counter which can be used to measure the count of cpu migrations
2302 by applications running on the platform. It corresponds to the
2303 "perf.cpu_migrations" field in the *Stats APIs.
2304 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MIN The page_faults_min perf
2305 event counter which can be used to measure the count of minor page
2306 faults by applications running on the platform. It corresponds to the
2307 "perf.page_faults_min" field in the *Stats APIs.
2308 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MAJ The page_faults_maj perf
2309 event counter which can be used to measure the count of major page
2310 faults by applications running on the platform. It corresponds to the
2311 "perf.page_faults_maj" field in the *Stats APIs.
2312 Sys::Virt::Domain::PERF_PARAM_ALIGNMENT_FAULTS The alignment_faults
2313 perf event counter which can be used to measure the count of alignment
2314 faults by applications running on the platform. It corresponds to the
2315 "perf.alignment_faults" field in the *Stats APIs.
2316 Sys::Virt::Domain::PERF_PARAM_EMULATION_FAULTS The emulation_faults
2317 perf event counter which can be used to measure the count of emulation
2318 faults by applications running on the platform. It corresponds to the
2319 "perf.emulation_faults" field in the *Stats APIs.
2320 IOTHREAD STATS
2322 The following constants defined IOThread statistics which can be
2323 monitored for a guest
2324 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_MAX_NS
2326 The maximum polling time that can be used by polling algorithm in
2327 ns. The polling time starts at 0 (zero) and is the time spent by
2328 the guest to process IOThread data before returning the CPU to the
2329 host. The polling time will be dynamically modified over time based
2330 on the poll_grow and poll_shrink parameters provided.
2331 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_GROW
2333 This provides a value for the dynamic polling adjustment algorithm
2334 to use to grow its polling interval up to the poll_max_ns value.
2335 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_SHRINK
2337 This provides a value for the dynamic polling adjustment algorithm
2338 to use to shrink its polling interval when the polling interval
2339 exceeds the poll_max_ns value.
2340 Sys::Virt::Domain::IOTHREAD_PARAM_THREAD_POOL_MIN
2342 Sets the lower bound for thread pool size. A value of -1 disables
2343 this bound leaving hypervisor use its default value, though this
2344 value is not accepted for running domains. Due to internal
2345 implementation it's recommended to set lower and upper bounds
2346 separately.
2347 Sys::Virt::Domain::IOTHREAD_PARAM_THREAD_POOL_MAX
2349 Sets the upper bound for thread pool size. A value of -1 disables
2350 this bound leaving hypervisor use its default value, though this
2351 value is not accepted for running domains. Since the upper band has
2352 to be equal to or greater than lower bound value of 0 is not
2353 accepted. Due to internal implementation it's recommended to set
2354 lower and upper bounds separately.
2355 VCPU FLAGS
2357 The following constants are useful when getting/setting the VCPU count
2358 for a guest
2359 Sys::Virt::Domain::VCPU_LIVE
2361 Flag to request the live value
2362 Sys::Virt::Domain::VCPU_CONFIG
2364 Flag to request the persistent config value
2365 Sys::Virt::Domain::VCPU_CURRENT
2367 Flag to request the current config value
2368 Sys::Virt::Domain::VCPU_MAXIMUM
2370 Flag to request adjustment of the maximum vCPU value
2371 Sys::Virt::Domain::VCPU_GUEST
2373 Flag to request the guest VCPU mask
2374 Sys::Virt::Domain::VCPU_HOTPLUGGABLE
2376 Flag to make vcpus added hot(un)pluggable
2377 STATE CHANGE EVENTS
2379 The following constants allow domain state change events to be
2380 interpreted. The events contain both a state change, and a reason.
2381 Sys::Virt::Domain::EVENT_DEFINED
2383 Indicates that a persistent configuration has been defined for the
2384 domain.
2385 Sys::Virt::Domain::EVENT_DEFINED_ADDED
2387 The defined configuration is newly added
2388 Sys::Virt::Domain::EVENT_DEFINED_UPDATED
2390 The defined configuration is an update to an existing
2391 configuration
2392 Sys::Virt::Domain::EVENT_DEFINED_RENAMED
2394 The defined configuration is a rename of an existing
2395 configuration
2396 Sys::Virt::Domain::EVENT_DEFINED_FROM_SNAPSHOT
2398 The defined configuration was restored from a snapshot
2399 Sys::Virt::Domain::EVENT_RESUMED
2401 The domain has resumed execution
2402 Sys::Virt::Domain::EVENT_RESUMED_MIGRATED
2404 The domain resumed because migration has completed. This is
2405 emitted on the destination host.
2406 Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED
2408 The domain resumed because the admin unpaused it.
2409 Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT
2411 The domain resumed because it was restored from a snapshot
2412 Sys::Virt::Domain::EVENT_RESUMED_POSTCOPY
2414 The domain resumed but post-copy is running in background
2415 Sys::Virt::Domain::EVENT_RESUMED_POSTCOPY_FAILED
2417 The domain is running, but migration failed in post-copy.
2418 Sys::Virt::Domain::EVENT_STARTED
2420 The domain has started running
2421 Sys::Virt::Domain::EVENT_STARTED_BOOTED
2423 The domain was booted from shutoff state
2424 Sys::Virt::Domain::EVENT_STARTED_MIGRATED
2426 The domain started due to an incoming migration
2427 Sys::Virt::Domain::EVENT_STARTED_RESTORED
2429 The domain was restored from saved state file
2430 Sys::Virt::Domain::EVENT_STARTED_FROM_SNAPSHOT
2432 The domain was restored from a snapshot
2433 Sys::Virt::Domain::EVENT_STARTED_WAKEUP
2435 The domain was woken up from suspend
2436 Sys::Virt::Domain::EVENT_STOPPED
2438 The domain has stopped running
2439 Sys::Virt::Domain::EVENT_STOPPED_CRASHED
2441 The domain stopped because guest operating system has crashed
2442 Sys::Virt::Domain::EVENT_STOPPED_DESTROYED
2444 The domain stopped because administrator issued a destroy
2445 command.
2446 Sys::Virt::Domain::EVENT_STOPPED_FAILED
2448 The domain stopped because of a fault in the host
2449 virtualization environment.
2450 Sys::Virt::Domain::EVENT_STOPPED_MIGRATED
2452 The domain stopped because it was migrated to another machine.
2453 Sys::Virt::Domain::EVENT_STOPPED_SAVED
2455 The domain was saved to a state file
2456 Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN
2458 The domain stopped due to graceful shutdown of the guest.
2459 Sys::Virt::Domain::EVENT_STOPPED_FROM_SNAPSHOT
2461 The domain was stopped due to a snapshot
2462 Sys::Virt::Domain::EVENT_SHUTDOWN
2464 The domain has shutdown but is not yet stopped
2465 Sys::Virt::Domain::EVENT_SHUTDOWN_FINISHED
2467 The domain finished shutting down
2468 Sys::Virt::Domain::EVENT_SHUTDOWN_HOST
2470 The domain shutdown due to host trigger
2471 Sys::Virt::Domain::EVENT_SHUTDOWN_GUEST
2473 The domain shutdown due to guest trigger
2474 Sys::Virt::Domain::EVENT_SUSPENDED
2476 The domain has stopped executing, but still exists
2477 Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED
2479 The domain has been suspended due to offline migration
2480 Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED
2482 The domain has been suspended due to administrator pause
2483 request.
2484 Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR
2486 The domain has been suspended due to a block device I/O error.
2487 Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT
2489 The domain has been suspended due to resume from snapshot
2490 Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG
2492 The domain has been suspended due to the watchdog triggering
2493 Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED
2495 The domain has been suspended due to restore from saved state
2496 Sys::Virt::Domain::EVENT_SUSPENDED_API_ERROR
2498 The domain has been suspended due to an API error
2499 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY
2501 The domain has been suspended for post-copy migration
2502 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY_FAILED
2504 The domain has been suspended due post-copy migration failing
2505 Sys::Virt::Domain::EVENT_UNDEFINED
2507 The persistent configuration has gone away
2508 Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED
2510 The domain configuration has gone away due to it being removed
2511 by administrator.
2512 Sys::Virt::Domain::EVENT_UNDEFINED_RENAMED
2514 The undefined configuration is a rename of an existing
2515 configuration
2516 Sys::Virt::Domain::EVENT_PMSUSPENDED
2518 The domain has stopped running
2519 Sys::Virt::Domain::EVENT_PMSUSPENDED_MEMORY
2521 The domain has suspend to RAM.
2522 Sys::Virt::Domain::EVENT_PMSUSPENDED_DISK
2524 The domain has suspend to Disk.
2525 Sys::Virt::Domain::EVENT_CRASHED
2527 The domain has crashed
2528 Sys::Virt::Domain::EVENT_CRASHED_PANICKED
2530 The domain has crashed due to a kernel panic
2531 Sys::Virt::Domain::EVENT_CRASHED_CRASHLOADED
2533 The domain has crashed and reloaded itself
2534 EVENT ID CONSTANTS
2536 Sys::Virt::Domain::EVENT_ID_LIFECYCLE
2537 Domain lifecycle events
2538 Sys::Virt::Domain::EVENT_ID_REBOOT
2540 Soft / warm reboot events
2541 Sys::Virt::Domain::EVENT_ID_RTC_CHANGE
2543 RTC clock adjustments
2544 Sys::Virt::Domain::EVENT_ID_IO_ERROR
2546 File IO errors, typically from disks
2547 Sys::Virt::Domain::EVENT_ID_WATCHDOG
2549 Watchdog device triggering
2550 Sys::Virt::Domain::EVENT_ID_GRAPHICS
2552 Graphics client connections.
2553 Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON
2555 File IO errors, typically from disks, with a root cause
2556 Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR
2558 Errors from the virtualization control channel
2559 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB
2561 Completion status of asynchronous block jobs, identified by source
2562 file name.
2563 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB_2
2565 Completion status of asynchronous block jobs, identified by target
2566 device name.
2567 Sys::Virt::Domain::EVENT_ID_DISK_CHANGE
2569 Changes in disk media
2570 Sys::Virt::Domain::EVENT_ID_TRAY_CHANGE
2572 CDROM media tray state
2573 Sys::Virt::Domain::EVENT_ID_PMSUSPEND
2575 Power management initiated suspend to RAM
2576 Sys::Virt::Domain::EVENT_ID_PMSUSPEND_DISK
2578 Power management initiated suspend to Disk
2579 Sys::Virt::Domain::EVENT_ID_PMWAKEUP
2581 Power management initiated wakeup
2582 Sys::Virt::Domain::EVENT_ID_BALLOON_CHANGE
2584 Balloon target changes
2585 Sys::Virt::Domain::EVENT_ID_DEVICE_ADDED
2587 Asynchronous guest device addition
2588 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVED
2590 Asynchronous guest device removal
2591 Sys::Virt::Domain::EVENT_ID_TUNABLE
2593 Changes of any domain tuning parameters. The callback will be
2594 provided with a hash listing all changed parameters. The later
2595 DOMAIN TUNABLE constants can be useful when accessing the hash keys
2596 Sys::Virt::Domain::EVENT_ID_AGENT_LIFECYCLE
2598 Domain guest agent lifecycle events. The "state" parameter to the
2599 callback will match one of the constants
2600 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_CONNECTED
2602 The agent is now connected
2603 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_DISCONNECTED
2605 The agent is now disconnected
2606 The second parameter, "reason", matches one of the following
2608 constants
2609 Sys::Virt::Domain::EVENT_ID_MIGRATION_ITERATION
2611 Domain migration progress iteration. The "iteration" parameter to
2612 the callback will specify the number of iterations migration has
2613 made over guest RAM.
2614 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_UNKNOWN
2616 The reason is unknown
2617 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_DOMAIN_STARTED
2619 The domain was initially booted
2620 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_CHANNEL
2622 The channel on a running guest changed state
2623 Sys::Virt::Domain::EVENT_ID_JOB_COMPLETED
2625 Domain background job completion notification. The callback
2626 provides a hash containing the job stats. The keys in the hash are
2627 the same as those used with the Sys::Virt::Domain::get_job_stats()
2628 method.
2629 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVAL_FAILED
2631 Guest device removal has failed.
2632 Sys::Virt::Domain::EVENT_ID_METADATA_CHANGE
2634 The domain metadata has changed
2635 Sys::Virt::Domain::EVENT_ID_BLOCK_THRESHOLD
2637 The event occurs when the hypervisor detects that the given storage
2638 element was written beyond the point specified by threshold. The
2639 event is useful for thin-provisioned storage.
2640 Sys::Virt::Domain::EVENT_ID_MEMORY_FAILURE
2642 The event occurs when the hypervisor detects hardware memory
2643 corruption.
2644 Sys::Virt::Domain::EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE
2646 The event occurs when the guest accepts a request to change the
2647 memory device size.
2648 IO ERROR EVENT CONSTANTS
2650 These constants describe what action was taken due to the IO error.
2651 Sys::Virt::Domain::EVENT_IO_ERROR_NONE
2653 No action was taken, the error was ignored & reported as success to
2654 guest
2655 Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE
2657 The guest is paused since the error occurred
2658 Sys::Virt::Domain::EVENT_IO_ERROR_REPORT
2660 The error has been reported to the guest OS
2661 WATCHDOG EVENT CONSTANTS
2663 These constants describe what action was taken due to the watchdog
2664 firing
2665 Sys::Virt::Domain::EVENT_WATCHDOG_NONE
2667 No action was taken, the watchdog was ignored
2668 Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE
2670 The guest is paused since the watchdog fired
2671 Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF
2673 The guest is powered off after the watchdog fired
2674 Sys::Virt::Domain::EVENT_WATCHDOG_RESET
2676 The guest is reset after the watchdog fired
2677 Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN
2679 The guest attempted to gracefully shutdown after the watchdog fired
2680 Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG
2682 No action was taken, the watchdog was logged
2683 Sys::Virt::Domain::EVENT_WATCHDOG_INJECTNMI
2685 An NMI was injected into the guest after the watchdog fired
2686 GRAPHICS EVENT PHASE CONSTANTS
2688 These constants describe the phase of the graphics connection
2689 Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT
2691 The initial client connection
2692 Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE
2694 The client has been authenticated & the connection is running
2695 Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT
2697 The client has disconnected
2698 GRAPHICS EVENT ADDRESS CONSTANTS
2700 These constants describe the format of the address
2701 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4
2703 An IPv4 address
2704 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6
2706 An IPv6 address
2707 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX
2709 An UNIX socket path address
2710 DISK CHANGE EVENT CONSTANTS
2712 These constants describe the reason for a disk change event
2713 Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START
2715 The disk media was cleared, as its source was missing when
2716 attempting to start the guest
2717 Sys::Virt::Domain::EVENT_DISK_DROP_MISSING_ON_START
2719 The disk device was dropped, as its source was missing when
2720 attempting to start the guest
2721 TRAY CHANGE CONSTANTS
2723 These constants describe the reason for a tray change event
2724 Sys::Virt::Domain::EVENT_TRAY_CHANGE_CLOSE
2726 The tray was closed
2727 Sys::Virt::Domain::EVENT_TRAY_CHANGE_OPEN
2729 The tray was opened
2730 DOMAIN BLOCK JOB TYPE CONSTANTS
2732 The following constants identify the different types of domain block
2733 jobs
2734 Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN
2736 An unknown block job type
2737 Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL
2739 The block pull job type
2740 Sys::Virt::Domain::BLOCK_JOB_TYPE_COPY
2742 The block copy job type
2743 Sys::Virt::Domain::BLOCK_JOB_TYPE_COMMIT
2745 The block commit job type
2746 Sys::Virt::Domain::BLOCK_JOB_TYPE_ACTIVE_COMMIT
2748 The block active commit job type
2749 Sys::Virt::Domain::BLOCK_JOB_TYPE_BACKUP
2751 The block backup job type
2752 DOMAIN BLOCK JOB COMPLETION CONSTANTS
2754 The following constants can be used to determine the completion status
2755 of a block job
2756 Sys::Virt::Domain::BLOCK_JOB_COMPLETED
2758 A successfully completed block job
2759 Sys::Virt::Domain::BLOCK_JOB_FAILED
2761 An unsuccessful block job
2762 Sys::Virt::Domain::BLOCK_JOB_CANCELED
2764 A block job canceled by the user
2765 Sys::Virt::Domain::BLOCK_JOB_READY
2767 A block job is running
2768 DOMAIN BLOCK REBASE CONSTANTS
2770 The following constants are useful when rebasing block devices
2771 Sys::Virt::Domain::BLOCK_REBASE_SHALLOW
2773 Limit copy to top of source backing chain
2774 Sys::Virt::Domain::BLOCK_REBASE_REUSE_EXT
2776 Reuse existing external file for copy
2777 Sys::Virt::Domain::BLOCK_REBASE_COPY_RAW
2779 Make destination file raw
2780 Sys::Virt::Domain::BLOCK_REBASE_COPY
2782 Start a copy job
2783 Sys::Virt::Domain::BLOCK_REBASE_COPY_DEV
2785 Treat destination as a block device instead of file
2786 Sys::Virt::Domain::BLOCK_REBASE_RELATIVE
2788 Keep backing chain referenced using relative names
2789 DOMAIN BLOCK COPY CONSTANTS
2791 The following constants are useful when copying block devices
2792 Sys::Virt::Domain::BLOCK_COPY_SHALLOW
2794 Limit copy to top of source backing chain
2795 Sys::Virt::Domain::BLOCK_COPY_REUSE_EXT
2797 Reuse existing external file for copy
2798 Sys::Virt::Domain::BLOCK_COPY_TRANSIENT_JOB
2800 Don't force usage of recoverable job for the copy operation
2801 Sys::Virt::Domain::BLOCK_COPY_SYNCHRONOUS_WRITES
2803 Force the copy job to synchronously propagate guest writes into the
2804 destination image, so that the copy is guaranteed to converge
2805 DOMAIN BLOCK JOB ABORT CONSTANTS
2807 The following constants are useful when aborting job copy jobs
2808 Sys::Virt::Domain::BLOCK_JOB_ABORT_ASYNC
2810 Request only, do not wait for completion
2811 Sys::Virt::Domain::BLOCK_JOB_ABORT_PIVOT
2813 Pivot to mirror when ending a copy job
2814 DOMAIN BLOCK COMMIT JOB CONSTANTS
2816 The following constants are useful with block commit job types
2817 Sys::Virt::Domain::BLOCK_COMMIT_DELETE
2819 Delete any files that are invalid after commit
2820 Sys::Virt::Domain::BLOCK_COMMIT_SHALLOW
2822 NULL base means next backing file, not whole chain
2823 Sys::Virt::Domain::BLOCK_COMMIT_ACTIVE
2825 Allow two phase commit when top is active layer
2826 Sys::Virt::Domain::BLOCK_COMMIT_RELATIVE
2828 Keep backing chain referenced using relative names
2829 DOMAIN SAVE / RESTORE FLAG CONSTANTS
2831 The following constants can be used when saving or restoring virtual
2832 machines
2833 Sys::Virt::Domain::SAVE_BYPASS_CACHE
2835 Do not use OS I/O cache when saving state.
2836 Sys::Virt::Domain::SAVE_PAUSED
2838 Mark the saved state as paused to prevent the guest CPUs starting
2839 upon restore.
2840 Sys::Virt::Domain::SAVE_RUNNING
2842 Mark the saved state as running to allow the guest CPUs to start
2843 upon restore.
2844 Sys::Virt::Domain::SAVE_RESET_NVRAM
2846 Reset the firmware NVRAM state from its original template
2847 SAVE / RESTORE PARAMETER CONSTANTS
2849 Sys::Virt::Domain::SAVE_PARAM_FILE
2850 Specify the save state file to save to or restore from.
2851 Sys::Virt::Domain::SAVE_PARAM_DXML
2853 Used to adjust guest xml on restore, e.g. to alter a device while
2854 domain is stopped.
2855 DOMAIN CORE DUMP CONSTANTS
2857 The following constants can be used when triggering domain core dumps
2858 Sys::Virt::Domain::DUMP_LIVE
2860 Do not pause execution while dumping the guest
2861 Sys::Virt::Domain::DUMP_CRASH
2863 Crash the guest after completing the core dump
2864 Sys::Virt::Domain::DUMP_BYPASS_CACHE
2866 Do not use OS I/O cache when writing core dump
2867 Sys::Virt::Domain::DUMP_RESET
2869 Reset the virtual machine after finishing the dump
2870 Sys::Virt::Domain::DUMP_MEMORY_ONLY
2872 Only include guest RAM in the dump, not the device state
2873 DESTROY CONSTANTS
2875 The following constants are useful when terminating guests using the
2876 "destroy" API.
2877 Sys::Virt::Domain::DESTROY_DEFAULT
2879 Destroy the guest using the default approach
2880 Sys::Virt::Domain::DESTROY_GRACEFUL
2882 Destroy the guest in a graceful manner
2883 Sys::Virt::Domain::DESTROY_REMOVE_LOGS
2885 Delete log files associated with the guest
2886 SHUTDOWN CONSTANTS
2888 The following constants are useful when requesting that a guest
2889 terminate using the "shutdown" API
2890 Sys::Virt::Domain::SHUTDOWN_DEFAULT
2892 Shutdown using the hypervisor's default mechanism
2893 Sys::Virt::Domain::SHUTDOWN_GUEST_AGENT
2895 Shutdown by issuing a command to a guest agent
2896 Sys::Virt::Domain::SHUTDOWN_ACPI_POWER_BTN
2898 Shutdown by injecting an ACPI power button press
2899 Sys::Virt::Domain::SHUTDOWN_INITCTL
2901 Shutdown by talking to initctl (containers only)
2902 Sys::Virt::Domain::SHUTDOWN_SIGNAL
2904 Shutdown by sending SIGTERM to the init process
2905 Sys::Virt::Domain::SHUTDOWN_PARAVIRT
2907 Shutdown by issuing a paravirt power control command
2908 REBOOT CONSTANTS
2910 The following constants are useful when requesting that a guest
2911 terminate using the "reboot" API
2912 Sys::Virt::Domain::REBOOT_DEFAULT
2914 Reboot using the hypervisor's default mechanism
2915 Sys::Virt::Domain::REBOOT_GUEST_AGENT
2917 Reboot by issuing a command to a guest agent
2918 Sys::Virt::Domain::REBOOT_ACPI_POWER_BTN
2920 Reboot by injecting an ACPI power button press
2921 Sys::Virt::Domain::REBOOT_INITCTL
2923 Reboot by talking to initctl (containers only)
2924 Sys::Virt::Domain::REBOOT_SIGNAL
2926 Reboot by sending SIGHUP to the init process
2927 Sys::Virt::Domain::REBOOT_PARAVIRT
2929 Reboot by issuing a paravirt power control command
2930 METADATA CONSTANTS
2932 The following constants are useful when reading/writing metadata about
2933 a guest
2934 Sys::Virt::Domain::METADATA_TITLE
2936 The short human friendly title of the guest
2937 Sys::Virt::Domain::METADATA_DESCRIPTION
2939 The long free text description of the guest
2940 Sys::Virt::Domain::METADATA_ELEMENT
2942 The structured metadata elements for the guest
2943 DISK ERROR CONSTANTS
2945 The following constants are useful when interpreting disk error codes
2946 Sys::Virt::Domain::DISK_ERROR_NONE
2948 No error
2949 Sys::Virt::Domain::DISK_ERROR_NO_SPACE
2951 The host storage has run out of free space
2952 Sys::Virt::Domain::DISK_ERROR_UNSPEC
2954 An unspecified error has occurred.
2955 MEMORY STATISTIC CONSTANTS
2957 Sys::Virt::Domain::MEMORY_STAT_SWAP_IN
2958 Swap in
2959 Sys::Virt::Domain::MEMORY_STAT_SWAP_OUT
2961 Swap out
2962 Sys::Virt::Domain::MEMORY_STAT_MINOR_FAULT
2964 Minor faults
2965 Sys::Virt::Domain::MEMORY_STAT_MAJOR_FAULT
2967 Major faults
2968 Sys::Virt::Domain::MEMORY_STAT_RSS
2970 Resident memory
2971 Sys::Virt::Domain::MEMORY_STAT_UNUSED
2973 Unused memory
2974 Sys::Virt::Domain::MEMORY_STAT_AVAILABLE
2976 Available memory
2977 Sys::Virt::Domain::MEMORY_STAT_ACTUAL_BALLOON
2979 Actual balloon limit
2980 Sys::Virt::Domain::MEMORY_STAT_USABLE
2982 Amount of usable memory
2983 Sys::Virt::Domain::MEMORY_STAT_LAST_UPDATE
2985 Time of last stats refresh from guest
2986 Sys::Virt::Domain::MEMORY_STAT_DISK_CACHES
2988 Disk cache size
2989 Sys::Virt::Domain::MEMORY_STAT_HUGETLB_PGALLOC
2991 The amount of successful huge page allocations
2992 Sys::Virt::Domain::MEMORY_STAT_HUGETLB_PGFAIL
2994 The amount of failed huge page allocations
2995 DOMAIN LIST CONSTANTS
2997 The following constants can be used when listing domains
2998 Sys::Virt::Domain::LIST_ACTIVE
3000 Only list domains that are currently active (running, or paused)
3001 Sys::Virt::Domain::LIST_AUTOSTART
3003 Only list domains that are set to automatically start on boot
3004 Sys::Virt::Domain::LIST_HAS_SNAPSHOT
3006 Only list domains that have a stored snapshot
3007 Sys::Virt::Domain::LIST_INACTIVE
3009 Only list domains that are currently inactive (shutoff, saved)
3010 Sys::Virt::Domain::LIST_MANAGEDSAVE
3012 Only list domains that have current managed save state
3013 Sys::Virt::Domain::LIST_NO_AUTOSTART
3015 Only list domains that are not set to automatically start on boto
3016 Sys::Virt::Domain::LIST_NO_MANAGEDSAVE
3018 Only list domains that do not have any managed save state
3019 Sys::Virt::Domain::LIST_NO_SNAPSHOT
3021 Only list domains that do not have a stored snapshot
3022 Sys::Virt::Domain::LIST_OTHER
3024 Only list domains that are not running, paused or shutoff
3025 Sys::Virt::Domain::LIST_PAUSED
3027 Only list domains that are paused
3028 Sys::Virt::Domain::LIST_PERSISTENT
3030 Only list domains which have a persistent config
3031 Sys::Virt::Domain::LIST_RUNNING
3033 Only list domains that are currently running
3034 Sys::Virt::Domain::LIST_SHUTOFF
3036 Only list domains that are currently shutoff
3037 Sys::Virt::Domain::LIST_TRANSIENT
3039 Only list domains that do not have a persistent config
3040 Sys::Virt::Domain::LIST_HAS_CHECKPOINT
3042 Only list domains that have a stored checkpoint
3043 Sys::Virt::Domain::LIST_NO_CHECKPOINT
3045 Only list domains that do not have a stored checkpoint
3046 SEND KEY CONSTANTS
3048 The following constants are to be used with the "send_key" API
3049 Sys::Virt::Domain::SEND_KEY_MAX_KEYS
3051 The maximum number of keys that can be sent in a single call to
3052 "send_key"
3053 BLOCK STATS CONSTANTS
3055 The following constants provide the names of well known block stats
3056 fields
3057 Sys::Virt::Domain::BLOCK_STATS_ERRS
3059 The number of I/O errors
3060 Sys::Virt::Domain::BLOCK_STATS_FLUSH_REQ
3062 The number of flush requests
3063 Sys::Virt::Domain::BLOCK_STATS_FLUSH_TOTAL_TIMES
3065 The time spent processing flush requests
3066 Sys::Virt::Domain::BLOCK_STATS_READ_BYTES
3068 The amount of data read
3069 Sys::Virt::Domain::BLOCK_STATS_READ_REQ
3071 The number of read requests
3072 Sys::Virt::Domain::BLOCK_STATS_READ_TOTAL_TIMES
3074 The time spent processing read requests
3075 Sys::Virt::Domain::BLOCK_STATS_WRITE_BYTES
3077 The amount of data written
3078 Sys::Virt::Domain::BLOCK_STATS_WRITE_REQ
3080 The number of write requests
3081 Sys::Virt::Domain::BLOCK_STATS_WRITE_TOTAL_TIMES
3083 The time spent processing write requests
3084 CPU STATS CONSTANTS
3086 The following constants provide the names of well known cpu stats
3087 fields
3088 Sys::Virt::Domain::CPU_STATS_CPUTIME
3090 The total CPU time, including both hypervisor and vCPU time.
3091 Sys::Virt::Domain::CPU_STATS_USERTIME
3093 THe total time in kernel
3094 Sys::Virt::Domain::CPU_STATS_SYSTEMTIME
3096 The total time in userspace
3097 Sys::Virt::Domain::CPU_STATS_VCPUTIME
3099 The total vCPU time.
3100 CPU STATS CONSTANTS
3102 The following constants provide the names of well known schedular
3103 parameters
3104 Sys::Virt::SCHEDULER_EMULATOR_PERIOD
3106 The duration of the time period for scheduling the emulator
3107 Sys::Virt::SCHEDULER_EMULATOR_QUOTA
3109 The quota for the emulator in one schedular time period
3110 Sys::Virt::SCHEDULER_IOTHREAD_PERIOD
3112 The duration of the time period for scheduling the iothread
3113 Sys::Virt::SCHEDULER_IOTHREAD_QUOTA
3115 The quota for the iothread in one schedular time period
3116 DOMAIN STATS FLAG CONSTANTS
3118 The following constants are used as flags when requesting bulk domain
3119 stats from "Sys::Virt::get_all_domain_stats".
3120 Sys::Virt::Domain::GET_ALL_STATS_ACTIVE
3122 Include stats for active domains
3123 Sys::Virt::Domain::GET_ALL_STATS_INACTIVE
3125 Include stats for inactive domains
3126 Sys::Virt::Domain::GET_ALL_STATS_OTHER
3128 Include stats for other domains
3129 Sys::Virt::Domain::GET_ALL_STATS_PAUSED
3131 Include stats for paused domains
3132 Sys::Virt::Domain::GET_ALL_STATS_PERSISTENT
3134 Include stats for persistent domains
3135 Sys::Virt::Domain::GET_ALL_STATS_RUNNING
3137 Include stats for running domains
3138 Sys::Virt::Domain::GET_ALL_STATS_SHUTOFF
3140 Include stats for shutoff domains
3141 Sys::Virt::Domain::GET_ALL_STATS_TRANSIENT
3143 Include stats for transient domains
3144 Sys::Virt::Domain::GET_ALL_STATS_ENFORCE_STATS
3146 Require that all requested stats fields are returned
3147 Sys::Virt::Domain::GET_ALL_STATS_BACKING
3149 Get stats for image backing files too
3150 Sys::Virt::Domain::GET_ALL_STATS_NOWAIT
3152 Skip stats if they can't be acquired without waiting
3153 DOMAIN STATS FIELD CONSTANTS
3155 The following constants are used to control which fields are returned
3156 for stats queries.
3157 Sys::Virt::Domain::STATS_BALLOON
3159 Balloon statistics
3160 Sys::Virt::Domain::STATS_BLOCK
3162 Block device info
3163 Sys::Virt::Domain::STATS_CPU_TOTAL
3165 CPU usage info
3166 Sys::Virt::Domain::STATS_INTERFACE
3168 Network interface info
3169 Sys::Virt::Domain::STATS_STATE
3171 General lifecycle state
3172 Sys::Virt::Domain::STATS_VCPU
3174 Virtual CPU info
3175 Sys::Virt::Domain::STATS_PERF
3177 Performance event counter values
3178 Sys::Virt::Domain::STATS_IOTHREAD
3180 IOThread performance statistics values
3181 Sys::Virt::Domain::STATS_MEMORY
3183 Memory bandwidth statistics values
3184 Sys::Virt::Domain::STATS_DIRTYRATE
3186 Memory dirty rate statistics
3187 Sys::Virt::Domain::STATS_VM
3189 Hypervisor-specific stats fields for given VM
3190 PROCESS SIGNALS
3192 The following constants provide the names of signals which can be sent
3193 to guest processes. They mostly correspond to POSIX signal names.
3194 Sys::Virt::Domain::PROCESS_SIGNAL_NOP
3196 SIGNOP
3197 Sys::Virt::Domain::PROCESS_SIGNAL_HUP
3199 SIGHUP
3200 Sys::Virt::Domain::PROCESS_SIGNAL_INT
3202 SIGINT
3203 Sys::Virt::Domain::PROCESS_SIGNAL_QUIT
3205 SIGQUIT
3206 Sys::Virt::Domain::PROCESS_SIGNAL_ILL
3208 SIGILL
3209 Sys::Virt::Domain::PROCESS_SIGNAL_TRAP
3211 SIGTRAP
3212 Sys::Virt::Domain::PROCESS_SIGNAL_ABRT
3214 SIGABRT
3215 Sys::Virt::Domain::PROCESS_SIGNAL_BUS
3217 SIGBUS
3218 Sys::Virt::Domain::PROCESS_SIGNAL_FPE
3220 SIGFPE
3221 Sys::Virt::Domain::PROCESS_SIGNAL_KILL
3223 SIGKILL
3224 Sys::Virt::Domain::PROCESS_SIGNAL_USR1
3226 SIGUSR1
3227 Sys::Virt::Domain::PROCESS_SIGNAL_SEGV
3229 SIGSEGV
3230 Sys::Virt::Domain::PROCESS_SIGNAL_USR2
3232 SIGUSR2
3233 Sys::Virt::Domain::PROCESS_SIGNAL_PIPE
3235 SIGPIPE
3236 Sys::Virt::Domain::PROCESS_SIGNAL_ALRM
3238 SIGALRM
3239 Sys::Virt::Domain::PROCESS_SIGNAL_TERM
3241 SIGTERM
3242 Sys::Virt::Domain::PROCESS_SIGNAL_STKFLT
3244 SIGSTKFLT
3245 Sys::Virt::Domain::PROCESS_SIGNAL_CHLD
3247 SIGCHLD
3248 Sys::Virt::Domain::PROCESS_SIGNAL_CONT
3250 SIGCONT
3251 Sys::Virt::Domain::PROCESS_SIGNAL_STOP
3253 SIGSTOP
3254 Sys::Virt::Domain::PROCESS_SIGNAL_TSTP
3256 SIGTSTP
3257 Sys::Virt::Domain::PROCESS_SIGNAL_TTIN
3259 SIGTTIN
3260 Sys::Virt::Domain::PROCESS_SIGNAL_TTOU
3262 SIGTTOU
3263 Sys::Virt::Domain::PROCESS_SIGNAL_URG
3265 SIGURG
3266 Sys::Virt::Domain::PROCESS_SIGNAL_XCPU
3268 SIGXCPU
3269 Sys::Virt::Domain::PROCESS_SIGNAL_XFSZ
3271 SIGXFSZ
3272 Sys::Virt::Domain::PROCESS_SIGNAL_VTALRM
3274 SIGVTALRM
3275 Sys::Virt::Domain::PROCESS_SIGNAL_PROF
3277 SIGPROF
3278 Sys::Virt::Domain::PROCESS_SIGNAL_WINCH
3280 SIGWINCH
3281 Sys::Virt::Domain::PROCESS_SIGNAL_POLL
3283 SIGPOLL
3284 Sys::Virt::Domain::PROCESS_SIGNAL_PWR
3286 SIGPWR
3287 Sys::Virt::Domain::PROCESS_SIGNAL_SYS
3289 SIGSYS
3290 Sys::Virt::Domain::PROCESS_SIGNAL_RT0
3292 SIGRT0
3293 Sys::Virt::Domain::PROCESS_SIGNAL_RT1
3295 SIGRT1
3296 Sys::Virt::Domain::PROCESS_SIGNAL_RT2
3298 SIGRT2
3299 Sys::Virt::Domain::PROCESS_SIGNAL_RT3
3301 SIGRT3
3302 Sys::Virt::Domain::PROCESS_SIGNAL_RT4
3304 SIGRT4
3305 Sys::Virt::Domain::PROCESS_SIGNAL_RT5
3307 SIGRT5
3308 Sys::Virt::Domain::PROCESS_SIGNAL_RT6
3310 SIGRT6
3311 Sys::Virt::Domain::PROCESS_SIGNAL_RT7
3313 SIGRT7
3314 Sys::Virt::Domain::PROCESS_SIGNAL_RT8
3316 SIGRT8
3317 Sys::Virt::Domain::PROCESS_SIGNAL_RT9
3319 SIGRT9
3320 Sys::Virt::Domain::PROCESS_SIGNAL_RT10
3322 SIGRT10
3323 Sys::Virt::Domain::PROCESS_SIGNAL_RT11
3325 SIGRT11
3326 Sys::Virt::Domain::PROCESS_SIGNAL_RT12
3328 SIGRT12
3329 Sys::Virt::Domain::PROCESS_SIGNAL_RT13
3331 SIGRT13
3332 Sys::Virt::Domain::PROCESS_SIGNAL_RT14
3334 SIGRT14
3335 Sys::Virt::Domain::PROCESS_SIGNAL_RT15
3337 SIGRT15
3338 Sys::Virt::Domain::PROCESS_SIGNAL_RT16
3340 SIGRT16
3341 Sys::Virt::Domain::PROCESS_SIGNAL_RT17
3343 SIGRT17
3344 Sys::Virt::Domain::PROCESS_SIGNAL_RT18
3346 SIGRT18
3347 Sys::Virt::Domain::PROCESS_SIGNAL_RT19
3349 SIGRT19
3350 Sys::Virt::Domain::PROCESS_SIGNAL_RT20
3352 SIGRT20
3353 Sys::Virt::Domain::PROCESS_SIGNAL_RT21
3355 SIGRT21
3356 Sys::Virt::Domain::PROCESS_SIGNAL_RT22
3358 SIGRT22
3359 Sys::Virt::Domain::PROCESS_SIGNAL_RT23
3361 SIGRT23
3362 Sys::Virt::Domain::PROCESS_SIGNAL_RT24
3364 SIGRT24
3365 Sys::Virt::Domain::PROCESS_SIGNAL_RT25
3367 SIGRT25
3368 Sys::Virt::Domain::PROCESS_SIGNAL_RT26
3370 SIGRT26
3371 Sys::Virt::Domain::PROCESS_SIGNAL_RT27
3373 SIGRT27
3374 Sys::Virt::Domain::PROCESS_SIGNAL_RT28
3376 SIGRT28
3377 Sys::Virt::Domain::PROCESS_SIGNAL_RT29
3379 SIGRT29
3380 Sys::Virt::Domain::PROCESS_SIGNAL_RT30
3382 SIGRT30
3383 Sys::Virt::Domain::PROCESS_SIGNAL_RT31
3385 SIGRT31
3386 Sys::Virt::Domain::PROCESS_SIGNAL_RT32
3388 SIGRT32
3389 DOMAIN TUNABLE CONSTANTS
3391 The following constants are useful when accessing domain tuning
3392 parameters in APIs and events
3393 Sys::Virt::Domain::TUNABLE_CPU_CPU_SHARES
3395 Proportional CPU weight
3396 Sys::Virt::Domain::TUNABLE_CPU_EMULATORPIN
3398 Emulator thread CPU pinning mask
3399 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_PERIOD
3401 Emulator thread CPU period
3402 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_QUOTA
3404 Emulator thread CPU quota
3405 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_PERIOD
3407 Iothread thread CPU period
3408 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_QUOTA
3410 Iothread thread CPU quota
3411 Sys::Virt::Domain::TUNABLE_CPU_VCPUPIN
3413 VCPU thread pinning mask
3414 Sys::Virt::Domain::TUNABLE_CPU_VCPU_PERIOD
3416 VCPU thread period
3417 Sys::Virt::Domain::TUNABLE_CPU_VCPU_QUOTA
3419 VCPU thread quota
3420 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_PERIOD
3422 VM global period
3423 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_QUOTA
3425 VM global quota
3426 Sys::Virt::Domain::TUNABLE_BLKDEV_DISK
3428 The name of guest disks
3429 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC
3431 Read throughput in bytes per sec
3432 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC
3434 Read throughput in I/O operations per sec
3435 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC
3437 Total throughput in bytes per sec
3438 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC
3440 Total throughput in I/O operations per sec
3441 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC
3443 Write throughput in bytes per sec
3444 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC
3446 Write throughput in I/O operations per sec
3447 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX
3449 Maximum read throughput in bytes per sec
3450 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX
3452 Maximum read throughput in I/O operations per sec
3453 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX
3455 Maximum total throughput in bytes per sec
3456 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX
3458 Maximum total throughput in I/O operations per sec
3459 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX
3461 Maximum write throughput in bytes per sec
3462 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX
3464 Maximum write throughput in I/O operations per sec
3465 Sys::Virt::Domain::TUNABLE_BLKDEV_SIZE_IOPS_SEC
3467 The maximum I/O operations per second
3468 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX_LENGTH
3470 The duration in seconds allowed for maximum total bytes processed
3471 per second.
3472 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX_LENGTH
3474 The duration in seconds allowed for maximum bytes read per second.
3475 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX_LENGTH
3477 The duration in seconds allowed for maximum bytes written per
3478 second.
3479 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX_LENGTH
3481 The duration in seconds allowed for maximum total I/O operations
3482 processed per second.
3483 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX_LENGTH
3485 The duration in seconds allowed for maximum I/O operations read per
3486 second.
3487 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX_LENGTH
3489 The duration in seconds allowed for maximum I/O operations written
3490 per second.
3491 Sys::Virt::Domain::TUNABLE_BLKDEV_GROUP_NAME
3493 The name of the blkdev group
3494 Sys::Virt::Domain::TUNABLE_IOTHREADSPIN
3496 The I/O threads pinning
3497 DOMAIN LIFECYCLE CONSTANTS
3499 The following constants are useful when setting action for lifecycle
3500 events.
3501 Sys::Virt::Domain::LIFECYCLE_POWEROFF
3503 The poweroff lifecycle event type
3504 Sys::Virt::Domain::LIFECYCLE_REBOOT
3506 The reboot lifecycle event type
3507 Sys::Virt::Domain::LIFECYCLE_CRASH
3509 The crash lifecycle event type
3510 DOMAIN LIFECYCLE ACTION CONSTANTS
3512 Sys::Virt::Domain::LIFECYCLE_ACTION_DESTROY
3513 The destroy lifecycle action
3514 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART
3516 The restart lifecycle action
3517 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART_RENAME
3519 The restart-rename lifecycle action
3520 Sys::Virt::Domain::LIFECYCLE_ACTION_PRESERVE
3522 The preserve lifecycle action
3523 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_DESTROY
3525 The coredump-destroy lifecycle action
3526 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_RESTART
3528 The coredump-restart lifecycle action
3529 MEMORY FAILURE ACTION CONSTANTS
3531 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_IGNORE
3532 The failure could be ignored
3533 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_INJECT
3535 An MCE was injected to the guest
3536 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_FATAL
3538 The failure is non-recoverable and the hypervisor was not able to
3539 handle it
3540 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_RESET
3542 The failure is non-recoverable and the guest was not able to handle
3543 it.
3544 MEMORY FAILURE RECIPIENT CONSTANTS
3546 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_RECIPIENT_HYPERVISOR
3547 The memory failure was in hypervisor address space
3548 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_RECIPIENT_GUEST
3550 The memory failure was in guest address space
3551 MEMORY FAILURE FLAG CONSTANTS
3553 Sys::Virt::Domain::MEMORY_FAILURE_ACTION_REQUIRED
3554 Whether the flag is action-required or action-optional
3555 Sys::Virt::Domain::MEMORY_FAILURE_RECURSIVE
3557 The failure occurred while the previous fault was being handled.
3558 MEMORY DIRTY RATE STATUS CONSTANTS
3560 Sys::Virt::Domain::DIRTYRATE_UNSTARTED
3561 The dirty rate is not being measured currently.
3562 Sys::Virt::Domain::DIRTYRATE_MEASURING
3564 The dity rate is in the process of being measured
3565 Sys::Virt::Domain::DIRTYRATE_MEASURED
3567 The dirty rate has been measured
3568
3570 Daniel P. Berrange <berrange@redhat.com>
3571
3573 Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
3574
3576 This program is free software; you can redistribute it and/or modify it
3577 under the terms of either the GNU General Public License as published
3578 by the Free Software Foundation (either version 2 of the License, or at
3579 your option any later version), or, the Artistic License, as specified
3580 in the Perl README file.
3581
3583 Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
3584perl v5.36.0 2023-01-30 Sys::Virt::Domain(3)