13.2. Using Storage Pools

Procedure 13.2. Creating Storage Pools with virsh

1. Read recommendations and ensure that all prerequisites are met

   For some storage pools, this guide recommends that you follow certain practices. In addition, there are prerequisites for some types of storage pools. To see the recommendations and prerequisites, if any, see Section 13.2.3, “Storage Pool Specifics”.

2. Define the storage pool

   Storage pools can be persistent or transient. A persistent storage pool survives a system restart of the host machine. A transient storage pool only exists until the host reboots.
   Do one of the following:
   • Define the storage pool using an XML file.
     a. Create a temporary XML file containing the storage pool information required for the new device.
     The XML file must contain specific fields, based on the storage pool type. For more information, see Section 13.2.3, “Storage Pool Specifics”.
     The following shows an example a storage pool definition XML file. In this example, the file is saved to ~/guest_images.xml

     <pool type='fs'>
       <name>guest_images_fs</name>
       <source>
         <device path='/dev/sdc1'/>
       </source>
       <target>
         <path>/guest_images</path>
       </target>
     </pool> 

     b. Use the virsh pool-define command to create a persistent storage pool or the virsh pool-create command to create and start a transient storage pool.

     # virsh pool-define ~/guest_images.xml
     Pool defined from guest_images_fs
     

     or

     # virsh pool-create ~/guest_images.xml
     Pool created from guest_images_fs

     c. Delete the XML file created in step a.
   • Use the virsh pool-define-as command to create a persistent storage pool or the virsh pool-create-as command to create a transient storage pool.
     The following examples create a persistent and then a transient filesystem-based storage pool mapped to /dev/sdc1 from the /guest_images directory.

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

     or

     # virsh pool-create-as guest_images_fs fs - - /dev/sdc1 - "/guest_images"
     Pool guest_images_fs created

     Note

     When using the virsh interface, option names in the commands are optional. If option names are not used, use dashes for fields that do not need to be specified.

3. Verify that the pool was created

   List all existing storage pools using the virsh pool-list --all.

   # virsh pool-list --all
   Name                 State      Autostart
   -----------------------------------------
   default              active     yes
   guest_images_fs      inactive   no
   

4. 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. Then use the virsh pool-list command to ensure that the storage pool is listed.

   # 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 ..
   # virsh pool-list --all
   Name                 State      Autostart
   -----------------------------------------
   default              active     yes
   guest_images_fs      inactive   no
   

   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.

5. Start the storage pool

   Use the virsh pool-start command to prepare the source device for usage.
   The action taken depends on the storage pool type. For example, for a file system-based storage pool, the virsh pool-start command mounts the file system. For an LVM-based storage pool, the virsh pool-start command activates the volume group usng the vgchange command.
   Then use the virsh pool-list command to ensure that the storage pool is active.

   # virsh pool-start guest_images_fs
   Pool guest_images_fs started
   # virsh pool-list --all
   Name                 State      Autostart
   -----------------------------------------
   default              active     yes
   guest_images_fs      active     no
   

   Note

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

6. Turn on autostart (optional)

   By default, a storage pool defined with virsh is not set to automatically start each time libvirtd starts. You can configure the storage pool to start automatically using the virsh pool-autostart command.

   # virsh pool-autostart guest_images_fs
   Pool guest_images_fs marked as autostarted
   
   # virsh pool-list --all
   Name                 State      Autostart
   -----------------------------------------
   default              active     yes
   guest_images_fs      active     yes
   

   The storage pool is now automatically started each time libvirtd starts.

7. Verify the storage pool

   Verify that the storage pool was created correctly, the sizes reported are as expected, and the state is reported as running. Verify there is a "lost+found" directory in the target path on the file system, indicating that the device is mounted.

   # 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
   # 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
   

Procedure 13.3. Creating Storage Pools with Virtual Machine Manager

1. Prepare the medium on which the storage pool will be created

   This will differ for different types of storage pools. For details, see Section 13.2.3, “Storage Pool Specifics”.
   In this example, you may need to relabel the disk with a GUID Partition Table.

2. Open the storage settings

   1. In Virtual Machine Manager, select the host connection you want to configure.
      Open the Edit menu and select Connection Details.
   2. Click the Storage tab in the Connection Details window.
      

      Figure 13.1. Storage tab

