Storage Management

This page describes the storage management capabilities in libvirt.

Core concepts
Storage pool XML
Storage volume XML
Storage backend drivers
Core concepts

The storage management APIs are based around 2 core concepts
1. Volume - a single storage volume which can be assigned to a guest, or used for creating further pools. A volume is either a block device, a raw file, or a special format file.
2. Pool - provides a means for taking a chunk of storage and carving it up into volumes. A pool can be used to manage things such as a physical disk, a NFS server, a iSCSI target, a host adapter, an LVM group.
These two concepts are mapped through to two libvirt objects, a virStorageVolPtr and a virStoragePoolPtr, each with a collection of APIs for their management.

Storage pool XML

Although all storage pool backends share the same public APIs and XML format, they have varying levels of capabilities. Some may allow creation of volumes, others may only allow use of pre-existing volumes. Some may have constraints on volume size, or placement.

The is the top level tag for a storage pool document is 'pool'. It has a single attribute type, which is one of dir, fs,netfs,disk,iscsi, logical. This corresponds to the storage backend drivers listed further along in this document.

First level elements

name

Providing a name for the pool which is unique to the host. This is mandatory when defining a pool

uuid

Providing an identifier for the pool which is globally unique. This is optional when defining a pool, a UUID will be generated if omitted

allocation

Providing the total storage allocation for the pool. This may be larger than the sum of the allocation of all volumes due to metadata overhead. This value is in bytes. This is not applicable when creating a pool.

capacity

Providing the total storage capacity for the pool. Due to underlying device constraints it may not be possible to use the full capacity for storage volumes. This value is in bytes. This is not applicable when creating a pool.

available

Providing the free space available for allocating new volumes in the pool. Due to underlying device constraints it may not be possible to allocate the entire free space to a single volume. This value is in bytes. This is not applicable when creating a pool.

source

Provides information about the source of the pool, such as the underlying host devices, or remote server

target

Provides information about the representation of the pool on the local host.

Source elements

device

Provides the source for pools backed by physical devices. May be repeated multiple times depending on backend driver. Contains a single attribute path which is the fully qualified path to the block device node.

directory

Provides the source for pools backed by directories. May only occur once. Contains a single attribute path which is the fully qualified path to the block device node.

host

Provides the source for pools backed by storage from a remote server. Will be used in combination with a directory or device element. Contains an attribute name which is the hostname or IP address of the server. May optionally contain a port attribute for the protocol specific port number.

format

Provides information about the format of the pool. This contains a single attribute type whose value is backend specific. This is typically used to indicate filesystem type, or network filesystem type, or partition table type, or LVM metadata type. All drivers are required to have a default value for this, so it is optional.

Target elements

path

