--- name: "Sys::Virt::StoragePool" section: "3pm" platform: "linux" package: "perl-sys-virt" version: "12.7.0-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Sys::Virt::StoragePool" --- # Sys::Virt::StoragePool(3pm) Represent & manage a libvirt storage pool ## 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 `"destroy"` method instead. - $pool-\>**destroy()** Immediately stop the storage pool. - $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 @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 `"list_all_volumes"` method is recommended as a more efficient alternative. - 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 `$flags` parameter can be used to filter the list of return storage volumes. - 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 ### STORAGE POOL DEFINE The following constants can be used to control the behaviour of storage pool define operations - Sys::Virt::StoragePool::DEFINE\_VALIDATE Validate the XML document against the XML schema ### 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 ### 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. - Sys::Virt::StoragePool::CREATE\_NORMAL Just create the storage pool without building it. - Sys::Virt::StoragePool::CREATE\_WITH\_BUILD When creating new storage pool also perform pool build without any flags. - 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. - 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. ### XML DOCUMENTS The following constants are useful when requesting XML for storage pools - Sys::Virt::StoragePool::XML\_INACTIVE Return XML describing the inactive state of the storage pool. ## LIST FILTERING The following constants are used to filter object lists - Sys::Virt::StoragePool::LIST\_ACTIVE Include storage pools which are active - Sys::Virt::StoragePool::LIST\_INACTIVE Include storage pools which are inactive - Sys::Virt::StoragePool::LIST\_AUTOSTART Include storage pools which are marked for autostart - Sys::Virt::StoragePool::LIST\_NO\_AUTOSTART Include storage pools which are not marked for autostart - Sys::Virt::StoragePool::LIST\_PERSISTENT Include storage pools which are persistent - Sys::Virt::StoragePool::LIST\_TRANSIENT Include storage pools which are transient - Sys::Virt::StoragePool::LIST\_DIR Include directory storage pools - Sys::Virt::StoragePool::LIST\_DISK Include disk storage pools - Sys::Virt::StoragePool::LIST\_FS Include filesystem storage pools - Sys::Virt::StoragePool::LIST\_ISCSI Include iSCSI storage pools - Sys::Virt::StoragePool::LIST\_LOGICAL Include LVM storage pools - Sys::Virt::StoragePool::LIST\_MPATH Include multipath storage pools - Sys::Virt::StoragePool::LIST\_NETFS Include network filesystem storage pools - Sys::Virt::StoragePool::LIST\_RBD Include RBD storage pools - Sys::Virt::StoragePool::LIST\_SCSI Include SCSI storage pools - Sys::Virt::StoragePool::LIST\_SHEEPDOG Include sheepdog storage pools - Sys::Virt::StoragePool::LIST\_GLUSTER Include gluster storage pools - Sys::Virt::StoragePool::LIST\_ZFS Include ZFS storage pools - Sys::Virt::StoragePool::LIST\_VSTORAGE Include VStorage storage pools - Sys::Virt::StoragePool::LIST\_ISCSI\_DIRECT Include direct iSCSI pools ### EVENT ID CONSTANTS - Sys::Virt::StoragePool::EVENT\_ID\_LIFECYCLE Storage pool lifecycle events - Sys::Virt::StoragePool::EVENT\_ID\_REFRESH Storage pool volume refresh events ### 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. - Sys::Virt::StoragePool::EVENT\_DEFINED Indicates that a persistent configuration has been defined for the storage pool - Sys::Virt::StoragePool::EVENT\_STARTED The storage pool has started running - Sys::Virt::StoragePool::EVENT\_STOPPED The storage pool has stopped running - Sys::Virt::StoragePool::EVENT\_UNDEFINED The persistent configuration has gone away - Sys::Virt::StoragePool::EVENT\_CREATED The underlying storage has been built - Sys::Virt::StoragePool::EVENT\_DELETED The underlying storage has been released ## AUTHORS Daniel P. Berrange \ ## 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"`