Sys::V...gePool(3pm)

📦
version 12.4.0 · 12 versions
, in epel 10

💖 NAME 💖

okay bestie, this is Sys::V...gePool(3pm) — aka the manual page for Sys::Virt::StoragePool — from User Contributed Perl Documentation. It's the module that does Represent & manage a libvirt storage pool. Yes, the ampersand is literally in the original, we're keeping it. 💅

✨ 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. iconic range, honestly 🌈

🛠️ METHODS 🛠️

my $uuid = $pool->get_uuid()

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

my $uuid = $pool->get_uuid_string()

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

my $name = $pool->get_name()

Returns a string with a locally unique name of the storage pool. local queen behavior 👑

$pool->is_active()

Returns a true value if the storage pool is currently running. vibe check: active ✅

$pool->is_persistent()

Returns a true value if the storage pool has a persistent configuration file defined. persistent, not just a phase 🦋

my $xml = $pool->get_xml_description()

Returns an XML document containing a complete description of the storage pool's configuration. the whole XML look, complete 💖

$pool->create()

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

$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. careful, bestie 💀

$pool->destroy()

Immediately stop the storage pool. immediately. no soft launch. 😭

$flag = $pool->get_autostart();

Return a true value if the storage pool is configured to automatically start upon boot. Return false, otherwise. boot-time main character energy ⭐

$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. set the vibe for next boot 🍓

$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. lowkey unused flags, but noted 🫶

$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. build it from the ground up 🧚

$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. optional wipe, so read twice 🚨

$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. state check 🔍
  • capacity — The total logical size of the storage pool. big picture capacity 💽
  • allocation — The current physical allocation of the storage pool. what's actually allocated 🎀
  • 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. math is not always mathing 😭

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. count first, list later 🦋

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. names, names, names 💅

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. O(n) RPC calls? not the efficient route, bestie 🫶

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. filtered volume list, we love efficiency ✨

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. name match, volume found 🎯

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. new volume just dropped 🔥

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. clone era 🧬

🌈 CONSTANTS 🌈

The following sets of constants may be useful in dealing with some of the methods in this package. constant stans, this is your moment ⭐

🎀 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. schema validation, no cap ✅

💅 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. asleep, not slaying 😴
  • Sys::Virt::StoragePool::STATE_BUILDING — The storage pool is still being constructed and is not ready for use yet. cooking, not ready 🍳
  • Sys::Virt::StoragePool::STATE_RUNNING — The storage pool is running and can be queried for volumes. up and serving ✅
  • Sys::Virt::StoragePool::STATE_DEGRADED — The storage pool is running, but its operation is degraded due to a failure. running but not okay 💀
  • Sys::Virt::StoragePool::STATE_INACCESSIBLE — The storage pool is not currently accessible. can't get in 🚪

🦋 DELETION MODES 🦋

  • Sys::Virt::StoragePool::DELETE_NORMAL — Delete the pool without any attempt to scrub data. normal delete, no scrub 🧹
  • Sys::Virt::StoragePool::DELETE_ZEROED — Fill the allocated storage with zeros when deleting. zero fill on delete 0️⃣

🌸 BUILD MODES 🌸

  • Sys::Virt::StoragePool::BUILD_NEW — Construct a new storage pool from constituent bits. new pool from the bits 🧱
  • Sys::Virt::StoragePool::BUILD_RESIZE — Resize an existing built storage pool preserving data where appropriate. resize, preserve the data 📏
  • Sys::Virt::StoragePool::BUILD_REPAIR — Repair an existing storage pool operating in degraded mode. repair era 🛠️
  • Sys::Virt::StoragePool::BUILD_NO_OVERWRITE — Do not overwrite existing storage pool data. do not overwrite, bestie 🛑
  • Sys::Virt::StoragePool::BUILD_OVERWRITE — Overwrite existing storage pool data. overwrite, dramatic 💥

✨ 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. create only, no build 🎀
  • Sys::Virt::StoragePool::CREATE_WITH_BUILD — When creating new storage pool also perform pool build without any flags. create plus build 🧚
  • 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. mutually exclusive, pick one ⚔️
  • 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. also mutually exclusive, don't do both 🚨

⭐ 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. inactive XML, still valid 📄

🍓 LIST FILTERING 🍓

