.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sys::Virt::StoragePool 3pm"
.TH Sys::Virt::StoragePool 3pm 2024-01-21 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sys::Virt::StoragePool \- Represent & manage a libvirt storage pool
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Sys::Virt::StoragePool\*(C'\fR 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.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "my $uuid = $pool\->\fBget_uuid()\fR" 4
.el .IP "my \f(CW$uuid\fR = \f(CW$pool\fR\->\fBget_uuid()\fR" 4
.IX Item "my $uuid = $pool->get_uuid()"
Returns a 16 byte long string containing the raw globally unique identifier
(UUID) for the storage pool.
.ie n .IP "my $uuid = $pool\->\fBget_uuid_string()\fR" 4
.el .IP "my \f(CW$uuid\fR = \f(CW$pool\fR\->\fBget_uuid_string()\fR" 4
.IX Item "my $uuid = $pool->get_uuid_string()"
Returns a printable string representation of the raw UUID, in the format
\&'XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX'.
.ie n .IP "my $name = $pool\->\fBget_name()\fR" 4
.el .IP "my \f(CW$name\fR = \f(CW$pool\fR\->\fBget_name()\fR" 4
.IX Item "my $name = $pool->get_name()"
Returns a string with a locally unique name of the storage pool
.ie n .IP $pool\->\fBis_active()\fR 4
.el .IP \f(CW$pool\fR\->\fBis_active()\fR 4
.IX Item "$pool->is_active()"
Returns a true value if the storage pool is currently running
.ie n .IP $pool\->\fBis_persistent()\fR 4
.el .IP \f(CW$pool\fR\->\fBis_persistent()\fR 4
.IX Item "$pool->is_persistent()"
Returns a true value if the storage pool has a persistent configuration
file defined
.ie n .IP "my $xml = $pool\->\fBget_xml_description()\fR" 4
.el .IP "my \f(CW$xml\fR = \f(CW$pool\fR\->\fBget_xml_description()\fR" 4
.IX Item "my $xml = $pool->get_xml_description()"
Returns an XML document containing a complete description of
the storage pool's configuration
.ie n .IP $pool\->\fBcreate()\fR 4
.el .IP \f(CW$pool\fR\->\fBcreate()\fR 4
.IX Item "$pool->create()"
Start a storage pool whose configuration was previously defined using the
\&\f(CW\*(C`define_storage_pool\*(C'\fR method in Sys::Virt.
.ie n .IP $pool\->\fBundefine()\fR 4
.el .IP \f(CW$pool\fR\->\fBundefine()\fR 4
.IX Item "$pool->undefine()"
Remove the configuration associated with a storage pool previously defined
with the \f(CW\*(C`define_storage pool\*(C'\fR method in Sys::Virt. If the storage pool is
running, you probably want to use the \f(CW\*(C`destroy\*(C'\fR method instead.
.ie n .IP $pool\->\fBdestroy()\fR 4
.el .IP \f(CW$pool\fR\->\fBdestroy()\fR 4
.IX Item "$pool->destroy()"
Immediately stop the storage pool.
.ie n .IP "$flag = $pool\->\fBget_autostart()\fR;" 4
.el .IP "\f(CW$flag\fR = \f(CW$pool\fR\->\fBget_autostart()\fR;" 4
.IX Item "$flag = $pool->get_autostart();"
Return a true value if the storage pool is configured to automatically
start upon boot. Return false, otherwise
.ie n .IP $pool\->set_autostart($flag) 4
.el .IP \f(CW$pool\fR\->set_autostart($flag) 4
.IX Item "$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
.ie n .IP $pool\->refresh([$flags]); 4
.el .IP \f(CW$pool\fR\->refresh([$flags]); 4
.IX Item "$pool->refresh([$flags]);"
Refresh the storage pool state. Typically this will rescan the list
of storage volumes. The \f(CW$flags\fR parameter is currently unused and
if omitted defaults to zero.
.ie n .IP $pool\->build([$flags]); 4
.el .IP \f(CW$pool\fR\->build([$flags]); 4
.IX Item "$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 \f(CW$flags\fR parameter allows control over the build operation
and if omitted defaults to zero.
.ie n .IP $pool\->delete([$flags]); 4
.el .IP \f(CW$pool\fR\->delete([$flags]); 4
.IX Item "$pool->delete([$flags]);"
Delete the storage pool. The \f(CW$flags\fR parameter allows the data to
be optionally wiped during delete and if omitted defaults to zero.
.ie n .IP "$info = $pool\->\fBget_info()\fR" 4
.el .IP "\f(CW$info\fR = \f(CW$pool\fR\->\fBget_info()\fR" 4
.IX Item "$info = $pool->get_info()"
Retrieve information about the current storage pool state. The
returned hash reference has the following keys
.RS 4
.IP state 4
.IX Item "state"
The current status of the storage pool. See constants later.
.IP capacity 4
.IX Item "capacity"
The total logical size of the storage pool
.IP allocation 4
.IX Item "allocation"
The current physical allocation of the storage pool
.IP available 4
.IX Item "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
.RE
.RS 4
.RE
.ie n .IP "my $nnames = $pool\->\fBnum_of_storage_volumes()\fR" 4
.el .IP "my \f(CW$nnames\fR = \f(CW$pool\fR\->\fBnum_of_storage_volumes()\fR" 4
.IX Item "my $nnames = $pool->num_of_storage_volumes()"
Return the number of running volumes in this storage pool. The value
can be used as the \f(CW\*(C`maxnames\*(C'\fR parameter to \f(CW\*(C`list_storage_vol_names\*(C'\fR.
.ie n .IP "my @volNames = $pool\->list_storage_vol_names($maxnames)" 4
.el .IP "my \f(CW@volNames\fR = \f(CW$pool\fR\->list_storage_vol_names($maxnames)" 4
.IX Item "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 \f(CW\*(C`get_volume_by_name\*(C'\fR method.
.ie n .IP "my @vols = $pool\->\fBlist_volumes()\fR" 4
.el .IP "my \f(CW@vols\fR = \f(CW$pool\fR\->\fBlist_volumes()\fR" 4
.IX Item "my @vols = $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. This method requires O(n)
RPC calls, so the \f(CW\*(C`list_all_volumes\*(C'\fR method is
recommended as a more efficient alternative.
.ie n .IP "my @volumes = $pool\->list_all_volumes($flags)" 4
.el .IP "my \f(CW@volumes\fR = \f(CW$pool\fR\->list_all_volumes($flags)" 4
.IX Item "my @volumes = $pool->list_all_volumes($flags)"
Return a list of all storage volumes associated with this pool.
The elements in the returned list are instances of the
Sys::Virt::StorageVol class. The \f(CW$flags\fR parameter can be
used to filter the list of return storage volumes.
.ie n .IP "my $vol = $pool\->get_volume_by_name($name)" 4
.el .IP "my \f(CW$vol\fR = \f(CW$pool\fR\->get_volume_by_name($name)" 4
.IX Item "my $vol = $pool->get_volume_by_name($name)"
Return the volume with a name of \f(CW$name\fR. The returned object is
an instance of the Sys::Virt::StorageVol class.
.ie n .IP "my $vol = $pool\->create_volume($xml)" 4
.el .IP "my \f(CW$vol\fR = \f(CW$pool\fR\->create_volume($xml)" 4
.IX Item "my $vol = $pool->create_volume($xml)"
Create a new volume based on the XML description passed into the \f(CW$xml\fR
parameter. The returned object is an instance of the Sys::Virt::StorageVol
class. If the optional \f(CW\*(C`clonevol\*(C'\fR is provided, data will be copied from
that source volume
.ie n .IP "my $vol = $pool\->clone_volume($xml, $clonevol);" 4
.el .IP "my \f(CW$vol\fR = \f(CW$pool\fR\->clone_volume($xml, \f(CW$clonevol\fR);" 4
.IX Item "my $vol = $pool->clone_volume($xml, $clonevol);"
Create a new volume based on the XML description passed into the \f(CW$xml\fR
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.
.SH CONSTANTS
.IX Header "CONSTANTS"
The following sets of constants may be useful in dealing with some of
the methods in this package
.SS "STORAGE POOL DEFINE"
.IX Subsection "STORAGE POOL DEFINE"
The following constants can be used to control the behaviour
of storage pool define operations
.IP Sys::Virt::StoragePool::DEFINE_VALIDATE 4
.IX Item "Sys::Virt::StoragePool::DEFINE_VALIDATE"
Validate the XML document against the XML schema
.SS "POOL STATES"
.IX Subsection "POOL STATES"
The following constants are useful for interpreting the \f(CW\*(C`state\*(C'\fR
key value in the hash returned by \f(CW\*(C`get_info\*(C'\fR
.IP Sys::Virt::StoragePool::STATE_INACTIVE 4
.IX Item "Sys::Virt::StoragePool::STATE_INACTIVE"
The storage pool is not currently active
.IP Sys::Virt::StoragePool::STATE_BUILDING 4
.IX Item "Sys::Virt::StoragePool::STATE_BUILDING"
The storage pool is still being constructed and is not ready for use
yet.
.IP Sys::Virt::StoragePool::STATE_RUNNING 4
.IX Item "Sys::Virt::StoragePool::STATE_RUNNING"
The storage pool is running and can be queried for volumes
.IP Sys::Virt::StoragePool::STATE_DEGRADED 4
.IX Item "Sys::Virt::StoragePool::STATE_DEGRADED"
The storage pool is running, but its operation is degraded due
to a failure.
.IP Sys::Virt::StoragePool::STATE_INACCESSIBLE 4
.IX Item "Sys::Virt::StoragePool::STATE_INACCESSIBLE"
The storage pool is not currently accessible
.SS "DELETION MODES"
.IX Subsection "DELETION MODES"
.IP Sys::Virt::StoragePool::DELETE_NORMAL 4
.IX Item "Sys::Virt::StoragePool::DELETE_NORMAL"
Delete the pool without any attempt to scrub data
.IP Sys::Virt::StoragePool::DELETE_ZEROED 4
.IX Item "Sys::Virt::StoragePool::DELETE_ZEROED"
Fill the allocated storage with zeros when deleting
.SS "BUILD MODES"
.IX Subsection "BUILD MODES"
.IP Sys::Virt::StoragePool::BUILD_NEW 4
.IX Item "Sys::Virt::StoragePool::BUILD_NEW"
Construct a new storage pool from constituent bits
.IP Sys::Virt::StoragePool::BUILD_RESIZE 4
.IX Item "Sys::Virt::StoragePool::BUILD_RESIZE"
Resize an existing built storage pool preserving data where
appropriate
.IP Sys::Virt::StoragePool::BUILD_REPAIR 4
.IX Item "Sys::Virt::StoragePool::BUILD_REPAIR"
Repair an existing storage pool operating in degraded mode
.IP Sys::Virt::StoragePool::BUILD_NO_OVERWRITE 4
.IX Item "Sys::Virt::StoragePool::BUILD_NO_OVERWRITE"
Do not overwrite existing storage pool data
.IP Sys::Virt::StoragePool::BUILD_OVERWRITE 4
.IX Item "Sys::Virt::StoragePool::BUILD_OVERWRITE"
Overwrite existing storage pool data
.SS "CREATE MODES"
.IX Subsection "CREATE MODES"
When creating a storage pool it can be built at the same time.
The following values are therefore close to their BUILD
counterparts.
.IP Sys::Virt::StoragePool::CREATE_NORMAL 4
.IX Item "Sys::Virt::StoragePool::CREATE_NORMAL"
Just create the storage pool without building it.
.IP Sys::Virt::StoragePool::CREATE_WITH_BUILD 4
.IX Item "Sys::Virt::StoragePool::CREATE_WITH_BUILD"
When creating new storage pool also perform pool build without any flags.
.IP Sys::Virt::StoragePool::CREATE_WITH_BUILD_OVERWRITE 4
.IX Item "Sys::Virt::StoragePool::CREATE_WITH_BUILD_OVERWRITE"
Create the pool and perform pool build using the BUILD_OVERWRITE
flag. This is mutually exclusive to CREATE_WITH_BUILD_NO_OVERWRITE.
.IP Sys::Virt::StoragePool::CREATE_WITH_BUILD_NO_OVERWRITE 4
.IX Item "Sys::Virt::StoragePool::CREATE_WITH_BUILD_NO_OVERWRITE"
Create the pool and perform pool build using the BUILD_NO_OVERWRITE
flag. This is mutually exclusive to CREATE_WITH_BUILD_OVERWRITE.
.SS "XML DOCUMENTS"
.IX Subsection "XML DOCUMENTS"
The following constants are useful when requesting
XML for storage pools
.IP Sys::Virt::StoragePool::XML_INACTIVE 4
.IX Item "Sys::Virt::StoragePool::XML_INACTIVE"
Return XML describing the inactive state of the storage
pool.
.SH "LIST FILTERING"
.IX Header "LIST FILTERING"
The following constants are used to filter object lists
.IP Sys::Virt::StoragePool::LIST_ACTIVE 4
.IX Item "Sys::Virt::StoragePool::LIST_ACTIVE"
Include storage pools which are active
.IP Sys::Virt::StoragePool::LIST_INACTIVE 4
.IX Item "Sys::Virt::StoragePool::LIST_INACTIVE"
Include storage pools which are inactive
.IP Sys::Virt::StoragePool::LIST_AUTOSTART 4
.IX Item "Sys::Virt::StoragePool::LIST_AUTOSTART"
Include storage pools which are marked for autostart
.IP Sys::Virt::StoragePool::LIST_NO_AUTOSTART 4
.IX Item "Sys::Virt::StoragePool::LIST_NO_AUTOSTART"
Include storage pools which are not marked for autostart
.IP Sys::Virt::StoragePool::LIST_PERSISTENT 4
.IX Item "Sys::Virt::StoragePool::LIST_PERSISTENT"
Include storage pools which are persistent
.IP Sys::Virt::StoragePool::LIST_TRANSIENT 4
.IX Item "Sys::Virt::StoragePool::LIST_TRANSIENT"
Include storage pools which are transient
.IP Sys::Virt::StoragePool::LIST_DIR 4
.IX Item "Sys::Virt::StoragePool::LIST_DIR"
Include directory storage pools
.IP Sys::Virt::StoragePool::LIST_DISK 4
.IX Item "Sys::Virt::StoragePool::LIST_DISK"
Include disk storage pools
.IP Sys::Virt::StoragePool::LIST_FS 4
.IX Item "Sys::Virt::StoragePool::LIST_FS"
Include filesystem storage pools
.IP Sys::Virt::StoragePool::LIST_ISCSI 4
.IX Item "Sys::Virt::StoragePool::LIST_ISCSI"
Include iSCSI storage pools
.IP Sys::Virt::StoragePool::LIST_LOGICAL 4
.IX Item "Sys::Virt::StoragePool::LIST_LOGICAL"
Include LVM storage pools
.IP Sys::Virt::StoragePool::LIST_MPATH 4
.IX Item "Sys::Virt::StoragePool::LIST_MPATH"
Include multipath storage pools
.IP Sys::Virt::StoragePool::LIST_NETFS 4
.IX Item "Sys::Virt::StoragePool::LIST_NETFS"
Include network filesystem storage pools
.IP Sys::Virt::StoragePool::LIST_RBD 4
.IX Item "Sys::Virt::StoragePool::LIST_RBD"
Include RBD storage pools
.IP Sys::Virt::StoragePool::LIST_SCSI 4
.IX Item "Sys::Virt::StoragePool::LIST_SCSI"
Include SCSI storage pools
.IP Sys::Virt::StoragePool::LIST_SHEEPDOG 4
.IX Item "Sys::Virt::StoragePool::LIST_SHEEPDOG"
Include sheepdog storage pools
.IP Sys::Virt::StoragePool::LIST_GLUSTER 4
.IX Item "Sys::Virt::StoragePool::LIST_GLUSTER"
Include gluster storage pools
.IP Sys::Virt::StoragePool::LIST_ZFS 4
.IX Item "Sys::Virt::StoragePool::LIST_ZFS"
Include ZFS storage pools
.IP Sys::Virt::StoragePool::LIST_VSTORAGE 4
.IX Item "Sys::Virt::StoragePool::LIST_VSTORAGE"
Include VStorage storage pools
.IP Sys::Virt::StoragePool::LIST_ISCSI_DIRECT 4
.IX Item "Sys::Virt::StoragePool::LIST_ISCSI_DIRECT"
Include direct iSCSI pools
.SS "EVENT ID CONSTANTS"
.IX Subsection "EVENT ID CONSTANTS"
.IP Sys::Virt::StoragePool::EVENT_ID_LIFECYCLE 4
.IX Item "Sys::Virt::StoragePool::EVENT_ID_LIFECYCLE"
Storage pool lifecycle events
.IP Sys::Virt::StoragePool::EVENT_ID_REFRESH 4
.IX Item "Sys::Virt::StoragePool::EVENT_ID_REFRESH"
Storage pool volume refresh events
.SS "LIFECYCLE CHANGE EVENTS"
.IX Subsection "LIFECYCLE CHANGE EVENTS"
The following constants allow storage pool lifecycle change events
to be interpreted. The events contain both a state change, and a
reason though the reason is currently unused.
.IP Sys::Virt::StoragePool::EVENT_DEFINED 4
.IX Item "Sys::Virt::StoragePool::EVENT_DEFINED"
Indicates that a persistent configuration has been defined for
the storage pool
.IP Sys::Virt::StoragePool::EVENT_STARTED 4
.IX Item "Sys::Virt::StoragePool::EVENT_STARTED"
The storage pool has started running
.IP Sys::Virt::StoragePool::EVENT_STOPPED 4
.IX Item "Sys::Virt::StoragePool::EVENT_STOPPED"
The storage pool has stopped running
.IP Sys::Virt::StoragePool::EVENT_UNDEFINED 4
.IX Item "Sys::Virt::StoragePool::EVENT_UNDEFINED"
The persistent configuration has gone away
.IP Sys::Virt::StoragePool::EVENT_CREATED 4
.IX Item "Sys::Virt::StoragePool::EVENT_CREATED"
The underlying storage has been built
.IP Sys::Virt::StoragePool::EVENT_DELETED 4
.IX Item "Sys::Virt::StoragePool::EVENT_DELETED"
The underlying storage has been released
.SH AUTHORS
.IX Header "AUTHORS"
Daniel P. Berrange <berrange@redhat.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2006\-2009 Red Hat
Copyright (C) 2006\-2009 Daniel P. Berrange
.SH LICENSE
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sys::Virt, Sys::Virt::Error, \f(CW\*(C`http://libvirt.org\*(C'\fR