NAME

Sys::Virt::StoragePool - Represent & manage a libvirt storage pool

DESCRIPTION

The Sys::Virt::StoragePool module represents a storage pool managed by libvirt. There are a variety of storage pool implementations for LVM, Local directories/filesystems, network filesystems, disk partitioning, iSCSI, and SCSI.

METHODS

my $uuid = $pool->get_uuid()

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

my $uuid = $pool->get_uuid_string()

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

my $name = $pool->get_name()

Returns a string with a locally unique name of the storage pool

my $xml = $pool->get_xml_description()

Returns an XML document containing a complete description of the storage pool's configuration

$pool->create()

Start a storage pool whose configuration was previously defined using the define_storage_pool method in Sys::Virt.

$pool->undefine()

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

$pool->destroy()

Immediately terminate the machine, and remove it from the virtual machine monitor. The $pool handle is invalid after this call completes and should not be used again.

$flag = $pool->get_autostart();

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

$pool->set_autostart($flag)

Set the state of the autostart flag, which determines whether the storage pool will automatically start upon boot of the host OS

$pool->refresh();

Refresh the storage pool state. Typically this will rescan the list of storage volumes.

$pool->build($flags);

Construct the storage pool if it does not exist. As an example, for a disk based storage pool this would ensure a partition table exists. The $flags parameter allows control over the build operation

$pool->delete($flags);

Delete the storage pool. The $flags parameter allows the data to be optionally wiped during delete.

%info = $pool->get_info()

Retrieve information about the current storage pool state. The returned hash has the following keys

state: The current status of the storage pool. See constants later.
capacity: The total logical size of the storage pool
allocation: The current physical allocation of the storage pool
available: The available space for creation of new volumes. This may be less than the difference between capacity & allocation if there are sizing / metadata constraints for volumes

my $nnames = $pool->num_of_storage_volumes()

Return the number of running volumes in this storage pool. The value can be used as the maxnames parameter to list_storage_vol_names.

my @volNames = $pool->list_storage_vol_names($maxnames)

Return a list of all volume names in this storage pool. The names can be used with the get_volume_by_name method.

my @nets = $pool->list_volumes()

Return a list of all volumes in the storage pool. The elements in the returned list are instances of the Sys::Virt::StorageVol class.

my $vol = $pool->get_volume_by_name($name)

Return the volume with a name of $name. The returned object is an instance of the Sys::Virt::StorageVol class.

my $vol = $pool->create_volume($xml)

Create a new volume based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::StorageVol class. If the optional clonevol is provided, data will be copied from that source volume

my $vol = $pool->clone_volume($xml, $clonevol);

Create a new volume based on the XML description passed into the $xml parameter. The returned object is an instance of the Sys::Virt::StorageVol class. The new volume will be populated with data from the specified clone source volume.

CONSTANTS

The following sets of constants may be useful in dealing with some of the methods in this package

POOL STATES

The following constants are useful for interpreting the state key value in the hash returned by get_info

Sys::Virt::StoragePool::STATE_INACTIVE: The storage pool is not currently active
Sys::Virt::StoragePool::STATE_BUILDING: The storage pool is still being constructed and is not ready for use yet.
Sys::Virt::StoragePool::STATE_RUNNING: The storage pool is running and can be queried for volumes
Sys::Virt::StoragePool::STATE_DEGRADED: The storage pool is running, but its operation is degraded due to a failure.

DELETION MODES

Sys::Virt::StoragePool::DELETE_NORMAL: Delete the pool without any attempt to scrub data
Sys::Virt::StoragePool::DELETE_ZEROED: Fill the allocated storage with zeros when deleting

BUILD MODES

Sys::Virt::StoragePool::BUILD_NEW: Construct a new storage pool from constituent bits
Sys::Virt::StoragePool::BUILD_RESIZE: Resize an existing built storage pool preserving data where appropriate
Sys::Virt::StoragePool::BUILD_REPAIR: Repair an existing storage pool operating in degraded mode

AUTHORS

Daniel P. Berrange <berrange@redhat.com>

COPYRIGHT

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.

CPAN RT