1Sys::Virt::Domain(3) User Contributed Perl Documentation Sys::Virt::Domain(3)
2
6 Sys::Virt::Domain - Represent & manage a libvirt guest domain
7
9 The "Sys::Virt::Domain" module represents a guest domain managed by the
10 virtual machine monitor.
11
13 my $id = $dom->get_id()
14 Returns an integer with a locally unique identifier for the domain.
15 my $uuid = $dom->get_uuid()
17 Returns a 16 byte long string containing the raw globally unique
18 identifier (UUID) for the domain.
19 my $uuid = $dom->get_uuid_string()
21 Returns a printable string representation of the raw UUID, in the
22 format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'.
23 my $name = $dom->get_name()
25 Returns a string with a locally unique name of the domain
26 my $hostname = $dom->get_hostname()
28 Returns a string representing the hostname of the guest
29 my $str = $dom->get_metadata($type, $uri, $flags =0)
31 Returns the metadata element of type $type associated with the
32 domain. If $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the
33 $uri parameter specifies the XML namespace to retrieve, otherwise
34 $uri should be "undef". The optional $flags parameter defaults to
35 zero.
36 $dom->set_metadata($type, $val, $key, $uri, $flags=0)
38 Sets the metadata element of type $type to hold the value $val. If
39 $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the $key and
40 $uri elements specify an XML namespace to use, otherwise they
41 should both be "nudef". The optional $flags parameter defaults to
42 zero.
43 $dom->is_active()
45 Returns a true value if the domain is currently running
46 $dom->is_persistent()
48 Returns a true value if the domain has a persistent configuration
49 file defined
50 $dom->is_updated()
52 Returns a true value if the domain is running and has a persistent
53 configuration file defined that is out of date compared to the
54 current live config.
55 my $xml = $dom->get_xml_description($flags=0)
57 Returns an XML document containing a complete description of the
58 domain's configuration. The optional $flags parameter controls
59 generation of the XML document, defaulting to 0 if omitted. It can
60 be one or more of the XML DUMP constants listed later in this
61 document.
62 my $type = $dom->get_os_type()
64 Returns a string containing the name of the OS type running within
65 the domain.
66 $dom->create($flags)
68 Start a domain whose configuration was previously defined using the
69 "define_domain" method in Sys::Virt. The $flags parameter accepts
70 one of the DOMAIN CREATION constants documented later, and defaults
71 to 0 if omitted.
72 $dom->undefine()
74 Remove the configuration associated with a domain previously
75 defined with the "define_domain" method in Sys::Virt. If the domain
76 is running, you probably want to use the "shutdown" or "destroy"
77 methods instead.
78 $dom->suspend()
80 Temporarily stop execution of the domain, allowing later
81 continuation by calling the "resume" method.
82 $dom->resume()
84 Resume execution of a domain previously halted with the "suspend"
85 method.
86 $dom->pm_wakeup()
88 Wakeup the guest from power management suspend state
89 $dom->pm_suspend_for_duration($target, $duration, $flags=0)
91 Tells the guest OS to enter the power management suspend state
92 identified by $target. The $target parameter should be one of the
93 NODE SUSPEND CONTANTS listed in "Sys::Virt". The $duration
94 specifies when the guest should automatically wakeup. The $flags
95 parameter is optional and defaults to zero.
96 $dom->save($filename)
98 Take a snapshot of the domain's state and save the information to
99 the file named in the $filename parameter. The domain can later be
100 restored from this file with the "restore_domain" method on the
101 Sys::Virt object.
102 $dom->managed_save($flags=0)
104 Take a snapshot of the domain's state and save the information to a
105 managed save location. The domain will be automatically restored
106 with this state when it is next started. The $flags parameter is
107 unused and defaults to zero.
108 $bool = $dom->has_managed_save_image($flags=0)
110 Return a non-zero value if the domain has a managed save image that
111 will be used at next start. The $flags parameter is unused and
112 defaults to zero.
113 $dom->managed_save_remove($flags=0)
115 Remove the current managed save image, causing the guest to perform
116 a full boot next time it is started. The $flags parameter is unused
117 and defaults to zero.
118 $dom->core_dump($filename[, $flags])
120 Trigger a core dump of the guest virtual machine, saving its memory
121 image to $filename so it can be analysed by tools such as "crash".
122 The optional $flags flags parameter is currently unused and if
123 omitted will default to 0.
124 $dom->destroy()
126 Immediately poweroff the machine. This is equivalent to removing
127 the power plug. The guest OS is given no time to cleanup / save
128 state. For a clean poweroff sequence, use the "shutdown" method
129 instead.
130 my $info = $dom->get_info()
132 Returns a hash reference summarising the execution state of the
133 domain. The elements of the hash are as follows:
134 maxMem
136 The maximum memory allowed for this domain, in kilobytes
137 memory
139 The current memory allocated to the domain in kilobytes
140 cpuTime
142 The amount of CPU time used by the domain
143 nrVirtCpu
145 The current number of virtual CPUs enabled in the domain
146 state
148 The execution state of the machine, which will be one of the
149 constants &Sys::Virt::Domain::STATE_*.
150 my ($state, $reason) = $dom->get_state()
152 Returns an array whose values specify the current state of the
153 guest, and the reason for it being in that state. The $state
154 values are the same as for the "get_info" API, and the $reason
155 values come from:
156 Sys::Virt::Domain::STATE_CRASHED_UNKNOWN
158 It is not known why the domain has crashed
159 Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN
161 It is not known why the domain has no state
162 Sys::Virt::Domain::STATE_PAUSED_DUMP
164 The guest is paused due to a core dump operation
165 Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT
167 The guest is paused due to a snapshot
168 Sys::Virt::Domain::STATE_PAUSED_IOERROR
170 The guest is paused due to an I/O error
171 Sys::Virt::Domain::STATE_PAUSED_MIGRATION
173 The guest is paused due to migration
174 Sys::Virt::Domain::STATE_PAUSED_SAVE
176 The guest is paused due to a save operation
177 Sys::Virt::Domain::STATE_PAUSED_UNKNOWN
179 It is not known why the domain has paused
180 Sys::Virt::Domain::STATE_PAUSED_USER
182 The guest is paused at admin request
183 Sys::Virt::Domain::STATE_PAUSED_WATCHDOG
185 The guest is paused due to the watchdog
186 Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN
188 The guest is paused while domain shutdown takes place
189 Sys::Virt::Domain::STATE_RUNNING_BOOTED
191 The guest is running after being booted
192 Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT
194 The guest is running after restore from snapshot
195 Sys::Virt::Domain::STATE_RUNNING_MIGRATED
197 The guest is running after migration
198 Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED
200 The guest is running after migration abort
201 Sys::Virt::Domain::STATE_RUNNING_RESTORED
203 The guest is running after restore from file
204 Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED
206 The guest is running after save cancel
207 Sys::Virt::Domain::STATE_RUNNING_UNKNOWN
209 It is not known why the domain has started
210 Sys::Virt::Domain::STATE_RUNNING_UNPAUSED
212 The guest is running after a resume
213 Sys::Virt::Domain::STATE_RUNNING_WAKEUP
215 The guest is running after wakeup from power management suspend
216 Sys::Virt::Domain::STATE_BLOCKED_UNKNOWN
218 The guest is blocked for an unknown reason
219 Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN
221 It is not known why the domain has shutdown
222 Sys::Virt::Domain::STATE_SHUTDOWN_USER
224 The guest is shutdown due to admin request
225 Sys::Virt::Domain::STATE_SHUTOFF_CRASHED
227 The guest is shutoff after a crash
228 Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED
230 The guest is shutoff after being destroyed
231 Sys::Virt::Domain::STATE_SHUTOFF_FAILED
233 The guest is shutoff due to a virtualization failure
234 Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT
236 The guest is shutoff after a snapshot
237 Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED
239 The guest is shutoff after migration
240 Sys::Virt::Domain::STATE_SHUTOFF_SAVED
242 The guest is shutoff after a save
243 Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN
245 The guest is shutoff due to controlled shutdown
246 Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN
248 It is not known why the domain has shutoff
249 Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN
251 It is not known why the domain was suspended
252 my $info = $dom->get_control_info($flags=0)
254 Returns a hash reference providing information about the control
255 channel. The returned keys in the hash are
256 "state"
258 One of the CONTROL INFO constants listed later
259 "details"
261 Currently unsed, always 0.
262 "stateTime"
264 The elapsed time since the control channel entered the current
265 state.
266 my @errs = $dom->get_disk_errors($flags=0)
268 Returns a list of all disk errors that have occurred on the backing
269 store for the guest's virtual disks. The returned array elements
270 are hash references, containing two keys
271 "path"
273 The path of the disk with an error
274 "error"
276 The error type
277 $dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0)
279 Sends a sequence of keycodes to the guest domain. The $keycodeset
280 should be one of the constants listed later in the KEYCODE SET
281 section. $holdtiem is the duration, in milliseconds, to keep the
282 key pressed before releasing it and sending the next keycode.
283 @keycodes is an array reference containing the list of keycodes to
284 send to the guest. The elements in the array should be keycode
285 values from the specified keycode set. $flags is currently unused.
286 my $info = $dom->get_block_info($dev, $flags=0)
288 Returns a hash reference summarising the disk usage of the host
289 backing store for a guest block device. The $dev parameter should
290 be the path to the backing store on the host. $flags is currently
291 unused and defaults to 0 if omitted. The returned hash contains the
292 following elements
293 capacity
295 Logical size in bytes of the block device backing image *
296 allocation
298 Highest allocated extent in bytes of the block device backing
299 image
300 physical
302 Physical size in bytes of the container of the backing image
303 $dom->set_max_memory($mem)
305 Set the maximum memory for the domain to the value $mem. The value
306 of the $mem parameter is specified in kilobytes.
307 $mem = $dom->get_max_memory()
309 Returns the current maximum memory allowed for this domain in
310 kilobytes.
311 $dom->set_memory($mem, $flags)
313 Set the current memory for the domain to the value $mem. The value
314 of the $mem parameter is specified in kilobytes. This must be less
315 than, or equal to the domain's max memory limit. The $flags
316 parameter can control whether the update affects the live guest, or
317 inactive config, defaulting to modifying the current state.
318 $dom->shutdown()
320 Request that the guest OS perform a graceful shutdown and poweroff.
321 This usually requires some form of cooperation from the guest
322 operating system, such as responding to an ACPI signal, or a guest
323 agent process. For an immediate, forceful poweroff, use the
324 "destroy" method instead.
325 $dom->reboot([$flags])
327 Request that the guest OS perform a graceful shutdown and
328 optionally restart. The optional $flags parameter is currently
329 unused and if omitted defaults to zero.
330 $dom->reset([$flags])
332 Perform a hardware reset of the virtual machine. The guest OS is
333 given no opportunity to shutdown gracefully. The optional $flags
334 parameter is currently unused and if omitted defaults to zero.
335 $dom->get_max_vcpus()
337 Return the maximum number of vcpus that are configured for the
338 domain
339 $dom->attach_device($xml[, $flags])
341 Hotplug a new device whose configuration is given by $xml, to the
342 running guest. The optional <$flags> parameter defaults to 0, but
343 can accept one of the device hotplug flags described later.
344 $dom->detach_device($xml[, $flags])
346 Hotunplug a existing device whose configuration is given by $xml,
347 from the running guest. The optional <$flags> parameter defaults to
348 0, but can accept one of the device hotplug flags described later.
349 $dom->update_device($xml[, $flags])
351 Update the configuration of an existing device. The new
352 configuration is given by $xml. The optional <$flags> parameter
353 defaults to 0 but can accept one of the device hotplug flags
354 described later.
355 $data = $dom->block_peek($path, $offset, $size[, $flags)
357 Peek into the guest disk $path, at byte $offset capturing $size
358 bytes of data. The returned scalar may contain embedded NULLs. The
359 optional $flags parameter is currently unused and if omitted
360 defaults to zero.
361 $data = $dom->memory_peek($offset, $size[, $flags])
363 Peek into the guest memory at byte $offset virtual address,
364 capturing $size bytes of memory. The return scalar may contain
365 embedded NULLs. The optional $flags parameter is currently unused
366 and if omitted defaults to zero.
367 $flag = $dom->get_autostart();
369 Return a true value if the guest domain is configured to
370 automatically start upon boot. Return false, otherwise
371 $dom->set_autostart($flag)
373 Set the state of the autostart flag, which determines whether the
374 guest will automatically start upon boot of the host OS
375 $dom->set_vcpus($count, [$flags])
377 Set the number of virtual CPUs in the guest VM to $count. The
378 optional $flags parameter can be used to control whether the
379 setting changes the live config or inactive config.
380 $count = $dom->get_vcpus([$flags])
382 Get the number of virtual CPUs in the guest VM. The optional
383 $flags parameter can be used to control whether to query the
384 setting of the live config or inactive config.
385 $type = $dom->get_scheduler_type()
387 Return the scheduler type for the guest domain
388 $stats = $dom->block_stats($path)
390 Fetch the current I/O statistics for the block device given by
391 $path. The returned hash reference contains keys for
392 "rd_req"
394 Number of read requests
395 "rd_bytes"
397 Number of bytes read
398 "wr_req"
400 Number of write requests
401 "wr_bytes"
403 Number of bytes written
404 "errs"
406 Some kind of error count
407 my $params = $dom->get_scheduler_parameters($flags=0)
409 Return the set of scheduler tunable parameters for the guest, as a
410 hash reference. The precise set of keys in the hash are specific to
411 the hypervisor.
412 $dom->set_scheduler_parameters($params, $flags=0)
414 Update the set of scheduler tunable parameters. The value names for
415 tunables vary, and can be discovered using the
416 "get_scheduler_params" call
417 my $params = $dom->get_memory_parameters($flags=0)
419 Return a hash reference containing the set of memory tunable
420 parameters for the guest. The keys in the hash are one of the
421 constants MEMORY PARAMETERS described later. The $flags parameter
422 accepts one or more the CONFIG OPTION constants documented later,
423 and defaults to 0 if omitted.
424 $dom->set_memory_parameters($params, $flags=0)
426 Update the memory tunable parameters for the guest. The $params
427 should be a hash reference whose keys are one of the MEMORY
428 PARAMETERS constants. The $flags parameter accepts one or more the
429 CONFIG OPTION constants documented later, and defaults to 0 if
430 omitted.
431 my $params = $dom->get_blkio_parameters($flags=0)
433 Return a hash reference containing the set of blkio tunable
434 parameters for the guest. The keys in the hash are one of the
435 constants BLKIO PARAMETERS described later. The $flags parameter
436 accepts one or more the CONFIG OPTION constants documented later,
437 and defaults to 0 if omitted.
438 $dom->set_blkio_parameters($params, $flags=0)
440 Update the blkio tunable parameters for the guest. The $params
441 should be a hash reference whose keys are one of the BLKIO
442 PARAMETERS constants. The $flags parameter accepts one or more the
443 CONFIG OPTION constants documented later, and defaults to 0 if
444 omitted.
445 $stats = $dom->get_block_iotune($disk, $flags=0)
447 Return a hash reference containing the set of blkio tunable
448 parameters for the guest disk $disk. The keys in the hash are one
449 of the constants BLOCK IOTUNE PARAMETERS described later.
450 $dom->set_block_iotune($disk, $params, $flags=0);
452 Update the blkio tunable parameters for the guest disk $disk. The
453 $params should be a hash reference whose keys are one of the BLOCK
454 IOTUNE PARAMETERS constants.
455 my $params = $dom->get_interface_parameters($intf, $flags=0)
457 Return a hash reference containing the set of interface tunable
458 parameters for the guest. The keys in the hash are one of the
459 constants INTERFACE PARAMETERS described later.
460 $dom->set_interface_parameters($intf, $params, $flags=0)
462 Update the interface tunable parameters for the guest. The $params
463 should be a hash reference whose keys are one of the INTERFACE
464 PARAMETERS constants.
465 my $params = $dom->get_numa_parameters($flags=0)
467 Return a hash reference containing the set of numa tunable
468 parameters for the guest. The keys in the hash are one of the
469 constants NUMA PARAMETERS described later. The $flags parameter
470 accepts one or more the CONFIG OPTION constants documented later,
471 and defaults to 0 if omitted.
472 $dom->set_numa_parameters($params, $flags=0)
474 Update the numa tunable parameters for the guest. The $params
475 should be a hash reference whose keys are one of the NUMA
476 PARAMETERS constants. The $flags parameter accepts one or more the
477 CONFIG OPTION constants documented later, and defaults to 0 if
478 omitted.
479 $dom->block_resize($disk, $newsize, $flags=0)
481 Resize the disk $disk to have new size $newsize KB. If the disk is
482 backed by a special image format, the actual resize is done by the
483 hypervisor. If the disk is backed by a raw file, or block device,
484 the resize must be done prior to invoking this API call, and it
485 merely updates the hypervisor's view of the disk size. The
486 following flags may be used
487 Sys::Virt::Domain::BLOCK_RESIZE_BYTES
489 Treat $newsize as if it were in bytes, rather than KB.
490 $dom->interface_stats($path)
492 Fetch the current I/O statistics for the block device given by
493 $path. The returned hash containins keys for
494 "rx_bytes"
496 Total bytes received
497 "rx_packets"
499 Total packets received
500 "rx_errs"
502 Total packets received with errors
503 "rx_drop"
505 Total packets drop at reception
506 "tx_bytes"
508 Total bytes transmitted
509 "tx_packets"
511 Total packets transmitted
512 "tx_errs"
514 Total packets transmitted with errors
515 "tx_drop"
517 Total packets dropped at transmission.
518 $dom->memory_stats($flags=0)
520 Fetch the current memory statistics for the guest domain. The
521 $flags parameter is currently unused and can be omitted. The
522 returned hash containins keys for
523 "swap_in"
525 Data read from swap space
526 "swap_out"
528 Data written to swap space
529 "major_fault"
531 Page fault involving disk I/O
532 "minor_fault"
534 Page fault not involving disk I/O
535 "unused"
537 Memory not used by the system
538 "available"
540 Total memory seen by guest
541 $info = $dom->get_security_label()
543 Fetch information about the security label assigned to the guest
544 domain. The returned hash reference has two keys, "model" gives the
545 name of the security model in effect (eg "selinux"), while "label"
546 provides the name of the security label applied to the domain. This
547 method only returns information about the first security label. To
548 retrieve all labels, use "get_security_label_list".
549 @info = $dom->get_security_label_list()
551 Fetches information about all security labels assigned to the guest
552 domain. The elements in the returned array are all hash references,
553 whose keys are as described for "get_security_label".
554 $ddom = $dom->migrate(destcon, flags, dname, uri, bandwidth)
556 Migrate a domain to an alternative host. The "destcon" parameter
557 should be a "Sys::Virt" connection to the remote target host. If
558 the "flags" parameter is zero offline migration will be performed.
559 The "Sys::Virt::Domain::MIGRATE_LIVE" constant can be used to
560 request live migration. The "dname" parameter allows the guest to
561 be renamed on the target host, if set to "undef", the domains'
562 current name will be maintained. In normal circumstances, the
563 source host determines the target hostname from the URI associated
564 with the "destcon" connection. If the destination host is multi-
565 homed it may be necessary to supply an alternate destination
566 hostame via the "uri" parameter. The "bandwidth" parameter allows
567 network usage to be throttled during migration. If set to zero, no
568 throttling will be performed. The "flags", "dname", "uri" and
569 "bandwidth" parameters are all optional, and if omitted default to
570 zero, "undef", "undef", and zero respectively.
571 $ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)
573 Migrate a domain to an alternative host. This function works in the
574 same way as "migrate", except is also allows "dxml" to specify a
575 changed XML configuration for the guest on the target host.
576 $dom->migrate_to_uri(desturi, flags, dname, bandwidth)
578 Migrate a domain to an alternative host. The "destri" parameter
579 should be a valid libvirt connection URI for the remote target
580 host. If the "flags" parameter is zero offline migration will be
581 performed. The "Sys::Virt::Domain::MIGRATE_LIVE" constant can be
582 used to request live migration. The "dname" parameter allows the
583 guest to be renamed on the target host, if set to "undef", the
584 domains' current name will be maintained. In normal circumstances,
585 the source host determines the target hostname from the URI
586 associated with the "destcon" connection. If the destination host
587 is multi-homed it may be necessary to supply an alternate
588 destination hostame via the "uri" parameter. The "bandwidth"
589 parameter allows network usage to be throttled during migration. If
590 set to zero, no throttling will be performed. The "flags", "dname"
591 and "bandwidth" parameters are all optional, and if omitted default
592 to zero, "undef", "undef", and zero respectively.
593 $dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)
595 Migrate a domain to an alternative host. This function works in
596 almost the same way as "migrate_to_uri", except is also allows
597 "dxml" to specify a changed XML configuration for the guest on the
598 target host. The "dconnuri" must always specify the URI of the
599 remote libvirtd daemon, or be "undef". The "miguri" parameter can
600 be used to specify the URI for initiating the migration operation,
601 or be "undef".
602 $dom->migrate_set_max_downtime($downtime, $flags)
604 Set the maximum allowed downtime during migration of the guest. A
605 longer downtime makes it more likely that migration will complete,
606 at the cost of longer time blackout for the guest OS at the switch
607 over point. The "downtime" parameter is measured in milliseconds.
608 The $flags parameter is currently unused and defaults to zero.
609 $dom->migrate_set_max_speed($bandwidth, $flags)
611 Set the maximum allowed bandwidth during migration of the guest.
612 The "bandwidth" parameter is measured in MB/second. The $flags
613 parameter is currently unused and defaults to zero.
614 $bandwidth = $dom->migrate_get_max_speed($flag)
616 Get the maximum allowed bandwidth during migration fo the guest.
617 The returned <bandwidth> value is measured in MB/second. The
618 $flags parameter is currently unused and defaults to zero.
619 $dom->inject_nmi($flags)
621 Trigger an NMI in the guest virtual machine. The $flags parameter
622 is currently unused and defaults to 0.
623 $dom->open_console($st, $devname, $flags)
625 Open the text console for a serial, parallel or paravirt console
626 device identified by $devname, connecting it to the stream $st. If
627 $devname is undefined, the default console will be opened. $st must
628 be a "Sys::Virt::Stream" object used for bi-directional
629 communication with the console. $flags is currently unused,
630 defaulting to 0.
631 $dom->open_graphics($idx, $fd, $flags)
633 Open the graphics console for a guest, identified by $idx, counting
634 from 0. The $fd should be a file descriptor for an anoymous socket
635 pair. The $flags argument should be one of the constants listed at
636 the end of this document, and defaults to 0.
637 my $mimetype = $dom->screenshot($st, $screen, $flags)
639 Capture a screenshot of the virtual machine's monitor. The $screen
640 parameter controls which monitor is captured when using a multi-
641 head or multi-card configuration. $st must be a "Sys::Virt::Stream"
642 object from which the data can be read. $flags is currently unused
643 and defaults to 0. The mimetype of the screenshot is returned
644 @vcpuinfo = $dom->get_vcpu_info($flags=0)
646 Obtain information about the state of all virtual CPUs in a running
647 guest domain. The returned list will have one element for each
648 vCPU, where each elements contains a hash reference. The keys in
649 the hash are, "number" the vCPU number, "cpu" the physical CPU on
650 which the vCPU is currently scheduled, "cpuTime" the cummulative
651 execution time of the vCPU, "state" the running state and
652 "affinity" giving the allowed shedular placement. The value for
653 "affinity" is a string representing a bitmask against physical
654 CPUs, 8 cpus per character. To extract the bits use the "unpack"
655 function with the "b*" template. NB The "state", "cpuTime", "cpu"
656 values are only available if using $flags value of 0, and the
657 domain is currently running; otherwise they will all be set to
658 zero.
659 $dom->pin_vcpu($vcpu, $mask)
661 Pin the virtual CPU given by index $vcpu to physical CPUs given by
662 $mask. The $mask is a string representing a bitmask against
663 physical CPUs, 8 cpus per character.
664 $mask = $dom->get_emulator_pin_info()
666 Obtain information about the CPU affinity of the emulator process.
667 The returned $mask is a bitstring against physical CPUs, 8 cpus per
668 character. To extract the bits use the "unpack" function with the
669 "b*" template.
670 $dom->pin_emulator($newmask, $flags=0)
672 Pin the emulator threads to the physical CPUs identified by the
673 affinity in $newmask. The $newmask is a bitstring against the
674 physical CPUa, 8 cpus per character. To create a suitable
675 bitstring, use the "vec" function with a value of 1 for the "BITS"
676 parameter.
677 my @stats = $dom->get_cpu_stats($startCpu, $numCpus, $flags=0)
679 Requests the guests host physical CPU usage statistics, starting
680 from host CPU <$startCpu> counting upto $numCpus. If $startCpu is
681 -1 and $numCpus is 1, then the utilization across all CPUs is
682 returned. Returns an array of hash references, each element
683 containing stats for one CPU.
684 my $info = $dom->get_job_info()
686 Returns a hash reference summarising the execution state of the
687 background job. The elements of the hash are as follows:
688 type
690 The type of job, one of the JOB TYPE constants listed later in
691 this document.
692 timeElapsed
694 The elapsed time in milliseconds
695 timeRemaining
697 The expected remaining time in milliseconds. Only set if the
698 "type" is JOB_UNBOUNDED.
699 dataTotal
701 The total amount of data expected to be processed by the job,
702 in bytes.
703 dataProcessed
705 The current amount of data processed by the job, in bytes.
706 dataRemaining
708 The expected amount of data remaining to be processed by the
709 job, in bytes.
710 memTotal
712 The total amount of mem expected to be processed by the job, in
713 bytes.
714 memProcessed
716 The current amount of mem processed by the job, in bytes.
717 memRemaining
719 The expected amount of mem remaining to be processed by the
720 job, in bytes.
721 fileTotal
723 The total amount of file expected to be processed by the job,
724 in bytes.
725 fileProcessed
727 The current amount of file processed by the job, in bytes.
728 fileRemaining
730 The expected amount of file remaining to be processed by the
731 job, in bytes.
732 $dom->abort_job()
734 Aborts the currently executing job
735 my $info = $dom->get_block_job_info($path, $flags=0)
737 Returns a hash reference summarising the execution state of the
738 block job. The $path parameter should be the fully qualified path
739 of the block device being changed.
740 $dom->set_block_job_speed($path, $bandwidth, $flags=0)
742 Change the maximum I/O bandwidth used by the block job that is
743 currently executing for $path. The $bandwidth argument is specified
744 in MB/s
745 $dom->abort_block_job($path, $flags=0)
747 Abort the current job that is executing for the block device
748 associated with $path
749 $dom->block_pull($path, $bandwith, $flags=0)
751 Merge the backing files associated with $path into the top level
752 file. The $bandwidth parameter specifies the maximum I/O rate to
753 allow in MB/s.
754 $dom->block_rebase($path, $base, $bandwith, $flags=0)
756 Switch the backing path associated with $path to instead use $base.
757 The $bandwidth parameter specifies the maximum I/O rate to allow in
758 MB/s.
759 $dom->block_commit($path, $base, $top, $bandwith, $flags=0)
761 Commit changes there were made to the temporary top level file
762 $top. Takes all the differences between $top and $base and merge
763 them into $base. The $bandwidth parameter specifies the maximum I/O
764 rate to allow in MB/s.
765 $count = $dom->num_of_snapshots()
767 Return the number of saved snapshots of the domain
768 @names = $dom->list_snapshot_names()
770 List the names of all saved snapshots. The names can be used with
771 the "lookup_snapshot_by_name"
772 @snapshots = $dom->list_snapshots()
774 Return a list of all snapshots currently known to the domain. The
775 elements in the returned list are instances of the
776 Sys::Virt::DomainSnapshot class. This method requires O(n) RPC
777 calls, so the "list_all_snapshots" method is recommended as a more
778 efficient alternative.
779 my @snapshots = $dom->list_all_snapshots($flags)
781 Return a list of all domain snapshots associated with this domain.
782 The elements in the returned list are instances of the
783 Sys::Virt::DomainSnapshot class. The $flags parameter can be used
784 to filter the list of return domain snapshots.
785 my $snapshot = $dom->get_snapshot_by_name($name)
787 Return the domain snapshot with a name of $name. The returned
788 object is an instance of the Sys::Virt::DomainSnapshot class.
789 $dom->has_current_snapshot()
791 Returns a true value if the domain has a currently active snapshot
792 $snapshot = $dom->current_snapshot()
794 Returns the currently active snapshot for the domain.
795 $snapshot = $dom->create_snapshot($xml[, $flags])
797 Create a new snapshot from the $xml. The $flags parameter accepts
798 the SNAPSHOT CREATION constants listed in
799 "Sys::Virt::DomainSnapshots".
800
802 A number of the APIs take a "flags" parameter. In most cases passing a
803 value of zero will be satisfactory. Some APIs, however, accept named
804 constants to alter their behaviour. This section documents the current
805 known constants.
806 DOMAIN STATE
808 The domain state constants are useful in interpreting the "state" key
809 in the hash returned by the "get_info" method.
810 Sys::Virt::Domain::STATE_NOSTATE
812 The domain is active, but is not running / blocked (eg idle)
813 Sys::Virt::Domain::STATE_RUNNING
815 The domain is active and running
816 Sys::Virt::Domain::STATE_BLOCKED
818 The domain is active, but execution is blocked
819 Sys::Virt::Domain::STATE_PAUSED
821 The domain is active, but execution has been paused
822 Sys::Virt::Domain::STATE_SHUTDOWN
824 The domain is active, but in the shutdown phase
825 Sys::Virt::Domain::STATE_SHUTOFF
827 The domain is inactive, and shut down.
828 Sys::Virt::Domain::STATE_CRASHED
830 The domain is inactive, and crashed.
831 Sys::Virt::Domain::STATE_PMSUSPENDED
833 The domain is active, but in power management suspend state
834 CONTROL INFO
836 The following constants can be used to determine what the guest domain
837 control channel status is
838 Sys::Virt::Domain::CONTROL_ERROR
840 The control channel has a fatal error
841 Sys::Virt::Domain::CONTROL_OK
843 The control channel is ready for jobs
844 Sys::Virt::Domain::CONTROL_OCCUPIED
846 The control channel is busy
847 Sys::Virt::Domain::CONTROL_JOB
849 The control channel is busy with a job
850 DOMAIN CREATION
852 The following constants can be used to control the behaviour of domain
853 creation
854 Sys::Virt::Domain::START_PAUSED
856 Keep the guest vCPUs paused after starting the guest
857 Sys::Virt::Domain::START_AUTODESTROY
859 Automatically destroy the guest when the connection is closed (or
860 fails)
861 Sys::Virt::Domain::START_BYPASS_CACHE
863 Do not use OS I/O cache if starting a domain with a saved state
864 image
865 Sys::Virt::Domain::START_FORCE_BOOT
867 Boot the guest, even if there was a saved snapshot
868 KEYCODE SETS
870 The following constants define the set of supported keycode sets
871 Sys::Virt::Domain::KEYCODE_SET_LINUX
873 The Linux event subsystem keycodes
874 Sys::Virt::Domain::KEYCODE_SET_XT
876 The original XT keycodes
877 Sys::Virt::Domain::KEYCODE_SET_ATSET1
879 The AT Set1 keycodes (aka XT)
880 Sys::Virt::Domain::KEYCODE_SET_ATSET2
882 The AT Set2 keycodes (aka AT)
883 Sys::Virt::Domain::KEYCODE_SET_ATSET3
885 The AT Set3 keycodes (aka PS2)
886 Sys::Virt::Domain::KEYCODE_SET_OSX
888 The OS-X keycodes
889 Sys::Virt::Domain::KEYCODE_SET_XT_KBD
891 The XT keycodes from the Linux Keyboard driver
892 Sys::Virt::Domain::KEYCODE_SET_USB
894 The USB HID keycode set
895 Sys::Virt::Domain::KEYCODE_SET_WIN32
897 The Windows keycode set
898 Sys::Virt::Domain::KEYCODE_SET_RFB
900 The XT keycode set, with the extended scancodes using the high bit
901 of the first byte, instead of the low bit of the second byte.
902 MEMORY PEEK
904 The following constants can be used with the "memory_peek" method's
905 flags parameter
906 Sys::Virt::Domain::MEMORY_VIRTUAL
908 Indicates that the offset is using virtual memory addressing.
909 Sys::Virt::Domain::MEMORY_PHYSICAL
911 Indicates that the offset is using physical memory addressing.
912 VCPU STATE
914 The following constants are useful when interpreting the virtual CPU
915 run state
916 Sys::Virt::Domain::VCPU_OFFLINE
918 The virtual CPU is not online
919 Sys::Virt::Domain::VCPU_RUNNING
921 The virtual CPU is executing code
922 Sys::Virt::Domain::VCPU_BLOCKED
924 The virtual CPU is waiting to be scheduled
925 OPEN GRAPHICS CONSTANTS
927 The following constants are used when opening a connection to the guest
928 graphics server
929 Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH
931 Skip authentication of the client
932 OPEN CONSOLE CONSTANTS
934 The following constants are used when opening a connection to the guest
935 console
936 Sys::Virt::Domain::OPEN_CONSOLE_FORCE
938 Force opening of the console, disconnecting any other open session
939 Sys::Virt::Domain::OPEN_CONSOLE_SAFE
941 Check if the console driver supports safe operations
942 XML DUMP OPTIONS
944 The following constants are used to control the information included in
945 the XML configuration dump
946 Sys::Virt::Domain::XML_INACTIVE
948 Report the persistent inactive configuration for the guest, even if
949 it is currently running.
950 Sys::Virt::Domain::XML_SECURE
952 Include security sensitive information in the XML dump, such as
953 passwords.
954 Sys::Virt::Domain::XML_UPDATE_CPU
956 Update the CPU model definition to match the current executing
957 state.
958 DEVICE HOTPLUG OPTIONS
960 The following constants are used to control device hotplug operations
961 Sys::Virt::Domain::DEVICE_MODIFY_CURRENT
963 Modify the domain in its current state
964 Sys::Virt::Domain::DEVICE_MODIFY_LIVE
966 Modify only the live state of the domain
967 Sys::Virt::Domain::DEVICE_MODIFY_CONFIG
969 Modify only the persistent config of the domain
970 Sys::Virt::Domain::DEVICE_MODIFY_FORCE
972 Force the device to be modified
973 MEMORY OPTIONS
975 The following constants are used to control memory change operations
976 Sys::Virt::Domain::MEM_CURRENT
978 Modify the current state
979 Sys::Virt::Domain::MEM_LIVE
981 Modify only the live state of the domain
982 Sys::Virt::Domain::MEM_CONFIG
984 Modify only the persistent config of the domain
985 Sys::Virt::Domain::MEM_MAXIMUM
987 Modify the maximum memory value
988 CONFIG OPTIONS
990 The following constants are used to control what configuration a domain
991 update changes
992 Sys::Virt::Domain::AFFECT_CURRENT
994 Modify the current state
995 Sys::Virt::Domain::AFFECT_LIVE
997 Modify only the live state of the domain
998 Sys::Virt::Domain::AFFECT_CONFIG
1000 Modify only the persistent config of the domain
1001 MIGRATE OPTIONS
1003 The following constants are used to control how migration is performed
1004 Sys::Virt::Domain::MIGRATE_LIVE
1006 Migrate the guest without interrupting its execution on the source
1007 host.
1008 Sys::Virt::Domain::MIGRATE_PEER2PEER
1010 Manage the migration process over a direct peer-2-peer connection
1011 between the source and destination host libvirtd daemons.
1012 Sys::Virt::Domain::MIGRATE_TUNNELLED
1014 Tunnel the migration data over the libvirt daemon connection,
1015 rather than the native hypervisor data transport. Requires
1016 PEER2PEER flag to be set.
1017 Sys::Virt::Domain::MIGRATE_PERSIST_DEST
1019 Make the domain persistent on the destination host, defining its
1020 configuration file upon completion of migration.
1021 Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE
1023 Remove the domain's persistent configuration after migration
1024 completes successfully.
1025 Sys::Virt::Domain::MIGRATE_PAUSED
1027 Do not re-start execution of the guest CPUs on the destination host
1028 after migration completes.
1029 Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK
1031 Copy the complete contents of the disk images during migration
1032 Sys::Virt::Domain::MIGRATE_NON_SHARED_INC
1034 Copy the incrementally changed contents of the disk images during
1035 migration
1036 Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION
1038 Do not allow changes to the virtual domain configuration while
1039 migration is taking place. This option is automatically implied if
1040 doing a peer-2-peer migration.
1041 Sys::Virt::Domain::MIGRATE_UNSAFE
1043 Migrate even if the compatibility check indicates the migration
1044 will be unsafe to the guest.
1045 UNDEFINE CONSTANTS
1047 The following constants can be used when undefining virtual domain
1048 configurations
1049 Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE
1051 Also remove any managed save image when undefining the virtual
1052 domain
1053 Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA
1055 Also remove any snapshot metadata when undefining the virtual
1056 domain.
1057 JOB TYPES
1059 The following constants describe the different background job types.
1060 Sys::Virt::Domain::JOB_NONE
1062 No job is active
1063 Sys::Virt::Domain::JOB_BOUNDED
1065 A job with a finite completion time is active
1066 Sys::Virt::Domain::JOB_UNBOUNDED
1068 A job with an unbounded completion time is active
1069 Sys::Virt::Domain::JOB_COMPLETED
1071 The job has finished, but isn't cleaned up
1072 Sys::Virt::Domain::JOB_FAILED
1074 The job has hit an error, but isn't cleaned up
1075 Sys::Virt::Domain::JOB_CANCELLED
1077 The job was aborted at user request, but isn't cleaned up
1078 MEMORY PARAMETERS
1080 The following constants are useful when getting/setting memory
1081 parameters for guests
1082 Sys::Virt::Domain::MEMORY_HARD_LIMIT
1084 The maximum memory the guest can use.
1085 Sys::Virt::Domain::MEMORY_SOFT_LIMIT
1087 The memory upper limit enforced during memory contention.
1088 Sys::Virt::Domain::MEMORY_MIN_GUARANTEE
1090 The minimum memory guaranteed to be reserved for the guest.
1091 Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT
1093 The maximum swap the guest can use.
1094 Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED
1096 The value of an unlimited memory parameter
1097 BLKIO PARAMETERS
1099 The following parameters control I/O tuning for the domain as a whole
1100 Sys::Virt::Domain::BLKIO_WEIGHT
1102 The I/O weight parameter
1103 Sys::Virt::Domain::BLKIO_DEVICE_WEIGHT
1105 The per-device I/O weight parameter
1106 BLKIO TUNING PARAMETERS
1108 The following parameters control I/O tuning for an individual guest
1109 disk.
1110 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_BYTES_SEC
1112 The total bytes processed per second.
1113 Sys::Virt::Domain::BLOCK_IOTUNE_READ_BYTES_SEC
1115 The bytes read per second.
1116 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_BYTES_SEC
1118 The bytes written per second.
1119 Sys::Virt::Domain::BLOCK_IOTUNE_TOTAL_IOPS_SEC
1121 The total I/O operations processed per second.
1122 Sys::Virt::Domain::BLOCK_IOTUNE_READ_IOPS_SEC
1124 The I/O operations read per second.
1125 Sys::Virt::Domain::BLOCK_IOTUNE_WRITE_IOPS_SEC
1127 The I/O operations written per second.
1128 SCHEDULER CONSTANTS
1130 Sys::Virt::Domain::SCHEDULER_CAP
1131 The VM cap tunable
1132 Sys::Virt::Domain::SCHEDULER_CPU_SHARES
1134 The CPU shares tunable
1135 Sys::Virt::Domain::SCHEDULER_LIMIT
1137 The VM limit tunable
1138 Sys::Virt::Domain::SCHEDULER_RESERVATION
1140 The VM reservation tunable
1141 Sys::Virt::Domain::SCHEDULER_SHARES
1143 The VM shares tunable
1144 Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD
1146 The VCPU period tunable
1147 Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA
1149 The VCPU quota tunable
1150 Sys::Virt::Domain::SCHEDULER_WEIGHT
1152 The VM weight tunable
1153 NUMA PARAMETERS
1155 The following constants are useful when getting/setting the guest NUMA
1156 memory policy
1157 Sys::Virt::Domain::NUMA_MODE
1159 The NUMA policy mode
1160 Sys::Virt::Domain::NUMA_NODESET
1162 The NUMA nodeset mask
1163 The following constants are useful when interpreting the
1165 "Sys::Virt::Domain::NUMA_MODE" parameter value
1166 Sys::Virt::Domain::NUMATUNE_MEM_STRICT
1168 Allocation is mandatory from the mask nodes
1169 Sys::Virt::Domain::NUMATUNE_MEM_PREFERRED
1171 Allocation is preferred from the masked nodes
1172 Sys::Virt::Domain::NUMATUNE_MEM_INTERLEAVE
1174 Allocation is interleaved across all masked nods
1175 INTERFACE PARAMETERS
1177 The following constants are useful when getting/setting the per network
1178 interface tunable parameters
1179 Sys::Virt::Domain::BANDWIDTH_IN_AVERAGE
1181 The average inbound bandwidth
1182 Sys::Virt::Domain::BANDWIDTH_IN_PEAK
1184 The peak inbound bandwidth
1185 Sys::Virt::Domain::BANDWIDTH_IN_BURST
1187 The burstable inbound bandwidth
1188 Sys::Virt::Domain::BANDWIDTH_OUT_AVERAGE
1190 The average outbound bandwidth
1191 Sys::Virt::Domain::BANDWIDTH_OUT_PEAK
1193 The peak outbound bandwidth
1194 Sys::Virt::Domain::BANDWIDTH_OUT_BURST
1196 The burstable outbound bandwidth
1197 VCPU FLAGS
1199 The following constants are useful when getting/setting the VCPU count
1200 for a guest
1201 Sys::Virt::Domain::VCPU_LIVE
1203 Flag to request the live value
1204 Sys::Virt::Domain::VCPU_CONFIG
1206 Flag to request the persistent config value
1207 Sys::Virt::Domain::VCPU_CURRENT
1209 Flag to request the current config value
1210 Sys::Virt::Domain::VCPU_MAXIMUM
1212 Flag to request adjustment of the maximum vCPU value
1213 STATE CHANGE EVENTS
1215 The following constants allow domain state change events to be
1216 interpreted. The events contain both a state change, and a reason.
1217 Sys::Virt::Domain::EVENT_DEFINED
1219 Indicates that a persistent configuration has been defined for the
1220 domain.
1221 Sys::Virt::Domain::EVENT_DEFINED_ADDED
1223 The defined configuration is newly added
1224 Sys::Virt::Domain::EVENT_DEFINED_UPDATED
1226 The defined configuration is an update to an existing
1227 configuration
1228 Sys::Virt::Domain::EVENT_RESUMED
1230 The domain has resumed execution
1231 Sys::Virt::Domain::EVENT_RESUMED_MIGRATED
1233 The domain resumed because migration has completed. This is
1234 emitted on the destination host.
1235 Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED
1237 The domain resumed because the admin unpaused it.
1238 Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT
1240 The domain resumed because it was restored from a snapshot
1241 Sys::Virt::Domain::EVENT_STARTED
1243 The domain has started running
1244 Sys::Virt::Domain::EVENT_STARTED_BOOTED
1246 The domain was booted from shutoff state
1247 Sys::Virt::Domain::EVENT_STARTED_MIGRATED
1249 The domain started due to an incoming migration
1250 Sys::Virt::Domain::EVENT_STARTED_RESTORED
1252 The domain was restored from saved state file
1253 Sys::Virt::Domain::EVENT_STARTED_FROM_SNAPSHOT
1255 The domain was restored from a snapshot
1256 Sys::Virt::Domain::EVENT_STARTED_WAKEUP
1258 The domain was woken up from suspend
1259 Sys::Virt::Domain::EVENT_STOPPED
1261 The domain has stopped running
1262 Sys::Virt::Domain::EVENT_STOPPED_CRASHED
1264 The domain stopped because guest operating system has crashed
1265 Sys::Virt::Domain::EVENT_STOPPED_DESTROYED
1267 The domain stopped because administrator issued a destroy
1268 command.
1269 Sys::Virt::Domain::EVENT_STOPPED_FAILED
1271 The domain stopped because of a fault in the host
1272 virtualization environment.
1273 Sys::Virt::Domain::EVENT_STOPPED_MIGRATED
1275 The domain stopped because it was migrated to another machine.
1276 Sys::Virt::Domain::EVENT_STOPPED_SAVED
1278 The domain was saved to a state file
1279 Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN
1281 The domain stopped due to graceful shutdown of the guest.
1282 Sys::Virt::Domain::EVENT_STOPPED_FROM_SNAPSHOT
1284 The domain was stopped due to a snapshot
1285 Sys::Virt::Domain::EVENT_SHUTDOWN
1287 The domain has shutdown but is not yet stopped
1288 Sys::Virt::Domain::EVENT_SHUTDOWN_FINISHED
1290 The domain finished shutting down
1291 Sys::Virt::Domain::EVENT_SUSPENDED
1293 The domain has stopped executing, but still exists
1294 Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED
1296 The domain has been suspended due to offline migration
1297 Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED
1299 The domain has been suspended due to administrator pause
1300 request.
1301 Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR
1303 The domain has been suspended due to a block device I/O error.
1304 Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT
1306 The domain has been suspended due to resume from snapshot
1307 Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG
1309 The domain has been suspended due to the watchdog triggering
1310 Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED
1312 The domain has been suspended due to restore from saved state
1313 Sys::Virt::Domain::EVENT_UNDEFINED
1315 The persistent configuration has gone away
1316 Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED
1318 The domain configuration has gone away due to it being removed
1319 by administrator.
1320 Sys::Virt::Domain::EVENT_PMSUSPENDED
1322 The domain has stopped running
1323 Sys::Virt::Domain::EVENT_PMSUSPENDED_MEMORY
1325 The domain has suspend to RAM.
1326 EVENT ID CONSTANTS
1328 Sys::Virt::Domain::EVENT_ID_LIFECYCLE
1329 Domain lifecycle events
1330 Sys::Virt::Domain::EVENT_ID_REBOOT
1332 Soft / warm reboot events
1333 Sys::Virt::Domain::EVENT_ID_RTC_CHANGE
1335 RTC clock adjustments
1336 Sys::Virt::Domain::EVENT_ID_IO_ERROR
1338 File IO errors, typically from disks
1339 Sys::Virt::Domain::EVENT_ID_WATCHDOG
1341 Watchdog device triggering
1342 Sys::Virt::Domain::EVENT_ID_GRAPHICS
1344 Graphics client connections.
1345 Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON
1347 File IO errors, typically from disks, with a root cause
1348 Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR
1350 Errors from the virtualization control channel
1351 Sys::Virt::Domain::EVENT_ID_BLOCK_JOB
1353 Completion status of asynchronous block jobs
1354 Sys::Virt::Domain::EVENT_ID_DISK_CHANGE
1356 Changes in disk media
1357 Sys::Virt::Domain::EVENT_ID_TRAY_CHANGE
1359 CDROM media tray state
1360 Sys::Virt::Domain::EVENT_ID_PMSUSPEND
1362 Power management initiated suspend
1363 Sys::Virt::Domain::EVENT_ID_PMWAKEUP
1365 Power management initiated wakeup
1366 Sys::Virt::Domain::EVENT_ID_BALLOON_CHANGE
1368 Balloon target changes
1369 IO ERROR EVENT CONSTANTS
1371 These constants describe what action was taken due to the IO error.
1372 Sys::Virt::Domain::EVENT_IO_ERROR_NONE
1374 No action was taken, the error was ignored & reported as success to
1375 guest
1376 Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE
1378 The guest is paused since the error occurred
1379 Sys::Virt::Domain::EVENT_IO_ERROR_REPORT
1381 The error has been reported to the guest OS
1382 WATCHDOG EVENT CONSTANTS
1384 These constants describe what action was taken due to the watchdog
1385 firing
1386 Sys::Virt::Domain::EVENT_WATCHDOG_NONE
1388 No action was taken, the watchdog was ignored
1389 Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE
1391 The guest is paused since the watchdog fired
1392 Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF
1394 The guest is powered off after the watchdog fired
1395 Sys::Virt::Domain::EVENT_WATCHDOG_RESET
1397 The guest is reset after the watchdog fired
1398 Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN
1400 The guest attempted to gracefully shutdown after the watchdog fired
1401 Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG
1403 No action was taken, the watchdog was logged
1404 GRAPHICS EVENT PHASE CONSTANTS
1406 These constants describe the phase of the graphics connection
1407 Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT
1409 The initial client connection
1410 Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE
1412 The client has been authenticated & the connection is running
1413 Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT
1415 The client has disconnected
1416 GRAPHICS EVENT ADDRESS CONSTANTS
1418 These constants describe the format of the address
1419 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4
1421 An IPv4 address
1422 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6
1424 An IPv6 address
1425 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX
1427 An UNIX socket path address
1428 DISK CHANGE EVENT CONSTANTS
1430 These constants describe the reason for a disk change event
1431 Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START
1433 The disk media was missing when attempting to start the guest
1434 TRAY CHANGE CONSTANTS
1436 These constants describe the reason for a tray change event
1437 Sys::Virt::Domain::EVENT_TRAY_CHANGE_CLOSE
1439 The tray was closed
1440 Sys::Virt::Domain::EVENT_TRAY_CHANGE_OPEN
1442 The tray was opened
1443 DOMAIN BLOCK JOB TYPE CONSTANTS
1445 The following constants identify the different types of domain block
1446 jobs
1447 Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN
1449 An unknown block job type
1450 Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL
1452 The block pull job type
1453 Sys::Virt::Domain::BLOCK_JOB_TYPE_COPY
1455 The block copy job type
1456 Sys::Virt::Domain::BLOCK_JOB_TYPE_COMMIT
1458 The block commit job type
1459 DOMAIN BLOCK JOB COMPLETION CONSTANTS
1461 The following constants can be used to determine the completion status
1462 of a block job
1463 Sys::Virt::Domain::BLOCK_JOB_COMPLETED
1465 A successfully completed block job
1466 Sys::Virt::Domain::BLOCK_JOB_FAILED
1468 An unsuccessful block job
1469 Sys::Virt::Domain::BLOCK_JOB_CANCELED
1471 A block job canceled byy the user
1472 DOMAIN BLOCK REBASE CONSTANTS
1474 The following constants are useful when rebasing block devices
1475 Sys::Virt::Domain::BLOCK_REBASE_SHALLOW
1477 Limit copy to top of source backing chain
1478 Sys::Virt::Domain::BLOCK_REBASE_REUSE_EXT
1480 Reuse existing external file for copy
1481 Sys::Virt::Domain::BLOCK_REBASE_COPY_RAW
1483 Make destination file raw
1484 Sys::Virt::Domain::BLOCK_REBASE_COPY
1486 Start a copy job
1487 DOMAIN BLOCK JOB ABORT CONSTANTS
1489 The following constants are useful when aborting job copy jobs
1490 Sys::Virt::Domain::BLOCK_JOB_ABORT_ASYNC
1492 Request only, do not wait for completion
1493 Sys::Virt::Domain::BLOCK_JOB_ABORT_PIVOT
1495 Pivot to mirror when ending a copy job
1496 DOMAIN BLOCK COMMIT JOB CONSTANTS
1498 The following constants are useful with block commit job types
1499 Sys::Virt::Domain::BLOCK_COMMIT_DELETE
1501 Delete any files that are invalid after commit
1502 Sys::Virt::Domain::BLOCK_COMMIT_SHALLOW
1504 NULL base means next backing file, not whole chain
1505 DOMAIN SAVE / RESTORE CONSTANTS
1507 The following constants can be used when saving or restoring virtual
1508 machines
1509 Sys::Virt::Domain::SAVE_BYPASS_CACHE
1511 Do not use OS I/O cache when saving state.
1512 Sys::Virt::Domain::SAVE_PAUSED
1514 Mark the saved state as paused to prevent the guest CPUs starting
1515 upon restore.
1516 Sys::Virt::Domain::SAVE_RUNNING
1518 Mark the saved state as running to allow the guest CPUs to start
1519 upon restore.
1520 DOMAIN CORE DUMP CONSTANTS
1522 The following constants can be used when triggering domain core dumps
1523 Sys::Virt::Domain::DUMP_LIVE
1525 Do not pause execution while dumping the guest
1526 Sys::Virt::Domain::DUMP_CRASH
1528 Crash the guest after completing the core dump
1529 Sys::Virt::Domain::DUMP_BYPASS_CACHE
1531 Do not use OS I/O cache when writing core dump
1532 Sys::Virt::Domain::DUMP_RESET
1534 Reset the virtual machine after finishing the dump
1535 Sys::Virt::Domain::DUMP_MEMORY_ONLY
1537 Only include guest RAM in the dump, not the device state
1538 DESTROY CONSTANTS
1540 The following constants are useful when terminating guests using the
1541 "destroy" API.
1542 Sys::Virt::Domain::DESTROY_DEFAULT
1544 Destroy the guest using the default approach
1545 Sys::Virt::Domain::DESTROY_GRACEFUL
1547 Destroy the guest in a graceful manner
1548 SHUTDOWN CONSTANTS
1550 The following constants are useful when requesting that a guest
1551 terminate using the "shutdown" API
1552 Sys::Virt::Domain::SHUTDOWN_DEFAULT
1554 Shutdown using the hypervisor's default mechanism
1555 Sys::Virt::Domain::SHUTDOWN_GUEST_AGENT
1557 Shutdown by issuing a command to a guest agent
1558 Sys::Virt::Domain::SHUTDOWN_ACPI_POWER_BTN
1560 Shutdown by injecting an ACPI power button press
1561 REBOOT CONSTANTS
1563 The following constants are useful when requesting that a guest
1564 terminate using the "reboot" API
1565 Sys::Virt::Domain::REBOOT_DEFAULT
1567 Reboot using the hypervisor's default mechanism
1568 Sys::Virt::Domain::REBOOT_GUEST_AGENT
1570 Reboot by issuing a command to a guest agent
1571 Sys::Virt::Domain::REBOOT_ACPI_POWER_BTN
1573 Reboot by injecting an ACPI power button press
1574 METADATA CONSTANTS
1576 The following constants are useful when reading/writing metadata about
1577 a guest
1578 Sys::Virt::Domain::METADATA_TITLE
1580 The short human friendly title of the guest
1581 Sys::Virt::Domain::METADATA_DESCRIPTION
1583 The long free text description of the guest
1584 Sys::Virt::Domain::METADATA_ELEMENT
1586 The structured metadata elements for the guest
1587 DISK ERROR CONSTANTS
1589 The following constants are useful when interpreting disk error codes
1590 Sys::Virt::Domain::DISK_ERROR_NONE
1592 No error
1593 Sys::Virt::Domain::DISK_ERROR_NO_SPACE
1595 The host storage has run out of free space
1596 Sys::Virt::Domain::DISK_ERROR_UNSPEC
1598 An unspecified error has ocurred.
1599 MEMORY STATISTIC CONSTANTS
1601 Sys::Virt::Domain::MEMORY_STAT_SWAP_IN
1602 Swap in
1603 Sys::Virt::Domain::MEMORY_STAT_SWAP_OUT
1605 Swap out
1606 Sys::Virt::Domain::MEMORY_STAT_MINOR_FAULT
1608 Minor faults
1609 Sys::Virt::Domain::MEMORY_STAT_MAJOR_FAULT
1611 Major faults
1612 Sys::Virt::Domain::MEMORY_STAT_RSS
1614 Resident memory
1615 Sys::Virt::Domain::MEMORY_STAT_UNUSED
1617 Unused memory
1618 Sys::Virt::Domain::MEMORY_STAT_AVAILABLE
1620 Available memory
1621 Sys::Virt::Domain::MEMORY_STAT_ACTUAL_BALLOON
1623 Actual balloon limit
1624 DOMAIN LIST CONSTANTS
1626 The following constants can be used when listing domains
1627 Sys::Virt::Domain::LIST_ACTIVE
1629 Only list domains that are currently active (running, or paused)
1630 Sys::Virt::Domain::LIST_AUTOSTART
1632 Only list domains that are set to automatically start on boot
1633 Sys::Virt::Domain::LIST_HAS_SNAPSHOT
1635 Only list domains that have a stored snapshot
1636 Sys::Virt::Domain::LIST_INACTIVE
1638 Only list domains that are currently inactive (shutoff, saved)
1639 Sys::Virt::Domain::LIST_MANAGEDSAVE
1641 Only list domains that have current managed save state
1642 Sys::Virt::Domain::LIST_NO_AUTOSTART
1644 Only list domains that are not set to automatically start on boto
1645 Sys::Virt::Domain::LIST_NO_MANAGEDSAVE
1647 Only list domains that do not have any managed save state
1648 Sys::Virt::Domain::LIST_NO_SNAPSHOT
1650 Only list domains that do not have a stored snapshot
1651 Sys::Virt::Domain::LIST_OTHER
1653 Only list domains that are not running, paused or shutoff
1654 Sys::Virt::Domain::LIST_PAUSED
1656 Only list domains that are paused
1657 Sys::Virt::Domain::LIST_PERSISTENT
1659 Only list domains which have a persistent config
1660 Sys::Virt::Domain::LIST_RUNNING
1662 Only list domains that are currently running
1663 Sys::Virt::Domain::LIST_SHUTOFF
1665 Only list domains that are currently shutoff
1666 Sys::Virt::Domain::LIST_TRANSIENT
1668 Only list domains that do not have a persistent config
1669 SEND KEY CONSTANTS
1671 The following constants are to be used with the "send_key" API
1672 Sys::Virt::Domain::SEND_KEY_MAX_KEYS
1674 The maximum number of keys that can be sent in a single call to
1675 "send_key"
1676 BLOCK STATS CONSTANTS
1678 The following constants provide the names of well known block stats
1679 fields
1680 Sys::Virt::Domain::BLOCK_STATS_ERRS
1682 The number of I/O errors
1683 Sys::Virt::Domain::BLOCK_STATS_FLUSH_REQ
1685 The number of flush requests
1686 Sys::Virt::Domain::BLOCK_STATS_FLUSH_TOTAL_TIMES
1688 The time spent processing flush requests
1689 Sys::Virt::Domain::BLOCK_STATS_READ_BYTES
1691 The amount of data read
1692 Sys::Virt::Domain::BLOCK_STATS_READ_REQ
1694 The number of read requests
1695 Sys::Virt::Domain::BLOCK_STATS_READ_TOTAL_TIMES
1697 The time spent processing read requests
1698 Sys::Virt::Domain::BLOCK_STATS_WRITE_BYTES
1700 The amount of data written
1701 Sys::Virt::Domain::BLOCK_STATS_WRITE_REQ
1703 The number of write requests
1704 Sys::Virt::Domain::BLOCK_STATS_WRITE_TOTAL_TIMES
1706 The time spent processing write requests
1707 CPU STATS CONSTANTS
1709 The following constants provide the names of well known cpu stats
1710 fields
1711 Sys::Virt::Domain::CPU_STATS_CPUTIME
1713 The total CPU time, including both hypervisor and vCPU time.
1714 Sys::Virt::Domain::CPU_STATS_USERTIME
1716 THe total time in kernel
1717 Sys::Virt::Domain::CPU_STATS_SYSTEMTIME
1719 The total time in userspace
1720 Sys::Virt::Domain::CPU_STATS_VCPUTIME
1722 The total vCPU time.
1723 CPU STATS CONSTANTS
1725 The following constants provide the names of well known schedular
1726 parameters
1727 Sys::Virt::SCHEDULER_EMULATOR_PERIOD
1729 The duration of the time period for scheduling the emulator
1730 Sys::Virt::SCHEDULER_EMULATOR_QUOTA
1732 The quota for the emulator in one schedular time period
1733
1735 Daniel P. Berrange <berrange@redhat.com>
1736
1738 Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
1739
1741 This program is free software; you can redistribute it and/or modify it
1742 under the terms of either the GNU General Public License as published
1743 by the Free Software Foundation (either version 2 of the License, or at
1744 your option any later version), or, the Artistic License, as specified
1745 in the Perl README file.
1746
1748 Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
1749perl v5.10.1 2015-07-23 Sys::Virt::Domain(3)