The following constants are used to filter object lists.

  • Sys::Virt::StoragePool::LIST_ACTIVE — Include storage pools which are active. active included ✅
  • Sys::Virt::StoragePool::LIST_INACTIVE — Include storage pools which are inactive. inactive included 😴
  • Sys::Virt::StoragePool::LIST_AUTOSTART — Include storage pools which are marked for autostart. autostart marked ⭐
  • Sys::Virt::StoragePool::LIST_NO_AUTOSTART — Include storage pools which are not marked for autostart. no autostart 🚫
  • Sys::Virt::StoragePool::LIST_PERSISTENT — Include storage pools which are persistent. persistent included 🦋
  • Sys::Virt::StoragePool::LIST_TRANSIENT — Include storage pools which are transient. transient included 💨
  • Sys::Virt::StoragePool::LIST_DIR — Include directory storage pools. directory pools 📁
  • Sys::Virt::StoragePool::LIST_DISK — Include disk storage pools. disk pools 💽
  • Sys::Virt::StoragePool::LIST_FS — Include filesystem storage pools. filesystem pools 🗂️
  • Sys::Virt::StoragePool::LIST_ISCSI — Include iSCSI storage pools. iSCSI pools 🌐
  • Sys::Virt::StoragePool::LIST_LOGICAL — Include LVM storage pools. LVM pools 🧱
  • Sys::Virt::StoragePool::LIST_MPATH — Include multipath storage pools. multipath pools 🛣️
  • Sys::Virt::StoragePool::LIST_NETFS — Include network filesystem storage pools. network filesystem pools 🌈
  • Sys::Virt::StoragePool::LIST_RBD — Include RBD storage pools. RBD pools 🟣
  • Sys::Virt::StoragePool::LIST_SCSI — Include SCSI storage pools. SCSI pools 🔌
  • Sys::Virt::StoragePool::LIST_SHEEPDOG — Include sheepdog storage pools. sheepdog pools 🐑
  • Sys::Virt::StoragePool::LIST_GLUSTER — Include gluster storage pools. gluster pools 🫙
  • Sys::Virt::StoragePool::LIST_ZFS — Include ZFS storage pools. ZFS pools ☀️
  • Sys::Virt::StoragePool::LIST_VSTORAGE — Include VStorage storage pools. VStorage pools 📦
  • Sys::Virt::StoragePool::LIST_ISCSI_DIRECT — Include direct iSCSI pools. direct iSCSI pools 🎯

💜 EVENT ID CONSTANTS 💜

  • Sys::Virt::StoragePool::EVENT_ID_LIFECYCLE — Storage pool lifecycle events. lifecycle events 🔄
  • Sys::Virt::StoragePool::EVENT_ID_REFRESH — Storage pool volume refresh events. 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. defined, persistent config 📝
  • Sys::Virt::StoragePool::EVENT_STARTED — The storage pool has started running. started running ▶️
  • Sys::Virt::StoragePool::EVENT_STOPPED — The storage pool has stopped running. stopped running ⏹️
  • Sys::Virt::StoragePool::EVENT_UNDEFINED — The persistent configuration has gone away. config gone 💨
  • Sys::Virt::StoragePool::EVENT_CREATED — The underlying storage has been built. storage built 🧱
  • Sys::Virt::StoragePool::EVENT_DELETED — The underlying storage has been released. storage released 🕊️

💜 AUTHORS 💜

Daniel P. Berrange <berrange@redhat.com> shoutout to Daniel P. Berrange 🫶

Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange. copyright lines, preserved exactly 📜

🌸 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 ✨

okay bestie, you're not done yet — here's where to go next 💅

  • Sys::Virt — the main module, the mothership, the main character 👑 this whole page is literally just one little corner of it, so go read it fr fr
  • Sys::Virt::Error — when things go sideways (and they will 😭), this is the one holding the error info you're gonna want
  • "http://libvirt.org" — the actual libvirt site, for when you wanna go straight to the source. no cap, it's giving reference material 🦋

and that's a wrap, bestie!! 🎀 this page was brought to you by perl v5.40.2, dated 2026-06-08, living at Sys::V...gePool(3pm) — go forth and pool those storage volumes, you're gonna slay 💖✨🫶

📦 where this page comes from