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
- $pool->is_active()
- Returns a true value if the storage pool is currently
running
- $pool->is_persistent()
- Returns a true value if the storage pool has a persistent
configuration file defined
- 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([$flags]);
- Refresh the storage pool state. Typically this will rescan
the list of storage volumes. The $flags parameter is currently unused and
if omitted defaults to zero.
- $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 and
if omitted defaults to zero.
- $pool->delete([$flags]);
- Delete the storage pool. The $flags parameter allows the
data to be optionally wiped during delete and if omitted defaults to
zero.
- $info = $pool->get_info()
- Retrieve information about the current storage pool state.
The returned hash reference 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.
- Sys::Virt::StoragePool::STATE_INACCESSIBLE
- The storage pool is not currently accessible
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
- Sys::Virt::StoragePool::BUILD_NO_OVERWRITE
- Do not overwrite existing storage pool data
- Sys::Virt::StoragePool::BUILD_OVERWRITE
- Overwrite existing storage pool data
AUTHORS¶
Daniel P. Berrange <berrange@redhat.com>
COPYRIGHT¶
Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 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"