21.29. Storage Pool Commands

Using libvirt, you can manage various storage solutions, including files, raw partitions, and domain-specific formats, used to provide the storage volumes visible as devices within virtual machines. For more detailed information, see the libvirt upstream pages. Many of the commands for administering storage pools are similar to the ones used for guest virtual machines.

21.29.1. Searching for a Storage Pool XML

The virsh find-storage-pool-sources type command displays the XML describing all storage pools of a given source that could be found. Types include: netfs, disk, dir, fs, iscsi, logical, and gluster. Note that all of the types correspond to the storage back-end drivers and there are more types available (see the man page for more details). You can also further restrict the query for pools by providing an template source XML file using the --srcSpec option.

Example 21.72. How to list the XML setting of available storage pools

The following example outputs the XML setting of all logical storage pools available on the system:
virsh find-storage-pool-sources logical
<sources>
  <source>
    <device path='/dev/mapper/luks-7a6bfc59-e7ed-4666-a2ed-6dcbff287149'/>
    <name>RHEL_dhcp-2-157</name>
    <format type='lvm2'/>
  </source>
</sources>

21.29.2. Finding a storage Pool

The virsh find-storage-pool-sources-as type command finds potential storage pool sources, given a specific type. Types include: netfs, disk, dir, fs, iscsi, logical, and gluster. Note that all of the types correspond to the storage back-end drivers and there are more types available (see the man page for more details). The command also takes the optional arguments host, port, and initiator. Each of these options will dictate what gets queried.

Example 21.73. How to find potential storage pool sources

The following example searches for a disk-based storage pool on the specified host machine. If you are unsure of your host name run the command virsh hostname first:
# virsh find-storage-pool-sources-as disk --host myhost.example.com

21.29.3. Listing Storage Pool Information

The virsh pool-info pool command lists the basic information about the specified storage pool object. This command requires the name or UUID of the storage pool. To retrieve this information, use the pool-list command.

Example 21.74. How to retrieve information on a storage pool

The following example retrieves information on the storage pool named vdisk:
virsh pool-info vdisk

Name:           vdisk
UUID:
State:          running
Persistent:     yes
Autostart:      no
Capacity:       125 GB
Allocation:     0.00
Available:      125 GB

21.29.4. Listing the Available Storage Pools

The virsh pool-list command lists all storage pool objects known to libvirt. By default, only active pools are listed; but using the --inactive argument lists just the inactive pools, and using the --all argument lists all of the storage pools. This command takes the following optional arguments, which filter the search results:
  • --inactive - lists the inactive storage pools
  • --all - lists both active and inactive storage pools
  • --persistent - lists the persistent storage pools
  • --transient - lists the transient storage pools
  • --autostart - lists the storage pools with autostart enabled
  • --no-autostart - lists the storage pools with autostart disabled
  • --type type - lists the pools that are only of the specified type
  • --details - lists the extended details for the storage pools
In addition to the above arguments, there are several sets of filtering flags that can be used to filter the content of the list. --persistent restricts the list to persistent pools, --transient restricts the list to transient pools, --autostart restricts the list to autostarting pools and finally --no-autostart restricts the list to the storage pools that have autostarting disabled.
For all storage pool commands which require a --type, the pool types must be separated by comma. The valid pool types include: dir, fs, netfs, logical, disk, iscsi, scsi, mpath, rbd, sheepdog, and gluster.
The --details option instructs virsh to additionally display pool persistence and capacity related information where available.

Note

When this command is used with older servers, it is forced to use a series of API calls with an inherent race, where a pool might not be listed or might appear more than once if it changed its state between calls while the list was being collected. Newer servers however, do not have this problem.

Example 21.75. How to list all storage pools

This example lists storage pools that are both active and inactive:
virsh pool-list --all
Name                 State      Autostart
-----------------------------------------
default             active     yes
vdisk               active     no

21.29.5. Refreshing a Storage Pool List

The virsh pool-refresh pool command refreshes the list of storage volumes contained in storage pool.

Example 21.76. How to refresh the list of the storage volumes in a storage pool

