1Sys::Virt::Domain(3pm)User Contributed Perl DocumentationSys::Virt::Domain(3pm)
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_PAUSED_API_ERROR
263 The guest is paused as a result of failed resume operation at
264 the end of some APIs which internally suspend guests.
265 Sys::Virt::Domain::STATE_RUNNING_BOOTED
267 The guest is running after being booted
268 Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT
270 The guest is running after restore from snapshot
271 Sys::Virt::Domain::STATE_RUNNING_MIGRATED
273 The guest is running after migration
274 Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED
276 The guest is running after migration abort
277 Sys::Virt::Domain::STATE_RUNNING_RESTORED
279 The guest is running after restore from file
280 Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED
282 The guest is running after save cancel
283 Sys::Virt::Domain::STATE_RUNNING_UNKNOWN
285 It is not known why the domain has started
286 Sys::Virt::Domain::STATE_RUNNING_UNPAUSED
288 The guest is running after a resume
289 Sys::Virt::Domain::STATE_RUNNING_WAKEUP
291 The guest is running after wakeup from power management suspend
292 Sys::Virt::Domain::STATE_RUNNING_CRASHED
294 The guest was restarted after crashing
295 Sys::Virt::Domain::STATE_RUNNING_POSTCOPY
297 The guest is running but post-copy is taking place
298 Sys::Virt::Domain::STATE_RUNNING_POSTCOPY_FAILED
300 The guest is running, but migration failed in post-copy
301 Sys::Virt::Domain::STATE_BLOCKED_UNKNOWN
303 The guest is blocked for an unknown reason
304 Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN
306 It is not known why the domain has shutdown
307 Sys::Virt::Domain::STATE_SHUTDOWN_USER
309 The guest is shutdown due to admin request
310 Sys::Virt::Domain::STATE_SHUTOFF_CRASHED
312 The guest is shutoff after a crash
313 Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED
315 The guest is shutoff after being destroyed
316 Sys::Virt::Domain::STATE_SHUTOFF_FAILED
318 The guest is shutoff due to a virtualization failure
319 Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT
321 The guest is shutoff after a snapshot
322 Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED
324 The guest is shutoff after migration
325 Sys::Virt::Domain::STATE_SHUTOFF_SAVED
327 The guest is shutoff after a save
328 Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN
330 The guest is shutoff due to controlled shutdown
331 Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN
333 It is not known why the domain has shutoff
334 Sys::Virt::Domain::STATE_SHUTOFF_DAEMON
336 The daemon stopped the guest due to a failure
337 Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN
339 It is not known why the domain was suspended to RAM
340 Sys::Virt::Domain::STATE_PMSUSPENDED_DISK_UNKNOWN
342 It is not known why the domain was suspended to disk
343 my $info = $dom->get_control_info($flags=0)
345 Returns a hash reference providing information about the control
346 channel. The returned keys in the hash are
347 "state"
349 One of the CONTROL INFO constants listed later
350 "details"
352 Currently unused, always 0.
353 "stateTime"
355 The elapsed time since the control channel entered the current
356 state.
357 my $time = $dom->get_time($flags=0);
359 Get the current time of the guest, in seconds and nanoseconds. The
360 $flags parameter is currently unused and defaults to zero. The
361 return value is an array ref with two elements, the first contains
362 the time in seconds, the second contains the remaining nanoseconds.
363 $dom->set_time($secs, $nsecs, $flags=0);
365 Set the current time of the guest, in seconds and nanoseconds. The
366 $flags parameter accepts one of
367 "Sys::Virt::Domain::TIME_SYNC"
369 Re-sync domain time from domain's RTC.
370 $dom->set_user_password($username, $password, $flags=0);
372 Update the password for account $username to be $password.
373 $password is the clear-text password string unless the
374 PASSWORD_ENCRYPTED flag is set.
375 "Sys::Virt::Domain::PASSWORD_ENCRYPTED"
377 The $password is encrypted with the password scheme required by
378 the guest OS.
379 $dom->rename($newname, $flags=0)
381 Change the name of an inactive guest to be $newname. The $flags
382 parameter is currently unused and defaults to zero.
383 my @errs = $dom->get_disk_errors($flags=0)
385 Returns a list of all disk errors that have occurred on the backing
386 store for the guest's virtual disks. The returned array elements
387 are hash references, containing two keys
388 "path"
390 The path of the disk with an error
391 "error"
393 The error type
394 $dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0)
396 Sends a sequence of keycodes to the guest domain. The $keycodeset
397 should be one of the constants listed later in the KEYCODE SET
398 section. $holdtiem is the duration, in milliseconds, to keep the
399 key pressed before releasing it and sending the next keycode.
400 @keycodes is an array reference containing the list of keycodes to
401 send to the guest. The elements in the array should be keycode
402 values from the specified keycode set. $flags is currently unused.
403 my $info = $dom->get_block_info($dev, $flags=0)
405 Returns a hash reference summarising the disk usage of the host
406 backing store for a guest block device. The $dev parameter should
407 be the path to the backing store on the host. $flags is currently
408 unused and defaults to 0 if omitted. The returned hash contains the
409 following elements
410 capacity
412 Logical size in bytes of the block device backing image *
413 allocation
415 Highest allocated extent in bytes of the block device backing
416 image
417 physical
419 Physical size in bytes of the container of the backing image
420 $dom->set_max_memory($mem)
422 Set the maximum memory for the domain to the value $mem. The value
423 of the $mem parameter is specified in kilobytes.
424 $mem = $dom->get_max_memory()
426 Returns the current maximum memory allowed for this domain in
427 kilobytes.
428 $dom->set_memory($mem, $flags)
430 Set the current memory for the domain to the value $mem. The value
431 of the $mem parameter is specified in kilobytes. This must be less
432 than, or equal to the domain's max memory limit. The $flags
433 parameter can control whether the update affects the live guest, or
434 inactive config, defaulting to modifying the current state.
435 $dom->set_memory_stats_period($period, $flags)
437 Set the period on which guests memory stats are refreshed, with
438 $period being a value in seconds. The $flags parameter is currently
439 unused.
440 $dom->shutdown()
442 Request that the guest OS perform a graceful shutdown and poweroff.
443 This usually requires some form of cooperation from the guest
444 operating system, such as responding to an ACPI signal, or a guest
445 agent process. For an immediate, forceful poweroff, use the
446 "destroy" method instead.
447 $dom->reboot([$flags])
449 Request that the guest OS perform a graceful shutdown and
450 optionally restart. The optional $flags parameter is currently
451 unused and if omitted defaults to zero.
452 $dom->reset([$flags])
454 Perform a hardware reset of the virtual machine. The guest OS is
455 given no opportunity to shutdown gracefully. The optional $flags
456 parameter is currently unused and if omitted defaults to zero.
457 $dom->get_max_vcpus()
459 Return the maximum number of vcpus that are configured for the
460 domain
461 $dom->attach_device($xml[, $flags])
463 Hotplug a new device whose configuration is given by $xml, to the
464 running guest. The optional <$flags> parameter defaults to 0, but
465 can accept one of the device hotplug flags described later.
466 $dom->detach_device($xml[, $flags])
468 Hotunplug an existing device whose configuration is given by $xml,
469 from the running guest. The optional <$flags> parameter defaults to
470 0, but can accept one of the device hotplug flags described later.
471 $dom->detach_device_alias($alias[, $flags])
473 Hotunplug an existing device which is identified by $alias. The
474 optional <$flags> parameter defaults to 0, but can accept one of
475 the device hotplug flags described later.
476 $dom->update_device($xml[, $flags])
478 Update the configuration of an existing device. The new
479 configuration is given by $xml. The optional <$flags> parameter
480 defaults to 0 but can accept one of the device hotplug flags
481 described later.
482 $data = $dom->block_peek($path, $offset, $size[, $flags])
484 Peek into the guest disk $path, at byte $offset capturing $size
485 bytes of data. The returned scalar may contain embedded NULLs. The
486 optional $flags parameter is currently unused and if omitted
487 defaults to zero.
488 $data = $dom->memory_peek($offset, $size[, $flags])
490 Peek into the guest memory at byte $offset virtual address,
491 capturing $size bytes of memory. The return scalar may contain
492 embedded NULLs. The optional $flags parameter is currently unused
493 and if omitted defaults to zero.
494 $flag = $dom->get_autostart();
496 Return a true value if the guest domain is configured to
497 automatically start upon boot. Return false, otherwise
498 $dom->set_autostart($flag)
500 Set the state of the autostart flag, which determines whether the
501 guest will automatically start upon boot of the host OS
502 $dom->set_vcpus($count, [$flags])
504 Set the number of virtual CPUs in the guest VM to $count. The
505 optional $flags parameter can be used to control whether the
506 setting changes the live config or inactive config.
507 $dom->set_vcpu($cpumap, $state, [$flags])
509 Set the state of the CPUs in $cpumap to $state. The $flags
510 parameter defaults to zero if not present.
511 $count = $dom->get_vcpus([$flags])
513 Get the number of virtual CPUs in the guest VM. The optional
514 $flags parameter can be used to control whether to query the
515 setting of the live config or inactive config.
516 $dom->set_guest_vcpus($cpumap, $state, [$flags=0])
518 Set the online status of the guest OS CPUs. The $cpumap parameter
519 describes the set of CPUs to modify (e.g. "0-3,^1"). $state is
520 either 1 to set the CPUs online, or 0 to set them offline. The
521 $flags parameter is currently unused and defaults to 0.
522 $info $dom->get_guest_vcpus([$flags=0])
524 Query information about the guest OS CPUs. The returned data is a
525 hash reference with the following keys.
526 vcpus
528 String containing bitmap representing CPU ids reported
529 currently known to the guest.
530 online
532 String containing bitmap representing CPU ids that are
533 currently online in the guest.
534 offlinable
536 String containing bitmap representing CPU ids that can be
537 offlined in the guest.
538 The $flags parameter is currently unused and defaults to 0.
540 $type = $dom->get_scheduler_type()
542 Return the scheduler type for the guest domain
543 $stats = $dom->block_stats($path)
545 Fetch the current I/O statistics for the block device given by
546 $path. The returned hash reference contains keys for
547 "rd_req"
549 Number of read requests
550 "rd_bytes"
552 Number of bytes read
553 "wr_req"
555 Number of write requests
556 "wr_bytes"
558 Number of bytes written
559 "errs"
561 Some kind of error count
562 my $params = $dom->get_scheduler_parameters($flags=0)
564 Return the set of scheduler tunable parameters for the guest, as a
565 hash reference. The precise set of keys in the hash are specific to
566 the hypervisor.
567 $dom->set_scheduler_parameters($params, $flags=0)
569 Update the set of scheduler tunable parameters. The value names for
570 tunables vary, and can be discovered using the
571 "get_scheduler_params" call
572 my $params = $dom->get_memory_parameters($flags=0)
574 Return a hash reference containing the set of memory tunable
575 parameters for the guest. The keys in the hash are one of the
576 constants MEMORY PARAMETERS described later. The $flags parameter
577 accepts one or more the CONFIG OPTION constants documented later,
578 and defaults to 0 if omitted.
579 $dom->set_memory_parameters($params, $flags=0)
581 Update the memory tunable parameters for the guest. The $params
582 should be a hash reference whose keys are one of the MEMORY
583 PARAMETERS constants. The $flags parameter accepts one or more the
584 CONFIG OPTION constants documented later, and defaults to 0 if
585 omitted.
586 my $params = $dom->get_blkio_parameters($flags=0)
588 Return a hash reference containing the set of blkio tunable
589 parameters for the guest. The keys in the hash are one of the
590 constants BLKIO PARAMETERS described later. The $flags parameter
591 accepts one or more the CONFIG OPTION constants documented later,
592 and defaults to 0 if omitted.
593 $dom->set_blkio_parameters($params, $flags=0)
595 Update the blkio tunable parameters for the guest. The $params
596 should be a hash reference whose keys are one of the BLKIO
597 PARAMETERS constants. The $flags parameter accepts one or more the
598 CONFIG OPTION constants documented later, and defaults to 0 if
599 omitted.
600 $stats = $dom->get_block_iotune($disk, $flags=0)
602 Return a hash reference containing the set of blkio tunable
603 parameters for the guest disk $disk. The keys in the hash are one
604 of the constants BLOCK IOTUNE PARAMETERS described later.
605 $dom->set_block_iotune($disk, $params, $flags=0);
607 Update the blkio tunable parameters for the guest disk $disk. The
608 $params should be a hash reference whose keys are one of the BLOCK
609 IOTUNE PARAMETERS constants.
610 my $params = $dom->get_interface_parameters($intf, $flags=0)
612 Return a hash reference containing the set of interface tunable
613 parameters for the guest. The keys in the hash are one of the
614 constants INTERFACE PARAMETERS described later.
615 $dom->set_interface_parameters($intf, $params, $flags=0)
617 Update the interface tunable parameters for the guest. The $params
618 should be a hash reference whose keys are one of the INTERFACE
619 PARAMETERS constants.
620 my $params = $dom->get_numa_parameters($flags=0)
622 Return a hash reference containing the set of numa tunable
623 parameters for the guest. The keys in the hash are one of the
624 constants NUMA PARAMETERS described later. The $flags parameter
625 accepts one or more the CONFIG OPTION constants documented later,
626 and defaults to 0 if omitted.
627 $dom->set_numa_parameters($params, $flags=0)
629 Update the numa tunable parameters for the guest. The $params
630 should be a hash reference whose keys are one of the NUMA
631 PARAMETERS constants. The $flags parameter accepts one or more the
632 CONFIG OPTION constants documented later, and defaults to 0 if
633 omitted.
634 my $params = $dom->get_perf_events($flags=0)
636 Return a hash reference containing the set of performance events
637 that are available for the guest. The keys in the hash are one of
638 the constants PERF EVENTS described later. The $flags parameter
639 accepts one or more the CONFIG OPTION constants documented later,
640 and defaults to 0 if omitted.
641 $dom->set_perf_events($params, $flags=0)
643 Update the enabled state for performance events for the guest. The
644 $params should be a hash reference whose keys are one of the PERF
645 EVENTS constants. The $flags parameter accepts one or more the
646 CONFIG OPTION constants documented later, and defaults to 0 if
647 omitted.
648 $dom->block_resize($disk, $newsize, $flags=0)
650 Resize the disk $disk to have new size $newsize KB. If the disk is
651 backed by a special image format, the actual resize is done by the
652 hypervisor. If the disk is backed by a raw file, or block device,
653 the resize must be done prior to invoking this API call, and it
654 merely updates the hypervisor's view of the disk size. The
655 following flags may be used
656 Sys::Virt::Domain::BLOCK_RESIZE_BYTES
658 Treat $newsize as if it were in bytes, rather than KB.
659 $dom->interface_stats($path)
661 Fetch the current I/O statistics for the block device given by
662 $path. The returned hash contains keys for
663 "rx_bytes"
665 Total bytes received
666 "rx_packets"
668 Total packets received
669 "rx_errs"
671 Total packets received with errors
672 "rx_drop"
674 Total packets drop at reception
675 "tx_bytes"
677 Total bytes transmitted
678 "tx_packets"
680 Total packets transmitted
681 "tx_errs"
683 Total packets transmitted with errors
684 "tx_drop"
686 Total packets dropped at transmission.
687 $dom->memory_stats($flags=0)
689 Fetch the current memory statistics for the guest domain. The
690 $flags parameter is currently unused and can be omitted. The
691 returned hash contains keys for
692 "swap_in"
694 Data read from swap space
695 "swap_out"
697 Data written to swap space
698 "major_fault"
700 Page fault involving disk I/O
701 "minor_fault"
703 Page fault not involving disk I/O
704 "unused"
706 Memory not used by the system
707 "available"
709 Total memory seen by guest
710 "rss"
712 Resident set size. Size of memory resident in host RAM.
713 $info = $dom->get_security_label()
715 Fetch information about the security label assigned to the guest
716 domain. The returned hash reference has two keys, "model" gives the
717 name of the security model in effect (e.g. "selinux"), while
718 "label" provides the name of the security label applied to the
719 domain. This method only returns information about the first
720 security label. To retrieve all labels, use
721 "get_security_label_list".
722 @info = $dom->get_security_label_list()
724 Fetches information about all security labels assigned to the guest
725 domain. The elements in the returned array are all hash references,
726 whose keys are as described for "get_security_label".
727 $ddom = $dom->migrate(destcon, \%params, flags=0)
729 Migrate a domain to an alternative host. The "destcon" parameter
730 should be a "Sys::Virt" connection to the remote target host. The
731 "flags" parameter takes one or more of the
732 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
733 document. The %params parameter is a hash reference used to set
734 various parameters for the migration operation, with the following
735 valid keys.
736 "Sys::Virt::Domain::MIGRATE_PARAM_URI"
738 The URI to use for initializing the domain migration. It takes
739 a hypervisor specific format. The uri_transports element of the
740 hypervisor capabilities XML includes details of the supported
741 URI schemes. When omitted libvirt will auto-generate suitable
742 default URI. It is typically only necessary to specify this URI
743 if the destination host has multiple interfaces and a specific
744 interface is required to transmit migration data.
745 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_NAME"
747 The name to be used for the domain on the destination host.
748 Omitting this parameter keeps the domain name the same. This
749 field is only allowed to be used with hypervisors that support
750 domain renaming during migration.
751 "Sys::Virt::Domain::MIGRATE_PARAM_DEST_XML"
753 The new configuration to be used for the domain on the
754 destination host. The configuration must include an identical
755 set of virtual devices, to ensure a stable guest ABI across
756 migration. Only parameters related to host side configuration
757 can be changed in the XML. Hypervisors which support this field
758 will forbid migration if the provided XML would cause a change
759 in the guest ABI. This field cannot be used to rename the
760 domain during migration (use VIR_MIGRATE_PARAM_DEST_NAME field
761 for that purpose). Domain name in the destination XML must
762 match the original domain name.
763 Omitting this parameter keeps the original domain
765 configuration. Using this field with hypervisors that do not
766 support changing domain configuration during migration will
767 result in a failure.
768 "Sys::Virt::Domain::MIGRATE_PARAM_GRAPHICS_URI"
770 URI to use for migrating client's connection to domain's
771 graphical console as VIR_TYPED_PARAM_STRING. If specified, the
772 client will be asked to automatically reconnect using these
773 parameters instead of the automatically computed ones. This can
774 be useful if, e.g., the client does not have a direct access to
775 the network virtualization hosts are connected to and needs to
776 connect through a proxy. The URI is formed as follows:
777 protocol://hostname[:port]/[?parameters]
779 where protocol is either "spice" or "vnc" and parameters is a
781 list of protocol specific parameters separated by '&'.
782 Currently recognized parameters are "tlsPort" and "tlsSubject".
783 For example,
784 spice://target.host.com:1234/?tlsPort=4567
786 "Sys::Virt::Domain::MIGRATE_PARAM_BANDWIDTH"
788 The maximum bandwidth (in MiB/s) that will be used for
789 migration. If set to 0 or omitted, libvirt will choose a
790 suitable default. Some hypervisors do not support this feature
791 and will return an error if this field is used and is not 0.
792 "Sys::Virt::Domain::MIGRATE_PARAM_BANDWIDTH_POSTCOPY"
794 The maximum bandwidth (in MiB/s) that will be used for
795 migration during post-copy phase. If set to 0 or omitted,
796 libvirt will choose a suitable default. Some hypervisors do not
797 support this feature and return an error if this field is used
798 and is not 0.
799 "Sys::Virt::Domain::MIGRATE_PARAM_LISTEN_ADDRESS"
801 The address on which to listen for incoming migration
802 connections. If omitted, libvirt will listen on the wildcard
803 address (0.0.0.0 or ::). This default may be a security risk if
804 guests, or other untrusted users have the ability to connect to
805 the virtualization host, thus use of an explicit restricted
806 listen address is recommended.
807 "Sys::Virt::Domain::MIGRATE_PARAM_DISK_PORT"
809 Port that destination server should use for incoming disks
810 migration. Type is VIR_TYPED_PARAM_INT. If set to 0 or omitted,
811 libvirt will choose a suitable default. At the moment this is
812 only supported by the QEMU driver.
813 "Sys::Virt::Domain::MIGRATE_PARAM_MIGRATE_DISKS"
815 The list of disks to migrate when doing block storage
816 migration. In contrast to other parameters whose values are
817 plain strings, the parameter value should be an array
818 reference, whose elements are in turn strings representing the
819 disk target names.
820 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION"
822 The type of compression method use use, either "xbzrle" or
823 "mt".
824 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_THREADS"
826 The number of compression threads to use
827 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_DTHREADS"
829 The number of decompression threads
830 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_MT_LEVEL"
832 The compression level from 0 (no compression) to 9 (maximum
833 compression)
834 "Sys::Virt::Domain::MIGRATE_PARAM_COMPRESSION_XBZRLE_CACHE"
836 The size of the cache for xbzrle compression
837 "Sys::Virt::Domain::MIGRATE_PARAM_PERSIST_XML"
839 The alternative persistent XML config to copy
840 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INITIAL"
842 The initial percentage to throttle guest vCPUs
843 "Sys::Virt::Domain::MIGRATE_PARAM_AUTO_CONVERGE_INCREMENT"
845 The additional percentage step size to throttle guest vCPUs if
846 progress is not made
847 "Sys::Virt::Domain::MIGRATE_PARAM_PARALLEL_CONNECTIONS"
849 The number of connections used during parallel migration.
850 "Sys::Virt::Domain::MIGRATE_PARAM_TLS_DESTINATION"
852 Override the destination host name used for TLS verification.
853 Normally the TLS certificate from the destination host must
854 match the host's name for TLS verification to succeed. When the
855 certificate does not match the destination hostname and the
856 expected certificate's hostname is known, this parameter can be
857 used to pass this expected hostname when starting the
858 migration.
859 "Sys::Virt::Domain::MIGRATE_PARAM_DISKS_URI"
861 The URI to use for initializing the domain migration for
862 storage. It takes a hypervisor specific format. The
863 uri_transports element of the hypervisor capabilities XML
864 includes details of the supported URI schemes. When omitted
865 libvirt will auto-generate suitable default URI. It is
866 typically only necessary to specify this URI if the destination
867 host has multiple interfaces and a specific interface is
868 required to transmit storage data.
869 "Sys::Virt::Domain::MIGRATE_PARAM_ZLIB_LEVEL"
871 The level of compression for zlib. Accepted values are in range
872 0-9. 0 is no compression, 1 is maximum speed and 9 is maximum
873 compression.
874 "Sys::Virt::Domain::MIGRATE_PARAM_ZSTD_LEVEL"
876 The level of compression for zstd. Accepted values are in range
877 0-20. 0 is no compression, 1 is maximum speed and 20 is maximum
878 compression.
879 $ddom = $dom->migrate(destcon, flags=0, dname=undef, uri=undef,
881 bandwidth=0)
882 Migrate a domain to an alternative host. Use of positional
883 parameters with "migrate" is deprecated in favour of passing a hash
884 reference as described above.
885 $ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)
887 Migrate a domain to an alternative host. This method is deprecated
888 in favour of passing a hash ref to "migrate".
889 $ddom = $dom->migrate_to_uri(desturi, \%params, flags=0)
891 Migrate a domain to an alternative host. The "desturi" parameter
892 should be a valid libvirt connection URI for the remote target
893 host. The "flags" parameter takes one or more of the
894 "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this
895 document. The %params parameter is a hash reference used to set
896 various parameters for the migration operation, with the same keys
897 described for the "migrate" API.
898 $dom->migrate_to_uri(desturi, flags, dname, bandwidth)
900 Migrate a domain to an alternative host. Use of positional
901 parameters with "migrate_to_uri" is deprecated in favour of passing
902 a hash reference as described above.
903 $dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)
905 Migrate a domain to an alternative host. This method is deprecated
906 in favour of passing a hash ref to "migrate_to_uri".
907 $dom->migrate_set_max_downtime($downtime, $flags=0)
909 Set the maximum allowed downtime during migration of the guest. A
910 longer downtime makes it more likely that migration will complete,
911 at the cost of longer time blackout for the guest OS at the switch
912 over point. The "downtime" parameter is measured in milliseconds.
913 The $flags parameter is currently unused and defaults to zero.
914 $downtime = $dom->migrate_get_max_downtime($flags=0) Get the current
916 value of the maximum downtime allowed during a migration of a guest.
917 The returned <downtime> value is measured in milliseconds. The $flags
918 parameter is currently unused and defaults to zero.
919 $dom->migrate_set_max_speed($bandwidth, $flags=0)
920 Set the maximum allowed bandwidth during migration of the guest.
921 The "bandwidth" parameter is measured in MB/second. The $flags
922 parameter takes zero or more of the constants:
923 $Sys::Virt::Domain::MIGRATE_MAX_SPEED_POSTCOPY
925 Set the post-copy speed instead of the pre-copy speed.
926 $bandwidth = $dom->migrate_get_max_speed($flags=0)
928 Get the maximum allowed bandwidth during migration of the guest.
929 The returned <bandwidth> value is measured in MB/second. The
930 $flags parameter is accepts the same constants as
931 "migrate_set_max_speed".
932 $dom->migrate_set_compression_cache($cacheSize, $flags=0)
934 Set the maximum allowed compression cache size during migration of
935 the guest. The "cacheSize" parameter is measured in bytes. The
936 $flags parameter is currently unused and defaults to zero.
937 $cacheSize = $dom->migrate_get_compression_cache($flags=0)
939 Get the maximum allowed compression cache size during migration of
940 the guest. The returned <bandwidth> value is measured in bytes.
941 The $flags parameter is currently unused and defaults to zero.
942 $dom->migrate_start_post_copy($flags=0)
944 Switch the domain from pre-copy to post-copy mode. This requires
945 that the original migrate command had the
946 "Sys::Virt::Domain::MIGRATE_POST_COPY" flag specified.
947 $dom->inject_nmi($flags)
949 Trigger an NMI in the guest virtual machine. The $flags parameter
950 is currently unused and defaults to 0.
951 $dom->open_console($st, $devname, $flags)
953 Open the text console for a serial, parallel or paravirt console
954 device identified by $devname, connecting it to the stream $st. If
955 $devname is undefined, the default console will be opened. $st must
956 be a "Sys::Virt::Stream" object used for bi-directional
957 communication with the console. $flags is currently unused,
958 defaulting to 0.
959 $dom->open_channel($st, $devname, $flags)
961 Open the text console for a data channel device identified by
962 $devname, connecting it to the stream $st. $st must be a
963 "Sys::Virt::Stream" object used for bi-directional communication
964 with the channel. $flags is currently unused, defaulting to 0.
965 $dom->open_graphics($idx, $fd, $flags)
967 Open the graphics console for a guest, identified by $idx, counting
968 from 0. The $fd should be a file descriptor for an anonymous socket
969 pair. The $flags argument should be one of the constants listed at
970 the end of this document, and defaults to 0.
971 $fd = $dom->open_graphics_fd($idx, $flags)
973 Open the graphics console for a guest, identified by $idx, counting
974 from 0. The $flags argument should be one of the constants listed
975 at the end of this document, and defaults to 0. The return value
976 will be a file descriptor connected to the console which must be
977 closed when no longer needed. This method is preferred over
978 "open_graphics" since it will work correctly under sVirt mandatory
979 access control policies.
980 my $mimetype = $dom->screenshot($st, $screen, $flags)
982 Capture a screenshot of the virtual machine's monitor. The $screen
983 parameter controls which monitor is captured when using a multi-
984 head or multi-card configuration. $st must be a "Sys::Virt::Stream"
985 object from which the data can be read. $flags is currently unused
986 and defaults to 0. The mimetype of the screenshot is returned
987 @vcpuinfo = $dom->get_vcpu_info($flags=0)
989 Obtain information about the state of all virtual CPUs in a running
990 guest domain. The returned list will have one element for each
991 vCPU, where each elements contains a hash reference. The keys in
992 the hash are, "number" the vCPU number, "cpu" the physical CPU on
993 which the vCPU is currently scheduled, "cpuTime" the cumulative
994 execution time of the vCPU, "state" the running state and
995 "affinity" giving the allowed scheduler placement. The value for
996 "affinity" is a string representing a bitmask against physical
997 CPUs, 8 cpus per character. To extract the bits use the "unpack"
998 function with the "b*" template. NB The "state", "cpuTime", "cpu"
999 values are only available if using $flags value of 0, and the
1000 domain is currently running; otherwise they will all be set to
1001 zero.
1002 $dom->pin_vcpu($vcpu, $mask)
1004 Pin the virtual CPU given by index $vcpu to physical CPUs given by
1005 $mask. The $mask is a string representing a bitmask against
1006 physical CPUs, 8 cpus per character.
1007 $mask = $dom->get_emulator_pin_info()
1009 Obtain information about the CPU affinity of the emulator process.
1010 The returned $mask is a bitstring against physical CPUs, 8 cpus per
1011 character. To extract the bits use the "unpack" function with the
1012 "b*" template.
1013 $dom->pin_emulator($newmask, $flags=0)
1015 Pin the emulator threads to the physical CPUs identified by the
1016 affinity in $newmask. The $newmask is a bitstring against the
1017 physical CPUa, 8 cpus per character. To create a suitable
1018 bitstring, use the "vec" function with a value of 1 for the "BITS"
1019 parameter.
1020 @iothreadinfo = $dom->get_iothread_info($flags=0)
1022 Obtain information about the state of all IOThreads in a running
1023 guest domain. The returned list will have one element for each
1024 IOThread, where each elements contains a hash reference. The keys
1025 in the hash are, "number" the IOThread number and "affinity" giving
1026 the allowed scheduler placement. The value for "affinity" is a
1027 string representing a bitmask against physical CPUs, 8 cpus per
1028 character. To extract the bits use the "unpack" function with the
1029 "b*" template.
1030 $dom->pin_iothread($iothread, $mask)
1032 Pin the IOThread given by index $iothread to physical CPUs given by
1033 $mask. The $mask is a string representing a bitmask against
1034 physical CPUs, 8 cpus per character.
1035 $dom->add_iothread($iothread, $flags=0)
1037 Add a new IOThread by the $iothread value to the guest domain. The
1038 $flags parameter accepts one or more the CONFIG OPTION constants
1039 documented later, and defaults to 0 if omitted.
1040 $dom->del_iothread($iothread, $flags=0)
1042 Delete an existing IOThread by the $iothread value from the guest
1043 domain. The $flags parameter accepts one or more the CONFIG OPTION
1044 constants documented later, and defaults to 0 if omitted.
1045 $dom->set_iothread($iothread, $params, $flags=0)
1047 Set parameters for the IOThread by the $iothread value on the guest
1048 domain. The $params parameter is a hash reference whose keys are
1049 the "IOTHREAD STATS" constants documented later. The $flags
1050 parameter accepts one or more the CONFIG OPTION constants
1051 documented later, and defaults to 0 if omitted.
1052 my @stats = $dom->get_cpu_stats($startCpu, $numCpus, $flags=0)
1054 Requests the guests host physical CPU usage statistics, starting
1055 from host CPU <$startCpu> counting up to $numCpus. If $startCpu is
1056 -1 and $numCpus is 1, then the utilization across all CPUs is
1057 returned. Returns an array of hash references, each element
1058 containing stats for one CPU.
1059 my $info = $dom->get_job_info()
1061 Returns a hash reference summarising the execution state of the
1062 background job. The elements of the hash are as follows:
1063 type
1065 The type of job, one of the JOB TYPE constants listed later in
1066 this document.
1067 timeElapsed
1069 The elapsed time in milliseconds
1070 timeRemaining
1072 The expected remaining time in milliseconds. Only set if the
1073 "type" is JOB_UNBOUNDED.
1074 dataTotal
1076 The total amount of data expected to be processed by the job,
1077 in bytes.
1078 dataProcessed
1080 The current amount of data processed by the job, in bytes.
1081 dataRemaining
1083 The expected amount of data remaining to be processed by the
1084 job, in bytes.
1085 memTotal
1087 The total amount of memory expected to be processed by the job,
1088 in bytes.
1089 memProcessed
1091 The current amount of memory processed by the job, in bytes.
1092 memRemaining
1094 The expected amount of memory remaining to be processed by the
1095 job, in bytes.
1096 fileTotal
1098 The total amount of file expected to be processed by the job,
1099 in bytes.
1100 fileProcessed
1102 The current amount of file processed by the job, in bytes.
1103 fileRemaining
1105 The expected amount of file remaining to be processed by the
1106 job, in bytes.
1107 my ($type, $stats) = $dom->get_job_stats($flags=0)
1109 Returns an array summarising the execution state of the background
1110 job. The $type value is one of the JOB TYPE constants listed later
1111 in this document. The $stats value is a hash reference, whose
1112 elements are one of the following constants.
1113 type
1115 The type of job, one of the JOB TYPE constants listed later in
1116 this document.
1117 The $flags parameter defaults to zero and can take one of the
1119 following constants.
1120 Sys::Virt::Domain::JOB_STATS_COMPLETED
1122 Return the stats of the most recently completed job.
1123 Sys::Virt::Domain::JOB_STATS_KEEP_COMPLETED
1125 Don't clear the completed stats after reading them.
1126 Sys::Virt::Domain::JOB_TIME_ELAPSED
1128 The elapsed time in milliseconds
1129 Sys::Virt::Domain::JOB_TIME_ELAPSED_NET
1131 Time in milliseconds since the beginning of the migration job
1132 NOT including the time required to transfer control flow from
1133 the source host to the destination host.
1134 Sys::Virt::Domain::JOB_TIME_REMAINING
1136 The expected remaining time in milliseconds. Only set if the
1137 "type" is JOB_UNBOUNDED.
1138 Sys::Virt::Domain::JOB_DATA_TOTAL
1140 The total amount of data expected to be processed by the job,
1141 in bytes.
1142 Sys::Virt::Domain::JOB_DATA_PROCESSED
1144 The current amount of data processed by the job, in bytes.
1145 Sys::Virt::Domain::JOB_DATA_REMAINING
1147 The expected amount of data remaining to be processed by the
1148 job, in bytes.
1149 Sys::Virt::Domain::JOB_MEMORY_TOTAL
1151 The total amount of memory expected to be processed by the job,
1152 in bytes.
1153 Sys::Virt::Domain::JOB_MEMORY_PROCESSED
1155 The current amount of memory processed by the job, in bytes.
1156 Sys::Virt::Domain::JOB_MEMORY_REMAINING
1158 The expected amount of memory remaining to be processed by the
1159 job, in bytes.
1160 Sys::Virt::Domain::JOB_MEMORY_CONSTANT
1162 The number of pages filled with a constant byte which have been
1163 transferred
1164 Sys::Virt::Domain::JOB_MEMORY_NORMAL
1166 The number of pages transferred without any compression
1167 Sys::Virt::Domain::JOB_MEMORY_NORMAL_BYTES
1169 The number of bytes transferred without any compression
1170 Sys::Virt::Domain::JOB_MEMORY_BPS
1172 The bytes per second transferred
1173 Sys::Virt::Domain::JOB_MEMORY_DIRTY_RATE
1175 The number of memory pages dirtied per second
1176 Sys::Virt::Domain::JOB_MEMORY_PAGE_SIZE
1178 The memory page size in bytes
1179 Sys::Virt::Domain::JOB_MEMORY_ITERATION
1181 The total number of iterations over guest memory
1182 Sys::Virt::Domain::JOB_MEMORY_POSTCOPY_REQS
1184 The number of page requests received from the destination host
1185 during post-copy migration.
1186 Sys::Virt::Domain::JOB_DISK_TOTAL
1188 The total amount of file expected to be processed by the job,
1189 in bytes.
1190 Sys::Virt::Domain::JOB_DISK_PROCESSED
1192 The current amount of file processed by the job, in bytes.
1193 Sys::Virt::Domain::JOB_DISK_REMAINING
1195 The expected amount of file remaining to be processed by the
1196 job, in bytes.
1197 Sys::Virt::Domain::JOB_DISK_BPS
1199 The bytes per second transferred
1200 Sys::Virt::Domain::JOB_AUTO_CONVERGE_THROTTLE
1202 The percentage by which vCPUs are currently throttled
1203 Sys::Virt::Domain::JOB_COMPRESSION_CACHE
1205 The size of the compression cache in bytes
1206 Sys::Virt::Domain::JOB_COMPRESSION_BYTES
1208 The number of compressed bytes transferred
1209 Sys::Virt::Domain::JOB_COMPRESSION_PAGES
1211 The number of compressed pages transferred
1212 Sys::Virt::Domain::JOB_COMPRESSION_CACHE_MISSES
1214 The number of changing pages not in compression cache
1215 Sys::Virt::Domain::JOB_COMPRESSION_OVERFLOW
1217 The number of changing pages in the compression cache but sent
1218 uncompressed since the compressed page was larger than the non-
1219 compressed page.
1220 Sys::Virt::Domain::JOB_DOWNTIME
1222 The number of milliseconds of downtime expected during
1223 migration switchover.
1224 Sys::Virt::Domain::JOB_DOWNTIME_NET
1226 Real measured downtime (ms) NOT including the time required to
1227 transfer control flow from the source host to the destination
1228 host.
1229 Sys::Virt::Domain::JOB_SETUP_TIME
1231 The number of milliseconds of time doing setup of the job
1232 Sys::Virt::Domain::JOB_OPERATION
1234 The type of operation associated with the job
1235 Sys::Virt::Domain::JOB_SUCCESS
1237 Whether the job was successfully completed.
1238 Sys::Virt::Domain::JOB_DISK_TEMP_TOTAL
1240 Possible total temporary disk space for the job in bytes
1241 Sys::Virt::Domain::JOB_DISK_TEMP_USED
1243 Current total temporary disk space for the job in bytes
1244 Sys::Virt::Domain::JOB_ERRMSG
1246 The error message from a failed job
1247 The values for the Sys::Virt::Domain::JOB_OPERATION field are
1249 Sys::Virt::Domain::JOB_OPERATION_UNKNOWN
1251 No known job type
1252 Sys::Virt::Domain::JOB_OPERATION_START
1254 The guest is starting
1255 Sys::Virt::Domain::JOB_OPERATION_SAVE
1257 The guest is saving to disk
1258 Sys::Virt::Domain::JOB_OPERATION_RESTORE
1260 The guest is restoring from disk
1261 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_IN
1263 The guest is migrating in from another host
1264 Sys::Virt::Domain::JOB_OPERATION_MIGRATION_OUT
1266 The guest is migrating out to another host
1267 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT
1269 The guest is saving a snapshot
1270 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT_REVERT
1272 The guest is reverting to a snapshot
1273 Sys::Virt::Domain::JOB_OPERATION_DUMP
1275 The guest is saving a crash dump
1276 Sys::Virt::Domain::JOB_OPERATION_BACKUP
1278 The guest is performing a block backup
1279 Sys::Virt::Domain::JOB_OPERATION_SNAPSHOT_DELETE
1281 The guest is deleting a snapshot
1282 $dom->abort_job($flags=0)
1284 Aborts the currently executing job. Valid $flags include:
1285 Sys::Virt::Domain::DOMAIN_ABORT_JOB_POSTCOPY
1287 Interrupt post-copy migration. It can later be resumed using
1288 migrate APIs with "MIGRATE_POSTCOPY_RESUME" flag.
1289 my $info = $dom->get_block_job_info($path, $flags=0)
1291 Returns a hash reference summarising the execution state of the
1292 block job. The $path parameter should be the fully qualified path
1293 of the block device being changed. Valid $flags include:
1294 Sys::Virt::Domain::BLOCK_JOB_INFO_BANDWIDTH_BYTES
1296 Treat bandwidth value as bytes instead of MiB.
1297 $dom->set_block_job_speed($path, $bandwidth, $flags=0)
1299 Change the maximum I/O bandwidth used by the block job that is
1300 currently executing for $path. The $bandwidth argument is specified
1301 in MB/s. The $flags parameter can take the bitwise union of the
1302 values:
1303 Sys::Virt::Domain::BLOCK_JOB_SPEED_BANDWIDTH_BYTES
1305 The $bandwidth parameter value is measured in bytes/s instead
1306 of MB/s.
1307 $dom->abort_block_job($path, $flags=0)
1309 Abort the current job that is executing for the block device
1310 associated with $path
1311 $dom->block_pull($path, $bandwidth, $flags=0)
1313 Merge the backing files associated with $path into the top level
1314 file. The $bandwidth parameter specifies the maximum I/O rate to
1315 allow in MB/s. The $flags parameter can take the bitwise union of
1316 the values:
1317 Sys::Virt::Domain::BLOCK_PULL_BANDWIDTH_BYTES
1319 The $bandwidth parameter value is measured in bytes/s instead
1320 of MB/s.
1321 $dom->block_rebase($path, $base, $bandwidth, $flags=0)
1323 Switch the backing path associated with $path to instead use $base.
1324 The $bandwidth parameter specifies the maximum I/O rate to allow in
1325 MB/s. The $flags parameter can take the bitwise union of the
1326 values:
1327 Sys::Virt::Domain::BLOCK_REBASE_BANDWIDTH_BYTES
1329 The $bandwidth parameter value is measured in bytes/s instead
1330 of MB/s.
1331 $dom->block_copy($path, $destxml, $params, $flags=0)
1333 Copy contents of a disk image <$path> into the target volume
1334 described by $destxml which follows the schema of the <disk>
1335 element in the domain XML. The $params parameter is a hash of
1336 optional parameters to control the process
1337 Sys::Virt::Domain::BLOCK_COPY_BANDWIDTH
1339 The maximum bandwidth in bytes per second.
1340 Sys::Virt::Domain::BLOCK_COPY_GRANULARITY
1342 The granularity in bytes of the copy process
1343 Sys::Virt::Domain::BLOCK_COPY_BUF_SIZE
1345 The maximum amount of data in flight in bytes.
1346 $dom->block_commit($path, $base, $top, $bandwidth, $flags=0)
1348 Commit changes there were made to the temporary top level file
1349 $top. Takes all the differences between $top and $base and merge
1350 them into $base. The $bandwidth parameter specifies the maximum I/O
1351 rate to allow in MB/s. The $flags parameter can take the bitwise
1352 union of the values:
1353 Sys::Virt::Domain::BLOCK_COMMIT_BANDWIDTH_BYTES
1355 The $bandwidth parameter value is measured in bytes instead of
1356 MB/s.
1357 $count = $dom->num_of_snapshots()
1359 Return the number of saved snapshots of the domain
1360 @names = $dom->list_snapshot_names()
1362 List the names of all saved snapshots. The names can be used with
1363 the "lookup_snapshot_by_name"
1364 @snapshots = $dom->list_snapshots()
1366 Return a list of all snapshots currently known to the domain. The
1367 elements in the returned list are instances of the
1368 Sys::Virt::DomainSnapshot class. This method requires O(n) RPC
1369 calls, so the "list_all_snapshots" method is recommended as a more
1370 efficient alternative.
1371 my @snapshots = $dom->list_all_snapshots($flags)
1373 Return a list of all domain snapshots associated with this domain.
1374 The elements in the returned list are instances of the
1375 Sys::Virt::DomainSnapshot class. The $flags parameter can be used
1376 to filter the list of return domain snapshots.
1377 my $snapshot = $dom->get_snapshot_by_name($name)
1379 Return the domain snapshot with a name of $name. The returned
1380 object is an instance of the Sys::Virt::DomainSnapshot class.
1381 $dom->has_current_snapshot()
1383 Returns a true value if the domain has a currently active snapshot
1384 $snapshot = $dom->current_snapshot()
1386 Returns the currently active snapshot for the domain.
1387 $snapshot = $dom->create_snapshot($xml[, $flags])
1389 Create a new snapshot from the $xml. The $flags parameter accepts
1390 the SNAPSHOT CREATION constants listed in
1391 "Sys::Virt::DomainSnapshots".
1392 my @checkpoints = $dom->list_all_checkpoints($flags)
1394 Return a list of all domain checkpoints associated with this
1395 domain. The elements in the returned list are instances of the
1396 Sys::Virt::DomainCheckpoint class. The $flags parameter can be used
1397 to filter the list of return domain checkpoints.
1398 my $checkpoint = $dom->get_checkpoint_by_name($name)
1400 Return the domain checkpoint with a name of $name. The returned
1401 object is an instance of the Sys::Virt::DomainCheckpoint class.
1402 $checkpoint = $dom->create_checkpoint($xml[, $flags])
1404 Create a new checkpoint from the $xml. The $flags parameter accepts
1405 the CHECKPOINT CREATION constants listed in
1406 "Sys::Virt::DomainCheckpoints".
1407 $dom->backup_begin($backupxml, $checkpointxml=undef, $flags=0);
1409 Start a point-in-time backup job for the specified disks of a
1410 running domain. The $backupxml parameter describes the backup
1411 operation, including which disks to use. The optional
1412 $checkpointxml parameter can be used to create a checkpoint
1413 covering to the same point in time as the backup. The optional
1414 $flags parameter can be one of the following constants:
1415 Sys::Virt::Domain::BACKUP_BEGIN_REUSE_EXTERNAL
1417 Assume that the output/temporary files for the backup have been
1418 precreated by the caller with the correct size and format.
1419 $xml = $dom->backup_get_xml_description($flags=0);
1421 Get the XML description of the currently executing backup job. If
1422 there is no backup job then an error is raised.
1423 $dom->fs_trim($mountPoint, $minimum, $flags=0);
1425 Issue an FS_TRIM command to the device at $mountPoint to remove
1426 chunks of unused space that are at least $minimum bytes in length.
1427 $flags is currently unused and defaults to zero.
1428 $dom->fs_freeze(\@mountPoints, $flags=0);
1430 Freeze all the filesystems associated with the @mountPoints array
1431 reference. If <@mountPoints> is an empty list, then all filesystems
1432 will be frozen. $flags is currently unused and defaults to zero.
1433 $dom->fs_thaw(\@mountPoints, $flags=0);
1435 Thaw all the filesystems associated with the @mountPoints array
1436 reference. If <@mountPoints> is an empty list, then all filesystems
1437 will be thawed. $flags is currently unused and defaults to zero.
1438 @fslist = $dom->get_fs_info($flags=0);
1440 Obtain a list of all guest filesystems. The returned list will
1441 contain one element for each filesystem, whose value will be a hash
1442 reference with the following keys
1443 name
1445 The name of the guest device that is mounted
1446 fstype
1448 The filesystem type (e.g. 'ext4', 'fat', 'ntfs', etc)
1449 mountpoint
1451 The location in the filesystem tree of the mount
1452 devalias
1454 An array reference containing list of device aliases associated
1455 with the guest device. The device aliases correspond to disk
1456 target names in the guest XML configuration
1457 @nics = $dom->get_interface_addresses($src, $flags=0);
1459 Obtain a list of all guest network interfaces. The $src parameter
1460 is one of the constants
1461 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_LEASE
1463 Extract the DHCP server lease information
1464 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_AGENT
1466 Query the guest OS via an agent
1467 Sys::Virt::Domain::INTERFACE_ADDRESSES_SRC_ARP
1469 Extract from the local ARP tables
1470 The returned list will contain one element for each interface. The
1472 values in the list will be a hash reference with the following keys
1473 name
1475 The name of the guest interface that is mounted
1476 hwaddr
1478 The hardware address, aka MAC, if available.
1479 addrs
1481 An array reference containing list of IP addresses associated
1482 with the guest NIC. Each element in the array is a further hash
1483 containing
1484 addr
1486 The IP address string
1487 prefix
1489 The IP address network prefix
1490 type
1492 The IP address type (IPv4 vs IPv6)
1493 $dom->send_process_signal($pid, $signum, $flags=0);
1495 Send the process $pid the signal $signum. The $signum value must be
1496 one of the constants listed later, not a POSIX or Linux signal
1497 value. $flags is currently unused and defaults to zero.
1498 $dom->set_block_threshold($dev, $threshold, $flags=0);
1500 Set the threshold level for delivering the EVENT_ID_BLOCK_THRESHOLD
1501 if the device or backing chain element described by $dev is written
1502 beyond the set $threshold level. The threshold level is unset once
1503 the event fires. The event might not be delivered at all if
1504 libvirtd was not running at the moment when the threshold was
1505 reached.
1506 $dom->set_lifecycle_action($type, $action, $flags=0)
1508 Changes the actions of lifecycle events for domain represented as
1509 <on_$type>$action</on_$type> in the domain XML.
1510 $info = $dom->get_launch_security_info($flags=0)
1512 Get information about the domain launch security policy. $flags is
1513 currently unused and defaults to zero. The returned hash may
1514 contain the following keys
1515 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_MEASUREMENT
1517 The AMD SEV launch measurement
1518 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_API_MAJOR
1520 The host SEV API major version
1521 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_API_MINOR
1523 The host SEV API minor version
1524 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_BUILD_ID
1526 The host SEV firmware build ID
1527 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_POLICY
1529 The guest SEV policy
1530 $dom->set_launch_security_state(\%params, $flags=0)
1532 Set information about the domain launch security state. $flags is
1533 currently unused and defaults to zero. The provided hash may
1534 contain the following keys
1535 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET
1537 The SEV secret string to inject
1538 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET_HEADER
1540 The SEV secret header string to inject
1541 Sys::Virt::Domain::LAUNCH_SECURITY_SEV_SECRET_SET_ADDRESS
1543 The address at which to inject the SEV secret. If omitted it
1544 can be automatically determined from the firmware
1545 $info = $dom->get_guest_info($types, $flags=0)
1547 Get information about the domain guest configuration. The $types
1548 parameter determines what pieces of information are returned and
1549 should be the bitwise or of the following constants:
1550 Sys::Virt::Domain::GUEST_INFO_USERS
1552 Active user information
1553 Sys::Virt::Domain::GUEST_INFO_OS
1555 Misc operating system information
1556 Sys::Virt::Domain::GUEST_INFO_TIMEZONE
1558 The guest timezone
1559 Sys::Virt::Domain::GUEST_INFO_HOSTNAME
1561 The guest hostname
1562 Sys::Virt::Domain::GUEST_INFO_FILESYSTEM
1564 Filesystem mount information
1565 Sys::Virt::Domain::GUEST_INFO_DISKS
1567 Block device information
1568 Sys::Virt::Domain::GUEST_INFO_INTERFACES
1570 Network interfaces information
1571 $flags is currently unused and defaults to zero.
1573 $dom->set_agent_response_timeout($timeout, $flags=0)
1575 Set the amount of time to wait for the agent to respond to a
1576 command. $timeout is a positive integer representing the number of
1577 seconds to wait, or one of the constants:
1578 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_BLOCK
1580 Wait forever with no timeout
1581 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_NOWAIT
1583 Don't want at all, return immediately
1584 Sys::Virt::Domain::AGENT_RESPONSE_TIMEOUT_DEFAULT
1586 Use the hypervisor driver's default timeout
1587 The $flags parameter is currently unused and defaults to zero.
1589 my @keys = $dom->authorized_ssh_keys_get($user, $flags=0)
1591 Retrieve the list of authorized SSH keys for the user account
1592 $user. The $flags parameter is currently unused and defaults to
1593 zero.
1594 $dom->authorized_ssh_keys_set($user, \@keys, $flags=0)
1596 Update the list of authorized SSH keys for the user account $user.
1597 The @keys parameter should be an array reference containing the new
1598 keys, if any. The default behaviour is to set the authorized SSH
1599 keys to the exact set specified in @keys. This can be modified via
1600 the $flags parameter which takes the following constants
1601 Sys::Virt::Domain::AUTHORIZED_SSH_KEYS_SET_APPEND
1603 Append @keys to the current set of keys, rather than replacing
1604 the existing keys.
1605 Sys::Virt::Domain::AUTHORIZED_SSH_KEYS_SET_REMOVE
1607 Remove @keys from the current set of keys, rather than
1608 replacing the existing keys. It is not an error if the keys do
1609 not exist.
1610 my @msgs = $dom->get_messages($flags=0)
1612 Retrieve a list of messages associated with the domain. The
1613 optional $flags parameter can accept zero or more of
1614 Sys::Virt::Domain::MESSAGE_DEPRECATION
1616 Warnings about use of deprecated features
1617 Sys::Virt::Domain::MESSAGE_TAINTING
1619 Warnings about actions that have tainting the domain
1620 $dom->start_dirty_rate_calc($dom, $secs, $flags=0)
1622 Request calculation of the domain's memory dirty rate over the next
1623 $secs seconds. $flags accepts one or more of
1624 Sys::Virt::Domain::DIRTYRATE_MODE_PAGE_SAMPLING
1626 Page sampling mode
1627 Sys::Virt::Domain::DIRTYRATE_MODE_DIRTY_BITMAP
1629 Dirty bitmap mode
1630 Sys::Virt::Domain::DIRTYRATE_MODE_DIRTY_RING
1632 Dirty ring mode
1633 $dom->fd_associate($name, \@fds, $flags=0)
1635 Associate a set of file descriptors in @fds with the domain, giving
1636 them the name $name. If $flags is non-zero, it can take one or
1637 more of:
1638 Sys::Virt::Domain::FD_ASSOCIATE_SECLABEL_RESTORE
1640 Attempt to restore the label when shutting down
1641 Sys::Virt::Domain::FD_ASSOCIATE_SECLABEL_WRITABLE
1643 Label the FD to permit the guest to write to it.
1644
1646 A number of the APIs take a "flags" parameter. In most cases passing a
1647 value of zero will be satisfactory. Some APIs, however, accept named
1648 constants to alter their behaviour. This section documents the current
1649 known constants.
1650 DOMAIN STATE
1652 The domain state constants are useful in interpreting the "state" key
1653 in the hash returned by the "get_info" method.
1654 Sys::Virt::Domain::STATE_NOSTATE
1656 The domain is active, but is not running / blocked (e.g. idle)
1657 Sys::Virt::Domain::STATE_RUNNING
1659 The domain is active and running
1660 Sys::Virt::Domain::STATE_BLOCKED
1662 The domain is active, but execution is blocked
1663 Sys::Virt::Domain::STATE_PAUSED
1665 The domain is active, but execution has been paused
1666 Sys::Virt::Domain::STATE_SHUTDOWN
1668 The domain is active, but in the shutdown phase
1669 Sys::Virt::Domain::STATE_SHUTOFF
1671 The domain is inactive, and shut down.
1672 Sys::Virt::Domain::STATE_CRASHED
1674 The domain is inactive, and crashed.
1675 Sys::Virt::Domain::STATE_PMSUSPENDED
1677 The domain is active, but in power management suspend state
1678 CONTROL INFO
1680 The following constants can be used to determine what the guest domain
1681 control channel status is
1682 Sys::Virt::Domain::CONTROL_ERROR
1684 The control channel has a fatal error
1685 Sys::Virt::Domain::CONTROL_OK
1687 The control channel is ready for jobs
1688 Sys::Virt::Domain::CONTROL_OCCUPIED
1690 The control channel is busy
1691 Sys::Virt::Domain::CONTROL_JOB
1693 The control channel is busy with a job
1694 If the status is "Sys::Virt::Domain::CONTROL_ERROR", then one of the
1696 following constants describes the reason
1697 Sys::Virt::Domain::CONTROL_ERROR_REASON_NONE
1699 There is no reason for the error available
1700 Sys::Virt::Domain::CONTROL_ERROR_REASON_UNKNOWN
1702 The reason for the error is unknown
1703 Sys::Virt::Domain::CONTROL_ERROR_REASON_INTERNAL
1705 There was an internal error in libvirt
1706 Sys::Virt::Domain::CONTROL_ERROR_REASON_MONITOR
1708 There was an error speaking to the monitor
1709 DOMAIN CREATION
1711 The following constants can be used to control the behaviour of domain
1712 creation
1713 Sys::Virt::Domain::START_PAUSED
1715 Keep the guest vCPUs paused after starting the guest
1716 Sys::Virt::Domain::START_AUTODESTROY
1718 Automatically destroy the guest when the connection is closed (or
1719 fails)
1720 Sys::Virt::Domain::START_BYPASS_CACHE
1722 Do not use OS I/O cache if starting a domain with a saved state
1723 image
1724 Sys::Virt::Domain::START_FORCE_BOOT
1726 Boot the guest, even if there was a saved snapshot
1727 Sys::Virt::Domain::START_VALIDATE
1729 Validate the XML document against the XML schema
1730 Sys::Virt::Domain::START_RESET_NVRAM
1732 Reset the firmware NVRAM state from its original template
1733 DOMAIN DEFINE
1735 The following constants can be used to control the behaviour of domain
1736 define operations
1737 Sys::Virt::Domain::DEFINE_VALIDATE
1739 Validate the XML document against the XML schema
1740 KEYCODE SETS
1742 The following constants define the set of supported keycode sets
1743 Sys::Virt::Domain::KEYCODE_SET_LINUX
1745 The Linux event subsystem keycodes
1746 Sys::Virt::Domain::KEYCODE_SET_XT
1748 The original XT keycodes
1749 Sys::Virt::Domain::KEYCODE_SET_ATSET1
1751 The AT Set1 keycodes (aka XT)
1752 Sys::Virt::Domain::KEYCODE_SET_ATSET2
1754 The AT Set2 keycodes (aka AT)
1755 Sys::Virt::Domain::KEYCODE_SET_ATSET3
1757 The AT Set3 keycodes (aka PS2)
1758 Sys::Virt::Domain::KEYCODE_SET_OSX
1760 The OS-X keycodes
1761 Sys::Virt::Domain::KEYCODE_SET_XT_KBD
1763 The XT keycodes from the Linux Keyboard driver
1764 Sys::Virt::Domain::KEYCODE_SET_USB
1766 The USB HID keycode set
1767 Sys::Virt::Domain::KEYCODE_SET_WIN32
1769 The Windows keycode set
1770 Sys::Virt::Domain::KEYCODE_SET_QNUM
1772 The XT keycode set, with the extended scancodes using the high bit
1773 of the first byte, instead of the low bit of the second byte.
1774 Sys::Virt::Domain::KEYCODE_SET_RFB
1776 A deprecated alias for "Sys::Virt::Domain::KEYCODE_SET_QNUM"
1777 MEMORY PEEK
1779 The following constants can be used with the "memory_peek" method's
1780 flags parameter
1781 Sys::Virt::Domain::MEMORY_VIRTUAL
1783 Indicates that the offset is using virtual memory addressing.
1784 Sys::Virt::Domain::MEMORY_PHYSICAL
1786 Indicates that the offset is using physical memory addressing.
1787 VCPU STATE
1789 The following constants are useful when interpreting the virtual CPU
1790 run state
1791 Sys::Virt::Domain::VCPU_OFFLINE
1793 The virtual CPU is not online
1794 Sys::Virt::Domain::VCPU_RUNNING
1796 The virtual CPU is executing code
1797 Sys::Virt::Domain::VCPU_BLOCKED
1799 The virtual CPU is waiting to be scheduled
1800 VCPU HOST PLACEMENT STATE
1802 The following constants are useful when interpreting the virtual CPU
1803 host placement
1804 Sys::Virt::Domain::VCPU_INFO_CPU_OFFLINE
1806 The virtual CPU is not online
1807 Sys::Virt::Domain::VCPU_INFO_CPU_UNAVAILABLE
1809 The virtual CPU placement is not available from this hypervisor
1810 OPEN GRAPHICS CONSTANTS
1812 The following constants are used when opening a connection to the guest
1813 graphics server
1814 Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH
1816 Skip authentication of the client
1817 OPEN CONSOLE CONSTANTS
1819 The following constants are used when opening a connection to the guest
1820 console
1821 Sys::Virt::Domain::OPEN_CONSOLE_FORCE
1823 Force opening of the console, disconnecting any other open session
1824 Sys::Virt::Domain::OPEN_CONSOLE_SAFE
1826 Check if the console driver supports safe operations
1827 OPEN CHANNEL CONSTANTS
1829 The following constants are used when opening a connection to the guest
1830 channel
1831 Sys::Virt::Domain::OPEN_CHANNEL_FORCE
1833 Force opening of the channel, disconnecting any other open session
1834 XML DUMP OPTIONS
1836 The following constants are used to control the information included in
1837 the XML configuration dump
1838 Sys::Virt::Domain::XML_INACTIVE
1840 Report the persistent inactive configuration for the guest, even if
1841 it is currently running.
1842 Sys::Virt::Domain::XML_SECURE
1844 Include security sensitive information in the XML dump, such as
1845 passwords.
1846 Sys::Virt::Domain::XML_UPDATE_CPU
1848 Update the CPU model definition to match the current executing
1849 state.
1850 Sys::Virt::Domain::XML_MIGRATABLE
1852 Update the XML to allow migration to older versions of libvirt
1853 DEVICE HOTPLUG OPTIONS
1855 The following constants are used to control device hotplug operations
1856 Sys::Virt::Domain::DEVICE_MODIFY_CURRENT
1858 Modify the domain in its current state
1859 Sys::Virt::Domain::DEVICE_MODIFY_LIVE
1861 Modify only the live state of the domain
1862 Sys::Virt::Domain::DEVICE_MODIFY_CONFIG
1864 Modify only the persistent config of the domain
1865 Sys::Virt::Domain::DEVICE_MODIFY_FORCE
1867 Force the device to be modified
1868 MEMORY OPTIONS
1870 The following constants are used to control memory change operations
1871 Sys::Virt::Domain::MEM_CURRENT
1873 Modify the current state
1874 Sys::Virt::Domain::MEM_LIVE
1876 Modify only the live state of the domain
1877 Sys::Virt::Domain::MEM_CONFIG
1879 Modify only the persistent config of the domain
1880 Sys::Virt::Domain::MEM_MAXIMUM
1882 Modify the maximum memory value
1883 CONFIG OPTIONS
1885 The following constants are used to control what configuration a domain
1886 update changes
1887 Sys::Virt::Domain::AFFECT_CURRENT
1889 Modify the current state
1890 Sys::Virt::Domain::AFFECT_LIVE
1892 Modify only the live state of the domain
1893 Sys::Virt::Domain::AFFECT_CONFIG
1895 Modify only the persistent config of the domain
1896 MIGRATE OPTIONS
1898 The following constants are used to control how migration is performed
1899 Sys::Virt::Domain::MIGRATE_LIVE
1901 Migrate the guest without interrupting its execution on the source
1902 host.
1903 Sys::Virt::Domain::MIGRATE_PEER2PEER
1905 Manage the migration process over a direct peer-2-peer connection
1906 between the source and destination host libvirtd daemons.
1907 Sys::Virt::Domain::MIGRATE_TUNNELLED
1909 Tunnel the migration data over the libvirt daemon connection,
1910 rather than the native hypervisor data transport. Requires
1911 PEER2PEER flag to be set.
1912 Sys::Virt::Domain::MIGRATE_PERSIST_DEST
1914 Make the domain persistent on the destination host, defining its
1915 configuration file upon completion of migration.
1916 Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE
1918 Remove the domain's persistent configuration after migration
1919 completes successfully.
1920 Sys::Virt::Domain::MIGRATE_PAUSED
1922 Do not re-start execution of the guest CPUs on the destination host
1923 after migration completes.
1924 Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK
1926 Copy the complete contents of the disk images during migration
1927 Sys::Virt::Domain::MIGRATE_NON_SHARED_INC
1929 Copy the incrementally changed contents of the disk images during
1930 migration
1931 Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION
1933 Do not allow changes to the virtual domain configuration while
1934 migration is taking place. This option is automatically implied if
1935 doing a peer-2-peer migration.
1936 Sys::Virt::Domain::MIGRATE_UNSAFE
1938 Migrate even if the compatibility check indicates the migration
1939 will be unsafe to the guest.
1940 Sys::Virt::Domain::MIGRATE_OFFLINE
1942 Migrate the guest config if the guest is not currently running
1943 Sys::Virt::Domain::MIGRATE_COMPRESSED
1945 Enable compression of the migration data stream
1946 Sys::Virt::Domain::MIGRATE_ABORT_ON_ERROR
1948 Abort if an I/O error occurs on the disk
1949 Sys::Virt::Domain::MIGRATE_AUTO_CONVERGE
1951 Force convergence of the migration operation by throttling guest
1952 runtime
1953 Sys::Virt::Domain::MIGRATE_RDMA_PIN_ALL
1955 Pin memory for RDMA transfer
1956 Sys::Virt::Domain::MIGRATE_POSTCOPY
1958 Enable support for post-copy migration
1959 Sys::Virt::Domain::MIGRATE_TLS
1961 Setting this flag will cause the migration to attempt to use the
1962 TLS environment configured by the hypervisor in order to perform
1963 the migration. If incorrectly configured on either source or
1964 destination, the migration will fail.
1965 Sys::Virt::Domain::MIGRATE_PARALLEL
1967 Send memory pages to the destination host through several network
1968 connections. See "Sys::Virt::Domain::MIGRATE_PARAM_PARALLEL_*"
1969 parameters for configuring the parallel migration.
1970 Sys::Virt::Domain::MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES
1972 Force the guest writes which happen when copying disk images for
1973 non-shared storage migration to be synchronously written to the
1974 destination. This ensures the storage migration converges for VMs
1975 doing heavy I/O on fast local storage and slow mirror.
1976 Sys::Virt::Domain::MIGRATE_POSTCOPY_RESUME
1978 Resume migration which failed in post-copy phase.
1979 Sys::Virt::Domain::MIGRATE_ZEROCOPY
1981 Attempt to avoid copying data. This is a request, not a guarantee
1982 and may apply to either one or both directions of data transfer at
1983 discretion of the hypervisor implementation.
1984 UNDEFINE CONSTANTS
1986 The following constants can be used when undefining virtual domain
1987 configurations
1988 Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE
1990 Also remove any managed save image when undefining the virtual
1991 domain
1992 Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA
1994 Also remove any snapshot metadata when undefining the virtual
1995 domain.
1996 Sys::Virt::Domain::UNDEFINE_NVRAM
1998 Also remove any NVRAM state file when undefining the virtual
1999 domain.
2000 Sys::Virt::Domain::UNDEFINE_KEEP_NVRAM
2002 keep NVRAM state file when undefining the virtual domain.
2003 Sys::Virt::Domain::UNDEFINE_CHECKPOINTS_METADATA
2005 Also remove any checkpoint metadata when undefining the virtual
2006 domain.
2007 Sys::Virt::Domain::UNDEFINE_TPM
2009 Also remove any TPM state when undefining the virtual domain.
2010 Sys::Virt::Domain::UNDEFINE_KEEP_TPM
2012 Keep TPM state when undefining the virtual domain.
2013 JOB TYPES
2015 The following constants describe the different background job types.
2016 Sys::Virt::Domain::JOB_NONE
2018 No job is active
2019 Sys::Virt::Domain::JOB_BOUNDED
2021 A job with a finite completion time is active
2022 Sys::Virt::Domain::JOB_UNBOUNDED
2024 A job with an unbounded completion time is active
2025 Sys::Virt::Domain::JOB_COMPLETED
2027 The job has finished, but isn't cleaned up
2028 Sys::Virt::Domain::JOB_FAILED
2030 The job has hit an error, but isn't cleaned up
2031 Sys::Virt::Domain::JOB_CANCELLED
2033 The job was aborted at user request, but isn't cleaned up
2034 MEMORY PARAMETERS
2036 The following constants are useful when getting/setting memory
2037 parameters for guests
2038 Sys::Virt::Domain::MEMORY_HARD_LIMIT
2040 The maximum memory the guest can use.
2041 Sys::Virt::Domain::MEMORY_SOFT_LIMIT
2043 The memory upper limit enforced during memory contention.
2044 Sys::Virt::Domain::MEMORY_MIN_GUARANTEE
2046 The minimum memory guaranteed to be reserved for the guest.
2047 Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT
2049 The maximum swap the guest can use.
2050 Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED
2052 The value of an unlimited memory parameter
2053 BLKIO PARAMETERS
2055 The following parameters control I/O tuning for the domain as a whole
2056 Sys::Virt::Domain::BLKIO_WEIGHT
2058 The I/O weight parameter
2059 Sys::Virt::Domain::BLKIO_DEVICE_WEIGHT
2061 The per-device I/O weight parameter
2062 Sys::Virt::Domain::BLKIO_DEVICE_READ_BPS
2064 The per-device I/O bytes read per second
2065 Sys::Virt::Domain::BLKIO_DEVICE_READ_IOPS
2067 The per-device I/O operations read per second
2068 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_BPS
2070 The per-device I/O bytes write per second
2071 Sys::Virt::Domain::BLKIO_DEVICE_WRITE_IOPS
2073 The per-device I/O operations write per second
2074 BLKIO TUNING PARAMETERS
2076 The following parameters control I/O tuning for an individual guest
2077 disk.
2078 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC
2080 The total bytes processed per second.
2081 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC
2083 The bytes read per second.
2084 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC
2086 The bytes written per second.
2087 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC
2089 The total I/O operations processed per second.
2090 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC
2092 The I/O operations read per second.
2093 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC
2095 The I/O operations written per second.
2096 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX
2098 The maximum total bytes processed per second.
2099 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX
2101 The maximum bytes read per second.
2102 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX
2104 The maximum bytes written per second.
2105 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX
2107 The maximum total I/O operations processed per second.
2108 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX
2110 The maximum I/O operations read per second.
2111 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX
2113 The maximum I/O operations written per second.
2114 Sys::Virt::Domain::BLOCK_IOTUNE_SIZE_IOPS_SEC
2116 The maximum I/O operations per second
2117 Sys::Virt::Domain::BLOCK_IOTUNE_GROUP_NAME
2119 A string representing a group name to allow sharing of I/O
2120 throttling quota between multiple drives
2121 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX_LENGTH
2123 The duration in seconds allowed for maximum total bytes processed
2124 per second.
2125 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC_MAX_LENGTH
2127 The duration in seconds allowed for maximum bytes read per second.
2128 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX_LENGTH
2130 The duration in seconds allowed for maximum bytes written per
2131 second.
2132 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX_LENGTH
2134 The duration in seconds allowed for maximum total I/O operations
2135 processed per second.
2136 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC_MAX_LENGTH
2138 The duration in seconds allowed for maximum I/O operations read per
2139 second.
2140 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX_LENGTH
2142 The duration in seconds allowed for maximum I/O operations written
2143 per second.
2144 SCHEDULER CONSTANTS
2146 Sys::Virt::Domain::SCHEDULER_CAP
2147 The VM cap tunable
2148 Sys::Virt::Domain::SCHEDULER_CPU_SHARES
2150 The CPU shares tunable
2151 Sys::Virt::Domain::SCHEDULER_LIMIT
2153 The VM limit tunable
2154 Sys::Virt::Domain::SCHEDULER_RESERVATION
2156 The VM reservation tunable
2157 Sys::Virt::Domain::SCHEDULER_SHARES
2159 The VM shares tunable
2160 Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD
2162 The VCPU period tunable
2163 Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA
2165 The VCPU quota tunable
2166 Sys::Virt::Domain::SCHEDULER_GLOBAL_PERIOD
2168 The VM global period tunable
2169 Sys::Virt::Domain::SCHEDULER_GLOBAL_QUOTA
2171 The VM global quota tunable
2172 Sys::Virt::Domain::SCHEDULER_WEIGHT
2174 The VM weight tunable
2175 NUMA PARAMETERS
2177 The following constants are useful when getting/setting the guest NUMA
2178 memory policy
2179 Sys::Virt::Domain::NUMA_MODE
2181 The NUMA policy mode
2182 Sys::Virt::Domain::NUMA_NODESET
2184 The NUMA nodeset mask
2185 The following constants are useful when interpreting the
2187 "Sys::Virt::Domain::NUMA_MODE" parameter value
2188 Sys::Virt::Domain::NUMATUNE_MEM_STRICT
2190 Allocation is mandatory from the mask nodes
2191 Sys::Virt::Domain::NUMATUNE_MEM_PREFERRED
2193 Allocation is preferred from the masked nodes
2194 Sys::Virt::Domain::NUMATUNE_MEM_INTERLEAVE
2196 Allocation is interleaved across all masked nodes
2197 Sys::Virt::Domain::NUMATUNE_MEM_RESTRICTIVE
2199 Allocation is determined by the host using the masked nodes.
2200 INTERFACE PARAMETERS
2202 The following constants are useful when getting/setting the per network
2203 interface tunable parameters
2204 Sys::Virt::Domain::BANDWIDTH_IN_AVERAGE
2206 The average inbound bandwidth
2207 Sys::Virt::Domain::BANDWIDTH_IN_PEAK
2209 The peak inbound bandwidth
2210 Sys::Virt::Domain::BANDWIDTH_IN_BURST
2212 The burstable inbound bandwidth
2213 Sys::Virt::Domain::BANDWIDTH_IN_FLOOR
2215 The minimum inbound bandwidth
2216 Sys::Virt::Domain::BANDWIDTH_OUT_AVERAGE
2218 The average outbound bandwidth
2219 Sys::Virt::Domain::BANDWIDTH_OUT_PEAK
2221 The peak outbound bandwidth
2222 Sys::Virt::Domain::BANDWIDTH_OUT_BURST
2224 The burstable outbound bandwidth
2225 PERF EVENTS
2227 The following constants defined performance events which can be
2228 monitored for a guest
2229 Sys::Virt::Domain::PERF_PARAM_CMT
2231 The CMT event counter which can be used to measure the usage of
2232 cache (bytes) by applications running on the platform. It
2233 corresponds to the "perf.cmt" field in the *Stats APIs.
2234 Sys::Virt::Domain::PERF_PARAM_MBML
2236 The MBML event counter which can be used to monitor the amount of
2237 data (bytes/s) sent through the memory controller on the socket.
2238 It corresponds to the "perf.mbml" field in the *Stats APIs.
2239 Sys::Virt::Domain::PERF_PARAM_MBMT
2241 The MBMT event counter which can be used to monitor total system
2242 bandwidth (bytes/s) from one level of cache to another. It
2243 corresponds to the "perf.mbmt" field in the *Stats APIs.
2244 Sys::Virt::Domain::PERF_PARAM_CACHE_MISSES
2246 The cache_misses perf event counter which can be used to measure
2247 the count of cache misses by applications running on the platform.
2248 It corresponds to the "perf.cache_misses" field in the *Stats APIs.
2249 Sys::Virt::Domain::PERF_PARAM_CACHE_REFERENCES
2251 The cache_references perf event counter which can be used to
2252 measure the count of cache hits by applications running on the
2253 platform. It corresponds to the "perf.cache_references" field in
2254 the *Stats APIs.
2255 Sys::Virt::Domain::PERF_PARAM_CPU_CYCLES
2257 The cpu_cycles perf event counter which can be used to measure how
2258 many cpu cycles one instruction needs. It corresponds to the
2259 "perf.cpu_cycles" field in the *Stats APIs.
2260 Sys::Virt::Domain::PERF_PARAM_INSTRUCTIONS
2262 The instructions perf event counter which can be used to measure
2263 the count of instructions by applications running on the platform.
2264 It corresponds to the "perf.instructions" field in the *Stats APIs.
2265 Sys::Virt::Domain::PERF_PARAM_BRANCH_INSTRUCTIONS
2267 The branch_instructions perf event counter which can be used to
2268 measure the count of instructions by applications running on the
2269 platform. It corresponds to the "perf.branch_instructions" field in
2270 the *Stats APIs.
2271 Sys::Virt::Domain::PERF_PARAM_BRANCH_MISSES
2273 The branch_misses perf event which can be used to measure the count
2274 of branch misses by applications running on the platform. It
2275 corresponds to the "perf.branch_misses" field in the *Stats APIs.
2276 Sys::Virt::Domain::PERF_PARAM_BUS_CYCLES
2278 The bus_cycles perf event counter which can be used to measure the
2279 count of bus cycles by applications running on the platform. It
2280 corresponds to the "perf.bus_cycles" field in the *Stats APIs.
2281 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_FRONTEND
2283 The stalled_cycles_frontend perf event counter which can be used to
2284 measure the count of stalled cpu cycles in the frontend of the
2285 instruction processor pipeline by applications running on the
2286 platform. It corresponds to the "perf.stalled_cycles_frontend"
2287 field in the *Stats APIs.
2288 Sys::Virt::Domain::PERF_PARAM_STALLED_CYCLES_BACKEND
2290 The stalled_cycles_backend perf event counter which can be used to
2291 measure the count of stalled cpu cycles in the backend of the
2292 instruction processor pipeline by application running on the
2293 platform. It corresponds to the "perf.stalled_cycles_backend" field
2294 in the *Stats APIs.
2295 Sys::Virt::Domain::PERF_PARAM_REF_CPU_CYCLES
2297 The ref_cpu_cycles perf event counter which can be used to measure
2298 the count of total cpu cycles not affected by CPU frequency scaling
2299 by applications running on the platform. It corresponds to the
2300 "perf.ref_cpu_cycles" field in the *Stats APIs.
2301 Sys::Virt::Domain::PERF_PARAM_CPU_CLOCK
2303 The cpu_clock perf event counter which can be used to measure the
2304 count of cpu clock time by applications running on the platform. It
2305 corresponds to the "perf.cpu_clock" field in the *Stats APIs.
2306 Sys::Virt::Domain::PERF_PARAM_TASK_CLOCK
2308 The task_clock perf event counter which can be used to measure the
2309 count of task clock time by applications running on the platform.
2310 It corresponds to the "perf.task_clock" field in the *Stats APIs.
2311 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS
2313 The page_faults perf event counter which can be used to measure the
2314 count of page faults by applications running on the platform. It
2315 corresponds to the "perf.page_faults" field in the *Stats APIs.
2316 Sys::Virt::Domain::PERF_PARAM_CONTEXT_SWITCHES
2318 The context_switches perf event counter which can be used to
2319 measure the count of context switches by applications running on
2320 the platform. It corresponds to the "perf.context_switches" field
2321 in the *Stats APIs.
2322 Sys::Virt::Domain::PERF_PARAM_CPU_MIGRATIONS
2324 The cpu_migrations perf event counter which can be used to measure
2325 the count of cpu migrations by applications running on the
2326 platform. It corresponds to the "perf.cpu_migrations" field in the
2327 *Stats APIs.
2328 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MIN
2330 The page_faults_min perf event counter which can be used to measure
2331 the count of minor page faults by applications running on the
2332 platform. It corresponds to the "perf.page_faults_min" field in the
2333 *Stats APIs.
2334 Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MAJ
2336 The page_faults_maj perf event counter which can be used to measure
2337 the count of major page faults by applications running on the
2338 platform. It corresponds to the "perf.page_faults_maj" field in the
2339 *Stats APIs.
2340 Sys::Virt::Domain::PERF_PARAM_ALIGNMENT_FAULTS
2342 The alignment_faults perf event counter which can be used to
2343 measure the count of alignment faults by applications running on
2344 the platform. It corresponds to the "perf.alignment_faults" field
2345 in the *Stats APIs.
2346 Sys::Virt::Domain::PERF_PARAM_EMULATION_FAULTS
2348 The emulation_faults perf event counter which can be used to
2349 measure the count of emulation faults by applications running on
2350 the platform. It corresponds to the "perf.emulation_faults" field
2351 in the *Stats APIs.
2352 IOTHREAD STATS
2354 The following constants defined IOThread statistics which can be
2355 monitored for a guest
2356 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_MAX_NS
2358 The maximum polling time that can be used by polling algorithm in
2359 ns. The polling time starts at 0 (zero) and is the time spent by
2360 the guest to process IOThread data before returning the CPU to the
2361 host. The polling time will be dynamically modified over time based
2362 on the poll_grow and poll_shrink parameters provided.
2363 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_GROW
2365 This provides a value for the dynamic polling adjustment algorithm
2366 to use to grow its polling interval up to the poll_max_ns value.
2367 Sys::Virt::Domain::IOTHREAD_PARAM_POLL_SHRINK
2369 This provides a value for the dynamic polling adjustment algorithm
2370 to use to shrink its polling interval when the polling interval
2371 exceeds the poll_max_ns value.
2372 Sys::Virt::Domain::IOTHREAD_PARAM_THREAD_POOL_MIN
2374 Sets the lower bound for thread pool size. A value of -1 disables
2375 this bound leaving hypervisor use its default value, though this
2376 value is not accepted for running domains. Due to internal
2377 implementation it's recommended to set lower and upper bounds
2378 separately.
2379 Sys::Virt::Domain::IOTHREAD_PARAM_THREAD_POOL_MAX
2381 Sets the upper bound for thread pool size. A value of -1 disables
2382 this bound leaving hypervisor use its default value, though this
2383 value is not accepted for running domains. Since the upper band has
2384 to be equal to or greater than lower bound value of 0 is not
2385 accepted. Due to internal implementation it's recommended to set
2386 lower and upper bounds separately.
2387 VCPU FLAGS
2389 The following constants are useful when getting/setting the VCPU count
2390 for a guest
2391 Sys::Virt::Domain::VCPU_LIVE
2393 Flag to request the live value
2394 Sys::Virt::Domain::VCPU_CONFIG
2396 Flag to request the persistent config value
2397 Sys::Virt::Domain::VCPU_CURRENT
2399 Flag to request the current config value
2400 Sys::Virt::Domain::VCPU_MAXIMUM
2402 Flag to request adjustment of the maximum vCPU value
2403 Sys::Virt::Domain::VCPU_GUEST
2405 Flag to request the guest VCPU mask
2406 Sys::Virt::Domain::VCPU_HOTPLUGGABLE
2408 Flag to make vcpus added hot(un)pluggable
2409 STATE CHANGE EVENTS
2411 The following constants allow domain state change events to be
2412 interpreted. The events contain both a state change, and a reason.
2413 Sys::Virt::Domain::EVENT_DEFINED
2415 Indicates that a persistent configuration has been defined for the
2416 domain.
2417 Sys::Virt::Domain::EVENT_DEFINED_ADDED
2419 The defined configuration is newly added
2420 Sys::Virt::Domain::EVENT_DEFINED_UPDATED
2422 The defined configuration is an update to an existing
2423 configuration
2424 Sys::Virt::Domain::EVENT_DEFINED_RENAMED
2426 The defined configuration is a rename of an existing
2427 configuration
2428 Sys::Virt::Domain::EVENT_DEFINED_FROM_SNAPSHOT
2430 The defined configuration was restored from a snapshot
2431 Sys::Virt::Domain::EVENT_RESUMED
2433 The domain has resumed execution
2434 Sys::Virt::Domain::EVENT_RESUMED_MIGRATED
2436 The domain resumed because migration has completed. This is
2437 emitted on the destination host.
2438 Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED
2440 The domain resumed because the admin unpaused it.
2441 Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT
2443 The domain resumed because it was restored from a snapshot
2444 Sys::Virt::Domain::EVENT_RESUMED_POSTCOPY
2446 The domain resumed but post-copy is running in background
2447 Sys::Virt::Domain::EVENT_RESUMED_POSTCOPY_FAILED
2449 The domain is running, but migration failed in post-copy.
2450 Sys::Virt::Domain::EVENT_STARTED
2452 The domain has started running
2453 Sys::Virt::Domain::EVENT_STARTED_BOOTED
2455 The domain was booted from shutoff state
2456 Sys::Virt::Domain::EVENT_STARTED_MIGRATED
2458 The domain started due to an incoming migration
2459 Sys::Virt::Domain::EVENT_STARTED_RESTORED
2461 The domain was restored from saved state file
2462 Sys::Virt::Domain::EVENT_STARTED_FROM_SNAPSHOT
2464 The domain was restored from a snapshot
2465 Sys::Virt::Domain::EVENT_STARTED_WAKEUP
2467 The domain was woken up from suspend
2468 Sys::Virt::Domain::EVENT_STOPPED
2470 The domain has stopped running
2471 Sys::Virt::Domain::EVENT_STOPPED_CRASHED
2473 The domain stopped because guest operating system has crashed
2474 Sys::Virt::Domain::EVENT_STOPPED_DESTROYED
2476 The domain stopped because administrator issued a destroy
2477 command.
2478 Sys::Virt::Domain::EVENT_STOPPED_FAILED
2480 The domain stopped because of a fault in the host
2481 virtualization environment.
2482 Sys::Virt::Domain::EVENT_STOPPED_MIGRATED
2484 The domain stopped because it was migrated to another machine.
2485 Sys::Virt::Domain::EVENT_STOPPED_SAVED
2487 The domain was saved to a state file
2488 Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN
2490 The domain stopped due to graceful shutdown of the guest.
2491 Sys::Virt::Domain::EVENT_STOPPED_FROM_SNAPSHOT
2493 The domain was stopped due to a snapshot
2494 Sys::Virt::Domain::EVENT_SHUTDOWN
2496 The domain has shutdown but is not yet stopped
2497 Sys::Virt::Domain::EVENT_SHUTDOWN_FINISHED
2499 The domain finished shutting down
2500 Sys::Virt::Domain::EVENT_SHUTDOWN_HOST
2502 The domain shutdown due to host trigger
2503 Sys::Virt::Domain::EVENT_SHUTDOWN_GUEST
2505 The domain shutdown due to guest trigger
2506 Sys::Virt::Domain::EVENT_SUSPENDED
2508 The domain has stopped executing, but still exists
2509 Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED
2511 The domain has been suspended due to offline migration
2512 Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED
2514 The domain has been suspended due to administrator pause
2515 request.
2516 Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR
2518 The domain has been suspended due to a block device I/O error.
2519 Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT
2521 The domain has been suspended due to resume from snapshot
2522 Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG
2524 The domain has been suspended due to the watchdog triggering
2525 Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED
2527 The domain has been suspended due to restore from saved state
2528 Sys::Virt::Domain::EVENT_SUSPENDED_API_ERROR
2530 The domain has been suspended due to an API error
2531 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY
2533 The domain has been suspended for post-copy migration
2534 Sys::Virt::Domain::EVENT_SUSPENDED_POSTCOPY_FAILED
2536 The domain has been suspended due post-copy migration failing
2537 Sys::Virt::Domain::EVENT_UNDEFINED
2539 The persistent configuration has gone away
2540 Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED
2542 The domain configuration has gone away due to it being removed
2543 by administrator.
2544 Sys::Virt::Domain::EVENT_UNDEFINED_RENAMED
2546 The undefined configuration is a rename of an existing
2547 configuration
2548 Sys::Virt::Domain::EVENT_PMSUSPENDED
2550 The domain has stopped running
2551 Sys::Virt::Domain::EVENT_PMSUSPENDED_MEMORY
2553 The domain has suspend to RAM.
2554 Sys::Virt::Domain::EVENT_PMSUSPENDED_DISK
2556 The domain has suspend to Disk.
2557 Sys::Virt::Domain::EVENT_CRASHED
2559 The domain has crashed
2560 Sys::Virt::Domain::EVENT_CRASHED_PANICKED
2562 The domain has crashed due to a kernel panic
2563 Sys::Virt::Domain::EVENT_CRASHED_CRASHLOADED
2565 The domain has crashed and reloaded itself
2566 EVENT ID CONSTANTS
2568 Sys::Virt::Domain::EVENT_ID_LIFECYCLE
2569 Domain lifecycle events
2570 Sys::Virt::Domain::EVENT_ID_REBOOT
2572 Soft / warm reboot events
2573 Sys::Virt::Domain::EVENT_ID_RTC_CHANGE
2575 RTC clock adjustments
2576 Sys::Virt::Domain::EVENT_ID_IO_ERROR
2578 File IO errors, typically from disks
2579 Sys::Virt::Domain::EVENT_ID_WATCHDOG
2581 Watchdog device triggering
2582 Sys::Virt::Domain::EVENT_ID_GRAPHICS
2584 Graphics client connections.
2585 Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON
2587 File IO errors, typically from disks, with a root cause
2588 Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR
2590 Errors from the virtualization control channel
2591 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB
2593 Completion status of asynchronous block jobs, identified by source
2594 file name.
2595 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB_2
2597 Completion status of asynchronous block jobs, identified by target
2598 device name.
2599 Sys::Virt::Domain::EVENT_ID_DISK_CHANGE
2601 Changes in disk media
2602 Sys::Virt::Domain::EVENT_ID_TRAY_CHANGE
2604 CDROM media tray state
2605 Sys::Virt::Domain::EVENT_ID_PMSUSPEND
2607 Power management initiated suspend to RAM
2608 Sys::Virt::Domain::EVENT_ID_PMSUSPEND_DISK
2610 Power management initiated suspend to Disk
2611 Sys::Virt::Domain::EVENT_ID_PMWAKEUP
2613 Power management initiated wakeup
2614 Sys::Virt::Domain::EVENT_ID_BALLOON_CHANGE
2616 Balloon target changes
2617 Sys::Virt::Domain::EVENT_ID_DEVICE_ADDED
2619 Asynchronous guest device addition
2620 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVED
2622 Asynchronous guest device removal
2623 Sys::Virt::Domain::EVENT_ID_TUNABLE
2625 Changes of any domain tuning parameters. The callback will be
2626 provided with a hash listing all changed parameters. The later
2627 DOMAIN TUNABLE constants can be useful when accessing the hash keys
2628 Sys::Virt::Domain::EVENT_ID_AGENT_LIFECYCLE
2630 Domain guest agent lifecycle events. The "state" parameter to the
2631 callback will match one of the constants
2632 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_CONNECTED
2634 The agent is now connected
2635 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_STATE_DISCONNECTED
2637 The agent is now disconnected
2638 The second parameter, "reason", matches one of the following
2640 constants
2641 Sys::Virt::Domain::EVENT_ID_MIGRATION_ITERATION
2643 Domain migration progress iteration. The "iteration" parameter to
2644 the callback will specify the number of iterations migration has
2645 made over guest RAM.
2646 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_UNKNOWN
2648 The reason is unknown
2649 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_DOMAIN_STARTED
2651 The domain was initially booted
2652 Sys::Virt::Domain::EVENT_AGENT_LIFECYCLE_REASON_CHANNEL
2654 The channel on a running guest changed state
2655 Sys::Virt::Domain::EVENT_ID_JOB_COMPLETED
2657 Domain background job completion notification. The callback
2658 provides a hash containing the job stats. The keys in the hash are
2659 the same as those used with the Sys::Virt::Domain::get_job_stats()
2660 method.
2661 Sys::Virt::Domain::EVENT_ID_DEVICE_REMOVAL_FAILED
2663 Guest device removal has failed.
2664 Sys::Virt::Domain::EVENT_ID_METADATA_CHANGE
2666 The domain metadata has changed
2667 Sys::Virt::Domain::EVENT_ID_BLOCK_THRESHOLD
2669 The event occurs when the hypervisor detects that the given storage
2670 element was written beyond the point specified by threshold. The
2671 event is useful for thin-provisioned storage.
2672 Sys::Virt::Domain::EVENT_ID_MEMORY_FAILURE
2674 The event occurs when the hypervisor detects hardware memory
2675 corruption.
2676 Sys::Virt::Domain::EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE
2678 The event occurs when the guest accepts a request to change the
2679 memory device size.
2680 IO ERROR EVENT CONSTANTS
2682 These constants describe what action was taken due to the IO error.
2683 Sys::Virt::Domain::EVENT_IO_ERROR_NONE
2685 No action was taken, the error was ignored & reported as success to
2686 guest
2687 Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE
2689 The guest is paused since the error occurred
2690 Sys::Virt::Domain::EVENT_IO_ERROR_REPORT
2692 The error has been reported to the guest OS
2693 WATCHDOG EVENT CONSTANTS
2695 These constants describe what action was taken due to the watchdog
2696 firing
2697 Sys::Virt::Domain::EVENT_WATCHDOG_NONE
2699 No action was taken, the watchdog was ignored
2700 Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE
2702 The guest is paused since the watchdog fired
2703 Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF
2705 The guest is powered off after the watchdog fired
2706 Sys::Virt::Domain::EVENT_WATCHDOG_RESET
2708 The guest is reset after the watchdog fired
2709 Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN
2711 The guest attempted to gracefully shutdown after the watchdog fired
2712 Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG
2714 No action was taken, the watchdog was logged
2715 Sys::Virt::Domain::EVENT_WATCHDOG_INJECTNMI
2717 An NMI was injected into the guest after the watchdog fired
2718 GRAPHICS EVENT PHASE CONSTANTS
2720 These constants describe the phase of the graphics connection
2721 Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT
2723 The initial client connection
2724 Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE
2726 The client has been authenticated & the connection is running
2727 Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT
2729 The client has disconnected
2730 GRAPHICS EVENT ADDRESS CONSTANTS
2732 These constants describe the format of the address
2733 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4
2735 An IPv4 address
2736 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6
2738 An IPv6 address
2739 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX
2741 An UNIX socket path address
2742 DISK CHANGE EVENT CONSTANTS
2744 These constants describe the reason for a disk change event
2745 Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START
2747 The disk media was cleared, as its source was missing when
2748 attempting to start the guest
2749 Sys::Virt::Domain::EVENT_DISK_DROP_MISSING_ON_START
2751 The disk device was dropped, as its source was missing when
2752 attempting to start the guest
2753 TRAY CHANGE CONSTANTS
2755 These constants describe the reason for a tray change event
2756 Sys::Virt::Domain::EVENT_TRAY_CHANGE_CLOSE
2758 The tray was closed
2759 Sys::Virt::Domain::EVENT_TRAY_CHANGE_OPEN
2761 The tray was opened
2762 DOMAIN BLOCK JOB TYPE CONSTANTS
2764 The following constants identify the different types of domain block
2765 jobs
2766 Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN
2768 An unknown block job type
2769 Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL
2771 The block pull job type
2772 Sys::Virt::Domain::BLOCK_JOB_TYPE_COPY
2774 The block copy job type
2775 Sys::Virt::Domain::BLOCK_JOB_TYPE_COMMIT
2777 The block commit job type
2778 Sys::Virt::Domain::BLOCK_JOB_TYPE_ACTIVE_COMMIT
2780 The block active commit job type
2781 Sys::Virt::Domain::BLOCK_JOB_TYPE_BACKUP
2783 The block backup job type
2784 DOMAIN BLOCK JOB COMPLETION CONSTANTS
2786 The following constants can be used to determine the completion status
2787 of a block job
2788 Sys::Virt::Domain::BLOCK_JOB_COMPLETED
2790 A successfully completed block job
2791 Sys::Virt::Domain::BLOCK_JOB_FAILED
2793 An unsuccessful block job
2794 Sys::Virt::Domain::BLOCK_JOB_CANCELED
2796 A block job canceled by the user
2797 Sys::Virt::Domain::BLOCK_JOB_READY
2799 A block job is running
2800 DOMAIN BLOCK REBASE CONSTANTS
2802 The following constants are useful when rebasing block devices
2803 Sys::Virt::Domain::BLOCK_REBASE_SHALLOW
2805 Limit copy to top of source backing chain
2806 Sys::Virt::Domain::BLOCK_REBASE_REUSE_EXT
2808 Reuse existing external file for copy
2809 Sys::Virt::Domain::BLOCK_REBASE_COPY_RAW
2811 Make destination file raw
2812 Sys::Virt::Domain::BLOCK_REBASE_COPY
2814 Start a copy job
2815 Sys::Virt::Domain::BLOCK_REBASE_COPY_DEV
2817 Treat destination as a block device instead of file
2818 Sys::Virt::Domain::BLOCK_REBASE_RELATIVE
2820 Keep backing chain referenced using relative names
2821 DOMAIN BLOCK COPY CONSTANTS
2823 The following constants are useful when copying block devices
2824 Sys::Virt::Domain::BLOCK_COPY_SHALLOW
2826 Limit copy to top of source backing chain
2827 Sys::Virt::Domain::BLOCK_COPY_REUSE_EXT
2829 Reuse existing external file for copy
2830 Sys::Virt::Domain::BLOCK_COPY_TRANSIENT_JOB
2832 Don't force usage of recoverable job for the copy operation
2833 Sys::Virt::Domain::BLOCK_COPY_SYNCHRONOUS_WRITES
2835 Force the copy job to synchronously propagate guest writes into the
2836 destination image, so that the copy is guaranteed to converge
2837 DOMAIN BLOCK JOB ABORT CONSTANTS
2839 The following constants are useful when aborting job copy jobs
2840 Sys::Virt::Domain::BLOCK_JOB_ABORT_ASYNC
2842 Request only, do not wait for completion
2843 Sys::Virt::Domain::BLOCK_JOB_ABORT_PIVOT
2845 Pivot to mirror when ending a copy job
2846 DOMAIN BLOCK COMMIT JOB CONSTANTS
2848 The following constants are useful with block commit job types
2849 Sys::Virt::Domain::BLOCK_COMMIT_DELETE
2851 Delete any files that are invalid after commit
2852 Sys::Virt::Domain::BLOCK_COMMIT_SHALLOW
2854 NULL base means next backing file, not whole chain
2855 Sys::Virt::Domain::BLOCK_COMMIT_ACTIVE
2857 Allow two phase commit when top is active layer
2858 Sys::Virt::Domain::BLOCK_COMMIT_RELATIVE
2860 Keep backing chain referenced using relative names
2861 DOMAIN SAVE / RESTORE FLAG CONSTANTS
2863 The following constants can be used when saving or restoring virtual
2864 machines
2865 Sys::Virt::Domain::SAVE_BYPASS_CACHE
2867 Do not use OS I/O cache when saving state.
2868 Sys::Virt::Domain::SAVE_PAUSED
2870 Mark the saved state as paused to prevent the guest CPUs starting
2871 upon restore.
2872 Sys::Virt::Domain::SAVE_RUNNING
2874 Mark the saved state as running to allow the guest CPUs to start
2875 upon restore.
2876 Sys::Virt::Domain::SAVE_RESET_NVRAM
2878 Reset the firmware NVRAM state from its original template
2879 SAVE / RESTORE PARAMETER CONSTANTS
2881 Sys::Virt::Domain::SAVE_PARAM_FILE
2882 Specify the save state file to save to or restore from.
2883 Sys::Virt::Domain::SAVE_PARAM_DXML
2885 Used to adjust guest xml on restore, e.g. to alter a device while
2886 domain is stopped.
2887 DOMAIN CORE DUMP CONSTANTS
2889 The following constants can be used when triggering domain core dumps
2890 Sys::Virt::Domain::DUMP_LIVE
2892 Do not pause execution while dumping the guest
2893 Sys::Virt::Domain::DUMP_CRASH
2895 Crash the guest after completing the core dump
2896 Sys::Virt::Domain::DUMP_BYPASS_CACHE
2898 Do not use OS I/O cache when writing core dump
2899 Sys::Virt::Domain::DUMP_RESET
2901 Reset the virtual machine after finishing the dump
2902 Sys::Virt::Domain::DUMP_MEMORY_ONLY
2904 Only include guest RAM in the dump, not the device state
2905 DESTROY CONSTANTS
2907 The following constants are useful when terminating guests using the
2908 "destroy" API.
2909 Sys::Virt::Domain::DESTROY_DEFAULT
2911 Destroy the guest using the default approach
2912 Sys::Virt::Domain::DESTROY_GRACEFUL
2914 Destroy the guest in a graceful manner
2915 Sys::Virt::Domain::DESTROY_REMOVE_LOGS
2917 Delete log files associated with the guest
2918 SHUTDOWN CONSTANTS
2920 The following constants are useful when requesting that a guest
2921 terminate using the "shutdown" API
2922 Sys::Virt::Domain::SHUTDOWN_DEFAULT
2924 Shutdown using the hypervisor's default mechanism
2925 Sys::Virt::Domain::SHUTDOWN_GUEST_AGENT
2927 Shutdown by issuing a command to a guest agent
2928 Sys::Virt::Domain::SHUTDOWN_ACPI_POWER_BTN
2930 Shutdown by injecting an ACPI power button press
2931 Sys::Virt::Domain::SHUTDOWN_INITCTL
2933 Shutdown by talking to initctl (containers only)
2934 Sys::Virt::Domain::SHUTDOWN_SIGNAL
2936 Shutdown by sending SIGTERM to the init process
2937 Sys::Virt::Domain::SHUTDOWN_PARAVIRT
2939 Shutdown by issuing a paravirt power control command
2940 REBOOT CONSTANTS
2942 The following constants are useful when requesting that a guest
2943 terminate using the "reboot" API
2944 Sys::Virt::Domain::REBOOT_DEFAULT
2946 Reboot using the hypervisor's default mechanism
2947 Sys::Virt::Domain::REBOOT_GUEST_AGENT
2949 Reboot by issuing a command to a guest agent
2950 Sys::Virt::Domain::REBOOT_ACPI_POWER_BTN
2952 Reboot by injecting an ACPI power button press
2953 Sys::Virt::Domain::REBOOT_INITCTL
2955 Reboot by talking to initctl (containers only)
2956 Sys::Virt::Domain::REBOOT_SIGNAL
2958 Reboot by sending SIGHUP to the init process
2959 Sys::Virt::Domain::REBOOT_PARAVIRT
2961 Reboot by issuing a paravirt power control command
2962 METADATA CONSTANTS
2964 The following constants are useful when reading/writing metadata about
2965 a guest
2966 Sys::Virt::Domain::METADATA_TITLE
2968 The short human friendly title of the guest
2969 Sys::Virt::Domain::METADATA_DESCRIPTION
2971 The long free text description of the guest
2972 Sys::Virt::Domain::METADATA_ELEMENT
2974 The structured metadata elements for the guest
2975 DISK ERROR CONSTANTS
2977 The following constants are useful when interpreting disk error codes
2978 Sys::Virt::Domain::DISK_ERROR_NONE
2980 No error
2981 Sys::Virt::Domain::DISK_ERROR_NO_SPACE
2983 The host storage has run out of free space
2984 Sys::Virt::Domain::DISK_ERROR_UNSPEC
2986 An unspecified error has occurred.
2987 MEMORY STATISTIC CONSTANTS
2989 Sys::Virt::Domain::MEMORY_STAT_SWAP_IN
2990 Swap in
2991 Sys::Virt::Domain::MEMORY_STAT_SWAP_OUT
2993 Swap out
2994 Sys::Virt::Domain::MEMORY_STAT_MINOR_FAULT
2996 Minor faults
2997 Sys::Virt::Domain::MEMORY_STAT_MAJOR_FAULT
2999 Major faults
3000 Sys::Virt::Domain::MEMORY_STAT_RSS
3002 Resident memory
3003 Sys::Virt::Domain::MEMORY_STAT_UNUSED
3005 Unused memory
3006 Sys::Virt::Domain::MEMORY_STAT_AVAILABLE
3008 Available memory
3009 Sys::Virt::Domain::MEMORY_STAT_ACTUAL_BALLOON
3011 Actual balloon limit
3012 Sys::Virt::Domain::MEMORY_STAT_USABLE
3014 Amount of usable memory
3015 Sys::Virt::Domain::MEMORY_STAT_LAST_UPDATE
3017 Time of last stats refresh from guest
3018 Sys::Virt::Domain::MEMORY_STAT_DISK_CACHES
3020 Disk cache size
3021 Sys::Virt::Domain::MEMORY_STAT_HUGETLB_PGALLOC
3023 The amount of successful huge page allocations
3024 Sys::Virt::Domain::MEMORY_STAT_HUGETLB_PGFAIL
3026 The amount of failed huge page allocations
3027 DOMAIN LIST CONSTANTS
3029 The following constants can be used when listing domains
3030 Sys::Virt::Domain::LIST_ACTIVE
3032 Only list domains that are currently active (running, or paused)
3033 Sys::Virt::Domain::LIST_AUTOSTART
3035 Only list domains that are set to automatically start on boot
3036 Sys::Virt::Domain::LIST_HAS_SNAPSHOT
3038 Only list domains that have a stored snapshot
3039 Sys::Virt::Domain::LIST_INACTIVE
3041 Only list domains that are currently inactive (shutoff, saved)
3042 Sys::Virt::Domain::LIST_MANAGEDSAVE
3044 Only list domains that have current managed save state
3045 Sys::Virt::Domain::LIST_NO_AUTOSTART
3047 Only list domains that are not set to automatically start on boto
3048 Sys::Virt::Domain::LIST_NO_MANAGEDSAVE
3050 Only list domains that do not have any managed save state
3051 Sys::Virt::Domain::LIST_NO_SNAPSHOT
3053 Only list domains that do not have a stored snapshot
3054 Sys::Virt::Domain::LIST_OTHER
3056 Only list domains that are not running, paused or shutoff
3057 Sys::Virt::Domain::LIST_PAUSED
3059 Only list domains that are paused
3060 Sys::Virt::Domain::LIST_PERSISTENT
3062 Only list domains which have a persistent config
3063 Sys::Virt::Domain::LIST_RUNNING
3065 Only list domains that are currently running
3066 Sys::Virt::Domain::LIST_SHUTOFF
3068 Only list domains that are currently shutoff
3069 Sys::Virt::Domain::LIST_TRANSIENT
3071 Only list domains that do not have a persistent config
3072 Sys::Virt::Domain::LIST_HAS_CHECKPOINT
3074 Only list domains that have a stored checkpoint
3075 Sys::Virt::Domain::LIST_NO_CHECKPOINT
3077 Only list domains that do not have a stored checkpoint
3078 SEND KEY CONSTANTS
3080 The following constants are to be used with the "send_key" API
3081 Sys::Virt::Domain::SEND_KEY_MAX_KEYS
3083 The maximum number of keys that can be sent in a single call to
3084 "send_key"
3085 BLOCK STATS CONSTANTS
3087 The following constants provide the names of well known block stats
3088 fields
3089 Sys::Virt::Domain::BLOCK_STATS_ERRS
3091 The number of I/O errors
3092 Sys::Virt::Domain::BLOCK_STATS_FLUSH_REQ
3094 The number of flush requests
3095 Sys::Virt::Domain::BLOCK_STATS_FLUSH_TOTAL_TIMES
3097 The time spent processing flush requests
3098 Sys::Virt::Domain::BLOCK_STATS_READ_BYTES
3100 The amount of data read
3101 Sys::Virt::Domain::BLOCK_STATS_READ_REQ
3103 The number of read requests
3104 Sys::Virt::Domain::BLOCK_STATS_READ_TOTAL_TIMES
3106 The time spent processing read requests
3107 Sys::Virt::Domain::BLOCK_STATS_WRITE_BYTES
3109 The amount of data written
3110 Sys::Virt::Domain::BLOCK_STATS_WRITE_REQ
3112 The number of write requests
3113 Sys::Virt::Domain::BLOCK_STATS_WRITE_TOTAL_TIMES
3115 The time spent processing write requests
3116 CPU STATS CONSTANTS
3118 The following constants provide the names of well known cpu stats
3119 fields
3120 Sys::Virt::Domain::CPU_STATS_CPUTIME
3122 The total CPU time, including both hypervisor and vCPU time.
3123 Sys::Virt::Domain::CPU_STATS_USERTIME
3125 THe total time in kernel
3126 Sys::Virt::Domain::CPU_STATS_SYSTEMTIME
3128 The total time in userspace
3129 Sys::Virt::Domain::CPU_STATS_VCPUTIME
3131 The total vCPU time.
3132 CPU STATS CONSTANTS
3134 The following constants provide the names of well known schedular
3135 parameters
3136 Sys::Virt::SCHEDULER_EMULATOR_PERIOD
3138 The duration of the time period for scheduling the emulator
3139 Sys::Virt::SCHEDULER_EMULATOR_QUOTA
3141 The quota for the emulator in one schedular time period
3142 Sys::Virt::SCHEDULER_IOTHREAD_PERIOD
3144 The duration of the time period for scheduling the iothread
3145 Sys::Virt::SCHEDULER_IOTHREAD_QUOTA
3147 The quota for the iothread in one schedular time period
3148 DOMAIN STATS FLAG CONSTANTS
3150 The following constants are used as flags when requesting bulk domain
3151 stats from "Sys::Virt::get_all_domain_stats".
3152 Sys::Virt::Domain::GET_ALL_STATS_ACTIVE
3154 Include stats for active domains
3155 Sys::Virt::Domain::GET_ALL_STATS_INACTIVE
3157 Include stats for inactive domains
3158 Sys::Virt::Domain::GET_ALL_STATS_OTHER
3160 Include stats for other domains
3161 Sys::Virt::Domain::GET_ALL_STATS_PAUSED
3163 Include stats for paused domains
3164 Sys::Virt::Domain::GET_ALL_STATS_PERSISTENT
3166 Include stats for persistent domains
3167 Sys::Virt::Domain::GET_ALL_STATS_RUNNING
3169 Include stats for running domains
3170 Sys::Virt::Domain::GET_ALL_STATS_SHUTOFF
3172 Include stats for shutoff domains
3173 Sys::Virt::Domain::GET_ALL_STATS_TRANSIENT
3175 Include stats for transient domains
3176 Sys::Virt::Domain::GET_ALL_STATS_ENFORCE_STATS
3178 Require that all requested stats fields are returned
3179 Sys::Virt::Domain::GET_ALL_STATS_BACKING
3181 Get stats for image backing files too
3182 Sys::Virt::Domain::GET_ALL_STATS_NOWAIT
3184 Skip stats if they can't be acquired without waiting
3185 DOMAIN STATS FIELD CONSTANTS
3187 The following constants are used to control which fields are returned
3188 for stats queries.
3189 Sys::Virt::Domain::STATS_BALLOON
3191 Balloon statistics
3192 Sys::Virt::Domain::STATS_BLOCK
3194 Block device info
3195 Sys::Virt::Domain::STATS_CPU_TOTAL
3197 CPU usage info
3198 Sys::Virt::Domain::STATS_INTERFACE
3200 Network interface info
3201 Sys::Virt::Domain::STATS_STATE
3203 General lifecycle state
3204 Sys::Virt::Domain::STATS_VCPU
3206 Virtual CPU info
3207 Sys::Virt::Domain::STATS_PERF
3209 Performance event counter values
3210 Sys::Virt::Domain::STATS_IOTHREAD
3212 IOThread performance statistics values
3213 Sys::Virt::Domain::STATS_MEMORY
3215 Memory bandwidth statistics values
3216 Sys::Virt::Domain::STATS_DIRTYRATE
3218 Memory dirty rate statistics
3219 Sys::Virt::Domain::STATS_VM
3221 Hypervisor-specific stats fields for given VM
3222 PROCESS SIGNALS
3224 The following constants provide the names of signals which can be sent
3225 to guest processes. They mostly correspond to POSIX signal names.
3226 Sys::Virt::Domain::PROCESS_SIGNAL_NOP
3228 SIGNOP
3229 Sys::Virt::Domain::PROCESS_SIGNAL_HUP
3231 SIGHUP
3232 Sys::Virt::Domain::PROCESS_SIGNAL_INT
3234 SIGINT
3235 Sys::Virt::Domain::PROCESS_SIGNAL_QUIT
3237 SIGQUIT
3238 Sys::Virt::Domain::PROCESS_SIGNAL_ILL
3240 SIGILL
3241 Sys::Virt::Domain::PROCESS_SIGNAL_TRAP
3243 SIGTRAP
3244 Sys::Virt::Domain::PROCESS_SIGNAL_ABRT
3246 SIGABRT
3247 Sys::Virt::Domain::PROCESS_SIGNAL_BUS
3249 SIGBUS
3250 Sys::Virt::Domain::PROCESS_SIGNAL_FPE
3252 SIGFPE
3253 Sys::Virt::Domain::PROCESS_SIGNAL_KILL
3255 SIGKILL
3256 Sys::Virt::Domain::PROCESS_SIGNAL_USR1
3258 SIGUSR1
3259 Sys::Virt::Domain::PROCESS_SIGNAL_SEGV
3261 SIGSEGV
3262 Sys::Virt::Domain::PROCESS_SIGNAL_USR2
3264 SIGUSR2
3265 Sys::Virt::Domain::PROCESS_SIGNAL_PIPE
3267 SIGPIPE
3268 Sys::Virt::Domain::PROCESS_SIGNAL_ALRM
3270 SIGALRM
3271 Sys::Virt::Domain::PROCESS_SIGNAL_TERM
3273 SIGTERM
3274 Sys::Virt::Domain::PROCESS_SIGNAL_STKFLT
3276 SIGSTKFLT
3277 Sys::Virt::Domain::PROCESS_SIGNAL_CHLD
3279 SIGCHLD
3280 Sys::Virt::Domain::PROCESS_SIGNAL_CONT
3282 SIGCONT
3283 Sys::Virt::Domain::PROCESS_SIGNAL_STOP
3285 SIGSTOP
3286 Sys::Virt::Domain::PROCESS_SIGNAL_TSTP
3288 SIGTSTP
3289 Sys::Virt::Domain::PROCESS_SIGNAL_TTIN
3291 SIGTTIN
3292 Sys::Virt::Domain::PROCESS_SIGNAL_TTOU
3294 SIGTTOU
3295 Sys::Virt::Domain::PROCESS_SIGNAL_URG
3297 SIGURG
3298 Sys::Virt::Domain::PROCESS_SIGNAL_XCPU
3300 SIGXCPU
3301 Sys::Virt::Domain::PROCESS_SIGNAL_XFSZ
3303 SIGXFSZ
3304 Sys::Virt::Domain::PROCESS_SIGNAL_VTALRM
3306 SIGVTALRM
3307 Sys::Virt::Domain::PROCESS_SIGNAL_PROF
3309 SIGPROF
3310 Sys::Virt::Domain::PROCESS_SIGNAL_WINCH
3312 SIGWINCH
3313 Sys::Virt::Domain::PROCESS_SIGNAL_POLL
3315 SIGPOLL
3316 Sys::Virt::Domain::PROCESS_SIGNAL_PWR
3318 SIGPWR
3319 Sys::Virt::Domain::PROCESS_SIGNAL_SYS
3321 SIGSYS
3322 Sys::Virt::Domain::PROCESS_SIGNAL_RT0
3324 SIGRT0
3325 Sys::Virt::Domain::PROCESS_SIGNAL_RT1
3327 SIGRT1
3328 Sys::Virt::Domain::PROCESS_SIGNAL_RT2
3330 SIGRT2
3331 Sys::Virt::Domain::PROCESS_SIGNAL_RT3
3333 SIGRT3
3334 Sys::Virt::Domain::PROCESS_SIGNAL_RT4
3336 SIGRT4
3337 Sys::Virt::Domain::PROCESS_SIGNAL_RT5
3339 SIGRT5
3340 Sys::Virt::Domain::PROCESS_SIGNAL_RT6
3342 SIGRT6
3343 Sys::Virt::Domain::PROCESS_SIGNAL_RT7
3345 SIGRT7
3346 Sys::Virt::Domain::PROCESS_SIGNAL_RT8
3348 SIGRT8
3349 Sys::Virt::Domain::PROCESS_SIGNAL_RT9
3351 SIGRT9
3352 Sys::Virt::Domain::PROCESS_SIGNAL_RT10
3354 SIGRT10
3355 Sys::Virt::Domain::PROCESS_SIGNAL_RT11
3357 SIGRT11
3358 Sys::Virt::Domain::PROCESS_SIGNAL_RT12
3360 SIGRT12
3361 Sys::Virt::Domain::PROCESS_SIGNAL_RT13
3363 SIGRT13
3364 Sys::Virt::Domain::PROCESS_SIGNAL_RT14
3366 SIGRT14
3367 Sys::Virt::Domain::PROCESS_SIGNAL_RT15
3369 SIGRT15
3370 Sys::Virt::Domain::PROCESS_SIGNAL_RT16
3372 SIGRT16
3373 Sys::Virt::Domain::PROCESS_SIGNAL_RT17
3375 SIGRT17
3376 Sys::Virt::Domain::PROCESS_SIGNAL_RT18
3378 SIGRT18
3379 Sys::Virt::Domain::PROCESS_SIGNAL_RT19
3381 SIGRT19
3382 Sys::Virt::Domain::PROCESS_SIGNAL_RT20
3384 SIGRT20
3385 Sys::Virt::Domain::PROCESS_SIGNAL_RT21
3387 SIGRT21
3388 Sys::Virt::Domain::PROCESS_SIGNAL_RT22
3390 SIGRT22
3391 Sys::Virt::Domain::PROCESS_SIGNAL_RT23
3393 SIGRT23
3394 Sys::Virt::Domain::PROCESS_SIGNAL_RT24
3396 SIGRT24
3397 Sys::Virt::Domain::PROCESS_SIGNAL_RT25
3399 SIGRT25
3400 Sys::Virt::Domain::PROCESS_SIGNAL_RT26
3402 SIGRT26
3403 Sys::Virt::Domain::PROCESS_SIGNAL_RT27
3405 SIGRT27
3406 Sys::Virt::Domain::PROCESS_SIGNAL_RT28
3408 SIGRT28
3409 Sys::Virt::Domain::PROCESS_SIGNAL_RT29
3411 SIGRT29
3412 Sys::Virt::Domain::PROCESS_SIGNAL_RT30
3414 SIGRT30
3415 Sys::Virt::Domain::PROCESS_SIGNAL_RT31
3417 SIGRT31
3418 Sys::Virt::Domain::PROCESS_SIGNAL_RT32
3420 SIGRT32
3421 DOMAIN TUNABLE CONSTANTS
3423 The following constants are useful when accessing domain tuning
3424 parameters in APIs and events
3425 Sys::Virt::Domain::TUNABLE_CPU_CPU_SHARES
3427 Proportional CPU weight
3428 Sys::Virt::Domain::TUNABLE_CPU_EMULATORPIN
3430 Emulator thread CPU pinning mask
3431 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_PERIOD
3433 Emulator thread CPU period
3434 Sys::Virt::Domain::TUNABLE_CPU_EMULATOR_QUOTA
3436 Emulator thread CPU quota
3437 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_PERIOD
3439 Iothread thread CPU period
3440 Sys::Virt::Domain::TUNABLE_CPU_IOTHREAD_QUOTA
3442 Iothread thread CPU quota
3443 Sys::Virt::Domain::TUNABLE_CPU_VCPUPIN
3445 VCPU thread pinning mask
3446 Sys::Virt::Domain::TUNABLE_CPU_VCPU_PERIOD
3448 VCPU thread period
3449 Sys::Virt::Domain::TUNABLE_CPU_VCPU_QUOTA
3451 VCPU thread quota
3452 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_PERIOD
3454 VM global period
3455 Sys::Virt::Domain::TUNABLE_CPU_GLOBAL_QUOTA
3457 VM global quota
3458 Sys::Virt::Domain::TUNABLE_BLKDEV_DISK
3460 The name of guest disks
3461 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC
3463 Read throughput in bytes per sec
3464 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC
3466 Read throughput in I/O operations per sec
3467 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC
3469 Total throughput in bytes per sec
3470 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC
3472 Total throughput in I/O operations per sec
3473 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC
3475 Write throughput in bytes per sec
3476 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC
3478 Write throughput in I/O operations per sec
3479 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX
3481 Maximum read throughput in bytes per sec
3482 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX
3484 Maximum read throughput in I/O operations per sec
3485 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX
3487 Maximum total throughput in bytes per sec
3488 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX
3490 Maximum total throughput in I/O operations per sec
3491 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX
3493 Maximum write throughput in bytes per sec
3494 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX
3496 Maximum write throughput in I/O operations per sec
3497 Sys::Virt::Domain::TUNABLE_BLKDEV_SIZE_IOPS_SEC
3499 The maximum I/O operations per second
3500 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX_LENGTH
3502 The duration in seconds allowed for maximum total bytes processed
3503 per second.
3504 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_BYTES_SEC_MAX_LENGTH
3506 The duration in seconds allowed for maximum bytes read per second.
3507 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX_LENGTH
3509 The duration in seconds allowed for maximum bytes written per
3510 second.
3511 Sys::Virt::Domain::TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX_LENGTH
3513 The duration in seconds allowed for maximum total I/O operations
3514 processed per second.
3515 Sys::Virt::Domain::TUNABLE_BLKDEV_READ_IOPS_SEC_MAX_LENGTH
3517 The duration in seconds allowed for maximum I/O operations read per
3518 second.
3519 Sys::Virt::Domain::TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX_LENGTH
3521 The duration in seconds allowed for maximum I/O operations written
3522 per second.
3523 Sys::Virt::Domain::TUNABLE_BLKDEV_GROUP_NAME
3525 The name of the blkdev group
3526 Sys::Virt::Domain::TUNABLE_IOTHREADSPIN
3528 The I/O threads pinning
3529 DOMAIN LIFECYCLE CONSTANTS
3531 The following constants are useful when setting action for lifecycle
3532 events.
3533 Sys::Virt::Domain::LIFECYCLE_POWEROFF
3535 The poweroff lifecycle event type
3536 Sys::Virt::Domain::LIFECYCLE_REBOOT
3538 The reboot lifecycle event type
3539 Sys::Virt::Domain::LIFECYCLE_CRASH
3541 The crash lifecycle event type
3542 DOMAIN LIFECYCLE ACTION CONSTANTS
3544 Sys::Virt::Domain::LIFECYCLE_ACTION_DESTROY
3545 The destroy lifecycle action
3546 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART
3548 The restart lifecycle action
3549 Sys::Virt::Domain::LIFECYCLE_ACTION_RESTART_RENAME
3551 The restart-rename lifecycle action
3552 Sys::Virt::Domain::LIFECYCLE_ACTION_PRESERVE
3554 The preserve lifecycle action
3555 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_DESTROY
3557 The coredump-destroy lifecycle action
3558 Sys::Virt::Domain::LIFECYCLE_ACTION_COREDUMP_RESTART
3560 The coredump-restart lifecycle action
3561 MEMORY FAILURE ACTION CONSTANTS
3563 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_IGNORE
3564 The failure could be ignored
3565 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_INJECT
3567 An MCE was injected to the guest
3568 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_FATAL
3570 The failure is non-recoverable and the hypervisor was not able to
3571 handle it
3572 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_ACTION_RESET
3574 The failure is non-recoverable and the guest was not able to handle
3575 it.
3576 MEMORY FAILURE RECIPIENT CONSTANTS
3578 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_RECIPIENT_HYPERVISOR
3579 The memory failure was in hypervisor address space
3580 Sys::Virt::Domain::EVENT_MEMORY_FAILURE_RECIPIENT_GUEST
3582 The memory failure was in guest address space
3583 MEMORY FAILURE FLAG CONSTANTS
3585 Sys::Virt::Domain::MEMORY_FAILURE_ACTION_REQUIRED
3586 Whether the flag is action-required or action-optional
3587 Sys::Virt::Domain::MEMORY_FAILURE_RECURSIVE
3589 The failure occurred while the previous fault was being handled.
3590 MEMORY DIRTY RATE STATUS CONSTANTS
3592 Sys::Virt::Domain::DIRTYRATE_UNSTARTED
3593 The dirty rate is not being measured currently.
3594 Sys::Virt::Domain::DIRTYRATE_MEASURING
3596 The dity rate is in the process of being measured
3597 Sys::Virt::Domain::DIRTYRATE_MEASURED
3599 The dirty rate has been measured
3600
3602 Daniel P. Berrange <berrange@redhat.com>
3603
3605 Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
3606
3608 This program is free software; you can redistribute it and/or modify it
3609 under the terms of either the GNU General Public License as published
3610 by the Free Software Foundation (either version 2 of the License, or at
3611 your option any later version), or, the Artistic License, as specified
3612 in the Perl README file.
3613
3615 Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
3616perl v5.38.0 2023-09-08 Sys::Virt::Domain(3pm)