NAME¶

Sys::Virt::Domain - Represent & manage a libvirt guest domain

DESCRIPTION¶

The "Sys::Virt::Domain" module represents a guest domain managed by the virtual machine monitor.

METHODS¶

my $id = $dom->get_id()

Returns an integer with a locally unique identifier for the domain.

my $uuid = $dom->get_uuid()

Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the domain.

my $uuid = $dom->get_uuid_string()

Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'.

my $name = $dom->get_name()

Returns a string with a locally unique name of the domain

my $hostname = $dom->get_hostname()

Returns a string representing the hostname of the guest

my $str = $dom->get_metadata($type, $uri, $flags =0)

Returns the metadata element of type $type associated with the domain. If $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the $uri parameter specifies the XML namespace to retrieve, otherwise $uri should be "undef". The optional $flags parameter defaults to zero.

$dom->set_metadata($type, $val, $key, $uri, $flags=0)

Sets the metadata element of type $type to hold the value $val. If $type is "Sys::Virt::Domain::METADATA_ELEMENT" then the $key and $uri elements specify an XML namespace to use, otherwise they should both be "nudef". The optional $flags parameter defaults to zero.

$dom->is_active()

Returns a true value if the domain is currently running

$dom->is_persistent()

Returns a true value if the domain has a persistent configuration file defined

$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.

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.

my $type = $dom->get_os_type()

Returns a string containing the name of the OS type running within the domain.

$dom->create($flags)

Start a domain whose configuration was previously defined using the "define_domain" method in Sys::Virt. The $flags parameter accepts one of the DOMAIN CREATION constants documented later, and defaults to 0 if omitted.

$dom->undefine()

Remove the configuration associated with a domain previously defined with the "define_domain" method in Sys::Virt. If the domain is running, you probably want to use the "shutdown" or "destroy" methods instead.

$dom->suspend()

Temporarily stop execution of the domain, allowing later continuation by calling the "resume" method.

$dom->resume()

Resume execution of a domain previously halted with the "suspend" method.

$dom->pm_wakeup()

Wakeup the guest from power management suspend state

$dom->pm_suspend_for_duration($target, $duration, $flags=0)

Tells the guest OS to enter the power management suspend state identified by $target. The $target parameter should be one of the NODE SUSPEND CONTANTS listed in "Sys::Virt". The $duration specifies when the guest should automatically wakeup. The $flags parameter is optional and defaults to zero.

$dom->save($filename)

Take a snapshot of the domain's state and save the information to the file named in the $filename parameter. The domain can later be restored from this file with the "restore_domain" method on the Sys::Virt object.

$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 $flags parameter is unused and defaults to zero.

$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 $flags parameter is unused and defaults to zero.

$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 $flags parameter is unused and defaults to zero.

$dom->core_dump($filename[, $flags])

Trigger a core dump of the guest virtual machine, saving its memory image to $filename so it can be analysed by tools such as "crash". The optional $flags flags parameter is currently unused and if omitted will default to 0.

$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 "shutdown" method instead.

my $info = $dom->get_info()

Returns a hash reference summarising the execution state of the domain. The elements of the hash are as follows:

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 $state values are the same as for the "get_info" API, and the $reason values come from:

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

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

$dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0)

Sends a sequence of keycodes to the guest domain. The $keycodeset should be one of the constants listed later in the KEYCODE SET section. $holdtiem is the duration, in milliseconds, to keep the key pressed before releasing it and sending the next keycode. @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. $flags is currently unused.

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 $dev parameter should be the path to the backing store on the host. $flags is currently unused and defaults to 0 if omitted. The returned hash contains the following elements

$dom->set_max_memory($mem)

Set the maximum memory for the domain to the value $mem. The value of the $mem parameter is specified in kilobytes.

$mem = $dom->get_max_memory()

Returns the current maximum memory allowed for this domain in kilobytes.

$dom->set_memory($mem, $flags)

Set the current memory for the domain to the value $mem. The value of the $mem parameter is specified in kilobytes. This must be less than, or equal to the domain's max memory limit. The $flags parameter can control whether the update affects the live guest, or inactive config, defaulting to modifying the current state.

$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 "destroy" method instead.

$dom->reboot([$flags])

Request that the guest OS perform a graceful shutdown and optionally restart. The optional $flags parameter is currently unused and if omitted defaults to zero.

$dom->reset([$flags])

