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 $dom->is_active()
28 Returns a true value if the domain is currently running
29 $dom->is_persistent()
31 Returns a true value if the domain has a persistent configuration
32 file defined
33 my $xml = $dom->get_xml_description()
35 Returns an XML document containing a complete description of the
36 domain's configuration
37 my $type = $dom->get_os_type()
39 Returns a string containing the name of the OS type running within
40 the domain.
41 $dom->create()
43 Start a domain whose configuration was previously defined using the
44 "define_domain" method in Sys::Virt.
45 $dom->undefine()
47 Remove the configuration associated with a domain previously
48 defined with the "define_domain" method in Sys::Virt. If the domain
49 is running, you probably want to use the "shutdown" or "destroy"
50 methods instead.
51 $dom->suspend()
53 Temporarily stop execution of the domain, allowing later
54 continuation by calling the "resume" method.
55 $dom->resume()
57 Resume execution of a domain previously halted with the "suspend"
58 method.
59 $dom->save($filename)
61 Take a snapshot of the domain's state and save the information to
62 the file named in the $filename parameter. The domain can later be
63 restored from this file with the "restore_domain" method on the
64 Sys::Virt object.
65 $dom->managed_save($flags=0)
67 Take a snapshot of the domain's state and save the information to a
68 managed save location. The domain will be automatically restored
69 with this state when it is next started. The $flags parameter is
70 unused and defaults to zero.
71 $bool = $dom->has_managed_save_image($flags=0)
73 Return a non-zero value if the domain has a managed save image that
74 will be used at next start. The $flags parameter is unused and
75 defaults to zero.
76 $dom->managed_save_remove($flags=0)
78 Remove the current managed save image, causing the guest to perform
79 a full boot next time it is started. The $flags parameter is unused
80 and defaults to zero.
81 $dom->core_dump($filename[, $flags])
83 Trigger a core dump of the guest virtual machine, saving its memory
84 image to $filename so it can be analysed by tools such as "crash".
85 The optional $flags flags parameter is currently unused and if
86 omitted will default to 0.
87 $dom->destroy()
89 Immediately terminate the machine, and remove it from the virtual
90 machine monitor. The $dom handle is invalid after this call
91 completes and should not be used again.
92 my $info = $dom->get_info()
94 Returns a hash reference summarising the execution state of the
95 domain. The elements of the hash are as follows:
96 maxMem
98 The maximum memory allowed for this domain, in kilobytes
99 memory
101 The current memory allocated to the domain in kilobytes
102 cpuTime
104 The amount of CPU time used by the domain
105 nrVirtCpu
107 The current number of virtual CPUs enabled in the domain
108 state
110 The execution state of the machine, which will be one of the
111 constants &Sys::Virt::Domain::STATE_*.
112 my $info = $dom->get_block_info($dev, $flags=0)
114 Returns a hash reference summarising the disk usage of the host
115 backing store for a guest block device. The $dev parameter should
116 be the path to the backing store on the host. $flags is currently
117 unused and defaults to 0 if omitted. The returned hash contains the
118 following elements
119 capacity
121 Logical size in bytes of the block device backing image *
122 allocation
124 Highest allocated extent in bytes of the block device backing
125 image
126 physical
128 Physical size in bytes of the container of the backing image
129 $dom->set_max_memory($mem)
131 Set the maximum memory for the domain to the value $mem. The value
132 of the $mem parameter is specified in kilobytes.
133 $mem = $dom->get_max_memory()
135 Returns the current maximum memory allowed for this domain in
136 kilobytes.
137 $dom->set_memory($mem)
139 Set the current memory for the domain to the value $mem. The value
140 of the $mem parameter is specified in kilobytes. This must be less
141 than, or equal to the domain's max memory limit.
142 $dom->shutdown()
144 Request that the guest OS perform a graceful shutdown and poweroff.
145 $dom->reboot([$flags])
147 Request that the guest OS perform a graceful shutdown and
148 optionally restart. The optional $flags parameter is currently
149 unused and if omitted defaults to zero.
150 $dom->get_max_vcpus()
152 Return the maximum number of vcpus that are configured for the
153 domain
154 $dom->attach_device($xml[, $flags])
156 Hotplug a new device whose configuration is given by $xml, to the
157 running guest. The optional <$flags> parameter defaults to 0, but
158 can accept one of the device hotplug flags described later.
159 $dom->detach_device($xml[, $flags])
161 Hotunplug a existing device whose configuration is given by $xml,
162 from the running guest. The optional <$flags> parameter defaults to
163 0, but can accept one of the device hotplug flags described later.
164 $dom->update_device($xml[, $flags])
166 Update the configuration of an existing device. The new
167 configuration is given by $xml. The optional <$flags> parameter
168 defaults to 0 but can accept one of the device hotplug flags
169 described later.
170 $data = $dom->block_peek($path, $offset, $size[, $flags)
172 Peek into the guest disk $path, at byte $offset capturing $size
173 bytes of data. The returned scalar may contain embedded NULLs. The
174 optional $flags parameter is currently unused and if omitted
175 defaults to zero.
176 $data = $dom->memory_peek($offset, $size[, $flags])
178 Peek into the guest memory at byte $offset virtual address,
179 capturing $size bytes of memory. The return scalar may contain
180 embedded NULLs. The optional $flags parameter is currently unused
181 and if omitted defaults to zero.
182 $flag = $dom->get_autostart();
184 Return a true value if the guest domain is configured to
185 automatically start upon boot. Return false, otherwise
186 $dom->set_autostart($flag)
188 Set the state of the autostart flag, which determines whether the
189 guest will automatically start upon boot of the host OS
190 $dom->set_vcpus($count)
192 Set the number of virtual CPUs in the guest VM to $count
193 $type = $dom->get_scheduler_type()
195 Return the scheduler type for the guest domain
196 %stats = $dom->block_stats($path)
198 Fetch the current I/O statistics for the block device given by
199 $path. The returned hash containins keys for
200 my %params = $dom->get_scheduler_parameters()
202 Return the set of scheduler tunable parameters for the guest.
203 $dom->set_scheduler_parameters($params)
205 Update the set of scheduler tunable parameters. The value names for
206 tunables vary, and can be discovered using the
207 "get_scheduler_params" call
208 "rd_req"
210 Number of read requests
211 "rd_bytes"
213 Number of bytes read
214 "wr_req"
216 Number of write requests
217 "wr_bytes"
219 Number of bytes written
220 "errs"
222 Some kind of error count
223 $dom->interface_stats($path)
225 Fetch the current I/O statistics for the block device given by
226 $path. The returned hash containins keys for
227 "rx_bytes"
229 Total bytes received
230 "rx_packets"
232 Total packets received
233 "rx_errs"
235 Total packets received with errors
236 "rx_drop"
238 Total packets drop at reception
239 "tx_bytes"
241 Total bytes transmitted
242 "tx_packets"
244 Total packets transmitted
245 "tx_errs"
247 Total packets transmitted with errors
248 "tx_drop"
250 Total packets dropped at transmission.
251 $dom->memory_stats($flags=0)
253 Fetch the current memory statistics for the guest domain. The
254 $flags parameter is currently unused and can be omitted. The
255 returned hash containins keys for
256 "swap_in"
258 Data read from swap space
259 "swap_out"
261 Data written to swap space
262 "major_fault"
264 Page fault involving disk I/O
265 "minor_fault"
267 Page fault not involving disk I/O
268 "unused"
270 Memory not used by the system
271 "available"
273 Total memory seen by guest
274 %info = $dom->get_security_label()
276 Fetch information about the security label assigned to the guest
277 domain. The returned hash has two keys, "model" gives the name of
278 the security model in effect (eg "selinux"), while "label" provides
279 the name of the security label applied to the domain.
280 $ddom = $dom->migrate(destcon, flags, dname, uri, bandwidth)
282 Migrate a domain to an alternative host. The "destcon" parameter
283 should be a "Sys::Virt" connection to the remote target host. If
284 the "flags" parameter is zero offline migration will be performed.
285 The "Sys::Virt::Domain::MIGRATE_LIVE" constant can be used to
286 request live migration. The "dname" parameter allows the guest to
287 be renamed on the target host, if set to "undef", the domains'
288 current name will be maintained. In normal circumstances, the
289 source host determines the target hostname from the URI associated
290 with the "destcon" connection. If the destination host is multi-
291 homed it may be necessary to supply an alternate destination
292 hostame via the "uri" parameter. The "bandwidth" parameter allows
293 network usage to be throttled during migration. If set to zero, no
294 throttling will be performed. The "flags", "dname", "uri" and
295 "bandwidth" parameters are all optional, and if omitted default to
296 zero, "undef", "undef", and zero respectively.
297 $dom->migrate_to_uri(desturi, flags, dname, uri, bandwidth)
299 Migrate a domain to an alternative host. The "destri" parameter
300 should be a valid libvirt connection URI for the remote target
301 host. If the "flags" parameter is zero offline migration will be
302 performed. The "Sys::Virt::Domain::MIGRATE_LIVE" constant can be
303 used to request live migration. The "dname" parameter allows the
304 guest to be renamed on the target host, if set to "undef", the
305 domains' current name will be maintained. In normal circumstances,
306 the source host determines the target hostname from the URI
307 associated with the "destcon" connection. If the destination host
308 is multi-homed it may be necessary to supply an alternate
309 destination hostame via the "uri" parameter. The "bandwidth"
310 parameter allows network usage to be throttled during migration. If
311 set to zero, no throttling will be performed. The "flags", "dname",
312 "uri" and "bandwidth" parameters are all optional, and if omitted
313 default to zero, "undef", "undef", and zero respectively.
314 $dom->migrate_set_max_downtime($downtime, $flags)
316 Set the maximum allowed downtime during migration of the guest. A
317 longer downtime makes it more likely that migration will complete,
318 at the cost of longer time blackout for the guest OS at the switch
319 over point. The "downtime" parameter is measured in milliseconds.
320 The $flags parameter is currently unused and defaults to zero.
321 @vcpuinfo = $dom->get_vcpu_info()
323 Obtain information about the state of all virtual CPUs in a running
324 guest domain. The returned list will have one element for each
325 vCPU, where each elements contains a hash reference. The keys in
326 the hash are, "number" the vCPU number, "cpu" the physical CPU on
327 which the vCPU is currently scheduled, "cpuTime" the cummulative
328 execution time of the vCPU, "state" the running state and
329 "affinity" giving the allowed shedular placement. The value for
330 "affinity" is a string representing a bitmask against physical
331 CPUs, 8 cpus per character.
332 $dom->pin_vcpu($vcpu, $mask)
334 Ping the virtual CPU given by index $vcpu to physical CPUs given by
335 $mask. The $mask is a string representing a bitmask against
336 physical CPUs, 8 cpus per character.
337 my $info = $dom->get_job_info()
339 Returns a hash reference summarising the execution state of the
340 background job. The elements of the hash are as follows:
341 $dom->abort_job()
343 Aborts the currently executing job
344 $count = $dom->num_of_snapshots()
346 Return the number of saved snapshots of the domain
347 @names = $dom->list_snapshot_names()
349 List the names of all saved snapshots. The names can be used with
350 the "lookup_snapshot_by_name"
351 @snapshots = $dom->list_snapshots()
353 Return a list of all snapshots currently known to the domain. The
354 elements in the returned list are instances of the
355 Sys::Virt::DomainSnapshot class.
356 $dom->has_current_snapshot()
358 Returns a true value if the domain has a currently active snapshot
359 $snapshot = $dom->current_snapshot()
361 Returns the currently active snapshot for the domain.
362 type
364 The type of job, one of the JOB TYPE constants listed later in
365 this document.
366 timeElapsed
368 The elapsed time in milliseconds
369 timeRemaining
371 The expected remaining time in milliseconds. Only set if the
372 "type" is JOB_UNBOUNDED.
373 dataTotal
375 The total amount of data expected to be processed by the job,
376 in bytes.
377 dataProcessed
379 The current amount of data processed by the job, in bytes.
380 dataRemaining
382 The expected amount of data remaining to be processed by the
383 job, in bytes.
384 memTotal
386 The total amount of mem expected to be processed by the job, in
387 bytes.
388 memProcessed
390 The current amount of mem processed by the job, in bytes.
391 memRemaining
393 The expected amount of mem remaining to be processed by the
394 job, in bytes.
395 fileTotal
397 The total amount of file expected to be processed by the job,
398 in bytes.
399 fileProcessed
401 The current amount of file processed by the job, in bytes.
402 fileRemaining
404 The expected amount of file remaining to be processed by the
405 job, in bytes.
406
408 A number of the APIs take a "flags" parameter. In most cases passing a
409 value of zero will be satisfactory. Some APIs, however, accept named
410 constants to alter their behaviour. This section documents the current
411 known constants.
412 DOMAIN STATE
414 The domain state constants are useful in interpreting the "state" key
415 in the hash returned by the "get_info" method.
416 Sys::Virt::Domain::STATE_NOSTATE
418 The domain is active, but is not running / blocked (eg idle)
419 Sys::Virt::Domain::STATE_RUNNING
421 The domain is active and running
422 Sys::Virt::Domain::STATE_BLOCKED
424 The domain is active, but execution is blocked
425 Sys::Virt::Domain::STATE_PAUSED
427 The domain is active, but execution has been paused
428 Sys::Virt::Domain::STATE_SHUTDOWN
430 The domain is active, but in the shutdown phase
431 Sys::Virt::Domain::STATE_SHUTOFF
433 The domain is inactive, and shut down.
434 Sys::Virt::Domain::STATE_CRASHED
436 The domain is inactive, and crashed.
437 MEMORY PEEK
439 The following constants can be used with the "memory_peek" method's
440 flags parameter
441 Sys::Virt::Domain::MEMORY_VIRTUAL
443 Indicates that the offset is using virtual memory addressing.
444 VCPU STATE
446 The following constants are useful when interpreting the virtual CPU
447 run state
448 Sys::Virt::Domain::VCPU_OFFLINE
450 The virtual CPU is not online
451 Sys::Virt::Domain::VCPU_RUNNING
453 The virtual CPU is executing code
454 Sys::Virt::Domain::VCPU_BLOCKED
456 The virtual CPU is waiting to be scheduled
457 XML DUMP OPTIONS
459 The following constants are used to control the information included in
460 the XML configuration dump
461 Sys::Virt::Domain::XML_INACTIVE
463 Report the persistent inactive configuration for the guest, even if
464 it is currently running.
465 Sys::Virt::Domain::XML_SECURE
467 Include security sensitive information in the XML dump, such as
468 passwords.
469 DEVICE HOTPLUG OPTIONS
471 The following constants are used to control device hotplug operations
472 Sys::Virt::Domain::DEVICE_MODIFY_CURRENT
474 Modify the domain in its current state
475 Sys::Virt::Domain::DEVICE_MODIFY_LIVE
477 Modify only the live state of the domain
478 Sys::Virt::Domain::DEVICE_MODIFY_CONFIG
480 Modify only the persistent config of the domain
481 MIGRATE OPTIONS
483 The following constants are used to control how migration is performed
484 Sys::Virt::Domain::MIGRATE_LIVE
486 Migrate the guest without interrupting its execution on the source
487 host.
488 Sys::Virt::Domain::MIGRATE_PEER2PEER
490 Manage the migration process over a direct peer-2-peer connection
491 between the source and destination host libvirtd daemons.
492 Sys::Virt::Domain::MIGRATE_TUNNELLED
494 Tunnel the migration data over the libvirt daemon connection,
495 rather than the native hypervisor data transport. Requires
496 PEER2PEER flag to be set.
497 Sys::Virt::Domain::MIGRATE_PERSIST_DEST
499 Make the domain persistent on the destination host, defining its
500 configuration file upon completion of migration.
501 Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE
503 Remove the domain's persistent configuration after migration
504 completes successfully.
505 Sys::Virt::Domain::MIGRATE_PAUSED
507 Do not re-start execution of the guest CPUs on the destination host
508 after migration completes.
509 JOB TYPES
511 The following constants describe the different background job types.
512 Sys::Virt::Domain::JOB_NONE
514 No job is active
515 Sys::Virt::Domain::JOB_BOUNDED
517 A job with a finite completion time is active
518 Sys::Virt::Domain::JOB_UNBOUNDED
520 A job with an unbounded completion time is active
521 Sys::Virt::Domain::JOB_COMPLETED
523 The job has finished, but isn't cleaned up
524 Sys::Virt::Domain::JOB_FAILED
526 The job has hit an error, but isn't cleaned up
527 Sys::Virt::Domain::JOB_CANCELLED
529 The job was aborted at user request, but isn't cleaned up
530 STATE CHANGE EVENTS
532 The following constants allow domain state change events to be
533 interpreted. The events contain both a state change, and a reason.
534 Sys::Virt::Domain::EVENT_DEFINED
536 Indicates that a persistent configuration has been defined for the
537 domain.
538 Sys::Virt::Domain::EVENT_DEFINED_ADDED
540 The defined configuration is newly added
541 Sys::Virt::Domain::EVENT_DEFINED_UPDATED
543 The defined configuration is an update to an existing
544 configuration
545 Sys::Virt::Domain::EVENT_RESUMED
547 The domain has resumed execution
548 Sys::Virt::Domain::EVENT_RESUMED_MIGRATED
550 The domain resumed because migration has completed. This is
551 emitted on the destination host.
552 Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED
554 The domain resumed because the admin unpaused it.
555 Sys::Virt::Domain::EVENT_STARTED
557 The domain has started running
558 Sys::Virt::Domain::EVENT_STARTED_BOOTED
560 The domain was booted from shutoff state
561 Sys::Virt::Domain::EVENT_STARTED_MIGRATED
563 The domain started due to an incoming migration
564 Sys::Virt::Domain::EVENT_STARTED_RESTORED
566 The domain was restored from saved state file
567 Sys::Virt::Domain::EVENT_STOPPED
569 The domain has stopped running
570 Sys::Virt::Domain::EVENT_STOPPED_CRASHED
572 The domain stopped because guest operating system has crashed
573 Sys::Virt::Domain::EVENT_STOPPED_DESTROYED
575 The domain stopped because administrator issued a destroy
576 command.
577 Sys::Virt::Domain::EVENT_STOPPED_FAILED
579 The domain stopped because of a fault in the host
580 virtualization environment.
581 Sys::Virt::Domain::EVENT_STOPPED_MIGRATED
583 The domain stopped because it was migrated to another machine.
584 Sys::Virt::Domain::EVENT_STOPPED_SAVED
586 The domain was saved to a state file
587 Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN
589 The domain stopped due to graceful shutdown of the guest.
590 Sys::Virt::Domain::EVENT_SUSPENDED
592 The domain has stopped executing, but still exists
593 Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED
595 The domain has been suspended due to offline migration
596 Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED
598 The domain has been suspended due to administrator pause
599 request.
600 Sys::Virt::Domain::EVENT_UNDEFINED
602 The persistent configuration has gone away
603 Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED
605 The domain configuration has gone away due to it being removed
606 by administrator.
607 EVENT ID CONSTANTS
609 Sys::Virt::Domain::EVENT_ID_LIFECYCLE
610 Domain lifecycle events
611 Sys::Virt::Domain::EVENT_ID_REBOOT
613 Soft / warm reboot events
614 Sys::Virt::Domain::EVENT_ID_RTC_CHANGE
616 RTC clock adjustments
617 Sys::Virt::Domain::EVENT_ID_IO_ERROR
619 File IO errors, typically from disks
620 Sys::Virt::Domain::EVENT_ID_WATCHDOG
622 Watchdog device triggering
623 Sys::Virt::Domain::EVENT_ID_GRAPHICS
625 Graphics client connections.
626 Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON
628 File IO errors, typically from disks, with a root cause
629 IO ERROR EVENT CONSTANTS
631 These constants describe what action was taken due to the IO error.
632 Sys::Virt::Domain::EVENT_IO_ERROR_NONE
634 No action was taken, the error was ignored & reported as success to
635 guest
636 Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE
638 The guest is paused since the error occurred
639 Sys::Virt::Domain::EVENT_IO_ERROR_REPORT
641 The error has been reported to the guest OS
642 WATCHDOG EVENT CONSTANTS
644 These constants describe what action was taken due to the watchdog
645 firing
646 Sys::Virt::Domain::EVENT_WATCHDOG_NONE
648 No action was taken, the watchdog was ignored
649 Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE
651 The guest is paused since the watchdog fired
652 Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF
654 The guest is powered off after the watchdog fired
655 Sys::Virt::Domain::EVENT_WATCHDOG_RESET
657 The guest is reset after the watchdog fired
658 Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN
660 The guest attempted to gracefully shutdown after the watchdog fired
661 Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG
663 No action was taken, the watchdog was logged
664 GRAPHICS EVENT PHASE CONSTANTS
666 These constants describe the phase of the graphics connection
667 Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT
669 The initial client connection
670 Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE
672 The client has been authenticated & the connection is running
673 Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT
675 The client has disconnected
676 GRAPHICS EVENT ADDRESS CONSTANTS
678 These constants describe the format of the address
679 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4
681 An IPv4 address
682 Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6
684 An IPv6 address
685
687 Daniel P. Berrange <berrange@redhat.com>
688
690 Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange
691
693 This program is free software; you can redistribute it and/or modify it
694 under the terms of either the GNU General Public License as published
695 by the Free Software Foundation (either version 2 of the License, or at
696 your option any later version), or, the Artistic License, as specified
697 in the Perl README file.
698
700 Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
701perl v5.12.3 2010-05-19 Sys::Virt::Domain(3)