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($flags=0)

Returns a string representing the hostname of the guest. $flags can be zero or more of

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 "undef". 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->create_with_files($fds, $flags)

Start a domain whose configuration was previously defined using the "define_domain" method in Sys::Virt. The $fds parameter is an array of UNIX file descriptors which will be passed to the init process of the container. This is only supported with container based virtualization.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, $dxml=undef, $params=undef, $flags=0)

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. The optional $dxml parameter can be used to alter portions of the domain XML that will be used when performing restore. The $params parameter is a hash reference whose keys is a subset of the SAVE / RESTORE PARAMETER CONSTANTS. The $flags parameter accepts one of the SAVE / RESTORE FLAG CONSTANTS described later and defaults to zero.

$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->managed_save_define_xml($xml, $flags=0)

Update the XML of the managed save image to $xml. The $flags parameter is unused and defaults to zero.

$xml = $dom->managed_save_get_xml_description($flags=0)

Get the XML in the managed save image. The $flags parameter accepts the following constants

$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->core_dump_format($filename, $format, [, $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 $format parameter is one of the core dump format constants. 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 $time = $dom->get_time($flags=0);

Get the current time of the guest, in seconds and nanoseconds. The $flags parameter is currently unused and defaults to zero. The return value is an array ref with two elements, the first contains the time in seconds, the second contains the remaining nanoseconds.

$dom->set_time($secs, $nsecs, $flags=0);

Set the current time of the guest, in seconds and nanoseconds. The $flags parameter accepts one of

$dom->set_user_password($username, $password, $flags=0);

Update the password for account $username to be $password. $password is the clear-text password string unless the PASSWORD_ENCRYPTED flag is set.

$dom->rename($newname, $flags=0)

Change the name of an inactive guest to be $newname. The $flags parameter is currently unused and defaults to zero.

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->set_memory_stats_period($period, $flags)

Set the period on which guests memory stats are refreshed, with $period being a value in seconds. The $flags parameter is currently unused.

$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 an 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->detach_device_alias($alias[, $flags])

Hotunplug an existing device which is identified by $alias. 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.

$dom->set_vcpu($cpumap, $state, [$flags])

Set the state of the CPUs in $cpumap to $state. The $flags parameter defaults to zero if not present.

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

$dom->set_guest_vcpus($cpumap, $state, [$flags=0])

Set the online status of the guest OS CPUs. The $cpumap parameter describes the set of CPUs to modify (eg "0-3,^1"). $state is either 1 to set the CPUs online, or 0 to set them offline. The $flags parameter is currently unused and defaults to 0.

$info $dom->get_guest_vcpus([$flags=0])

Query information about the guest OS CPUs. The returned data is a hash reference with the following keys.

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

my $params = $dom->get_perf_events($flags=0)

Return a hash reference containing the set of performance events that are available for the guest. The keys in the hash are one of the constants PERF EVENTS described later. The $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

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

Update the enabled state for performance events for the guest. The $params should be a hash reference whose keys are one of the PERF EVENTS 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, \%params, flags=0)

Migrate a domain to an alternative host. The "destcon" parameter should be a "Sys::Virt" connection to the remote target host. The "flags" parameter takes one or more of the "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this document. The %params parameter is a hash reference used to set various parameters for the migration operation, with the following valid keys.

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

Migrate a domain to an alternative host. Use of positional parameters with "migrate" is deprecated in favour of passing a hash reference as described above.

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

Migrate a domain to an alternative host. This method is deprecated in favour of passing a hash ref to "migrate".

$ddom = $dom->migrate_to_uri(desturi, \%params, flags=0)

Migrate a domain to an alternative host. The "desturi" parameter should be a valid libvirt connection URI for the remote target host. The "flags" parameter takes one or more of the "Sys::Virt::Domain::MIGRATE_XXX" constants described later in this document. The %params parameter is a hash reference used to set various parameters for the migration operation, with the same keys described for the "migrate" API.

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

Migrate a domain to an alternative host. Use of positional parameters with "migrate_to_uri" is deprecated in favour of passing a hash reference as described above.

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

Migrate a domain to an alternative host. This method is deprecated in favour of passing a hash ref to "migrate_to_uri".

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

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.

$downtime = $dom->migrate_get_max_downtime($flags=0) Get the current value of the maximum downtime allowed during a migration of a guest. The returned <downtime> value is measured in milliseconds. The $flags parameter is currently unused and defaults to zero.

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

Set the maximum allowed bandwidth during migration of the guest. The "bandwidth" parameter is measured in MB/second. The $flags parameter takes zero or more of the constants:

$bandwidth = $dom->migrate_get_max_speed($flags=0)

Get the maximum allowed bandwidth during migration fo the guest. The returned <bandwidth> value is measured in MB/second. The $flags parameter is accepts the same constants as "migrate_set_max_speed".

$dom->migrate_set_compression_cache($cacheSize, $flags=0)

Set the maximum allowed compression cache size during migration of the guest. The "cacheSize" parameter is measured in bytes. The $flags parameter is currently unused and defaults to zero.

$cacheSize = $dom->migrate_get_compression_cache($flags=0)

Get the maximum allowed compression cache size during migration of the guest. The returned <bandwidth> value is measured in bytes. The $flags parameter is currently unused and defaults to zero.

$dom->migrate_start_post_copy($flags=0)

Switch the domain from pre-copy to post-copy mode. This requires that the original migrate command had the "Sys::Virt::Domain::MIGRATE_POST_COPY" flag specified.

$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_channel($st, $devname, $flags)

Open the text console for a data channel device identified by $devname, connecting it to the stream $st. $st must be a "Sys::Virt::Stream" object used for bi-directional communication with the channel. $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.

$fd = $dom->open_graphics_fd($idx, $flags)

Open the graphics console for a guest, identified by $idx, counting from 0. The $flags argument should be one of the constants listed at the end of this document, and defaults to 0. The return value will be a file descriptor connected to the console which must be closed when no longer needed. This method is preferred over "open_graphics" since it will work correctly under sVirt mandatory access control policies.

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

@iothreadinfo = $dom->get_iothread_info($flags=0)

Obtain information about the state of all IOThreads in a running guest domain. The returned list will have one element for each IOThread, where each elements contains a hash reference. The keys in the hash are, "number" the IOThread number and "affinity" giving the allowed schedular 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.

$dom->pin_iothread($iothread, $mask)

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

$dom->add_iothread($iothread, $flags=0)

Add a new IOThread by the $iothread value to the guest domain. The $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

$dom->del_iothread($iothread, $flags=0)

Delete an existing IOThread by the $iothread value from the guest domain. The $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

$dom->set_iothread($iothread, $params, $flags=0)

Set parameters for the IOThread by the $iothread value on the guest domain. The $params parameter is a hash reference whose keys are the "IOTHREAD STATS" constants documented later. The $flags parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted.

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

Requests the guests host physical CPU usage statistics, starting from host CPU <$startCpu> counting up to $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:

my ($type, $stats) = $dom->get_job_stats($flags=0)

Returns an array summarising the execution state of the background job. The $type value is one of the JOB TYPE constants listed later in this document. The $stats value is a hash reference, whose elements are one of the following constants.

$dom->abort_job($flags=0)

Aborts the currently executing job. Valid $flags include:

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. Valid $flags include:

$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. The $flags parameter can take the bitwise union of the values:

$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, $bandwidth, $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. The $flags parameter can take the bitwise union of the values:

$dom->block_rebase($path, $base, $bandwidth, $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. The $flags parameter can take the bitwise union of the values:

$dom->block_copy($path, $destxml, $params, $flags=0)

Copy contents of a disk image <$path> into the target volume described by $destxml which follows the schema of the <disk> element in the domain XML. The $params parameter is a hash of optional parameters to control the process

$dom->block_commit($path, $base, $top, $bandwidth, $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. The $flags parameter can take the bitwise union of the values:

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

my @checkpoints = $dom->list_all_checkpoints($flags)

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

my $checkpoint = $dom->get_checkpoint_by_name($name)

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

$checkpoint = $dom->create_checkpoint($xml[, $flags])

Create a new checkpoint from the $xml. The $flags parameter accepts the CHECKPOINT CREATION constants listed in "Sys::Virt::DomainCheckpoints".

$dom->backup_begin($backupxml, $checkpointxml=undef, $flags=0);

Start a point-in-time backup job for the specified disks of a running domain. The $backupxml parameter describes the backup operation, including which disks to use. The optional $checkpointxml parameter can be used to create a checkpoint covering to the same point in time as the backup. The optional $flags parameter can be one of the following constants:

$xml = $dom->backup_get_xml_description($flags=0);

Get the XML description of the currently executing backup job. If there is no backup job then an error is raised.

$dom->fs_trim($mountPoint, $minimum, $flags=0);

Issue an FS_TRIM command to the device at $mountPoint to remove chunks of unused space that are at least $minimum bytes in length. $flags is currently unused and defaults to zero.

$dom->fs_freeze(\@mountPoints, $flags=0);

Freeze all the filesystems associated with the @mountPoints array reference. If <@mountPoints> is an empty list, then all filesystems will be frozen. $flags is currently unused and defaults to zero.

$dom->fs_thaw(\@mountPoints, $flags=0);

Thaw all the filesystems associated with the @mountPoints array reference. If <@mountPoints> is an empty list, then all filesystems will be thawed. $flags is currently unused and defaults to zero.

@fslist = $dom->get_fs_info($flags=0);

Obtain a list of all guest filesystems. The returned list will contain one element for each filesystem, whose value will be a hash reference with the following keys

@nics = $dom->get_interface_addresses($src, $flags=0);

Obtain a list of all guest network interfaces. The $src parameter is one of the constants

$dom->send_process_signal($pid, $signum, $flags=0);

Send the process $pid the signal $signum. The $signum value must be one of the constants listed later, not a POSIX or Linux signal value. $flags is currently unused and defaults to zero.

$dom->set_block_threshold($dev, $threshold, $flags=0);

Set the threshold level for delivering the EVENT_ID_BLOCK_THRESHOLD if the device or backing chain element described by $dev is written beyond the set $threshold level. The threshold level is unset once the event fires. The event might not be delivered at all if libvirtd was not running at the moment when the threshold was reached.

$dom->set_lifecycle_action($type, $action, $flags=0)

Changes the actions of lifecycle events for domain represented as <on_$type>$action</on_$type> in the domain XML.

$info = $dom->get_launch_security_info($flags=0)

Get information about the domain launch security policy. $flags is currently unused and defaults to zero. The returned hash may contain the following keys

$dom->set_launch_security_state(\%params, $flags=0)

Set information about the domain launch security state. $flags is currently unused and defaults to zero. The provided hash may contain the following keys

$info = $dom->get_guest_info($types, $flags=0)

Get information about the domain guest configuration. The $types parameter determines what pieces of information are returned and should be the bitwise or of the following constants:

$dom->set_agent_response_timeout($timeout, $flags=0)

Set the amount of time to wait for the agent to respond to a command. $timeout is a positive integer representing the number of seconds to wait, or one of the constants:

my @keys = $dom->authorized_ssh_keys_get($user, $flags=0)

Retrieve the list of authorized SSH keys for the user account $user. The $flags parameter is currently unused and defaults to zero.

$dom->authorized_ssh_keys_set($user, \@keys, $flags=0)

Update the list of authorized SSH keys for the user account $user. The @keys parameter should be an array reference containing the new keys, if any. The default behaviour is to set the authorized SSH keys to the exact set specified in @keys. This can be modified via the $flags parameter which takes the following constants

my @msgs = $dom->get_messages($flags=0)

Retrieve a list of messages associated with the domain. The optional $flags parameter can accept zero or more of

$dom->start_dirty_rate_calc($dom, $secs, $flags=0)

Request calculation of the domain's memory dirty rate over the next $secs seconds. $flags accepts one or more of

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"