# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Domain - Represent & manage a libvirt guest domain =head1 DESCRIPTION The C module represents a guest domain managed by the virtual machine monitor. =head1 METHODS =over 4 =cut package Sys::Virt::Domain; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is requried"; my $self; if (exists $params{name}) { $self = Sys::Virt::Domain::_lookup_by_name($con, $params{name}); } elsif (exists $params{id}) { $self = Sys::Virt::Domain::_lookup_by_id($con, $params{id}); } elsif (exists $params{uuid}) { if (length($params{uuid}) == 16) { $self = Sys::Virt::Domain::_lookup_by_uuid($con, $params{uuid}); } elsif (length($params{uuid}) == 32 || length($params{uuid}) == 36) { $self = Sys::Virt::Domain::_lookup_by_uuid_string($con, $params{uuid}); } else { die "UUID must be either 16 unsigned bytes, or 32/36 hex characters long"; } } elsif (exists $params{xml}) { if ($params{nocreate}) { $self = Sys::Virt::Domain::_define_xml($con, $params{xml}); } else { $self = Sys::Virt::Domain::_create($con, $params{xml}, $params{flags}); } } else { die "address, id or uuid parameters are required"; } bless $self, $class; return $self; } =item my $id = $dom->get_id() Returns an integer with a locally unique identifier for the domain. =item my $uuid = $dom->get_uuid() Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the domain. =item my $uuid = $dom->get_uuid_string() Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. =item my $name = $dom->get_name() Returns a string with a locally unique name of the domain =item my $hostname = $dom->get_hostname() Returns a string representing the hostname of the guest =item my $str = $dom->get_metadata($type, $uri, $flags =0) Returns the metadata element of type C<$type> associated with the domain. If C<$type> is C then the C<$uri> parameter specifies the XML namespace to retrieve, otherwise C<$uri> should be C. The optional C<$flags> parameter defaults to zero. =item $dom->set_metadata($type, $val, $key, $uri, $flags=0) Sets the metadata element of type C<$type> to hold the value C<$val>. If C<$type> is C then the C<$key> and C<$uri> elements specify an XML namespace to use, otherwise they should both be C. The optional C<$flags> parameter defaults to zero. =item $dom->is_active() Returns a true value if the domain is currently running =item $dom->is_persistent() Returns a true value if the domain has a persistent configuration file defined =item $dom->is_updated() Returns a true value if the domain is running and has a persistent configuration file defined that is out of date compared to the current live config. =item my $xml = $dom->get_xml_description($flags=0) Returns an XML document containing a complete description of the domain's configuration. The optional $flags parameter controls generation of the XML document, defaulting to 0 if omitted. It can be one or more of the XML DUMP constants listed later in this document. =item my $type = $dom->get_os_type() Returns a string containing the name of the OS type running within the domain. =item $dom->create($flags) Start a domain whose configuration was previously defined using the C method in L. The C<$flags> parameter accepts one of the DOMAIN CREATION constants documented later, and defaults to 0 if omitted. =item $dom->undefine() Remove the configuration associated with a domain previously defined with the C method in L. If the domain is running, you probably want to use the C or C methods instead. =item $dom->suspend() Temporarily stop execution of the domain, allowing later continuation by calling the C method. =item $dom->resume() Resume execution of a domain previously halted with the C method. =item $dom->pm_wakeup() Wakeup the guest from power management suspend state =item $dom->pm_suspend_for_duration($target, $duration, $flags=0) Tells the guest OS to enter the power management suspend state identified by C<$target>. The C<$target> parameter should be one of the NODE SUSPEND CONTANTS listed in C. The C<$duration> specifies when the guest should automatically wakeup. The C<$flags> parameter is optional and defaults to zero. =item $dom->save($filename) Take a snapshot of the domain's state and save the information to the file named in the C<$filename> parameter. The domain can later be restored from this file with the C method on the L object. =item $dom->managed_save($flags=0) Take a snapshot of the domain's state and save the information to a managed save location. The domain will be automatically restored with this state when it is next started. The C<$flags> parameter is unused and defaults to zero. =item $bool = $dom->has_managed_save_image($flags=0) Return a non-zero value if the domain has a managed save image that will be used at next start. The C<$flags> parameter is unused and defaults to zero. =item $dom->managed_save_remove($flags=0) Remove the current managed save image, causing the guest to perform a full boot next time it is started. The C<$flags> parameter is unused and defaults to zero. =item $dom->core_dump($filename[, $flags]) Trigger a core dump of the guest virtual machine, saving its memory image to C<$filename> so it can be analysed by tools such as C. The optional C<$flags> flags parameter is currently unused and if omitted will default to 0. =item $dom->destroy() Immediately poweroff the machine. This is equivalent to removing the power plug. The guest OS is given no time to cleanup / save state. For a clean poweroff sequence, use the C method instead. =item my $info = $dom->get_info() Returns a hash reference summarising the execution state of the domain. The elements of the hash are as follows: =over 4 =item maxMem The maximum memory allowed for this domain, in kilobytes =item memory The current memory allocated to the domain in kilobytes =item cpuTime The amount of CPU time used by the domain =item nrVirtCpu The current number of virtual CPUs enabled in the domain =item state The execution state of the machine, which will be one of the constants &Sys::Virt::Domain::STATE_*. =back =item my ($state, $reason) = $dom->get_state() Returns an array whose values specify the current state of the guest, and the reason for it being in that state. The C<$state> values are the same as for the C API, and the C<$reason> values come from: =over 4 =item Sys::Virt::Domain::STATE_CRASHED_UNKNOWN It is not known why the domain has crashed =item Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN It is not known why the domain has no state =item Sys::Virt::Domain::STATE_PAUSED_DUMP The guest is paused due to a core dump operation =item Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT The guest is paused due to a snapshot =item Sys::Virt::Domain::STATE_PAUSED_IOERROR The guest is paused due to an I/O error =item Sys::Virt::Domain::STATE_PAUSED_MIGRATION The guest is paused due to migration =item Sys::Virt::Domain::STATE_PAUSED_SAVE The guest is paused due to a save operation =item Sys::Virt::Domain::STATE_PAUSED_UNKNOWN It is not known why the domain has paused =item Sys::Virt::Domain::STATE_PAUSED_USER The guest is paused at admin request =item Sys::Virt::Domain::STATE_PAUSED_WATCHDOG The guest is paused due to the watchdog =item Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN The guest is paused while domain shutdown takes place =item Sys::Virt::Domain::STATE_PAUSED_SNAPSHOT The guest is paused while a snapshot takes place =item Sys::Virt::Domain::STATE_RUNNING_BOOTED The guest is running after being booted =item Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT The guest is running after restore from snapshot =item Sys::Virt::Domain::STATE_RUNNING_MIGRATED The guest is running after migration =item Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED The guest is running after migration abort =item Sys::Virt::Domain::STATE_RUNNING_RESTORED The guest is running after restore from file =item Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED The guest is running after save cancel =item Sys::Virt::Domain::STATE_RUNNING_UNKNOWN It is not known why the domain has started =item Sys::Virt::Domain::STATE_RUNNING_UNPAUSED The guest is running after a resume =item Sys::Virt::Domain::STATE_RUNNING_WAKEUP The guest is running after wakeup from power management suspend =item Sys::Virt::Domain::STATE_BLOCKED_UNKNOWN The guest is blocked for an unknown reason =item Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN It is not known why the domain has shutdown =item Sys::Virt::Domain::STATE_SHUTDOWN_USER The guest is shutdown due to admin request =item Sys::Virt::Domain::STATE_SHUTOFF_CRASHED The guest is shutoff after a crash =item Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED The guest is shutoff after being destroyed =item Sys::Virt::Domain::STATE_SHUTOFF_FAILED The guest is shutoff due to a virtualization failure =item Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT The guest is shutoff after a snapshot =item Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED The guest is shutoff after migration =item Sys::Virt::Domain::STATE_SHUTOFF_SAVED The guest is shutoff after a save =item Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN The guest is shutoff due to controlled shutdown =item Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN It is not known why the domain has shutoff =item Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN It is not known why the domain was suspended to RAM =item Sys::Virt::Domain::STATE_PMSUSPENDED_DISK_UNKNOWN It is not known why the domain was suspended to disk =back =item my $info = $dom->get_control_info($flags=0) Returns a hash reference providing information about the control channel. The returned keys in the hash are =over 4 =item C One of the CONTROL INFO constants listed later =item C
Currently unsed, always 0. =item C The elapsed time since the control channel entered the current state. =back =item my @errs = $dom->get_disk_errors($flags=0) Returns a list of all disk errors that have occurred on the backing store for the guest's virtual disks. The returned array elements are hash references, containing two keys =over 4 =item C The path of the disk with an error =item C The error type =back =item $dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0) Sends a sequence of keycodes to the guest domain. The C<$keycodeset> should be one of the constants listed later in the KEYCODE SET section. C<$holdtiem> is the duration, in milliseconds, to keep the key pressed before releasing it and sending the next keycode. C<@keycodes> is an array reference containing the list of keycodes to send to the guest. The elements in the array should be keycode values from the specified keycode set. C<$flags> is currently unused. =item my $info = $dom->get_block_info($dev, $flags=0) Returns a hash reference summarising the disk usage of the host backing store for a guest block device. The C<$dev> parameter should be the path to the backing store on the host. C<$flags> is currently unused and defaults to 0 if omitted. The returned hash contains the following elements =over 4 =item capacity Logical size in bytes of the block device backing image * =item allocation Highest allocated extent in bytes of the block device backing image =item physical Physical size in bytes of the container of the backing image =back =item $dom->set_max_memory($mem) Set the maximum memory for the domain to the value C<$mem>. The value of the C<$mem> parameter is specified in kilobytes. =item $mem = $dom->get_max_memory() Returns the current maximum memory allowed for this domain in kilobytes. =item $dom->set_memory($mem, $flags) Set the current memory for the domain to the value C<$mem>. The value of the C<$mem> parameter is specified in kilobytes. This must be less than, or equal to the domain's max memory limit. The C<$flags> parameter can control whether the update affects the live guest, or inactive config, defaulting to modifying the current state. =item $dom->shutdown() Request that the guest OS perform a graceful shutdown and poweroff. This usually requires some form of cooperation from the guest operating system, such as responding to an ACPI signal, or a guest agent process. For an immediate, forceful poweroff, use the C method instead. =item $dom->reboot([$flags]) Request that the guest OS perform a graceful shutdown and optionally restart. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $dom->reset([$flags]) Perform a hardware reset of the virtual machine. The guest OS is given no opportunity to shutdown gracefully. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $dom->get_max_vcpus() Return the maximum number of vcpus that are configured for the domain =item $dom->attach_device($xml[, $flags]) Hotplug a new device whose configuration is given by C<$xml>, to the running guest. The optional <$flags> parameter defaults to 0, but can accept one of the device hotplug flags described later. =item $dom->detach_device($xml[, $flags]) Hotunplug a existing device whose configuration is given by C<$xml>, from the running guest. The optional <$flags> parameter defaults to 0, but can accept one of the device hotplug flags described later. =item $dom->update_device($xml[, $flags]) Update the configuration of an existing device. The new configuration is given by C<$xml>. The optional <$flags> parameter defaults to 0 but can accept one of the device hotplug flags described later. =item $data = $dom->block_peek($path, $offset, $size[, $flags) Peek into the guest disk C<$path>, at byte C<$offset> capturing C<$size> bytes of data. The returned scalar may contain embedded NULLs. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $data = $dom->memory_peek($offset, $size[, $flags]) Peek into the guest memory at byte C<$offset> virtual address, capturing C<$size> bytes of memory. The return scalar may contain embedded NULLs. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $flag = $dom->get_autostart(); Return a true value if the guest domain is configured to automatically start upon boot. Return false, otherwise =item $dom->set_autostart($flag) Set the state of the autostart flag, which determines whether the guest will automatically start upon boot of the host OS =item $dom->set_vcpus($count, [$flags]) Set the number of virtual CPUs in the guest VM to C<$count>. The optional C<$flags> parameter can be used to control whether the setting changes the live config or inactive config. =item $count = $dom->get_vcpus([$flags]) Get the number of virtual CPUs in the guest VM. The optional C<$flags> parameter can be used to control whether to query the setting of the live config or inactive config. =item $type = $dom->get_scheduler_type() Return the scheduler type for the guest domain =item $stats = $dom->block_stats($path) Fetch the current I/O statistics for the block device given by C<$path>. The returned hash reference contains keys for =over 4 =item C Number of read requests =item C Number of bytes read =item C Number of write requests =item C Number of bytes written =item C Some kind of error count =back =item my $params = $dom->get_scheduler_parameters($flags=0) Return the set of scheduler tunable parameters for the guest, as a hash reference. The precise set of keys in the hash are specific to the hypervisor. =item $dom->set_scheduler_parameters($params, $flags=0) Update the set of scheduler tunable parameters. The value names for tunables vary, and can be discovered using the C call =item my $params = $dom->get_memory_parameters($flags=0) Return a hash reference containing the set of memory tunable parameters for the guest. The keys in the hash are one of the constants MEMORY PARAMETERS described later. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->set_memory_parameters($params, $flags=0) Update the memory tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the MEMORY PARAMETERS constants. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item my $params = $dom->get_blkio_parameters($flags=0) Return a hash reference containing the set of blkio tunable parameters for the guest. The keys in the hash are one of the constants BLKIO PARAMETERS described later. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->set_blkio_parameters($params, $flags=0) Update the blkio tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the BLKIO PARAMETERS constants. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $stats = $dom->get_block_iotune($disk, $flags=0) Return a hash reference containing the set of blkio tunable parameters for the guest disk C<$disk>. The keys in the hash are one of the constants BLOCK IOTUNE PARAMETERS described later. =item $dom->set_block_iotune($disk, $params, $flags=0); Update the blkio tunable parameters for the guest disk C<$disk>. The C<$params> should be a hash reference whose keys are one of the BLOCK IOTUNE PARAMETERS constants. =item my $params = $dom->get_interface_parameters($intf, $flags=0) Return a hash reference containing the set of interface tunable parameters for the guest. The keys in the hash are one of the constants INTERFACE PARAMETERS described later. =item $dom->set_interface_parameters($intf, $params, $flags=0) Update the interface tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the INTERFACE PARAMETERS constants. =item my $params = $dom->get_numa_parameters($flags=0) Return a hash reference containing the set of numa tunable parameters for the guest. The keys in the hash are one of the constants NUMA PARAMETERS described later. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->set_numa_parameters($params, $flags=0) Update the numa tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the NUMA PARAMETERS constants. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->block_resize($disk, $newsize, $flags=0) Resize the disk C<$disk> to have new size C<$newsize> KB. If the disk is backed by a special image format, the actual resize is done by the hypervisor. If the disk is backed by a raw file, or block device, the resize must be done prior to invoking this API call, and it merely updates the hypervisor's view of the disk size. The following flags may be used =over 4 =item Sys::Virt::Domain::BLOCK_RESIZE_BYTES Treat C<$newsize> as if it were in bytes, rather than KB. =back =item $dom->interface_stats($path) Fetch the current I/O statistics for the block device given by C<$path>. The returned hash containins keys for =over 4 =item C Total bytes received =item C Total packets received =item C Total packets received with errors =item C Total packets drop at reception =item C Total bytes transmitted =item C Total packets transmitted =item C Total packets transmitted with errors =item C Total packets dropped at transmission. =back =item $dom->memory_stats($flags=0) Fetch the current memory statistics for the guest domain. The C<$flags> parameter is currently unused and can be omitted. The returned hash containins keys for =over 4 =item C Data read from swap space =item C Data written to swap space =item C Page fault involving disk I/O =item C Page fault not involving disk I/O =item C Memory not used by the system =item C Total memory seen by guest =back =item $info = $dom->get_security_label() Fetch information about the security label assigned to the guest domain. The returned hash reference has two keys, C gives the name of the security model in effect (eg C), while C