3. Create a new storage pool

   Note

   Using Virtual Machine Manager, you can only create persistent storage pools. Transient storage pools can only be created using virsh.

   1. Add a new storage pool (part 1)

      Click the button at the bottom of the window. The Add a New Storage Pool wizard appears.
      Enter a Name for the storage pool. This example uses the name guest_images_fs.
      Select a storage pool type to create from the Type drop-down list. This example uses fs: Pre-Formatted Block Device.
      

      Figure 13.2. Storage pool name and type

      Click the Forward button to continue.

   2. Add a new pool (part 2)

      

      Figure 13.3. Storage pool path

      Configure the storage pool with the relevant parameters. For information on the parameters for each type of storage pool, see Section 13.2.3, “Storage Pool Specifics”.
      For some types of storage pools, a Build Pool check box appears in the dialog. If you want to build the storage pool from the storage, check the Build Pool check box.
      Verify the details and click the Finish button to create the storage pool.

Procedure 13.4. Preparing a Gluster server

1. Obtain the IP address of the Gluster server by listing its status with the following command:

   # gluster volume status
   Status of volume: gluster-vol1
   Gluster process						Port	Online	Pid
   ------------------------------------------------------------------------------
   Brick 222.111.222.111:/gluster-vol1 			49155	Y	18634
   
   Task Status of Volume gluster-vol1
   ------------------------------------------------------------------------------
   There are no active volume tasks
   

2. If not installed, install the glusterfs-fuse package.
3. If not enabled, enable the virt_use_fusefs boolean. Check that it is enabled.

   # setsebool virt_use_fusefs on
   # getsebool virt_use_fusefs
   virt_use_fusefs --> on
   

Procedure 13.5. Creating an iSCSI target

1. Install the targetcli package

   # yum install targetcli

2. Launch the targetcli command set

   # targetcli

3. Create storage objects

   Create three storage objects, using a storage pool.
   1. Create a block storage object
      1. Navigate to the /backstores/block directory.
      2. Run the create command.

         # create [block-name][filepath]

         For example:

         # create block1 dev=/dev/sdb1

   2. Create a fileio object
      1. Navigate to the /fileio directory.
      2. Run the create command.

         # create [fileio-name][image-name] [image-size]

         For example:

         # create fileio1 /foo.img 50M

   3. Create a ramdisk object
      1. Navigate to the /ramdisk directory.
      2. Run the create command.

         # create [ramdisk-name] [ramdisk-size]

         For example:

         # create ramdisk1 1M

   4. Make note of the names of the disks created in this step. They will be used later.

4. Create an iSCSI target

   1. Navigate to the /iscsi directory.
   2. Create the target in one of two ways:
      • Run the create command with no parameters.
        The iSCSI qualified name (IQN) is generated automatically.
      • Run the create command specifying the IQN and the server. For example:

        # create iqn.2010-05.com.example.server1:iscsirhel7guest

5. Define the portal IP address

   To export the block storage over iSCSI, the portal, LUNs, and access control lists ACLs must first be configured.
   The portal includes the IP address and TCP that the target monitors, and the initiators to which it connects. iSCSI uses port 3260. This port is configured by default.
   To connect to port 3260:
   1. Navigate to the /tpg directory.
   2. Run the following:

      # portals/ create

      This command makes all available IP addresses listening to port 3260.
      If you want only a single IP address to listen to port 3260, add the IP address to the end of the command. For example:

      # portals/ create 143.22.16.33

6. Configure the LUNs and assign storage objects to the fabric

   This step uses the storage objects created in creating storage objects.
   1. Navigate to the luns directory for the TPG created in defining the portal IP address. For example:

      # iscsi>iqn.iqn.2010-05.com.example.server1:iscsirhel7guest

   2. Assign the first LUN to the ramdisk. For example:

      # create /backstores/ramdisk/ramdisk1

   3. Assign the second LUN to the block disk. For example:

      # create /backstores/block/block1

   4. Assign the third LUN to the fileio disk. For example:

      # create /backstores/fileio/fileio1

   5. List the resulting LUNs.

      /iscsi/iqn.20...csirhel7guest ls
      
      o- tgp1 ............................................................[enabled, auth]
        o- acls...................................................................[0 ACL]
        o- luns..................................................................[3 LUNs]
        | o- lun0......................................................[ramdisk/ramdisk1]
        | o- lun1...............................................[block/block1 (dev/vdb1)]
        | o- lun2................................................[fileio/file1 (foo.img)]
        o- portals.............................................................[1 Portal]
          o- IP-ADDRESS:3260.........................................................[OK]
      