The following example refreshes the list for the storage volume named vdisk:
virsh pool-refresh vdisk

Pool vdisk refreshed

21.29.6. Creating, Defining, and Starting Storage Pools

21.29.6.1. Building a storage pool

The virsh pool-build pool command builds a storage pool using the name given in the command. The optional arguments --overwrite and --no-overwrite can only be used for an FS storage pool or with a disk or logical type based storage pool. Note that if [--overwrite] or [--no-overwrite] are not provided and the pool used is FS, it is assumed that the type is actually directory-based. In addition to the pool name, the storage pool UUID may be used as well.
If --no-overwrite is specified, it probes to determine if a file system already exists on the target device, returning an error if it exists, or using mkfs to format the target device if it does not. If --overwrite is specified, then the mkfs command is executed and any existing data on the target device is overwritten.

Example 21.77. How to build a storage pool

The following example creates a disk-based storage pool named vdisk:
virsh pool-build vdisk

Pool vdisk built

21.29.6.2. Defining a storage pool from an XML file

The virsh pool-define file command creates, but does not start, a storage pool object from the XML file.

Example 21.78. How to define a storage pool from an XML file

This example assumes that you have already created an XML file with the settings for your storage pool. For example:
<pool type="dir">
	<name>vdisk</name>
	<target>
          <path>/var/lib/virt/images</path>
	</target>
</pool>
The following command then builds a directory type storage pool from the XML file (named vdisk.xml in this example):
virsh pool-define vdisk.xml

Pool vdisk defined
To confirm that the storage pool was defined, run the virsh pool-list --all command as shown in Example 21.75, “How to list all storage pools”. When you run the command, however, the status will show as inactive as the pool has not been started. For directions on starting the storage pool refer to Example 21.82, “How to start a storage pool”.

21.29.6.3. Creating storage pools

The virsh pool-create file command creates and starts a storage pool from its associated XML file.

Example 21.79. How to create a storage pool from an XML file

In this example assumes that you have already created an XML file with the settings for your storage pool. For example:
<pool type="dir">
	<name>vdisk</name>
	<target>
          <path>/var/lib/virt/images</path>
	</target>
</pool>
The following example builds a directory-type storage pool based on the XML file (named vdisk.xml in this example):
virsh pool-create vdisk.xml

Pool vdisk created
To confirm that the storage pool was created, run the virsh pool-list --all command as shown in Example 21.75, “How to list all storage pools”. When you run the command, however, the status will show as inactive as the pool has not been started. For directions on starting the storage pool refer to Example 21.82, “How to start a storage pool”.

21.29.6.4. Creating storage pools

The virsh pool-create-as name command creates and starts a pool object name from the raw parameters given. This command takes the following options:
  • --print-xml - displays the contents of the XML file, but does not define or create a storage pool from it
  • --type type defines the storage pool type. Refer to Section 21.29.4, “Listing the Available Storage Pools” for the types you can use.
  • --source-host hostname - the source host physical machine for underlying storage
  • --source-path path - the location of the underlying storage
  • --source-dev path - the device for the underlying storage
  • --source-name name - the name of the source underlying storage
  • --source-format format - the format of the source underlying storage
  • --target path - the target for the underlying storage

Example 21.80. How to create and start a storage pool

The following example creates and starts a storage pool named vdisk at the /mnt directory:
virsh pool-create-as --name vdisk --type dir --target /mnt

Pool vdisk created

21.29.6.5. Defining a storage pool

The virsh pool-define-as <name> command creates, but does not start, a pool object name from the raw parameters given. This command accepts the following options:
  • --print-xml - displays the contents of the XML file, but does not define or create a storage pool from it
  • --type type defines the storage pool type. Refer to Section 21.29.4, “Listing the Available Storage Pools” for the types you can use.
  • --source-host hostname - source host physical machine for underlying storage
  • --source-path path - location of the underlying storage
  • --source-dev devicename - device for the underlying storage
  • --source-name sourcename - name of the source underlying storage
  • --source-format format - format of the source underlying storage
  • --target targetname - target for the underlying storage
