- 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 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, scsi
- (all since 0.4.1),
- mpath (since 0.7.1),
- rbd (since 0.9.13),
- sheepdog (since 0.10.0),
- gluster (since 1.2.0),
- zfs (since 1.2.8),
- vstorage (since 3.1.0),
- or iscsi-direct (since 4.7.0).
- This corresponds to the
- storage backend drivers listed further along in this document.
-
Providing a name for the pool which is unique to the host.
- This is mandatory when defining a pool. Since 0.4.1
-
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. Since 0.4.1
-
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. Since 0.4.1
-
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. Since 0.4.1
-
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. Since 0.4.1
Controls whether the filesystem performs copy-on-write (COW) for
- images in the pool. This may only be set for directory / filesystem
- pools on the btrfs filesystem. If not set then libvirt
- will attempt to disable COW on any btrfs filesystems.
- Since 6.6.0.
- A single source element is contained within the top level
- pool element. This tag is used to describe the source of
- the storage pool. The set of child elements that it will contain
- depend on the pool type, but come from the following child elements:
-
Provides the source for pools backed by physical devices
- (pool types fs, logical, disk,
- iscsi, iscsi-direct, zfs,
- vstorage).
- May be repeated multiple times depending on backend driver. Contains
- a required attribute path which is either the fully
- qualified path to the block device node or for iscsi
- or iscsi-direct the iSCSI Qualified Name (IQN).
- Since 0.4.1
-
An optional attribute part_separator for each
- path may be supplied. Valid values for the attribute
- may be either "yes" or "no". This attribute is to be used for a
- disk pool type using a path to a
- device mapper multipath device. Setting the attribute to "yes"
- causes libvirt to attempt to generate and find target volume path's
- using a "p" separator. The default algorithm used by device mapper
- is to add the "p" separator only when the source device path ends
- with a number; however, it's possible to configure the devmapper
- device to not use 'user_friendly_names' thus creating partitions
- with the "p" separator even when the device source path does not
- end with a number.
- Since 1.3.1
-
dir
-
Provides the source for pools backed by directories (pool
- types dir, netfs, gluster),
- or optionally to select a subdirectory
- within a pool that resembles a filesystem (pool
- type gluster). May
- only occur once. Contains a single attribute path
- which is the fully qualified path to the backing directory or
- for a netfs pool type using format
- type "cifs", the path to the Samba share without the leading slash.
- Since 0.4.1
-
adapter
-
Provides the source for pools backed by SCSI adapters (pool
- type scsi). May only occur once.
-
-
name
-
The SCSI adapter name (e.g. "scsi_host1", although a name
- such as "host1" is still supported for backwards compatibility,
- it is not recommended). The scsi_host name to be used can be
- determined from the output of a virsh nodedev-list
- scsi_host command followed by a combination of
- lspci and virsh nodedev-dumpxml
- scsi_hostN commands to find the scsi_hostN
- to be used. Since 0.6.2
-
- It is further recommended to utilize the
- parentaddr element since it's possible to have
- the path to which the scsi_hostN uses change between system
- reboots. Since 1.2.7
-
-
-
-
-
type
-
Specifies the adapter type. Valid values are "scsi_host" or
- "fc_host". If omitted and the name attribute is
- specified, then it defaults to "scsi_host". To keep backwards
- compatibility, this attribute is optional only for the
- "scsi_host" adapter, but is mandatory for the "fc_host" adapter.
- Since 1.0.5
- A "fc_host" capable scsi_hostN can be determined by using
- virsh nodedev-list --cap fc_host.
- Since 1.2.8
-
- Note: Regardless of whether a "scsi_host" adapter type is defined
- using a name or a parentaddr, it
- should refer to a real scsi_host adapter as found through a
- virsh nodedev-list scsi_host and virsh
- nodedev-dumpxml scsi_hostN on one of the scsi_host's
- displayed. It should not refer to a "fc_host" capable scsi_hostN
- nor should it refer to the vHBA created for some "fc_host"
- adapter. For a vHBA the nodedev-dumpxml
- output parent setting will be the "fc_host" capable scsi_hostN
- value. Additionally, do not refer to an iSCSI scsi_hostN for the
- "scsi_host" source. An iSCSI scsi_hostN's
- nodedev-dumpxml output parent field is generally
- "computer". This is a libvirt created parent value indicating
- no parent was defined for the node device.
-
-
-
-
-
wwnn and wwpn
-
The required "World Wide Node Name" (wwnn) and
- "World Wide Port Name" (wwpn) are used by the
- "fc_host" adapter to uniquely identify the vHBA device in the
- Fibre Channel storage fabric. If the vHBA device already exists
- as a Node Device, then libvirt will use it; otherwise, the vHBA
- will be created using the provided values. It is considered a
- configuration error use the values from the HBA as those would
- be for a "scsi_host" type pool instead. The
- wwnn and wwpn have very specific
- format requirements based on the hypervisor being used, thus
- care should be taken if you decide to generate your own to
- follow the standards; otherwise, the pool will fail to start
- with an opaque error message indicating failure to write to
- the vport_create file during vport create/delete due to
- "No such file or directory".
- Since 1.0.4
-
-
-
-
parent
-
Used by the "fc_host" adapter type to optionally specify the
- parent scsi_host device defined in the
- Node Device database as the
- NPIV
- virtual Host Bus Adapter (vHBA). The value provided must be
- a vport capable scsi_host. The value is not the scsi_host of
- the vHBA created by 'virsh nodedev-create', rather it is
- the parent of that vHBA. If the value is not provided, libvirt
- will determine the parent based either finding the wwnn,wwpn
- defined for an existing scsi_host or by creating a vHBA. Providing
- the parent attribute is also useful for the duplicate pool
- definition checks. This is more important in environments where
- both the "fc_host" and "scsi_host" source adapter pools are being
- used in order to ensure a new definition doesn't duplicate using
- the scsi_hostN of some existing storage pool.
- Since 1.0.4
-
-
parent_wwnn and parent_wwpn
-
Instead of the parent to specify which scsi_host
- to use by name, it's possible to provide the wwnn and wwpn of
- the parent to be used for the vHBA in order to ensure that
- between reboots or after a hardware configuration change that
- the scsi_host parent name doesn't change. Both the parent_wwnn
- and parent_wwpn must be provided.
- Since 3.0.0
-
-
parent_fabric_wwn
-
Instead of the parent to specify which scsi_host
- to use by name, it's possible to provide the fabric_wwn on which
- the scsi_host exists. This provides flexibility for choosing
- a scsi_host that may be available on the fabric rather than
- requiring a specific parent by wwnn or wwpn to be available.
- Since 3.0.0
-
-
managed
-
An optional attribute to instruct the SCSI storage backend to
- manage destroying the vHBA when the pool is destroyed. For
- configurations that do not provide an already created vHBA
- from a 'virsh nodedev-create', libvirt will set this property
- to "yes". For configurations that have already created a vHBA
- via 'virsh nodedev-create' and are using the wwnn/wwpn from
- that vHBA and optionally the scsi_host parent, setting this
- attribute to "yes" will allow libvirt to destroy the node device
- when the pool is destroyed. If this attribute is set to "no" or
- not defined in the XML, then libvirt will not destroy the vHBA.
- Since 1.2.11
-
-
-
-
parentaddr
-
Used by the "scsi_host" adapter type instead of the
- name attribute to more uniquely identify the
- SCSI host. Using a combination of the unique_id
- attribute and the address element to formulate
- a PCI address, a search will be performed of the
- /sys/class/scsi_host/hostNN links for a
- matching PCI address with a matching unique_id
- value in the /sys/class/scsi_host/hostNN/unique_id
- file. The value in the "unique_id" file will be unique enough
- for the specific PCI address. The hostNN will be
- used by libvirt as the basis to define which SCSI host is to
- be used for the currently booted system.
- Since 1.2.7
-
-
address
-
The PCI address of the scsi_host device to be used. Using
- a PCI address provides consistent naming across system reboots
- and kernel reloads. The address will have four attributes:
- domain (a 2-byte hex integer, not currently used
- by qemu), bus (a hex value between 0 and 0xff,
- inclusive), slot (a hex value between 0x0 and
- 0x1f, inclusive), and function (a value between
- 0 and 7, inclusive). The PCI address can be determined by
- listing the /sys/bus/pci/devices and the
- /sys/class/scsi_host directories in order to
- find the expected scsi_host device. The address will be
- provided in a format such as "0000:00:1f:2" which can be
- used to generate the expected PCI address
- "domain='0x0000' bus='0x00' slot='0x1f' function='0x0'".
- Optionally, using the combination of the commands 'virsh
- nodedev-list scsi_host' and 'virsh nodedev-dumpxml' for a
- specific list entry and converting the resulting
- path element as the basis to formulate the
- correctly formatted PCI address.
-
-
-
-
unique_id
-
Required parentaddr attribute used to determine
- which of the scsi_host adapters for the provided PCI address
- should be used. The value is determine by contents of the
- unique_id file for the specific scsi_host adapter.
- For a PCI address of "0000:00:1f:2", the unique identifier files
- can be found using the command
- find -H /sys/class/scsi_host/host*/unique_id |
- xargs grep '[0-9]'. Optionally, the
- virsh nodedev-dumpxml scsi_hostN' of a
- specific scsi_hostN list entry will list the
- unique_id value.
-
-
-
-
-
-
host
-
Provides the source for pools backed by storage from a
- remote server (pool types netfs, iscsi,
- iscsi-direct,
- rbd, sheepdog, gluster). 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. Duplicate storage pool definition checks may perform
- a cursory check that the same host name by string comparison in the
- new pool does not match an existing pool's source host name when
- combined with the directory or device
- element. Name resolution of the provided hostname or IP address
- is left to the storage driver backend interactions with the remote
- server. See the storage driver page for
- any restrictions for specific storage backends.
- Since 0.4.1
-
initiator
-
Required by the iscsi-direct pool in order to provide
- the iSCSI Qualified Name (IQN) to communicate with the pool's
- device target IQN. There is one sub-element
- iqn with the name attribute to describe
- the IQN for the initiator.
- Since 4.7.0
-
auth
-
If present, the auth element provides the
- authentication credentials needed to access the source by the
- setting of the type attribute (pool
- types iscsi, iscsi-direct, rbd).
- The type
- must be either "chap" or "ceph". Use "ceph" for
- Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
- (Challenge-Handshake Authentication Protocol) iSCSI
- targets. Additionally a mandatory attribute
- username identifies the username to use during
- authentication as well as a sub-element secret with
- a mandatory attribute type, to tie back to a
- libvirt secret object that
- holds the actual password or other credentials. The domain XML
- intentionally does not expose the password, only the reference
- to the object that manages the password.
- The secret element requires either a uuid
- attribute with the UUID of the secret object or a usage
- attribute matching the key that was specified in the
- secret object. Since 0.9.7 for "ceph" and
- 1.1.1 for "chap"
-
-
name
-
Provides the source for pools backed by storage from a
- named element (pool types logical, rbd,
- sheepdog, gluster). Contains a
- string identifier.
- Since 0.4.5
-
format
-
Provides information about the format of the pool (pool
- types fs, netfs, disk,
- logical). 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. Since 0.4.1
-
-
protocol
-
For a netfs Storage Pool provide a mechanism to
- define which NFS protocol version number will be used to contact
- the server's NFS service. The attribute ver accepts
- an unsigned integer as the version number to use.
- Since 5.1.0
-
vendor
-
Provides optional information about the vendor of the
- storage device. This contains a single
- attribute name whose value is backend
- specific. Since 0.8.4
-
product
-
Provides an optional product name of the storage device.
- This contains a single attribute name whose value
- is backend specific. Since 0.8.4
- A single target element is contained within the top level
- pool element for some types of pools (pool
- types dir, fs, netfs,
- logical, disk, iscsi,
- scsi, mpath, zfs).
- This tag is used to describe the mapping of
- the storage pool into the host filesystem. It can contain the following
- child elements:
-
Provides the location at which the pool will be mapped into
- the local filesystem namespace, as an absolute path. For a
- filesystem/directory based pool it will be a fully qualified name of
- the directory in which volumes will be created. For device based pools
- it will be a fully qualified 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.
- For logical and zfs pool types, a
- provided value is ignored and a default path generated.
- For a Multipath pool (type mpath), the provided
- value is ignored and the default value of "/dev/mapper" is used.
- Since 0.4.1
-
-
permissions
-
This is currently only useful for directory or filesystem based
- pools, which are mapped as a directory into the local filesystem
- namespace. It provides information about the permissions to use for the
- final directory when the pool is built. There are 4 child elements.
- The mode element contains the octal permission set.
- The mode defaults to 0711 when not provided.
- The owner element contains the numeric user ID.
- The group element contains the numeric group ID.
- If owner or group aren't specified when
- creating a directory, the UID and GID of the libvirtd process are used.
- The label element contains the MAC (eg SELinux)
- label string.
- Since 0.4.1
- For running directory or filesystem based pools, these fields
- will be filled with the values used by the existing directory.
- Since 1.2.16
-
- 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. Since 0.4.1
-
- The optional refresh element can control how the pool and
- associated volumes are refreshed (pool type rbd). The
- allocation attribute of the volume child element
- controls the method used for computing the allocation of a volume. The
- valid attribute values are default to compute the actual
- usage or capacity to use the logical capacity for cases where
- computing the allocation is too expensive. The following XML snippet
- shows the syntax:
-
- Usage of Storage Pool Namespaces provides a mechanism to provide
- pool type specific data in a free form or arbitrary manner via
- XML syntax targeted solely for the needs of the specific pool type
- which is not otherwise supported in standard XML. For the "fs" and
- "netfs" pool types this provides a mechanism to provide additional
- mount options on the command line. For the "rbd" pool this provides
- a mechanism to override default settings for RBD configuration options.
-
-
- Usage of namespaces comes with no support guarantees. It is intended
- for developers testing out a concept prior to requesting an explicitly
- supported XML option in libvirt, and thus should never be used in
- production.
-
-
-
fs:mount_opts
-
Provides an XML namespace mechanism to optionally utilize
- specifically named options for the mount command via the "-o"
- option for the fs or netfs type storage
- pools. In order to designate that the Storage Pool will be using
- the mechanism, the pool element must be modified to
- provide the XML namespace attribute syntax as follows:
-
-
- The fs:mount_opts defines the mount options by
- specifying multiple fs:option subelements with
- the attribute name specifying the mount option to
- be added. The value of the named option is not checked since
- it's possible options don't exist on all distributions. It is
- expected that proper and valid options will be supplied for the
- target host.
-
-
- The following XML snippet shows the syntax required in order to
- utilize for a netfs pool:
-
Provides an XML namespace mechanism to optionally utilize
- specifically named options for the RBD configuration options
- via the rados_conf_set API for the rbd type
- storage pools. In order to designate that the Storage Pool
- will be using the mechanism, the pool element
- must be modified to provide the XML namespace attribute
- syntax as follows:
-
-
- The rbd:config_opts defines the configuration options
- by specifying multiple rbd:option subelements with
- the attribute name specifying the configuration option
- to be added and value specifying the configuration
- option value. The name and value for each option is only checked
- to be not empty. The name and value provided are not checked since
- it's possible options don't exist on all distributions. It is
- expected that proper and valid options will be supplied for the
- target host.
-
-
- The following XML snippet shows the syntax required in order to
- utilize
-
- 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, netdir or ploop), which is also available
- from virStorageVolGetInfo(). The storage volume
- XML format is available since 0.4.1
-
Providing a name for the volume which is unique to the pool.
- This is mandatory when defining a volume. For a disk pool, the
- name must be combination of the source device path
- device and next partition number to be created. For example, if
- the source device path is /dev/sdb and there are no
- partitions on the disk, then the name must be sdb1 with the next
- name being sdb2 and so on.
- Since 0.4.1
-
key
-
Providing an identifier for the volume which identifies a
- single volume. In some cases it's possible to have two distinct keys
- identifying a single volume. This field cannot be set when creating
- a volume: it is always generated.
- Since 0.4.1
-
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. Different types of pools may treat
- sparse volumes differently. For example, the logical
- pool will not automatically expand volume's allocation when it
- gets full; the user is responsible for doing that or configuring
- dmeventd to do so automatically.
-
- By default this is specified in bytes, but an optional attribute
- unit can be specified to adjust the passed value.
- Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes,
- 103 or 1000 bytes), 'K' or 'KiB' (kibibytes,
- 210 or 1024 bytes), 'MB' (megabytes, 106
- or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 220
- or 1,048,576 bytes), 'GB' (gigabytes, 109 or
- 1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 230
- or 1,073,741,824 bytes), 'TB' (terabytes, 1012 or
- 1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes,
- 240 or 1,099,511,627,776 bytes), 'PB' (petabytes,
- 1015 or 1,000,000,000,000,000 bytes), 'P' or 'PiB'
- (pebibytes, 250 or 1,125,899,906,842,624 bytes),
- 'EB' (exabytes, 1018 or 1,000,000,000,000,000,000
- bytes), or 'E' or 'EiB' (exbibytes, 260 or
- 1,152,921,504,606,846,976 bytes). Since
- 0.4.1, multi-character unit since
- 0.9.11
-
capacity
-
Providing the logical capacity for the volume. This value is
- in bytes by default, but a unit attribute can be
- specified with the same semantics as for allocation
- This is compulsory when creating a volume.
- Since 0.4.1
-
physical
-
This output only element provides the host physical size of
- the target storage volume. The default output unit
- will be in bytes.
- Since 3.0.0
-
source
-
Provides information about the underlying storage allocation
- of the volume. This may not be available for some pool types.
- Since 0.4.1
-
target
-
Provides information about the representation of the volume
- on the local host. Since 0.4.1
- A single target element is contained within the top level
- volume element. This tag is used to describe the mapping of
- the storage volume into the host filesystem. It can contain the following
- child elements:
-
Provides the location at which the volume can be accessed on
- the local filesystem, as an absolute path. This is a readonly
- attribute, so shouldn't be specified when creating a volume.
- Since 0.4.1
-
format
-
Provides information about the pool specific volume format.
- For disk pools it will provide the partition table format type, but is
- not preserved after a pool refresh or libvirtd restart. Use extended
- in order to create an extended disk extent partition. 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 attribute. Consult the
- storage driver page for the list of valid
- volume format type values for each specific pool. The
- format will be ignored on input for pools without a
- volume format type value and the default pool format will be used.
- Since 0.4.1
-
permissions
-
Provides information about the 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. There are 4 child elements.
- The mode element contains the octal permission set.
- The mode defaults to 0600 when not provided.
- The owner element contains the numeric user ID.
- The group element contains the numeric group ID.
- If owner or group aren't specified when
- creating a supported volume, the UID and GID of the libvirtd process
- are used. The label element contains the MAC (eg SELinux)
- label string.
- For existing directory or filesystem based volumes, these fields
- will be filled with the values used by the existing file.
- Since 0.4.1
-
-
timestamps
-
Provides timing information about the volume. Up to four
- sub-elements are present,
- where atime, btime, ctime
- and mtime hold the access, birth, change and
- modification time of the volume, where known. The used time
- format is <seconds>.<nanoseconds> since the
- beginning of the epoch (1 Jan 1970). If nanosecond resolution
- is 0 or otherwise unsupported by the host OS or filesystem,
- then the nanoseconds part is omitted. This is a readonly
- attribute and is ignored when creating a volume.
- Since 0.10.0
-
-
encryption
-
If present, specifies how the volume is encrypted. See
- the Storage Encryption page
- for more information.
-
-
compat
-
Specify compatibility level. So far, this is only used for
- type='qcow2' volumes. Valid values are 0.10
- and 1.1 so far, specifying QEMU version the images should
- be compatible with. If the feature element is present,
- 1.1 is used.
- Since 1.1.0 If omitted, 0.10 is used.
- Since 1.1.2
-
-
nocow
-
Turn off COW of the newly created volume. So far, this is only valid
- for a file image in btrfs file system. It will improve performance when
- the file image is used in VM. To create non-raw file images, it
- requires QEMU version since 2.1. Since 1.2.7
-
-
clusterSize
-
Changes the qcow2 cluster size which can affect image file size
- and performance.
- Since 7.4.0
-
-
features
-
Format-specific features. Only used for qcow2 now.
- Valid sub-elements are:
-
-
<lazy_refcounts/> - allow delayed reference
- counter updates. Since 1.1.0
- 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:
-
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 volume.
- Since 0.6.0
-
format
-
Provides information about the pool specific backing store 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. 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.
- Since 0.6.0
-
permissions
-
Provides information about the permissions of the backing file.
- See volume permissions documentation for explanation
- of individual fields.
- Since 0.6.0
-
-
-
diff --git a/docs/formatstorage.rst b/docs/formatstorage.rst
new file mode 100644
index 0000000000..d7ca58788a
--- /dev/null
+++ b/docs/formatstorage.rst
@@ -0,0 +1,829 @@
+.. role:: since
+
+==================================
+Storage pool and volume XML format
+==================================
+
+.. contents::
+
+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 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``, ``scsi`` (all :since:`since 0.4.1` ), ``mpath`` (
+:since:`since 0.7.1` ), ``rbd`` ( :since:`since 0.9.13` ), ``sheepdog`` (
+:since:`since 0.10.0` ), ``gluster`` ( :since:`since 1.2.0` ), ``zfs`` (
+:since:`since 1.2.8` ), ``vstorage`` ( :since:`since 3.1.0` ), or
+``iscsi-direct`` ( :since:`since 4.7.0` ). This corresponds to the storage
+backend drivers listed further along in this document.
+
+Storage pool general metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+
+ virtimages
+ 3e3fce45-4f53-4fa7-bb32-11f34168b82b
+ 10000000
+ 50000000
+ 40000000
+ ...
+
+``name``
+ Providing a name for the pool which is unique to the host. This is mandatory
+ when defining a pool. :since:`Since 0.4.1`
+``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.
+ :since:`Since 0.4.1`
+``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. :since:`Since
+ 0.4.1`
+``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.
+ :since:`Since 0.4.1`
+``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. :since:`Since 0.4.1`
+
+Features
+~~~~~~~~
+
+Some pools support optional features:
+
+::
+
+ ...
+
+
+
+ ...
+
+Valid features are:
+
+``cow``
+ Controls whether the filesystem performs copy-on-write (COW) for images in
+ the pool. This may only be set for directory / filesystem pools on the
+ ``btrfs`` filesystem. If not set then libvirt will attempt to disable COW
+ on any btrfs filesystems. :since:`Since 6.6.0`.
+
+Source elements
+~~~~~~~~~~~~~~~
+
+A single ``source`` element is contained within the top level ``pool`` element.
+This tag is used to describe the source of the storage pool. The set of child
+elements that it will contain depend on the pool type, but come from the
+following child elements:
+
+::
+
+ ...
+
+
+
+
+
+
+
+
+
+ ...
+
+::
+
+ ...
+
+
+
+
+ ...
+
+::
+
+ ...
+
+
+
+ ...
+
+::
+
+ ...
+
+
+
+
+
+
+
+ ...
+
+::
+
+ ...
+
+
+
+ ...
+
+::
+
+ ...
+
+
+
+
+
+
+ ...
+
+``device``
+ Provides the source for pools backed by physical devices (pool types ``fs``,
+ ``logical``, ``disk``, ``iscsi``, ``iscsi-direct``, ``zfs``, ``vstorage``).
+ May be repeated multiple times depending on backend driver. Contains a
+ required attribute ``path`` which is either the fully qualified path to the
+ block device node or for ``iscsi`` or ``iscsi-direct`` the iSCSI Qualified
+ Name (IQN). :since:`Since 0.4.1`
+
+ An optional attribute ``part_separator`` for each ``path`` may be supplied.
+ Valid values for the attribute may be either "yes" or "no". This attribute is
+ to be used for a ``disk`` pool type using a ``path`` to a device mapper
+ multipath device. Setting the attribute to "yes" causes libvirt to attempt to
+ generate and find target volume path's using a "p" separator. The default
+ algorithm used by device mapper is to add the "p" separator only when the
+ source device path ends with a number; however, it's possible to configure
+ the devmapper device to not use 'user_friendly_names' thus creating
+ partitions with the "p" separator even when the device source path does not
+ end with a number. :since:`Since 1.3.1`
+
+``dir``
+ Provides the source for pools backed by directories (pool types ``dir``,
+ ``netfs``, ``gluster``), or optionally to select a subdirectory within a pool
+ that resembles a filesystem (pool type ``gluster``). May only occur once.
+ Contains a single attribute ``path`` which is the fully qualified path to the
+ backing directory or for a ``netfs`` pool type using ``format`` type "cifs",
+ the path to the Samba share without the leading slash. :since:`Since 0.4.1`
+``adapter``
+ Provides the source for pools backed by SCSI adapters (pool type ``scsi``).
+ May only occur once.
+
+ ``name``
+ The SCSI adapter name (e.g. "scsi_host1", although a name such as "host1"
+ is still supported for backwards compatibility, it is not recommended).
+ The scsi_host name to be used can be determined from the output of a
+ ``virsh nodedev-list scsi_host`` command followed by a
+ combination of ``lspci`` and
+ ``virsh nodedev-dumpxml scsi_hostN`` commands to find the
+ ``scsi_hostN`` to be used. :since:`Since 0.6.2`
+
+ It is further recommended to utilize the ``parentaddr`` element since it's
+ possible to have the path to which the scsi_hostN uses change between
+ system reboots. :since:`Since 1.2.7`
+
+ ``type``
+ Specifies the adapter type. Valid values are "scsi_host" or "fc_host". If
+ omitted and the ``name`` attribute is specified, then it defaults to
+ "scsi_host". To keep backwards compatibility, this attribute is optional
+ **only** for the "scsi_host" adapter, but is mandatory for the "fc_host"
+ adapter. :since:`Since 1.0.5` A "fc_host" capable scsi_hostN can be
+ determined by using ``virsh nodedev-list --cap fc_host``. :since:`Since
+ 1.2.8`
+
+ Note: Regardless of whether a "scsi_host" adapter type is defined using a
+ ``name`` or a ``parentaddr``, it should refer to a real scsi_host adapter
+ as found through a ``virsh nodedev-list scsi_host`` and
+ ``virsh nodedev-dumpxml scsi_hostN`` on one of the scsi_host's
+ displayed. It should not refer to a "fc_host" capable scsi_hostN nor
+ should it refer to the vHBA created for some "fc_host" adapter. For a vHBA
+ the ``nodedev-dumpxml`` output parent setting will be the "fc_host"
+ capable scsi_hostN value. Additionally, do not refer to an iSCSI
+ scsi_hostN for the "scsi_host" source. An iSCSI scsi_hostN's
+ ``nodedev-dumpxml`` output parent field is generally "computer". This is a
+ libvirt created parent value indicating no parent was defined for the node
+ device.
+
+ ``wwnn`` and ``wwpn``
+ The required "World Wide Node Name" (``wwnn``) and "World Wide Port Name"
+ (``wwpn``) are used by the "fc_host" adapter to uniquely identify the vHBA
+ device in the Fibre Channel storage fabric. If the vHBA device already
+ exists as a Node Device, then libvirt will use it; otherwise, the vHBA
+ will be created using the provided values. It is considered a
+ configuration error use the values from the HBA as those would be for a
+ "scsi_host" ``type`` pool instead. The ``wwnn`` and ``wwpn`` have very
+ specific format requirements based on the hypervisor being used, thus care
+ should be taken if you decide to generate your own to follow the
+ standards; otherwise, the pool will fail to start with an opaque error
+ message indicating failure to write to the vport_create file during vport
+ create/delete due to "No such file or directory". :since:`Since 1.0.4`
+
+ ``parent``
+ Used by the "fc_host" adapter type to optionally specify the parent
+ scsi_host device defined in the `Node Device `__ database
+ as the `NPIV `__ virtual
+ Host Bus Adapter (vHBA). The value provided must be a vport capable
+ scsi_host. The value is not the scsi_host of the vHBA created by 'virsh
+ nodedev-create', rather it is the parent of that vHBA. If the value is not
+ provided, libvirt will determine the parent based either finding the
+ wwnn,wwpn defined for an existing scsi_host or by creating a vHBA.
+ Providing the parent attribute is also useful for the duplicate pool
+ definition checks. This is more important in environments where both the
+ "fc_host" and "scsi_host" source adapter pools are being used in order to
+ ensure a new definition doesn't duplicate using the scsi_hostN of some
+ existing storage pool. :since:`Since 1.0.4`
+ ``parent_wwnn`` and ``parent_wwpn``
+ Instead of the ``parent`` to specify which scsi_host to use by name, it's
+ possible to provide the wwnn and wwpn of the parent to be used for the
+ vHBA in order to ensure that between reboots or after a hardware
+ configuration change that the scsi_host parent name doesn't change. Both
+ the parent_wwnn and parent_wwpn must be provided. :since:`Since 3.0.0`
+ ``parent_fabric_wwn``
+ Instead of the ``parent`` to specify which scsi_host to use by name, it's
+ possible to provide the fabric_wwn on which the scsi_host exists. This
+ provides flexibility for choosing a scsi_host that may be available on the
+ fabric rather than requiring a specific parent by wwnn or wwpn to be
+ available. :since:`Since 3.0.0`
+ ``managed``
+ An optional attribute to instruct the SCSI storage backend to manage
+ destroying the vHBA when the pool is destroyed. For configurations that do
+ not provide an already created vHBA from a 'virsh nodedev-create', libvirt
+ will set this property to "yes". For configurations that have already
+ created a vHBA via 'virsh nodedev-create' and are using the wwnn/wwpn from
+ that vHBA and optionally the scsi_host parent, setting this attribute to
+ "yes" will allow libvirt to destroy the node device when the pool is
+ destroyed. If this attribute is set to "no" or not defined in the XML,
+ then libvirt will not destroy the vHBA. :since:`Since 1.2.11`
+
+ ``parentaddr``
+ Used by the "scsi_host" adapter type instead of the ``name`` attribute to
+ more uniquely identify the SCSI host. Using a combination of the
+ ``unique_id`` attribute and the ``address`` element to formulate a PCI
+ address, a search will be performed of the ``/sys/class/scsi_host/hostNN``
+ links for a matching PCI address with a matching ``unique_id`` value in
+ the ``/sys/class/scsi_host/hostNN/unique_id`` file. The value in the
+ "unique_id" file will be unique enough for the specific PCI address. The
+ ``hostNN`` will be used by libvirt as the basis to define which SCSI host
+ is to be used for the currently booted system. :since:`Since 1.2.7`
+
+ ``address``
+ The PCI address of the scsi_host device to be used. Using a PCI address
+ provides consistent naming across system reboots and kernel reloads.
+ The address will have four attributes: ``domain`` (a 2-byte hex
+ integer, not currently used by qemu), ``bus`` (a hex value between 0
+ and 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f,
+ inclusive), and ``function`` (a value between 0 and 7, inclusive). The
+ PCI address can be determined by listing the ``/sys/bus/pci/devices``
+ and the ``/sys/class/scsi_host`` directories in order to find the
+ expected scsi_host device. The address will be provided in a format
+ such as "0000:00:1f:2" which can be used to generate the expected PCI
+ address "domain='0x0000' bus='0x00' slot='0x1f' function='0x0'".
+ Optionally, using the combination of the commands 'virsh nodedev-list
+ scsi_host' and 'virsh nodedev-dumpxml' for a specific list entry and
+ converting the resulting ``path`` element as the basis to formulate the
+ correctly formatted PCI address.
+
+ ``unique_id``
+ Required ``parentaddr`` attribute used to determine which of the
+ scsi_host adapters for the provided PCI address should be used. The
+ value is determine by contents of the ``unique_id`` file for the
+ specific scsi_host adapter. For a PCI address of "0000:00:1f:2", the
+ unique identifier files can be found using the command
+ ``find -H /sys/class/scsi_host/host*/unique_id | xargs grep '[0-9]'``.
+ Optionally, the ``virsh nodedev-dumpxml scsi_hostN``' of a specific
+ scsi_hostN list entry will list the ``unique_id`` value.
+``host``
+ Provides the source for pools backed by storage from a remote server (pool
+ types ``netfs``, ``iscsi``, ``iscsi-direct``, ``rbd``, ``sheepdog``,
+ ``gluster``). 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. Duplicate storage pool definition checks may perform a
+ cursory check that the same host name by string comparison in the new pool
+ does not match an existing pool's source host name when combined with the
+ ``directory`` or ``device`` element. Name resolution of the provided hostname
+ or IP address is left to the storage driver backend interactions with the
+ remote server. See the `storage driver page `__ for any
+ restrictions for specific storage backends. :since:`Since 0.4.1`
+``initiator``
+ Required by the ``iscsi-direct`` pool in order to provide the iSCSI Qualified
+ Name (IQN) to communicate with the pool's ``device`` target IQN. There is one
+ sub-element ``iqn`` with the ``name`` attribute to describe the IQN for the
+ initiator. :since:`Since 4.7.0`
+``auth``
+ If present, the ``auth`` element provides the authentication credentials
+ needed to access the source by the setting of the ``type`` attribute (pool
+ types ``iscsi``, ``iscsi-direct``, ``rbd``). The ``type`` must be either
+ "chap" or "ceph". Use "ceph" for Ceph RBD (Rados Block Device) network
+ sources and use "iscsi" for CHAP (Challenge-Handshake Authentication
+ Protocol) iSCSI targets. Additionally a mandatory attribute ``username``
+ identifies the username to use during authentication as well as a sub-element
+ ``secret`` with a mandatory attribute ``type``, to tie back to a `libvirt
+ secret object `__ that holds the actual password or other
+ credentials. The domain XML intentionally does not expose the password, only
+ the reference to the object that manages the password. The ``secret`` element
+ requires either a ``uuid`` attribute with the UUID of the secret object or a
+ ``usage`` attribute matching the key that was specified in the secret object.
+ :since:`Since 0.9.7 for "ceph" and 1.1.1 for "chap"`
+``name``
+ Provides the source for pools backed by storage from a named element (pool
+ types ``logical``, ``rbd``, ``sheepdog``, ``gluster``). Contains a string
+ identifier. :since:`Since 0.4.5`
+``format``
+ Provides information about the format of the pool (pool types ``fs``,
+ ``netfs``, ``disk``, ``logical``). 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. :since:`Since 0.4.1`
+``protocol``
+ For a ``netfs`` Storage Pool provide a mechanism to define which NFS protocol
+ version number will be used to contact the server's NFS service. The
+ attribute ``ver`` accepts an unsigned integer as the version number to use.
+ :since:`Since 5.1.0`
+``vendor``
+ Provides optional information about the vendor of the storage device. This
+ contains a single attribute ``name`` whose value is backend specific.
+ :since:`Since 0.8.4`
+``product``
+ Provides an optional product name of the storage device. This contains a
+ single attribute ``name`` whose value is backend specific. :since:`Since
+ 0.8.4`
+
+Storage pool target elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A single ``target`` element is contained within the top level ``pool`` element
+for some types of pools (pool types ``dir``, ``fs``, ``netfs``, ``logical``,
+``disk``, ``iscsi``, ``scsi``, ``mpath``, ``zfs``). This tag is used to describe
+the mapping of the storage pool into the host filesystem. It can contain the
+following child elements:
+
+::
+
+ ...
+
+ /dev/disk/by-path
+
+ 107
+ 107
+ 0744
+
+
+
+
+
+``path``
+ Provides the location at which the pool will be mapped into the local
+ filesystem namespace, as an absolute path. For a filesystem/directory based
+ pool it will be a fully qualified name of the directory in which volumes will
+ be created. For device based pools it will be a fully qualified 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. For ``logical`` and ``zfs``
+ pool types, a provided value is ignored and a default path generated. For a
+ Multipath pool (type ``mpath``), the provided value is ignored and the
+ default value of "/dev/mapper" is used. :since:`Since 0.4.1`
+``permissions``
+ This is currently only useful for directory or filesystem based pools, which
+ are mapped as a directory into the local filesystem namespace. It provides
+ information about the permissions to use for the final directory when the
+ pool is built. There are 4 child elements. The ``mode`` element contains the
+ octal permission set. The ``mode`` defaults to 0711 when not provided. The
+ ``owner`` element contains the numeric user ID. The ``group`` element
+ contains the numeric group ID. If ``owner`` or ``group`` aren't specified
+ when creating a directory, the UID and GID of the libvirtd process are used.
+ The ``label`` element contains the MAC (eg SELinux) label string.
+ :since:`Since 0.4.1` For running directory or filesystem based pools, these
+ fields will be filled with the values used by the existing directory.
+ :since:`Since 1.2.16`
+
+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. :since:`Since 0.4.1`
+
+Refresh overrides
+~~~~~~~~~~~~~~~~~
+
+The optional ``refresh`` element can control how the pool and associated volumes
+are refreshed (pool type ``rbd``). The ``allocation`` attribute of the
+``volume`` child element controls the method used for computing the allocation
+of a volume. The valid attribute values are ``default`` to compute the actual
+usage or ``capacity`` to use the logical capacity for cases where computing the
+allocation is too expensive. The following XML snippet shows the syntax:
+
+::
+
+
+ myrbdpool
+ ...
+
+ ...
+
+
+
+ ...
+
+
+:since:`Since 5.2.0`
+
+Storage Pool Namespaces
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Usage of Storage Pool Namespaces provides a mechanism to provide pool type
+specific data in a free form or arbitrary manner via XML syntax targeted solely
+for the needs of the specific pool type which is not otherwise supported in
+standard XML. For the "fs" and "netfs" pool types this provides a mechanism to
+provide additional mount options on the command line. For the "rbd" pool this
+provides a mechanism to override default settings for RBD configuration options.
+
+Usage of namespaces comes with no support guarantees. It is intended for
+developers testing out a concept prior to requesting an explicitly supported XML
+option in libvirt, and thus should never be used in production.
+
+``fs:mount_opts``
+ Provides an XML namespace mechanism to optionally utilize specifically named
+ options for the mount command via the "-o" option for the ``fs`` or ``netfs``
+ type storage pools. In order to designate that the Storage Pool will be using
+ the mechanism, the ``pool`` element must be modified to provide the XML
+ namespace attribute syntax as follows:
+
+ xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'
+
+ The ``fs:mount_opts`` defines the mount options by specifying multiple
+ ``fs:option`` subelements with the attribute ``name`` specifying the mount
+ option to be added. The value of the named option is not checked since it's
+ possible options don't exist on all distributions. It is expected that proper
+ and valid options will be supplied for the target host.
+
+ The following XML snippet shows the syntax required in order to utilize for a
+ netfs pool:
+
+ ::
+
+
+ nfsimages
+ ...
+
+ ...
+
+ ...
+
+ ...
+
+
+
+
+
+
+ ...
+
+ :since:`Since 5.1.0.`
+
+``rbd:config_opts``
+ Provides an XML namespace mechanism to optionally utilize specifically named
+ options for the RBD configuration options via the rados_conf_set API for the
+ ``rbd`` type storage pools. In order to designate that the Storage Pool will
+ be using the mechanism, the ``pool`` element must be modified to provide the
+ XML namespace attribute syntax as follows:
+
+ xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'
+
+ The ``rbd:config_opts`` defines the configuration options by specifying
+ multiple ``rbd:option`` subelements with the attribute ``name`` specifying
+ the configuration option to be added and ``value`` specifying the
+ configuration option value. The name and value for each option is only
+ checked to be not empty. The name and value provided are not checked since
+ it's possible options don't exist on all distributions. It is expected that
+ proper and valid options will be supplied for the target host.
+
+ The following XML snippet shows the syntax required in order to utilize
+
+ ::
+
+
+ myrbdpool
+ ...
+
+ ...
+
+ ...
+
+ ...
+
+ ...
+
+
+
+
+
+
+
+ :since:`Since 5.1.0.`
+
+Storage volume XML
+------------------
+
+A storage volume will generally be either a file or a device node; :since:`since
+1.2.0` , an optional output-only attribute ``type`` lists the actual type (file,
+block, dir, network, netdir or ploop), which is also available from
+``virStorageVolGetInfo()``. The storage volume XML format is available
+:since:`since 0.4.1`
+
+Storage volume general metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+
+ sparse.img
+ /var/lib/xen/images/sparse.img
+ 0
+ 1
+ ...
+
+``name``
+ Providing a name for the volume which is unique to the pool. This is
+ mandatory when defining a volume. For a disk pool, the name must be
+ combination of the ``source`` device path device and next partition number to
+ be created. For example, if the ``source`` device path is /dev/sdb and there
+ are no partitions on the disk, then the name must be sdb1 with the next name
+ being sdb2 and so on. :since:`Since 0.4.1`
+``key``
+ Providing an identifier for the volume which identifies a single volume. In
+ some cases it's possible to have two distinct keys identifying a single
+ volume. This field cannot be set when creating a volume: it is always
+ generated. :since:`Since 0.4.1`
+``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. Different types of pools may treat sparse volumes differently. For
+ example, the ``logical`` pool will not automatically expand volume's
+ allocation when it gets full; the user is responsible for doing that or
+ configuring dmeventd to do so automatically.
+ By default this is specified in bytes, but an optional attribute ``unit`` can
+ be specified to adjust the passed value. Values can be: 'B' or 'bytes' for
+ bytes, 'KB' (kilobytes, 10\ :sup:`3` or 1000 bytes), 'K' or 'KiB' (kibibytes,
+ 2\ :sup:`10` or 1024 bytes), 'MB' (megabytes, 10\ :sup:`6` or 1,000,000
+ bytes), 'M' or 'MiB' (mebibytes, 2\ :sup:`20` or 1,048,576 bytes), 'GB'
+ (gigabytes, 10\ :sup:`9` or 1,000,000,000 bytes), 'G' or 'GiB' (gibibytes,
+ 2\ :sup:`30` or 1,073,741,824 bytes), 'TB' (terabytes, 10\ :sup:`12` or
+ 1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes, 2\ :sup:`40` or
+ 1,099,511,627,776 bytes), 'PB' (petabytes, 10\ :sup:`15` or
+ 1,000,000,000,000,000 bytes), 'P' or 'PiB' (pebibytes, 2\ :sup:`50` or
+ 1,125,899,906,842,624 bytes), 'EB' (exabytes, 10\ :sup:`18` or
+ 1,000,000,000,000,000,000 bytes), or 'E' or 'EiB' (exbibytes, 2\ :sup:`60` or
+ 1,152,921,504,606,846,976 bytes). :since:`Since 0.4.1`, multi-character
+ ``unit`` :since:`since 0.9.11`.
+``capacity``
+ Providing the logical capacity for the volume. This value is in bytes by
+ default, but a ``unit`` attribute can be specified with the same semantics as
+ for ``allocation`` This is compulsory when creating a volume. :since:`Since
+ 0.4.1`
+``physical``
+ This output only element provides the host physical size of the target
+ storage volume. The default output ``unit`` will be in bytes. :since:`Since
+ 3.0.0`
+``source``
+ Provides information about the underlying storage allocation of the volume.
+ This may not be available for some pool types. :since:`Since 0.4.1`
+``target``
+ Provides information about the representation of the volume on the local
+ host. :since:`Since 0.4.1`
+
+Storage volume target elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A single ``target`` element is contained within the top level ``volume``
+element. This tag is used to describe the mapping of the storage volume into the
+host filesystem. It can contain the following child elements:
+
+::
+
+ ...
+
+ /var/lib/virt/images/sparse.img
+
+
+ 107
+ 107
+ 0744
+
+
+
+ 1341933637.273190990
+ 1341930622.047245868
+ 1341930622.047245868
+
+
+ ...
+
+ 1.1
+
+ 64
+
+
+
+
+
+``path``
+ Provides the location at which the volume can be accessed on the local
+ filesystem, as an absolute path. This is a readonly attribute, so shouldn't
+ be specified when creating a volume. :since:`Since 0.4.1`
+``format``
+ Provides information about the pool specific volume format. For disk pools it
+ will provide the partition table format type, but is not preserved after a
+ pool refresh or libvirtd restart. Use extended in order to create an extended
+ disk extent partition. 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`` attribute. Consult the `storage driver page `__
+ for the list of valid volume format type values for each specific pool. The
+ ``format`` will be ignored on input for pools without a volume format type
+ value and the default pool format will be used. :since:`Since 0.4.1`
+``permissions``
+ Provides information about the 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. There are 4 child elements.
+ The ``mode`` element contains the octal permission set. The ``mode`` defaults
+ to 0600 when not provided. The ``owner`` element contains the numeric user
+ ID. The ``group`` element contains the numeric group ID. If ``owner`` or
+ ``group`` aren't specified when creating a supported volume, the UID and GID
+ of the libvirtd process are used. The ``label`` element contains the MAC (eg
+ SELinux) label string. For existing directory or filesystem based volumes,
+ these fields will be filled with the values used by the existing file.
+ :since:`Since 0.4.1`
+``timestamps``
+ Provides timing information about the volume. Up to four sub-elements are
+ present, where ``atime``, ``btime``, ``ctime`` and ``mtime`` hold the access,
+ birth, change and modification time of the volume, where known. The used time
+ format is . since the beginning of the epoch (1 Jan
+ 1970). If nanosecond resolution is 0 or otherwise unsupported by the host OS
+ or filesystem, then the nanoseconds part is omitted. This is a readonly
+ attribute and is ignored when creating a volume. :since:`Since 0.10.0`
+``encryption``
+ If present, specifies how the volume is encrypted. See the `Storage
+ Encryption `__ page for more information.
+``compat``
+ Specify compatibility level. So far, this is only used for ``type='qcow2'``
+ volumes. Valid values are ``0.10`` and ``1.1`` so far, specifying QEMU
+ version the images should be compatible with. If the ``feature`` element is
+ present, 1.1 is used. :since:`Since 1.1.0` If omitted, 0.10 is used.
+ :since:`Since 1.1.2`
+``nocow``
+ Turn off COW of the newly created volume. So far, this is only valid for a
+ file image in btrfs file system. It will improve performance when the file
+ image is used in VM. To create non-raw file images, it requires QEMU version
+ since 2.1. :since:`Since 1.2.7`
+``clusterSize``
+ Changes the qcow2 cluster size which can affect image file size and
+ performance. :since:`Since 7.4.0`
+``features``
+ Format-specific features. Only used for ``qcow2`` now. Valid sub-elements
+ are:
+
+ - ```` - allow delayed reference counter updates.
+ :since:`Since 1.1.0`
+
+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:
+
+::
+
+ ...
+
+ /var/lib/virt/images/master.img
+
+
+ 107
+ 107
+ 0744
+
+
+
+
+
+``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 volume. :since:`Since 0.6.0`
+``format``
+ Provides information about the pool specific backing store 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. 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. :since:`Since 0.6.0`
+``permissions``
+ Provides information about the permissions of the backing file. See volume
+ ``permissions`` documentation for explanation of individual fields.
+ :since:`Since 0.6.0`
+
+Example configuration
+---------------------
+
+Here are a couple of examples, for a more complete set demonstrating every type
+of storage pool, consult the `storage driver page `__
+
+File based storage pool
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+
+ virtimages
+
+ /var/lib/virt/images
+
+
+
+iSCSI based storage pool
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+
+ virtimages
+
+
+
+
+
+
+
+
+ /dev/disk/by-path
+
+
+
+Storage volume
+~~~~~~~~~~~~~~
+
+::
+
+
+ sparse.img
+ 0
+ 1
+
+ /var/lib/virt/images/sparse.img
+
+ 107
+ 107
+ 0744
+
+
+
+
+
+Storage volume using LUKS
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+
+ MyLuks.img
+ 5
+
+ /var/lib/virt/images/MyLuks.img
+
+
+
+
+
+
diff --git a/docs/meson.build b/docs/meson.build
index 3e708acf0e..04e32f7bf1 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -71,7 +71,6 @@ docs_html_in_files = [
'formatsnapshot',
'formatstoragecaps',
'formatstorageencryption',
- 'formatstorage',
'goals',
'governance',
'hooks',
@@ -118,6 +117,7 @@ docs_rst_files = [
'formatbackup',
'formatcheckpoint',
'formatdomain',
+ 'formatstorage',
'glib-adoption',
'hacking',
'libvirt-go',