Provides the location at which the pool will be mapped into the local filesystem namespace. For a filesystem/directory based pool it will be the name of the directory in which volumes will be created. For device based pools it will be the name of the directory in which devices nodes exist. For the latter /dev/ may seem like the logical choice, however, devices nodes there are not guaranteed stable across reboots, since they are allocated on demand. It is preferable to use a stable location such as one of the /dev/disk/by-{path,id,uuid,label locations.

permissions

Provides information about the default permissions to use when creating volumes. This is currently only useful for directory or filesystem based pools, where the volumes allocated are simple files. For pools where the volumes are device nodes, the hotplug scripts determine permissions. It contains 4 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 (eg SELinux) label string.

Device extents

If a storage pool exposes information about its underlying placement / allocation scheme, the device element within the source element may contain information about its available extents. Some pools have a constraint that a volume must be allocated entirely within a single constraint (eg disk partition pools). Thus the extent information allows an application to determine the maximum possible size for a new volume

For storage pools supporting extent information, within each device element there will be zero or more freeExtent elements. Each of these elements contains two attributes, start and end which provide the boundaries of the extent on the device, measured in bytes.

Storage volume XML

A storage volume will be either a file or a device node.

First level elements

name

Providing a name for the pool which is unique to the host. This is mandatory when defining a pool

uuid

Providing an identifier for the pool which is globally unique. This is optional when defining a pool, a UUID will be generated if omitted

allocation

Providing the total storage allocation for the volume. This may be smaller than the logical capacity if the volume is sparsely allocated. It may also be larger than the logical capacity if the volume has substantial metadata overhead. This value is in bytes. If omitted when creating a volume, the volume will be fully allocated at time of creation. If set to a value smaller than the capacity, the pool has the option of deciding to sparsely allocate a volume. It does not have to honour requests for sparse allocation though.

capacity

Providing the logical capacity for the volume. This value is in bytes. This is compulsory when creating a volume

source

Provides information about the underlying storage allocation of the volume. This may not be available for some pool types.

target

Provides information about the representation of the volume on the local host.

Target elements

path

Provides the location at which the pool will be mapped into the local filesystem namespace. For a filesystem/directory based pool it will be the name of the directory in which volumes will be created. For device based pools it will be the name of the directory in which devices nodes exist. For the latter /dev/ may seem like the logical choice, however, devices nodes there are not guaranteed stable across reboots, since they are allocated on demand. It is preferrable to use a stable location such as one of the /dev/disk/by-{path,id,uuid,label locations.

format

Provides information about the pool specific volume format. For disk pools it will provide the partition type. For filesystem or directory pools it will provide the file format type, eg cow, qcow, vmdk, raw. If omitted when creating a volume, the pool's default format will be used. The actual format is specified via the type. Consult the pool-specific docs for the list of valid values.

permissions

Provides information about the default permissions to use when creating volumes. This is currently only useful for directory or filesystem based pools, where the volumes allocated are simple files. For pools where the volumes are device nodes, the hotplug scripts determine permissions. It contains 4 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 (eg SELinux) label string.

Storage backend drivers

This section illustrates the capabilities / format for each of the different backend storage pool drivers

Directory pool

A pool with a type of dir provides the means to manage files within a directory. The files can be fully allocated raw files, sparsely allocated raw files, or one of the special disk formats such as qcow,qcow2,vmdk, cow, etc as supported by the qemu-img program. If the directory does not exist at the time the pool is defined, the build operation can be used to create it.

Example pool input definition
```
<pool type="dir">
  <name>virtimages</name>
  <target>
    <path>/var/lib/virt/images</path>
  </target>
</pool>
```
Valid pool format types

The directory pool does not use the pool format type element.

Valid volume format types

One of the following options:
- raw: a plain file
- bochs: Bochs disk image format
- cloop: compressed loopback disk image format
- cow: User Mode Linux disk image format
- dmg: Mac disk image format
- iso: CDROM disk image format
- qcow: QEMU v1 disk image format
- qcow2: QEMU v2 disk image format
- vmdk: VMWare disk image format
- vpc: VirtualPC disk image format
When listing existing volumes all these formats are supported natively. When creating new volumes, only a subset may be available. The raw type is guaranteed always available. The qcow2 type can be created if either qemu-img or qcow-create tools are present. The others are dependent on support of the qemu-img tool.
Filesystem pool

This is a variant of the directory pool. Instead of creating a directory on an existing mounted filesystem though, it expects a source block device to be named. This block device will be mounted and files managed in the directory of its mount point. It will default to allowing the kernel to automatically discover the filesystem type, though it can be specified manually if required.

Example pool input
```
<pool type="fs">
  <name>virtimages</name>
  <source>
    <device path="/dev/VolGroup00/VirtImages"/>
  </source>
  <target>
    <path>/var/lib/virt/images</path>
  </target>
</pool>
```
Valid pool format types

The filesystem pool supports the following formats:
- auto - automatically determine format
- ext2
- ext3
- ext4
- ufs
- iso9660
- udf
- gfs
- gfs2
- vfat
- hfs+
- xfs
Valid volume format types

The valid volume types are the same as for the directory pool type.

Network filesystem pool

This is a variant of the filesystem pool. Instead of requiring a local block device as the source, it requires the name of a host and path of an exported directory. It will mount this network filesystem and manage files within the directory of its mount point. It will default to using NFS as the protocol.

Example pool input
```
<pool type="netfs">
  <name>virtimages</name>
  <source>
    <host name="nfs.example.com"/>
    <dir path="/var/lib/virt/images"/>
  </source>
  <target>
    <path>/var/lib/virt/images</path>
  </target>
</pool>
```
Valid pool format types

The network filesystem pool supports the following formats:
- auto - automatically determine format
- nfs
Valid volume format types

The valid volume types are the same as for the directory pool type.

Logical volume pools

This provides a pool based on an LVM volume group. For a pre-defined LVM volume group, simply providing the group name is sufficient, while to build a new group requires providing a list of source devices to serve as physical volumes. Volumes will be allocated by carving out chunks of storage from the volume group.

Example pool input
```
<pool type="logical">
  <name>HostVG</name>
  <source>
    <device path="/dev/sda1"/>
    <device path="/dev/sdb1"/>
    <device path="/dev/sdc1"/>
  </source>
  <target>
    <path>/dev/HostVG</path>
  </target>
</pool>
```
Valid pool format types

The logical volume pool does not use the pool format type element.

Valid volume format types

The logical volume pool does not use the volume format type element.

Disk volume pools

This provides a pool based on a physical disk. Volumes are created by adding partitions to the disk. Disk pools are have constraints on the size and placement of volumes. The 'free extents' information will detail the regions which are available for creating new volumes. A volume cannot span across 2 different free extents.

Example pool input
```
<pool type="disk">
  <name>sda</name>
  <source>
    <device path='/dev/sda'/>
  </source>
  <target>
    <path>/dev</path>
  </target>
</pool>
```
Valid pool format types

The disk volume pool accepts the following pool format types, representing the common partition table types:
- dos
- dvh
- gpt
- mac
- bsd
- pc98
- sun
The dos or gpt formats are recommended for best portability - the latter is needed for disks larger than 2TB.

Valid volume format types

The disk volume pool accepts the following volume format types, representing the common partition entry types:
- none
- linux
- fat16
- fat32
- linux-swap
- linux-lvm
- linux-raid
- extended
iSCSI volume pools

This provides a pool based on an iSCSI target. Volumes must be pre-allocated on the iSCSI server, and cannot be created via the libvirt APIs. Since /dev/XXX names may change each time libvirt logs into the iSCSI target, it is recommended to configure the pool to use /dev/disk/by-path or /dev/disk/by-id for the target path. These provide persistent stable naming for LUNs

Example pool input
```
<pool type="iscsi">
  <name>virtimages</name>
  <source>
    <host name="iscsi.example.com"/>
    <device path="demo-target"/>
  </source>
  <target>
    <path>/dev/disk/by-path</path>
  </target>
</pool>
```
Valid pool format types

The logical volume pool does not use the pool format type element.

Valid volume format types

The logical volume pool does not use the volume format type element.

Storage Management

Core concepts

Storage pool XML

First level elements

Source elements

Target elements

Device extents

Storage volume XML

First level elements

Target elements

Storage backend drivers

Directory pool

Example pool input definition

Valid pool format types

Valid volume format types

Filesystem pool

Example pool input

Valid pool format types

Valid volume format types

Network filesystem pool

Example pool input

Valid pool format types

Valid volume format types

Logical volume pools

Example pool input

Valid pool format types

Valid volume format types

Disk volume pools

Example pool input

Valid pool format types

Valid volume format types

iSCSI volume pools

Example pool input

Valid pool format types

Valid volume format types

main menu

related links