If --print-xml is specified, then it prints the XML of the pool object without creating or defining the pool. Otherwise, the pool requires a specified type to be built. For all storage pool commands which require a type, the pool types must be separated by comma. The valid pool types include: dir, fs, netfs, logical, disk, iscsi, scsi, mpath, rbd, sheepdog, and gluster.

Example 21.81. How to define a storage pool

The following example defines a storage pool named vdisk, but does not start it. After this command runs, use the virsh pool-start command to activate the storage pool:
virsh pool-define-as --name vdisk --type dir --target /mnt

Pool vdisk defined

21.29.6.6. Starting a storage pool

The virsh pool-start pool command starts the specified storage pool, which was previously defined but inactive. This command may also use the UUID for the storage pool as well as the pool's name.

Example 21.82. How to start a storage pool

The following example starts the vdisk storage pool that you built in Example 21.79, “How to create a storage pool from an XML file”:
virsh pool-start vdisk

Pool vdisk started
To verify the pool has started run the virsh pool-list --all command and confirm that the status is active, as shown in Example 21.75, “How to list all storage pools”.

21.29.6.7. Auto-starting a storage pool

The virsh pool-autostart pool command enables a storage pool to automatically start at boot. This command requires the pool name or UUID. To disable the pool-autostart command use the --disable argument in the command.

Example 21.83. How to autostart a storage pool

The following example autostarts the vdisk storage pool that you built in Example 21.79, “How to create a storage pool from an XML file”:
virsh pool-autostart vdisk

Pool vdisk autostarted

21.29.7. Stopping and Deleting Storage Pools

The virsh pool-destroy pool command stops a storage pool. Once stopped, libvirt will no longer manage the pool but the raw data contained in the pool is not changed, and can be later recovered with the pool-create command.

Example 21.84. How to stop a storage pool

The following example stops the vdisk storage pool that you built in Example 21.79, “How to create a storage pool from an XML file”:
virsh pool-destroy vdisk

Pool vdisk destroyed
The virsh pool-delete pool command destroys the resources used by the specified storage pool. It is important to note that this operation is non-recoverable and non-reversible. However, the pool structure will still exist after this command, ready to accept the creation of new storage volumes.

Example 21.85. How to delete a storage pool

The following sample deletes the vdisk storage pool that you built in Example 21.79, “How to create a storage pool from an XML file”.
virsh pool-delete vdisk

Pool vdisk deleted
The virsh pool-undefine pool command undefines the configuration for an inactive pool.

Example 21.86. How to undefine a storage pool

The following examples undefines the vdisk storage pool that you built in Example 21.79, “How to create a storage pool from an XML file”. This makes your storage pool transient.
virsh pool-undefine vdisk

Pool vdisk undefined

21.29.8. Creating an XML Dump File for a Pool

The virsh pool-dumpxml pool command returns the XML information about the specified storage pool object. Using the option --inactive dumps the configuration that will be used on next start of the pool instead of the current pool configuration.

Example 21.87. How to retrieve a storage pool's configuration settings

The following example retrieves the configuration settings for the vdisk storage pool that you built in Example 21.79, “How to create a storage pool from an XML file”. Once the command runs, the configuration file opens in the terminal:
virsh pool-dumpxml vdisk
<pool type="dir">
	<name>vdisk</name>
	<target>
          <path>/var/lib/virt/images</path>
	</target>
</pool>

21.29.9. Editing the Storage Pool's Configuration File

The pool-edit pool command opens the specified storage pool's XML configuration file for editing.
This method is the only method that should be used to edit an XML configuration file as it does error checking before applying.

Example 21.88. How to edit a storage pool's configuration settings

The following example edits the configuration settings for the vdisk storage pool that you built in Example 21.79, “How to create a storage pool from an XML file”. Once the command runs, the configuration file opens in your default editor:
virsh pool-edit vdisk
<pool type="dir">
	<name>vdisk</name>
	<target>
          <path>/var/lib/virt/images</path>
	</target>
</pool>