20.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.
20.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 20.71. 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>
20.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 20.72. 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.com20.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 20.73. 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
20.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 20.74. 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
20.29.5. Refreshing a Storage Pool List
The
virsh pool-refresh pool command refreshes the list of storage volumes contained in storage pool.
Example 20.75. 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
20.29.6. Creating, Defining, and Starting Storage Pools
20.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 20.76. How to build a storage pool
The following example creates a disk-based storage pool named vdisk:
# virsh pool-build vdisk
Pool vdisk built
20.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 20.77. 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/libvirt/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 20.74, “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 see Example 20.81, “How to start a storage pool”.
20.29.6.3. Creating storage pools
The
virsh pool-create file command creates and starts a storage pool from its associated XML file.
Example 20.78. 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/libvirt/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 20.74, “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 see Example 20.81, “How to start a storage pool”.
20.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--typetype defines the storage pool type. See Section 20.29.4, “Listing the Available Storage Pools” for the types you can use.--source-hosthostname - the source host physical machine for underlying storage--source-pathpath - the location of the underlying storage--source-devpath - the device for the underlying storage--source-namename - the name of the source underlying storage--source-formatformat - the format of the source underlying storage--targetpath - the target for the underlying storage
Example 20.79. 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
20.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--typetype defines the storage pool type. See Section 20.29.4, “Listing the Available Storage Pools” for the types you can use.--source-hosthostname - source host physical machine for underlying storage--source-pathpath - location of the underlying storage--source-devdevicename - device for the underlying storage--source-namesourcename - name of the source underlying storage--source-formatformat - format of the source underlying storage--targettargetname - 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 20.80. 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
20.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 20.81. How to start a storage pool
The following example starts the vdisk storage pool that you built in Example 20.78, “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 20.74, “How to list all storage pools”.
20.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 20.82. How to autostart a storage pool
The following example autostarts the vdisk storage pool that you built in Example 20.78, “How to create a storage pool from an XML file”:
# virsh pool-autostart vdisk
Pool vdisk autostarted
20.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 20.83. How to stop a storage pool
The following example stops the vdisk storage pool that you built in Example 20.78, “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 20.84. How to delete a storage pool
The following sample deletes the vdisk storage pool that you built in Example 20.78, “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 20.85. How to undefine a storage pool
The following examples undefines the vdisk storage pool that you built in Example 20.78, “How to create a storage pool from an XML file”. This makes your storage pool transient.
# virsh pool-undefine vdisk
Pool vdisk undefined
20.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 20.86. 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 20.78, “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/libvirt/images</path>
</target>
</pool>
20.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 20.87. 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 20.78, “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/libvirt/images</path>
</target>
</pool>