Perform a hardware reset of the virtual machine. The guest OS is given no opportunity to shutdown gracefully. The optional $flags parameter is currently unused and if omitted defaults to zero.

$dom->get_max_vcpus()

Return the maximum number of vcpus that are configured for the domain

$dom->attach_device($xml[, $flags])

Hotplug a new device whose configuration is given by $xml, to the running guest. The optional <$flags> parameter defaults to 0, but can accept one of the device hotplug flags described later.

$dom->detach_device($xml[, $flags])

Hotunplug a existing device whose configuration is given by $xml, from the running guest. The optional <$flags> parameter defaults to 0, but can accept one of the device hotplug flags described later.

$dom->update_device($xml[, $flags])

Update the configuration of an existing device. The new configuration is given by $xml. The optional <$flags> parameter defaults to 0 but can accept one of the device hotplug flags described later.

$data = $dom->block_peek($path, $offset, $size[, $flags)

Peek into the guest disk $path, at byte $offset capturing $size bytes of data. The returned scalar may contain embedded NULLs. The optional $flags parameter is currently unused and if omitted defaults to zero.

$data = $dom->memory_peek($offset, $size[, $flags])

Peek into the guest memory at byte $offset virtual address, capturing $size bytes of memory. The return scalar may contain embedded NULLs. The optional $flags parameter is currently unused and if omitted defaults to zero.

$flag = $dom->get_autostart();

Return a true value if the guest domain is configured to automatically start upon boot. Return false, otherwise

$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

$dom->set_vcpus($count, [$flags])

Set the number of virtual CPUs in the guest VM to $count. The optional $flags parameter can be used to control whether the setting changes the live config or inactive config.

$count = $dom->get_vcpus([$flags])

Get the number of virtual CPUs in the guest VM. The optional $flags parameter can be used to control whether to query the setting of the live config or inactive config.

$type = $dom->get_scheduler_type()

Return the scheduler type for the guest domain

$stats = $dom->block_stats($path)

Fetch the current I/O statistics for the block device given by $path. The returned hash reference contains keys for

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.

$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 "get_scheduler_params" call

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 $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

$dom->set_memory_parameters($params, $flags=0)

Update the memory tunable parameters for the guest. The $params should be a hash reference whose keys are one of the MEMORY PARAMETERS constants. The $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

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 $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

$dom->set_blkio_parameters($params, $flags=0)

Update the blkio tunable parameters for the guest. The $params should be a hash reference whose keys are one of the BLKIO PARAMETERS constants. The $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

$stats = $dom->get_block_iotune($disk, $flags=0)

Return a hash reference containing the set of blkio tunable parameters for the guest disk $disk. The keys in the hash are one of the constants BLOCK IOTUNE PARAMETERS described later.

$dom->set_block_iotune($disk, $params, $flags=0);

Update the blkio tunable parameters for the guest disk $disk. The $params should be a hash reference whose keys are one of the BLOCK IOTUNE PARAMETERS constants.

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.

$dom->set_interface_parameters($intf, $params, $flags=0)

Update the interface tunable parameters for the guest. The $params should be a hash reference whose keys are one of the INTERFACE PARAMETERS constants.

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 $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

$dom->set_numa_parameters($params, $flags=0)

Update the numa tunable parameters for the guest. The $params should be a hash reference whose keys are one of the NUMA PARAMETERS constants. The $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

$dom->block_resize($disk, $newsize, $flags=0)

Resize the disk $disk to have new size $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

$dom->interface_stats($path)

Fetch the current I/O statistics for the block device given by $path. The returned hash containins keys for

$dom->memory_stats($flags=0)

Fetch the current memory statistics for the guest domain. The $flags parameter is currently unused and can be omitted. The returned hash containins keys for

$info = $dom->get_security_label()

Fetch information about the security label assigned to the guest domain. The returned hash reference has two keys, "model" gives the name of the security model in effect (eg "selinux"), while "label" provides the name of the security label applied to the domain. This method only returns information about the first security label. To retrieve all labels, use "get_security_label_list".

@info = $dom->get_security_label_list()

Fetches information about all security labels assigned to the guest domain. The elements in the returned array are all hash references, whose keys are as described for "get_security_label".

$ddom = $dom->migrate(destcon, flags, dname, uri, bandwidth)

Migrate a domain to an alternative host. The "destcon" parameter should be a "Sys::Virt" connection to the remote target host. If the "flags" parameter is zero offline migration will be performed. The "Sys::Virt::Domain::MIGRATE_LIVE" constant can be used to request live migration. The "dname" parameter allows the guest to be renamed on the target host, if set to "undef", the domains' current name will be maintained. In normal circumstances, the source host determines the target hostname from the URI associated with the "destcon" connection. If the destination host is multi-homed it may be necessary to supply an alternate destination hostame via the "uri" parameter. The "bandwidth" parameter allows network usage to be throttled during migration. If set to zero, no throttling will be performed. The "flags", "dname", "uri" and "bandwidth" parameters are all optional, and if omitted default to zero, "undef", "undef", and zero respectively.

$ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)

