14.2. Managing virtual machine storage pools using the CLI

You can use the CLI to manage the following aspects of your storage pools to assign storage to your virtual machines (VMs):

14.2.1. Viewing storage pool information using the CLI

Using the CLI, you can view a list of all storage pools with limited or full details about the storage pools. You can also filter the storage pools listed.

Procédure

  • Use the virsh pool-list command to view storage pool information. 

    # virsh pool-list --all --details
 Name                State    Autostart  Persistent    Capacity  Allocation   Available
 default             running  yes        yes          48.97 GiB   23.93 GiB   25.03 GiB
 Downloads           running  yes        yes         175.62 GiB   62.02 GiB  113.60 GiB
 RHEL-Storage-Pool   running  yes        yes         214.62 GiB   93.02 GiB  168.60 GiB

Ressources supplémentaires

  • The virsh pool-list --help command

14.2.2. Creating directory-based storage pools using the CLI

A directory-based storage pool is based on a directory in an existing mounted file system. This is useful, for example, when you want to use the remaining space on the file system for other purposes. You can use the virsh utility to create directory-based storage pools.

Conditions préalables

  • Ensure your hypervisor supports directory storage pools: 

    # virsh pool-capabilities | grep "'dir' supported='yes'"

    If the command displays any output, directory pools are supported.

Procédure

  1. Create a storage pool

    Use the virsh pool-define-as command to define and create a directory-type storage pool. For example, to create a storage pool named guest_images_dir that uses the /guest_images directory: 

    # virsh pool-define-as guest_images_dir dir --target "/guest_images"
Pool guest_images_dir defined

    If you already have an XML configuration of the storage pool you want to create, you can also define the pool based on the XML. For details, see Directory-based storage pool parameters.

  2. Create the storage pool target path

    Use the virsh pool-build command to create a storage pool target path for a pre-formatted file system storage pool, initialize the storage source device, and define the format of the data. 

    # virsh pool-build guest_images_dir
  Pool guest_images_dir built

# ls -la /guest_images
  total 8
  drwx------.  2 root root 4096 May 31 19:38 .
  dr-xr-xr-x. 25 root root 4096 May 31 19:38 ..

  3. Verify that the pool was created

    Use the virsh pool-list command to verify that the pool was created.

    [ subs="+quotes"] 

# *virsh pool-list --all*

  Name                 State      Autostart
  -----------------------------------------
  default              active     yes
  guest_images_dir     inactive   no

  1. Start the storage pool

    Use the virsh pool-start command to mount the storage pool. 

    # virsh pool-start guest_images_dir
  Pool guest_images_dir started
    Note

    The virsh pool-start command is only necessary for persistent storage pools. Transient storage pools are automatically started when they are created.

  2. [Optional] Turn on autostart

    By default, a storage pool defined with the virsh command is not set to automatically start each time virtualization services start. Use the virsh pool-autostart command to configure the storage pool to autostart. 

    # virsh pool-autostart guest_images_dir
  Pool guest_images_dir marked as autostarted

Vérification

  • Use the virsh pool-info command to verify that the storage pool is in the running state. Check if the sizes reported are as expected and if autostart is configured correctly. 

    # virsh pool-info guest_images_dir
  Name:           guest_images_dir
  UUID:           c7466869-e82a-a66c-2187-dc9d6f0877d0
  State:          running
  Persistent:     yes
  Autostart:      yes
  Capacity:       458.39 GB
  Allocation:     197.91 MB
  Available:      458.20 GB

14.2.3. Creating disk-based storage pools using the CLI

In a disk-based storage pool, the pool is based on a disk partition. This is useful, for example, when you want to have an entire disk partition dedicated as virtual machine (VM) storage. You can use the virsh utility to create disk-based storage pools.

Conditions préalables

  • Ensure your hypervisor supports disk-based storage pools: 

    # virsh pool-capabilities | grep "'disk' supported='yes'"

    If the command displays any output, disk-based pools are supported.

  • Prepare a device on which you will base the storage pool. For this purpose, prefer partitions (for example, /dev/sdb1) or LVM volumes. If you provide a VM with write access to an entire disk or block device (for example, /dev/sdb), the VM will likely partition it or create its own LVM groups on it. This can result in system errors on the host.

    However, if you require using an entire block device for the storage pool, Red Hat recommends protecting any important partitions on the device from GRUB’s os-prober function. To do so, edit the /etc/default/grub file and apply one of the following configurations:

    • Disable os-prober. 

      GRUB_DISABLE_OS_PROBER=true

    • Prevent os-prober from discovering a specific partition. For example: 

      GRUB_OS_PROBER_SKIP_LIST="5ef6313a-257c-4d43@/dev/sdb1"
  • Back up any data on the selected storage device before creating a storage pool. Depending on the version of libvirt being used, dedicating a disk to a storage pool may reformat and erase all data currently stored on the disk device.