7. Create ACLs for each initiator

   Enable authentication when the initiator connects. You can also resrict specified LUNs to specified intiators. Targets and initiators have unique names. iSCSI initiators use IQNs.
   1. Find the IQN of the iSCSI initiator, using the initiator name. For example:

      # cat /etc/iscsi/initiator2.iscsi
      InitiatorName=create iqn.2010-05.com.example.server1:iscsirhel7guest

      This IQN is used to create the ACLs.
   2. Navigate to the acls directory.
   3. Create ACLs by doing one of the following:
      • Create ACLS for all LUNs and initiators by running the create command with no parameters.

        # create

      • Create an ACL for a specific LUN and initiator, run the create command specifying the IQN of the iSCSI intiator. For example:

        # create iqn.2010-05.com.example.server1:888

      • Configure the kernel target to use a single user ID and password for all initiators.

        # set auth userid=user_ID
        # set auth password=password
        # set attribute authentication=1
        # set attribute generate_node_acls=1

   After completing this procedure, continue by securing the storage pool.

8. Save the configuration

   Make the configuration persistent by overwriting the previous boot settings.

   # saveconfig

9. Enable the service

   To apply the saved settings on the next boot, enable the service.

   # systemctl enable target.service

Procedure 13.6. Configuring a logical volume on a RAID array

1. Create a RAID5 array

   For information on creating a RAID5 array, see the Red Hat Enterprise Linux 7 Storage Administration Guide.

2. Create an LVM logical volume on the RAID5 array

   For information on creating an LVM logical volume on a RAID5 array, see the Red Hat Enterprise Linux 7 Logical Volume Manager Administration Guide.

Procedure 13.7. Testing discoverability

• Ensure that the new iSCSI device is discoverable.

  # iscsiadm --mode discovery --type sendtargets --portal server1.example.com
  143.22.16.33:3260,1 iqn.2010-05.com.example.server1:iscsirhel7guest

Procedure 13.8. Testing device attachment

1. Attach the new iSCSI device

   Attach the new device (iqn.2010-05.com.example.server1:iscsirhel7guest) to determine whether the device can be attached.

   # iscsiadm -d2 -m node --login
   scsiadm: Max file limits 1024 1024
   
   Logging in to [iface: default, target: iqn.2010-05.com.example.server1:iscsirhel7guest, portal: 143.22.16.33,3260]
   Login to [iface: default, target: iqn.2010-05.com.example.server1:iscsirhel7guest, portal: 143.22.16.33,3260] successful.
   