Migrate a domain to an alternative host. This function works in the same way as "migrate", except is also allows "dxml" to specify a changed XML configuration for the guest on the target host.

$dom->migrate_to_uri(desturi, flags, dname, bandwidth)

Migrate a domain to an alternative host. The "destri" parameter should be a valid libvirt connection URI for the remote target host. If the "flags" parameter is zero offline migration will be performed. The "Sys::Virt::Domain::MIGRATE_LIVE" constant can be used to request live migration. The "dname" parameter allows the guest to be renamed on the target host, if set to "undef", the domains' current name will be maintained. In normal circumstances, the source host determines the target hostname from the URI associated with the "destcon" connection. If the destination host is multi-homed it may be necessary to supply an alternate destination hostame via the "uri" parameter. The "bandwidth" parameter allows network usage to be throttled during migration. If set to zero, no throttling will be performed. The "flags", "dname" and "bandwidth" parameters are all optional, and if omitted default to zero, "undef", "undef", and zero respectively.

$dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)

Migrate a domain to an alternative host. This function works in almost the same way as "migrate_to_uri", except is also allows "dxml" to specify a changed XML configuration for the guest on the target host. The "dconnuri" must always specify the URI of the remote libvirtd daemon, or be "undef". The "miguri" parameter can be used to specify the URI for initiating the migration operation, or be "undef".

$dom->migrate_set_max_downtime($downtime, $flags)

Set the maximum allowed downtime during migration of the guest. A longer downtime makes it more likely that migration will complete, at the cost of longer time blackout for the guest OS at the switch over point. The "downtime" parameter is measured in milliseconds. The $flags parameter is currently unused and defaults to zero.

$dom->migrate_set_max_speed($bandwidth, $flags)

Set the maximum allowed bandwidth during migration of the guest. The "bandwidth" parameter is measured in MB/second. The $flags parameter is currently unused and defaults to zero.

$bandwidth = $dom->migrate_get_max_speed($flag)

Get the maximum allowed bandwidth during migration fo the guest. The returned <bandwidth> value is measured in MB/second. The $flags parameter is currently unused and defaults to zero.

$dom->inject_nmi($flags)

Trigger an NMI in the guest virtual machine. The $flags parameter is currently unused and defaults to 0.

$dom->open_console($st, $devname, $flags)

Open the text console for a serial, parallel or paravirt console device identified by $devname, connecting it to the stream $st. If $devname is undefined, the default console will be opened. $st must be a "Sys::Virt::Stream" object used for bi-directional communication with the console. $flags is currently unused, defaulting to 0.

$dom->open_graphics($idx, $fd, $flags)

Open the graphics console for a guest, identified by $idx, counting from 0. The $fd should be a file descriptor for an anoymous socket pair. The $flags argument should be one of the constants listed at the end of this document, and defaults to 0.

my $mimetype = $dom->screenshot($st, $screen, $flags)

Capture a screenshot of the virtual machine's monitor. The $screen parameter controls which monitor is captured when using a multi-head or multi-card configuration. $st must be a "Sys::Virt::Stream" object from which the data can be read. $flags is currently unused and defaults to 0. The mimetype of the screenshot is returned

@vcpuinfo = $dom->get_vcpu_info($flags=0)

Obtain information about the state of all virtual CPUs in a running guest domain. The returned list will have one element for each vCPU, where each elements contains a hash reference. The keys in the hash are, "number" the vCPU number, "cpu" the physical CPU on which the vCPU is currently scheduled, "cpuTime" the cummulative execution time of the vCPU, "state" the running state and "affinity" giving the allowed shedular placement. The value for "affinity" is a string representing a bitmask against physical CPUs, 8 cpus per character. To extract the bits use the "unpack" function with the "b*" template. NB The "state", "cpuTime", "cpu" values are only available if using $flags value of 0, and the domain is currently running; otherwise they will all be set to zero.