Procédure

  1. Create a storage pool

    Use the virsh pool-define-as command to define and create a disk-type storage pool. The following example creates a storage pool named guest_images_disk that uses the /dev/sdb device and is mounted on the /dev directory. 

    # virsh pool-define-as guest_images_disk disk --source-format=gpt --source-dev=/dev/sdb --target /dev
Pool guest_images_disk defined

    If you already have an XML configuration of the storage pool you want to create, you can also define the pool based on the XML. For details, see Disk-based storage pool parameters.

  2. Create the storage pool target path

    Use the virsh pool-build command to create a storage pool target path for a pre-formatted file-system storage pool, initialize the storage source device, and define the format of the data. 

    # virsh pool-build guest_images_disk
  Pool guest_images_disk built
    Note

    Building the target path is only necessary for disk-based, file system-based, and logical storage pools. If libvirt detects that the source storage device’s data format differs from the selected storage pool type, the build fails, unless the overwrite option is specified.

  3. Verify that the pool was created

    Use the virsh pool-list command to verify that the pool was created. 

    # virsh pool-list --all

  Name                 State      Autostart
  -----------------------------------------
  default              active     yes
  guest_images_disk    inactive   no

  4. Start the storage pool

    Use the virsh pool-start command to mount the storage pool. 

    # virsh pool-start guest_images_disk
  Pool guest_images_disk started
    Note

    The virsh pool-start command is only necessary for persistent storage pools. Transient storage pools are automatically started when they are created.

  5. [Optional] Turn on autostart

    By default, a storage pool defined with the virsh command is not set to automatically start each time virtualization services start. Use the virsh pool-autostart command to configure the storage pool to autostart. 

    # virsh pool-autostart guest_images_disk
  Pool guest_images_disk marked as autostarted

Vérification

  • Use the virsh pool-info command to verify that the storage pool is in the running state. Check if the sizes reported are as expected and if autostart is configured correctly. 

    # virsh pool-info guest_images_disk
  Name:           guest_images_disk
  UUID:           c7466869-e82a-a66c-2187-dc9d6f0877d0
  State:          running
  Persistent:     yes
  Autostart:      yes
  Capacity:       458.39 GB
  Allocation:     197.91 MB
  Available:      458.20 GB

14.2.4. Creating filesystem-based storage pools using the CLI

When you want to create a storage pool on a file system that is not mounted, use the filesystem-based storage pool. This storage pool is based on a given file-system mountpoint. You can use the virsh utility to create filesystem-based storage pools.

Conditions préalables

  • Ensure your hypervisor supports filesystem-based storage pools: 

    # virsh pool-capabilities | grep "'fs' supported='yes'"

    If the command displays any output, file-based pools are supported.

  • Prepare a device on which you will base the storage pool. For this purpose, prefer partitions (for example, /dev/sdb1) or LVM volumes. If you provide a VM with write access to an entire disk or block device (for example, /dev/sdb), the VM will likely partition it or create its own LVM groups on it. This can result in system errors on the host.

    However, if you require using an entire block device for the storage pool, Red Hat recommends protecting any important partitions on the device from GRUB’s os-prober function. To do so, edit the /etc/default/grub file and apply one of the following configurations:

    • Disable os-prober. 

      GRUB_DISABLE_OS_PROBER=true

    • Prevent os-prober from discovering a specific partition. For example: 

      GRUB_OS_PROBER_SKIP_LIST="5ef6313a-257c-4d43@/dev/sdb1"

Procédure

  1. Create a storage pool

    Use the virsh pool-define-as command to define and create a filesystem-type storage pool. For example, to create a storage pool named guest_images_fs that uses the /dev/sdc1 partition, and is mounted on the /guest_images directory: 

    # virsh pool-define-as guest_images_fs fs --source-dev /dev/sdc1 --target /guest_images
Pool guest_images_fs defined

    If you already have an XML configuration of the storage pool you want to create, you can also define the pool based on the XML. For details, see Filesystem-based storage pool parameters.

  2. Define the storage pool target path

    Use the virsh pool-build command to create a storage pool target path for a pre-formatted file-system storage pool, initialize the storage source device, and define the format of the data. 

    # virsh pool-build guest_images_fs
  Pool guest_images_fs built

