20.29. Storage Pool Commands
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: 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.com 20.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 : 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: 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 : 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 : 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: The following command then builds a directory type storage pool from the XML file (named vdisk.xml in this example): 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: The following example builds a directory-type storage pool based on the XML file (named vdisk.xml in this example): 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 --type type defines the storage pool type. See Section 20.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 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: 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 --type type defines the storage pool type. See Section 20.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 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: 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" : 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" : 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" : 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" . 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. 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 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: 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 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> virsh pool-info vdisk Name: vdisk UUID: State: running Persistent: yes Autostart: no Capacity: 125 GB Allocation: 0.00 Available: 125 GB virsh pool-list --all Name State Autostart ----------------------------------------- default active yes vdisk active no virsh pool-refresh vdisk Pool vdisk refreshed virsh pool-build vdisk Pool vdisk built <pool type="dir"> <name>vdisk</name> <target> <path>/var/lib/libvirt/images</path> </target> </pool> virsh pool-define vdisk.xml Pool vdisk defined <pool type="dir"> <name>vdisk</name> <target> <path>/var/lib/libvirt/images</path> </target> </pool> virsh pool-create vdisk.xml Pool vdisk created virsh pool-create-as --name vdisk --type dir --target /mnt Pool vdisk created virsh pool-define-as --name vdisk --type dir --target /mnt Pool vdisk defined virsh pool-start vdisk Pool vdisk started virsh pool-autostart vdisk Pool vdisk autostarted virsh pool-destroy vdisk Pool vdisk destroyed virsh pool-delete vdisk Pool vdisk deleted virsh pool-undefine vdisk Pool vdisk undefined virsh pool-dumpxml vdisk <pool type="dir"> <name>vdisk</name> <target> <path>/var/lib/libvirt/images</path> </target> </pool> virsh pool-edit vdisk <pool type="dir"> <name>vdisk</name> <target> <path>/var/lib/libvirt/images</path> </target> </pool>