$dom->pin_vcpu($vcpu, $mask)

Pin the virtual CPU given by index $vcpu to physical CPUs given by $mask. The $mask is a string representing a bitmask against physical CPUs, 8 cpus per character.

$mask = $dom->get_emulator_pin_info()

Obtain information about the CPU affinity of the emulator process. The returned $mask is a bitstring against physical CPUs, 8 cpus per character. To extract the bits use the "unpack" function with the "b*" template.

$dom->pin_emulator($newmask, $flags=0)

Pin the emulator threads to the physical CPUs identified by the affinity in $newmask. The $newmask is a bitstring against the physical CPUa, 8 cpus per character. To create a suitable bitstring, use the "vec" function with a value of 1 for the "BITS" parameter.

my @stats = $dom->get_cpu_stats($startCpu, $numCpus, $flags=0)

Requests the guests host physical CPU usage statistics, starting from host CPU <$startCpu> counting upto $numCpus. If $startCpu is -1 and $numCpus is 1, then the utilization across all CPUs is returned. Returns an array of hash references, each element containing stats for one CPU.

my $info = $dom->get_job_info()

Returns a hash reference summarising the execution state of the background job. The elements of the hash are as follows:

$dom->abort_job()

Aborts the currently executing job

my $info = $dom->get_block_job_info($path, $flags=0)

Returns a hash reference summarising the execution state of the block job. The $path parameter should be the fully qualified path of the block device being changed.

$dom->set_block_job_speed($path, $bandwidth, $flags=0)

Change the maximum I/O bandwidth used by the block job that is currently executing for $path. The $bandwidth argument is specified in MB/s

$dom->abort_block_job($path, $flags=0)

Abort the current job that is executing for the block device associated with $path

$dom->block_pull($path, $bandwith, $flags=0)

Merge the backing files associated with $path into the top level file. The $bandwidth parameter specifies the maximum I/O rate to allow in MB/s.

$dom->block_rebase($path, $base, $bandwith, $flags=0)

Switch the backing path associated with $path to instead use $base. The $bandwidth parameter specifies the maximum I/O rate to allow in MB/s.

$dom->block_commit($path, $base, $top, $bandwith, $flags=0)

Commit changes there were made to the temporary top level file $top. Takes all the differences between $top and $base and merge them into $base. The $bandwidth parameter specifies the maximum I/O rate to allow in MB/s.

$count = $dom->num_of_snapshots()

Return the number of saved snapshots of the domain

@names = $dom->list_snapshot_names()

List the names of all saved snapshots. The names can be used with the "lookup_snapshot_by_name"

@snapshots = $dom->list_snapshots()

Return a list of all snapshots currently known to the domain. The elements in the returned list are instances of the Sys::Virt::DomainSnapshot class. This method requires O(n) RPC calls, so the "list_all_snapshots" method is recommended as a more efficient alternative.

my @snapshots = $dom->list_all_snapshots($flags)

Return a list of all domain snapshots associated with this domain. The elements in the returned list are instances of the Sys::Virt::DomainSnapshot class. The $flags parameter can be used to filter the list of return domain snapshots.

my $snapshot = $dom->get_snapshot_by_name($name)

Return the domain snapshot with a name of $name. The returned object is an instance of the Sys::Virt::DomainSnapshot class.

$dom->has_current_snapshot()

Returns a true value if the domain has a currently active snapshot

$snapshot = $dom->current_snapshot()

Returns the currently active snapshot for the domain.

$snapshot = $dom->create_snapshot($xml[, $flags])

Create a new snapshot from the $xml. The $flags parameter accepts the SNAPSHOT CREATION constants listed in "Sys::Virt::DomainSnapshots".

CONSTANTS¶

A number of the APIs take a "flags" parameter. In most cases passing a value of zero will be satisfactory. Some APIs, however, accept named constants to alter their behaviour. This section documents the current known constants.

AUTHORS¶

Daniel P. Berrange <berrange@redhat.com>

COPYRIGHT¶

Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange

LICENSE¶

This program is free software; you can redistribute it and/or modify it under the terms of either the GNU General Public License as published by the Free Software Foundation (either version 2 of the License, or at your option any later version), or, the Artistic License, as specified in the Perl README file.

SEE ALSO¶

Sys::Virt, Sys::Virt::Error, "http://libvirt.org"