# ls -la /guest_images
  total 8
  drwx------.  2 root root 4096 May 31 19:38 .
  dr-xr-xr-x. 25 root root 4096 May 31 19:38 ..

  3. Verify that the pool was created

    Use the virsh pool-list command to verify that the pool was created. 

    # virsh pool-list --all

  Name                 State      Autostart
  -----------------------------------------
  default              active     yes
  guest_images_fs      inactive   no

  4. Start the storage pool

    Use the virsh pool-start command to mount the storage pool. 

    # virsh pool-start guest_images_fs
  Pool guest_images_fs started
    Note

    The virsh pool-start command is only necessary for persistent storage pools. Transient storage pools are automatically started when they are created.

  5. Optional: Turn on autostart

    By default, a storage pool defined with the virsh command is not set to automatically start each time virtualization services start. Use the virsh pool-autostart command to configure the storage pool to autostart. 

    # virsh pool-autostart guest_images_fs
  Pool guest_images_fs marked as autostarted

Vérification

  1. Use the virsh pool-info command to verify that the storage pool is in the running state. Check if the sizes reported are as expected and if autostart is configured correctly. 

    # virsh pool-info guest_images_fs
  Name:           guest_images_fs
  UUID:           c7466869-e82a-a66c-2187-dc9d6f0877d0
  State:          running
  Persistent:     yes
  Autostart:      yes
  Capacity:       458.39 GB
  Allocation:     197.91 MB
  Available:      458.20 GB

  2. Verify there is a lost+found directory in the target path on the file system, indicating that the device is mounted. 

    # mount | grep /guest_images
  /dev/sdc1 on /guest_images type ext4 (rw)

# ls -la /guest_images
  total 24
  drwxr-xr-x.  3 root root  4096 May 31 19:47 .
  dr-xr-xr-x. 25 root root  4096 May 31 19:38 ..
  drwx------.  2 root root 16384 May 31 14:18 lost+found

14.2.5. Creating iSCSI-based storage pools using the CLI

Internet Small Computer Systems Interface (iSCSI) is an IP-based storage networking standard for linking data storage facilities. If you want to have a storage pool on an iSCSI server, you can use the virsh utility to create iSCSI-based storage pools.

Conditions préalables

  • Ensure your hypervisor supports iSCSI-based storage pools: 

    # virsh pool-capabilities | grep "'iscsi' supported='yes'"

    If the command displays any output, iSCSI-based pools are supported.

Procédure

  1. Create a storage pool

    Use the virsh pool-define-as command to define and create an iSCSI-type storage pool. For example, to create a storage pool named guest_images_iscsi that uses the iqn.2010-05.com.example.server1:iscsirhel7guest IQN on the server1.example.com, and is mounted on the /dev/disk/by-path path: 

    # virsh pool-define-as --name guest_images_iscsi --type iscsi --source-host server1.example.com --source-dev iqn.2010-05.com.example.server1:iscsirhel7guest --target /dev/disk/by-path
Pool guest_images_iscsi defined

    If you already have an XML configuration of the storage pool you want to create, you can also define the pool based on the XML. For details, see iSCSI-based storage pool parameters.

  2. Verify that the pool was created

    Use the virsh pool-list command to verify that the pool was created. 

    # virsh pool-list --all

  Name                 State      Autostart
  -----------------------------------------
  default              active     yes
  guest_images_iscsi   inactive   no

  3. Start the storage pool

    Use the virsh pool-start command to mount the storage pool. 

    # virsh pool-start guest_images_iscsi
  Pool guest_images_iscsi started
    Note

    The virsh pool-start command is only necessary for persistent storage pools. Transient storage pools are automatically started when they are created.

  4. [Optional] Turn on autostart

    By default, a storage pool defined with the virsh command is not set to automatically start each time virtualization services start. Use the virsh pool-autostart command to configure the storage pool to autostart. 

    # virsh pool-autostart guest_images_iscsi
  Pool guest_images_iscsi marked as autostarted

Vérification

  • Use the virsh pool-info command to verify that the storage pool is in the running state. Check if the sizes reported are as expected and if autostart is configured correctly. 

    # virsh pool-info guest_images_iscsi
  Name:           guest_images_iscsi
  UUID:           c7466869-e82a-a66c-2187-dc9d6f0877d0
  State:          running
  Persistent:     yes
  Autostart:      yes
  Capacity:       458.39 GB
  Allocation:     197.91 MB
  Available:      458.20 GB

14.2.6. Creating LVM-based storage pools using the CLI

