Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

23.19. Storage Volumes

A storage volume will generally be either a file or a device node; since 1.2.0, an optional output-only attribute type lists the actual type (file, block, dir, network, or netdir),

23.19.1. General Metadata

The top section of the <volume> element contains information known as metadata as shown in this XML example: 
         
      ...
      <volume type='file'>
        <name>sparse.img</name>
        <key>/var/lib/libvirt/images/sparse.img</key>
        <allocation>0</allocation>
        <capacity unit="T">1</capacity>
        ...
      </volume>

Figure 23.83. General metadata for storage volumes

The table (Table 23.30, “Volume child elements”) explains the child elements that are valid for the parent <volume> element:

Table 23.30. Volume child elements

Element Description
<name> Provides a name for the storage volume which is unique to the storage pool. This is mandatory when defining a storage volume.
<key> Provides an identifier for the storage volume which identifies a single storage volume. In some cases it is possible to have two distinct keys identifying a single storage volume. This field cannot be set when creating a storage volume as it is always generated.
<allocation> Provides the total storage allocation for the storage volume. This may be smaller than the logical capacity if the storage volume is sparsely allocated. It may also be larger than the logical capacity if the storage volume has substantial metadata overhead. This value is in bytes. If omitted when creating a storage volume, the storage volume will be fully allocated at time of creation. If set to a value smaller than the capacity, the storage pool has the option of deciding to sparsely allocate a storage volume or not. Different types of storage pools may treat sparse storage volumes differently. For example, a logical pool will not automatically expand a storage volume's allocation when it gets full; the user is responsible for configuring it or configuring dmeventd to do so automatically. By default, this is specified in bytes. See Note
<capacity> Provides the logical capacity for the storage volume. This value is in bytes by default, but a <unit> attribute can be specified with the same semantics as for <allocation> described in Note. This is compulsory when creating a storage volume.
<source> Provides information about the underlying storage allocation of the storage volume. This may not be available for some storage pool types.
<target> Provides information about the representation of the storage volume on the local host physical machine.

Note

When necessary, an optional attribute unit can be specified to adjust the passed value. This attribute can be used with the elements <allocation> and <capacity>. Accepted values for the attribute unit include:
  • B or bytes for bytes
  • KB for kilobytes
  • K or KiB for kibibytes
  • MB for megabytes
  • M or MiB for mebibytes
  • GB for gigabytes
  • G or GiB for gibibytes
  • TB for terabytes
  • T or TiB for tebibytes
  • PB for petabytes
  • P or PiB for pebibytes
  • EB for exabytes
  • E or EiB for exbibytes

23.19.2. Setting Target Elements

The <target> element can be placed in the <volume> top level element. It is used to describe the mapping that is done on the storage volume into the host physical machine filesystem. This element can take the following child elements: 
         
       <target>
          <path>/var/lib/libvirt/images/sparse.img</path>
          <format type='qcow2'/>
          <permissions>
            <owner>107</owner>
            <group>107</group>
            <mode>0744</mode>
            <label>virt_image_t</label>
          </permissions>
          <compat>1.1</compat>
          <features>
            <lazy_refcounts/>
          </features>
        </target>

Figure 23.84. Target child elements

The specific child elements for <target> are explained in Table 23.31, “Target child elements”:

Table 23.31. Target child elements

Element Description
<path> Provides the location at which the storage volume can be accessed on the local filesystem, as an absolute path. This is a read-only attribute, and should not be specified when creating a volume.
<format> Provides information about the pool specific volume format. For disk-based storage pools, it will provide the partition type. For filesystem or directory-based storage pools, it will provide the file format type, (such as cow, qcow, vmdk, raw). If omitted when creating a storage volume, the storage pool's default format will be used. The actual format is specified by the type attribute. See the sections on the specific storage pools in Section 13.2, “Using Storage Pools” for the list of valid values.
<permissions> Provides information about the default permissions to use when creating storage volumes. This is currently only useful for directory or filesystem-based storage pools, where the storage volumes allocated are simple files. For storage pools where the storage volumes are device nodes, the hot-plug scripts determine permissions. It contains four child elements. The <mode> element contains the octal permission set. The <owner> element contains the numeric user ID. The <group> element contains the numeric group ID. The <label> element contains the MAC (for example, SELinux) label string.
<compat> Specify compatibility level. So far, this is only used for <type='qcow2'> volumes. Valid values are <compat>0.10</compat> for qcow2 (version 2) and <compat>1.1</compat> for qcow2 (version 3) so far for specifying the QEMU version the images should be compatible with. If the <feature> element is present, <compat>1.1</compat> is used. If omitted, qemu-img default is used.
<features> Format-specific features. Presently is only used with <format type='qcow2'/> (version 3). Valid sub-elements include <lazy_refcounts/>. This reduces the amount of metadata writes and flushes, and therefore improves initial write performance. This improvement is seen especially for writethrough cache modes, at the cost of having to repair the image after a crash, and allows delayed reference counter updates. It is recommended to use this feature with qcow2 (version 3), as it is faster when this is implemented.

23.19.3. Setting Backing Store Elements

A single <backingStore> element is contained within the top level <volume> element. This tag is used to describe the optional copy-on-write backing store for the storage volume. It can contain the following child elements: 
            
        <backingStore>
          <path>/var/lib/libvirt/images/master.img</path>
          <format type='raw'/>
          <permissions>
            <owner>107</owner>
            <group>107</group>
            <mode>0744</mode>
            <label>virt_image_t</label>
          </permissions>
        </backingStore>

Figure 23.85. Backing store child elements

Table 23.32. Backing store child elements

Element Description
<path> Provides the location at which the backing store can be accessed on the local filesystem, as an absolute path. If omitted, there is no backing store for this storage volume.
<format> Provides information about the pool specific backing store format. For disk-based storage pools it will provide the partition type. For filesystem or directory-based storage pools it will provide the file format type (such as cow, qcow, vmdk, raw). The actual format is specified via the <type> attribute. Consult the pool-specific docs for the list of valid values. Most file formats require a backing store of the same format, however, the qcow2 format allows a different backing store format.
<permissions> Provides information about the permissions of the backing file. It contains four child elements. The <owner> element contains the numeric user ID. The <group> element contains the numeric group ID. The <label> element contains the MAC (for example, SELinux) label string.