2. Detach the device

   # iscsiadm -d2 -m node --logout
   scsiadm: Max file limits 1024 1024
   
   Logging out of session [sid: 2, target: iqn.2010-05.com.example.server1:iscsirhel7guest, portal: 143.22.16.33,3260
   Logout of [sid: 2, target: iqn.2010-05.com.example.server1:iscsirhel7guest, portal: 143.22.16.33,3260] successful.

Procedure 13.9. Using libvirt secrets for an iSCSI storage pool

1. Create a libvirt secret file

   Create a libvirt secret file with a challenge-handshake authentication protocol (CHAP) user name. For example:

   <secret ephemeral='no' private='yes'>
       <description>Passphrase for the iSCSI example.com server</description>
       <usage type='iscsi'>
           <target>iscsirhel7secret</target>
       </usage>
   </secret>    

2. Define the secret

   # virsh secret-define secret.xml

3. Verify the UUID

   # virsh secret-list
   UUID                                  Usage
   --------------------------------------------------------------------------------
   2d7891af-20be-4e5e-af83-190e8a922360  iscsi iscsirhel7secret

4. Assign a secret to the UID

   Use the following commands to assign a secret to the UUID in the output of the previous step. This ensures that the CHAP username and password are in a libvirt-controlled secret list.

   # MYSECRET=`printf %s "password123" | base64`
   # virsh secret-set-value 2d7891af-20be-4e5e-af83-190e8a922360 $MYSECRET

5. Add an authentication entry to the storage pool

   Modify the <source> entry in the storage pool's XML file using virsh edit, and add an <auth> element, specifying authentication type, username, and secret usage.
   For example:

   <pool type='iscsi'>
     <name>iscsirhel7pool</name>
       <source>
          <host name='192.168.122.1'/>
          <device path='iqn.2010-05.com.example.server1:iscsirhel7guest'/>
          <auth type='chap' username='redhat'>
             <secret usage='iscsirhel7secret'/>
          </auth>
       </source>
     <target>
       <path>/dev/disk/by-path</path>
     </target>
   </pool>     

   Note

   The <auth> sub-element exists in different locations within the guest XML's <pool> and <disk> elements. For a <pool>, <auth> is specified within the <source> element, as this describes where to find the pool sources, since authentication is a property of some pool sources (iSCSI and RBD). For a <disk>, which is a sub-element of a domain, the authentication to the iSCSI or RBD disk is a property of the disk.

   In addition, the <auth> sub-element for a disk differs from that of a storage pool.

   <auth username='redhat'>
     <secret type='iscsi' usage='iscsirhel7secret'/>
   </auth>  

6. Activate the changes

   The storage pool must be started to activate these changes.
   • If the storage pool has not yet been started, follow the steps in Creating Storage Pools with virsh to define and start the storage pool.
   • If the pool has already been started, enter the following commands to stop and restart the storage pool:

     # virsh pool-destroy iscsirhel7pool
     # virsh pool-start iscsirhel7pool

Procedure 13.10. Creating a vHBA

1. Locate HBAs on the host system

   To locate the HBAs on your host system, use the virsh nodedev-list --cap vports command.
   The following example shows a host that has two HBAs that support vHBA:

   # virsh nodedev-list --cap vports
   scsi_host3
   scsi_host4
   

2. Check the HBA's details

   Use the virsh nodedev-dumpxml HBA_device command to see the HBA's details.

   # virsh nodedev-dumpxml scsi_host3

   The output from the command lists the <name>, <wwnn>, and <wwpn> fields, which are used to create a vHBA. <max_vports> shows the maximum number of supported vHBAs. For example:

   <device>
     <name>scsi_host3</name>
     <path>/sys/devices/pci0000:00/0000:00:04.0/0000:10:00.0/host3</path>
     <parent>pci_0000_10_00_0</parent>
     <capability type='scsi_host'>
       <host>3</host>
       <unique_id>0</unique_id>
       <capability type='fc_host'>
         <wwnn>20000000c9848140</wwnn>
         <wwpn>10000000c9848140</wwpn>
         <fabric_wwn>2002000573de9a81</fabric_wwn>
       </capability>
       <capability type='vport_ops'>
         <max_vports>127</max_vports>
         <vports>0</vports>
       </capability>
     </capability>
   </device>   

   In this example, the <max_vports> value shows there are a total 127 virtual ports available for use in the HBA configuration. The <vports> value shows the number of virtual ports currently being used. These values update after creating a vHBA.

3. Create a vHBA host device

   Create an XML file similar to one of the following for the vHBA host. In this examples, the file is named vhba_host3.xml.
   This example uses scsi_host3 to describe the parent vHBA.

   # cat vhba_host3.xml
   <device>
     <parent>scsi_host3</parent>
     <capability type='scsi_host'>
       <capability type='fc_host'>
       </capability>
     </capability>
   </device>   

   This example uses a WWNN/WWPN pair to describe the parent vHBA.

   # cat vhba_host3.xml
   <device>
     <name>vhba</name>
     <parent wwnn='20000000c9848140' wwpn='10000000c9848140'/>
     <capability type='scsi_host'>
       <capability type='fc_host'>
       </capability>
     </capability>
   </device>   

   Note

   The WWNN and WWPN values must match those in the HBA details seen in Procedure 13.10, “Creating a vHBA”.
   The <parent> field specifies the HBA device to associate with this vHBA device. The details in the <device> tag are used in the next step to create a new vHBA device for the host. For more information on the nodedev XML format, see the libvirt upstream pages.

4. Create a new vHBA on the vHBA host device

   To create a vHBA on the basis of vhba_host3, use the virsh nodedev-create command:

   # virsh nodedev-create vhba_host3.xml
   Node device scsi_host5 created from vhba_host3.xml

5. Verify the vHBA

   Verify the new vHBA's details (scsi_host5) with the virsh nodedev-dumpxml command:

   # virsh nodedev-dumpxml scsi_host5
   <device>
     <name>scsi_host5</name>
     <path>/sys/devices/pci0000:00/0000:00:04.0/0000:10:00.0/host3/vport-3:0-0/host5</path>
     <parent>scsi_host3</parent>
     <capability type='scsi_host'>
       <host>5</host>
       <unique_id>2</unique_id>
       <capability type='fc_host'>
         <wwnn>5001a4a93526d0a1</wwnn>
         <wwpn>5001a4ace3ee047d</wwpn>
         <fabric_wwn>2002000573de9a81</fabric_wwn>
       </capability>
     </capability>
   </device>  

1. List the defined storage pools:

   # virsh pool-list --all
   Name                 State      Autostart
   -----------------------------------------
   default              active     yes
   guest_images_pool    active     yes
   

2. Stop the storage pool you want to delete.

   # virsh pool-destroy guest_images_disk

3. (Optional) For some types of storage pools, you can optionally remove the directory where the storage pool resides:

   # virsh pool-delete guest_images_disk

4. Remove the storage pool's definition.

   # virsh pool-undefine guest_images_disk

5. Confirm the pool is undefined:

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

1. Select the storage pool you want to delete in the storage pool list in the Storage tab of the Connection Details window.
2. Click at the bottom of the Storage window. This stops the storage pool and releases any resources in use by it.
3. Click .

   Note

   The icon is only enabled if the storage pool is stopped.
   The storage pool is deleted.