If you want to have a storage pool that is part of an LVM volume group, you can use the virsh utility to create LVM-based storage pools.

Recommendations

Be aware of the following before creating an LVM-based storage pool:

  • LVM-based storage pools do not provide the full flexibility of LVM.
  • libvirt supports thin logical volumes, but does not provide the features of thin storage pools.

  • LVM-based storage pools are volume groups. You can create volume groups using the virsh utility, but this way you can only have one device in the created volume group. To create a volume group with multiple devices, use the LVM utility instead, see How to create a volume group in Linux with LVM.

    For more detailed information about volume groups, refer to the Red Hat Enterprise Linux Logical Volume Manager Administration Guide.

  • LVM-based storage pools require a full disk partition. If you activate a new partition or device using virsh commands, the partition will be formatted and all data will be erased. If you are using a host’s existing volume group, as in these procedures, nothing will be erased.

Conditions préalables

  • Ensure your hypervisor supports LVM-based storage pools: 

    # virsh pool-capabilities | grep "'logical' supported='yes'"

    If the command displays any output, LVM-based pools are supported.

Procédure

  1. Create a storage pool

    Use the virsh pool-define-as command to define and create an LVM-type storage pool. For example, the following command creates a storage pool named guest_images_lvm that uses the lvm_vg volume group and is mounted on the /dev/lvm_vg directory: 

    # virsh pool-define-as guest_images_lvm logical --source-name lvm_vg --target /dev/lvm_vg
Pool guest_images_lvm defined

    If you already have an XML configuration of the storage pool you want to create, you can also define the pool based on the XML. For details, see LVM-based storage pool parameters.

  2. Verify that the pool was created

    Use the virsh pool-list command to verify that the pool was created. 

    # virsh pool-list --all

  Name                   State      Autostart
  -------------------------------------------
  default                active     yes
  guest_images_lvm       inactive   no

  3. Start the storage pool

    Use the virsh pool-start command to mount the storage pool. 

    # virsh pool-start guest_images_lvm
  Pool guest_images_lvm started
    Note

    The virsh pool-start command is only necessary for persistent storage pools. Transient storage pools are automatically started when they are created.

  4. [Optional] Turn on autostart

    By default, a storage pool defined with the virsh command is not set to automatically start each time virtualization services start. Use the virsh pool-autostart command to configure the storage pool to autostart. 

    # virsh pool-autostart guest_images_lvm
  Pool guest_images_lvm marked as autostarted

Vérification

  • Use the virsh pool-info command to verify that the storage pool is in the running state. Check if the sizes reported are as expected and if autostart is configured correctly. 

    # virsh pool-info guest_images_lvm
  Name:           guest_images_lvm
  UUID:           c7466869-e82a-a66c-2187-dc9d6f0877d0
  State:          running
  Persistent:     yes
  Autostart:      yes
  Capacity:       458.39 GB
  Allocation:     197.91 MB
  Available:      458.20 GB

14.2.7. Creating NFS-based storage pools using the CLI

If you want to have a storage pool on a Network File System (NFS) server, you can use the virsh utility to create NFS-based storage pools.

Conditions préalables

  • Ensure your hypervisor supports NFS-based storage pools: 

    # virsh pool-capabilities | grep "<value>nfs</value>"

    If the command displays any output, NFS-based pools are supported.

Procédure

  1. Create a storage pool

    Use the virsh pool-define-as command to define and create an NFS-type storage pool. For example, to create a storage pool named guest_images_netfs that uses a NFS server with IP 111.222.111.222 mounted on the server directory /home/net_mount using the target directory /var/lib/libvirt/images/nfspool: 

    # virsh pool-define-as --name guest_images_netfs --type netfs --source-host='111.222.111.222' --source-path='/home/net_mount' --source-format='nfs' --target='/var/lib/libvirt/images/nfspool'

    If you already have an XML configuration of the storage pool you want to create, you can also define the pool based on the XML. For details, see NFS-based storage pool parameters.

  2. Verify that the pool was created

    Use the virsh pool-list command to verify that the pool was created. 

    # virsh pool-list --all

  Name                 State      Autostart
  -----------------------------------------
  default              active     yes
  guest_images_netfs   inactive   no

  3. Start the storage pool

    Use the virsh pool-start command to mount the storage pool. 

    # virsh pool-start guest_images_netfs
  Pool guest_images_netfs started
    Note

    The virsh pool-start command is only necessary for persistent storage pools. Transient storage pools are automatically started when they are created.

  4. [Optional] Turn on autostart

    By default, a storage pool defined with the virsh command is not set to automatically start each time virtualization services start. Use the virsh pool-autostart command to configure the storage pool to autostart. 

    # virsh pool-autostart guest_images_netfs
  Pool guest_images_netfs marked as autostarted

Vérification

  • Use the virsh pool-info command to verify that the storage pool is in the running state. Check if the sizes reported are as expected and if autostart is configured correctly. 

    # virsh pool-info guest_images_netfs
  Name:           guest_images_netfs
  UUID:           c7466869-e82a-a66c-2187-dc9d6f0877d0
  State:          running
  Persistent:     yes
  Autostart:      yes
  Capacity:       458.39 GB
  Allocation:     197.91 MB
  Available:      458.20 GB

14.2.8. Creating SCSI-based storage pools with vHBA devices using the CLI

If you want to have a storage pool on a Small Computer System Interface (SCSI) device, your host must be able to connect to the SCSI device using a virtual host bus adapter (vHBA). You can then use the virsh utility to create SCSI-based storage pools.

Conditions préalables

  • Ensure your hypervisor supports SCSI-based storage pools: 

    # virsh pool-capabilities | grep "'scsi' supported='yes'"

    If the command displays any output, SCSI-based pools are supported.

  • Before creating a SCSI-based storage pools with vHBA devices, create a vHBA. For more information, see Creating vHBAs.

Procédure

  1. Create a storage pool

    Use the virsh pool-define-as command to define and create SCSI storage pool using a vHBA. For example, the following creates a storage pool named guest_images_vhba that uses a vHBA identified by the scsi_host3 parent adapter, world-wide port number 5001a4ace3ee047d, and world-wide node number 5001a4a93526d0a1. The storage pool is mounted on the /dev/disk/ directory: 

    # virsh pool-define-as guest_images_vhba scsi --adapter-parent scsi_host3 --adapter-wwnn 5001a4a93526d0a1 --adapter-wwpn 5001a4ace3ee047d --target /dev/disk/
Pool guest_images_vhba defined

    If you already have an XML configuration of the storage pool you want to create, you can also define the pool based on the XML. For details, see Parameters for SCSI-based storage pools with vHBA devices.

  2. Verify that the pool was created

    Use the virsh pool-list command to verify that the pool was created. 

    # virsh pool-list --all

  Name                 State      Autostart
  -----------------------------------------
  default              active     yes
  guest_images_vhba    inactive   no

  3. Start the storage pool

    Use the virsh pool-start command to mount the storage pool. 

    # virsh pool-start guest_images_vhba
  Pool guest_images_vhba started
    Note

    The virsh pool-start command is only necessary for persistent storage pools. Transient storage pools are automatically started when they are created.

  4. [Optional] Turn on autostart

    By default, a storage pool defined with the virsh command is not set to automatically start each time virtualization services start. Use the virsh pool-autostart command to configure the storage pool to autostart. 

    # virsh pool-autostart guest_images_vhba
  Pool guest_images_vhba marked as autostarted

Vérification

  • Use the virsh pool-info command to verify that the storage pool is in the running state. Check if the sizes reported are as expected and if autostart is configured correctly. 

    # virsh pool-info guest_images_vhba
  Name:           guest_images_vhba
  UUID:           c7466869-e82a-a66c-2187-dc9d6f0877d0
  State:          running
  Persistent:     yes
  Autostart:      yes
  Capacity:       458.39 GB
  Allocation:     197.91 MB
  Available:      458.20 GB

14.2.9. Deleting storage pools using the CLI

To remove a storage pool from your host system, you must stop the pool and remove its XML definition.

Procédure

  1. List the defined storage pools using the virsh pool-list command. 

    # virsh pool-list --all
Name                 State      Autostart
-------------------------------------------
default              active     yes
Downloads            active     yes
RHEL-Storage-Pool   active     yes

  2. Stop the storage pool you want to delete using the virsh pool-destroy command. 

    # virsh pool-destroy Downloads
Pool Downloads destroyed

  3. Optional: For some types of storage pools, you can remove the directory where the storage pool resides using the virsh pool-delete command. Note that to do so, the directory must be empty. 

    # virsh pool-delete Downloads
Pool Downloads deleted

  4. Delete the definition of the storage pool using the virsh pool-undefine command. 

    # virsh pool-undefine Downloads
Pool Downloads has been undefined

Vérification

  • Confirm that the storage pool was deleted. 

    # virsh pool-list --all
Name                 State      Autostart
-------------------------------------------
default              active     yes
rhel-Storage-Pool   active     yes