+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Storage pool and volume XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="StoragePool">Storage pool XML</a></h2>
-
- <p>
- 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.
- </p>
- <p>
- The top level tag for a storage pool document is 'pool'. It has
- a single attribute <code>type</code>, which is one of <code>dir</code>,
- <code>fs</code>, <code>netfs</code>, <code>disk</code>,
- <code>iscsi</code>, <code>logical</code>, <code>scsi</code>
- (all <span class="since">since 0.4.1</span>),
- <code>mpath</code> (<span class="since">since 0.7.1</span>),
- <code>rbd</code> (<span class="since">since 0.9.13</span>),
- <code>sheepdog</code> (<span class="since">since 0.10.0</span>),
- <code>gluster</code> (<span class="since">since 1.2.0</span>),
- <code>zfs</code> (<span class="since">since 1.2.8</span>),
- <code>vstorage</code> (<span class="since">since 3.1.0</span>),
- or <code>iscsi-direct</code> (<span class="since">since 4.7.0</span>).
- This corresponds to the
- storage backend drivers listed further along in this document.
- </p>
- <h3><a id="StoragePoolFirst">General metadata</a></h3>
-
- <pre>
-<pool type="iscsi">
- <name>virtimages</name>
- <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
- <allocation>10000000</allocation>
- <capacity>50000000</capacity>
- <available>40000000</available>
- ...</pre>
-
- <dl>
- <dt><code>name</code></dt>
- <dd>Providing a name for the pool which is unique to the host.
- This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
- <dt><code>uuid</code></dt>
- <dd>Providing an identifier for the pool which is globally unique.
- This is optional when defining a pool, a UUID will be generated if
- omitted. <span class="since">Since 0.4.1</span></dd>
- <dt><code>allocation</code></dt>
- <dd>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. <span class="since">Since 0.4.1</span></dd>
- <dt><code>capacity</code></dt>
- <dd>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. <span class="since">Since 0.4.1</span></dd>
- <dt><code>available</code></dt>
- <dd>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. <span class="since">Since 0.4.1</span></dd>
- </dl>
-
- <h3><a id="StoragePoolFeatures">Features</a></h3>
-
- <p>
- Some pools support optional features:
- </p>
-
- <pre>
-...
-<features>
- <cow state='no'>
-</features>
-...</pre>
-
- <p>
- Valid features are:
- </p>
- <ul>
- <dd><code>cow</code></dd>
- <dt>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 <code>btrfs</code> filesystem. If not set then libvirt
- will attempt to disable COW on any btrfs filesystems.
- <span class="since">Since 6.6.0</span>.</dt>
- </ul>
-
- <h3><a id="StoragePoolSource">Source elements</a></h3>
-
- <p>
- A single <code>source</code> element is contained within the top level
- <code>pool</code> 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:
- </p>
-
- <pre>
-...
-<source>
- <host name="iscsi.example.com"/>
- <device path="iqn.2013-06.com.example:iscsi-pool"/>
- <auth type='chap' username='myname'>
- <secret usage='mycluster_myname'/>
- </auth>
- <vendor name="Acme"/>
- <product name="model"/>
-</source>
-...</pre>
-
- <pre>
-...
-<source>
- <device path='/dev/mapper/mpatha' part_separator='no'/>
- <format type='gpt'/>
-</source>
-...</pre>
-
- <pre>
-...
-<source>
- <adapter type='scsi_host' name='scsi_host1'/>
-</source>
-...</pre>
-
- <pre>
-...
-<source>
- <adapter type='scsi_host'>
- <parentaddr unique_id='1'>
- <address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/>
- </parentaddr>
- </adapter>
-</source>
-...</pre>
-
- <pre>
-...
-<source>
- <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/>
-</source>
-...</pre>
-
- <pre>
-...
- <source>
- <host name='localhost'/>
- <dir path='/var/lib/libvirt/images'/>
- <format type='nfs'/>
- <protocol ver='3'/>
- </source>
-...</pre>
-
- <dl>
- <dt><code>device</code></dt>
- <dd>Provides the source for pools backed by physical devices
- (pool types <code>fs</code>, <code>logical</code>, <code>disk</code>,
- <code>iscsi</code>, <code>iscsi-direct</code>, <code>zfs</code>,
- <code>vstorage</code>).
- May be repeated multiple times depending on backend driver. Contains
- a required attribute <code>path</code> which is either the fully
- qualified path to the block device node or for <code>iscsi</code>
- or <code>iscsi-direct</code> the iSCSI Qualified Name (IQN).
- <span class="since">Since 0.4.1</span>
- <p>An optional attribute <code>part_separator</code> for each
- <code>path</code> may be supplied. Valid values for the attribute
- may be either "yes" or "no". This attribute is to be used for a
- <code>disk</code> pool type using a <code>path</code> 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.
- <span class="since">Since 1.3.1</span></p></dd>
- <dt><code>dir</code></dt>
- <dd>Provides the source for pools backed by directories (pool
- types <code>dir</code>, <code>netfs</code>, <code>gluster</code>),
- or optionally to select a subdirectory
- within a pool that resembles a filesystem (pool
- type <code>gluster</code>). May
- only occur once. Contains a single attribute <code>path</code>
- which is the fully qualified path to the backing directory or
- for a <code>netfs</code> pool type using <code>format</code>
- type "cifs", the path to the Samba share without the leading slash.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>adapter</code></dt>
- <dd>Provides the source for pools backed by SCSI adapters (pool
- type <code>scsi</code>). May only occur once.
- <dl>
- <dt><code>name</code></dt>
- <dd>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 <code>virsh nodedev-list
- scsi_host</code> command followed by a combination of
- <code>lspci</code> and <code>virsh nodedev-dumpxml
- scsi_hostN</code> commands to find the <code>scsi_hostN</code>
- to be used. <span class="since">Since 0.6.2</span>
- <p>
- It is further recommended to utilize the
- <code>parentaddr</code> element since it's possible to have
- the path to which the scsi_hostN uses change between system
- reboots. <span class="since">Since 1.2.7</span>
- </p>
- </dd>
- </dl>
- <dl>
- <dt><code>type</code></dt>
- <dd>Specifies the adapter type. Valid values are "scsi_host" or
- "fc_host". If omitted and the <code>name</code> attribute is
- specified, then it defaults to "scsi_host". To keep backwards
- compatibility, this attribute is optional <b>only</b> for the
- "scsi_host" adapter, but is mandatory for the "fc_host" adapter.
- <span class="since">Since 1.0.5</span>
- A "fc_host" capable scsi_hostN can be determined by using
- <code>virsh nodedev-list --cap fc_host</code>.
- <span class="since">Since 1.2.8</span>
- <p>
- Note: Regardless of whether a "scsi_host" adapter type is defined
- using a <code>name</code> or a <code>parentaddr</code>, it
- should refer to a real scsi_host adapter as found through a
- <code>virsh nodedev-list scsi_host</code> and <code>virsh
- nodedev-dumpxml scsi_hostN</code> 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 <code>nodedev-dumpxml</code>
- 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
- <code>nodedev-dumpxml</code> output parent field is generally
- "computer". This is a libvirt created parent value indicating
- no parent was defined for the node device.
- </p>
- </dd>
- </dl>
- <dl>
- <dt><code>wwnn</code> and <code>wwpn</code></dt>
- <dd>The required "World Wide Node Name" (<code>wwnn</code>) and
- "World Wide Port Name" (<code>wwpn</code>) 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" <code>type</code> pool instead. The
- <code>wwnn</code> and <code>wwpn</code> 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".
- <span class="since">Since 1.0.4</span>
- </dd>
- </dl>
- <dl>
- <dt><code>parent</code></dt>
- <dd>Used by the "fc_host" adapter type to optionally specify the
- parent scsi_host device defined in the
- <a href="formatnode.html">Node Device</a> database as the
- <a href="https://wiki.libvirt.org/page/NPIV_in_libvirt">NPIV</a>
- 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.
- <span class="since">Since 1.0.4</span>
- </dd>
- <dt><code>parent_wwnn</code> and <code>parent_wwpn</code></dt>
- <dd>Instead of the <code>parent</code> 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.
- <span class="since">Since 3.0.0</span>
- </dd>
- <dt><code>parent_fabric_wwn</code></dt>
- <dd>Instead of the <code>parent</code> 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.
- <span class="since">Since 3.0.0</span>
- </dd>
- <dt><code>managed</code></dt>
- <dd>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.
- <span class="since">Since 1.2.11</span>
- </dd>
- </dl>
- <dl>
- <dt><code>parentaddr</code></dt>
- <dd>Used by the "scsi_host" adapter type instead of the
- <code>name</code> attribute to more uniquely identify the
- SCSI host. Using a combination of the <code>unique_id</code>
- attribute and the <code>address</code> element to formulate
- a PCI address, a search will be performed of the
- <code>/sys/class/scsi_host/hostNN</code> links for a
- matching PCI address with a matching <code>unique_id</code>
- value in the <code>/sys/class/scsi_host/hostNN/unique_id</code>
- file. The value in the "unique_id" file will be unique enough
- for the specific PCI address. The <code>hostNN</code> will be
- used by libvirt as the basis to define which SCSI host is to
- be used for the currently booted system.
- <span class="since">Since 1.2.7</span>
- <dl>
- <dt><code>address</code></dt>
- <dd>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:
- <code>domain</code> (a 2-byte hex integer, not currently used
- by qemu), <code>bus</code> (a hex value between 0 and 0xff,
- inclusive), <code>slot</code> (a hex value between 0x0 and
- 0x1f, inclusive), and <code>function</code> (a value between
- 0 and 7, inclusive). The PCI address can be determined by
- listing the <code>/sys/bus/pci/devices</code> and the
- <code>/sys/class/scsi_host</code> 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
- <code>path</code> element as the basis to formulate the
- correctly formatted PCI address.
- </dd>
- </dl>
- <dl>
- <dt><code>unique_id</code></dt>
- <dd>Required <code>parentaddr</code> 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
- <code>unique_id</code> 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
- <code>find -H /sys/class/scsi_host/host*/unique_id |
- xargs grep '[0-9]'</code>. Optionally, the
- <code>virsh nodedev-dumpxml scsi_hostN</code>' of a
- specific scsi_hostN list entry will list the
- <code>unique_id</code> value.
- </dd>
- </dl>
- </dd>
- </dl>
- </dd>
- <dt><code>host</code></dt>
- <dd>Provides the source for pools backed by storage from a
- remote server (pool types <code>netfs</code>, <code>iscsi</code>,
- <code>iscsi-direct</code>,
- <code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
- used in combination with a <code>directory</code>
- or <code>device</code> element. Contains an attribute <code>name</code>
- which is the hostname or IP address of the server. May optionally
- contain a <code>port</code> 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 <code>directory</code> or <code>device</code>
- element. Name resolution of the provided hostname or IP address
- is left to the storage driver backend interactions with the remote
- server. See the <a href="storage.html">storage driver page</a> for
- any restrictions for specific storage backends.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>initiator</code></dt>
- <dd>Required by the <code>iscsi-direct</code> pool in order to provide
- the iSCSI Qualified Name (IQN) to communicate with the pool's
- <code>device</code> target IQN. There is one sub-element
- <code>iqn</code> with the <code>name</code> attribute to describe
- the IQN for the initiator.
- <span class="since">Since 4.7.0</span></dd>
- <dt><code>auth</code></dt>
- <dd>If present, the <code>auth</code> element provides the
- authentication credentials needed to access the source by the
- setting of the <code>type</code> attribute (pool
- types <code>iscsi</code>, <code>iscsi-direct</code>, <code>rbd</code>).
- The <code>type</code>
- 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
- <code>username</code> identifies the username to use during
- authentication as well as a sub-element <code>secret</code> with
- a mandatory attribute <code>type</code>, to tie back to a
- <a href="formatsecret.html">libvirt secret object</a> 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 <code>secret</code> element requires either a <code>uuid</code>
- attribute with the UUID of the secret object or a <code>usage</code>
- attribute matching the key that was specified in the
- secret object. <span class="since">Since 0.9.7 for "ceph" and
- 1.1.1 for "chap"</span>
- </dd>
- <dt><code>name</code></dt>
- <dd>Provides the source for pools backed by storage from a
- named element (pool types <code>logical</code>, <code>rbd</code>,
- <code>sheepdog</code>, <code>gluster</code>). Contains a
- string identifier.
- <span class="since">Since 0.4.5</span></dd>
- <dt><code>format</code></dt>
- <dd>Provides information about the format of the pool (pool
- types <code>fs</code>, <code>netfs</code>, <code>disk</code>,
- <code>logical</code>). This
- contains a single attribute <code>type</code> 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. <span class="since">Since 0.4.1</span></dd>
-
- <dt><code>protocol</code></dt>
- <dd>For a <code>netfs</code> Storage Pool provide a mechanism to
- define which NFS protocol version number will be used to contact
- the server's NFS service. The attribute <code>ver</code> accepts
- an unsigned integer as the version number to use.
- <span class="since">Since 5.1.0</span></dd>
- <dt><code>vendor</code></dt>
- <dd>Provides optional information about the vendor of the
- storage device. This contains a single
- attribute <code>name</code> whose value is backend
- specific. <span class="since">Since 0.8.4</span></dd>
- <dt><code>product</code></dt>
- <dd>Provides an optional product name of the storage device.
- This contains a single attribute <code>name</code> whose value
- is backend specific. <span class="since">Since 0.8.4</span></dd>
- </dl>
-
- <h3><a id="StoragePoolTarget">Target elements</a></h3>
-
- <p>
- A single <code>target</code> element is contained within the top level
- <code>pool</code> element for some types of pools (pool
- types <code>dir</code>, <code>fs</code>, <code>netfs</code>,
- <code>logical</code>, <code>disk</code>, <code>iscsi</code>,
- <code>scsi</code>, <code>mpath</code>, <code>zfs</code>).
- This tag is used to describe the mapping of
- the storage pool into the host filesystem. It can contain the following
- child elements:
- </p>
-
- <pre>
- ...
- <target>
- <path>/dev/disk/by-path</path>
- <permissions>
- <owner>107</owner>
- <group>107</group>
- <mode>0744</mode>
- <label>virt_image_t</label>
- </permissions>
- </target>
-</pool></pre>
-
- <dl>
- <dt><code>path</code></dt>
- <dd>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 <code>/dev/</code> 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 <code>/dev/disk/by-{path|id|uuid|label}</code> locations.
- For <code>logical</code> and <code>zfs</code> pool types, a
- provided value is ignored and a default path generated.
- For a Multipath pool (type <code>mpath</code>), the provided
- value is ignored and the default value of "/dev/mapper" is used.
- <span class="since">Since 0.4.1</span>
- </dd>
- <dt><code>permissions</code></dt>
- <dd>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 <code>mode</code> element contains the octal permission set.
- The <code>mode</code> defaults to 0711 when not provided.
- The <code>owner</code> element contains the numeric user ID.
- The <code>group</code> element contains the numeric group ID.
- If <code>owner</code> or <code>group</code> aren't specified when
- creating a directory, the UID and GID of the libvirtd process are used.
- The <code>label</code> element contains the MAC (eg SELinux)
- label string.
- <span class="since">Since 0.4.1</span>
- For running directory or filesystem based pools, these fields
- will be filled with the values used by the existing directory.
- <span class="since">Since 1.2.16</span>
- </dd>
- </dl>
-
- <h3><a id="StoragePoolExtents">Device extents</a></h3>
-
- <p>
- If a storage pool exposes information about its underlying
- placement / allocation scheme, the <code>device</code> element
- within the <code>source</code> 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
- </p>
- <p>
- For storage pools supporting extent information, within each
- <code>device</code> element there will be zero or more <code>freeExtent</code>
- elements. Each of these elements contains two attributes, <code>start</code>
- and <code>end</code> which provide the boundaries of the extent on the
- device, measured in bytes. <span class="since">Since 0.4.1</span>
- </p>
-
- <h3><a id="StoragePoolRefresh">Refresh overrides</a></h3>
-
- <p>
- The optional <code>refresh</code> element can control how the pool and
- associated volumes are refreshed (pool type <code>rbd</code>). The
- <code>allocation</code> attribute of the <code>volume</code> child element
- controls the method used for computing the allocation of a volume. The
- valid attribute values are <code>default</code> to compute the actual
- usage or <code>capacity</code> to use the logical capacity for cases where
- computing the allocation is too expensive. The following XML snippet
- shows the syntax:
- <pre>
-<pool type="rbd">
- <name>myrbdpool</name>
-...
- <source/>
-...
- <refresh>
- <volume allocation='capacity'/>
- </refresh>
-...
-</pool>
-</pre>
- <span class="since">Since 5.2.0</span>
- </p>
-
- <h3><a id="StoragePoolNamespaces">Storage Pool Namespaces</a></h3>
-
- <p>
- 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.
- </p>
- <p>
- 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.
- </p>
- <dl>
- <dt><code>fs:mount_opts</code></dt>
- <dd>Provides an XML namespace mechanism to optionally utilize
- specifically named options for the mount command via the "-o"
- option for the <code>fs</code> or <code>netfs</code> type storage
- pools. In order to designate that the Storage Pool will be using
- the mechanism, the <code>pool</code> element must be modified to
- provide the XML namespace attribute syntax as follows:
-
- <p>
- xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'
- </p>
-
- <p>
- The <code>fs:mount_opts</code> defines the mount options by
- specifying multiple <code>fs:option</code> subelements with
- the attribute <code>name</code> 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.
- </p>
-
- The following XML snippet shows the syntax required in order to
- utilize for a netfs pool:
- <pre>
-<pool type="netfs" xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'>
- <name>nfsimages</name>
-...
- <source>
-...
- </source>
-...
- <target>
-...
- </target>
- <fs:mount_opts>
- <fs:option name='sync'/>
- <fs:option name='lazytime'/>
- </fs:mount_opts>
-</pool>
-...</pre>
-
- <span class="since">Since 5.1.0.</span></dd>
-
- <dt><code>rbd:config_opts</code></dt>
- <dd>Provides an XML namespace mechanism to optionally utilize
- specifically named options for the RBD configuration options
- via the rados_conf_set API for the <code>rbd</code> type
- storage pools. In order to designate that the Storage Pool
- will be using the mechanism, the <code>pool</code> element
- must be modified to provide the XML namespace attribute
- syntax as follows:
-
- <p>
- xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'
- </p>
-
- <p>
- The <code>rbd:config_opts</code> defines the configuration options
- by specifying multiple <code>rbd:option</code> subelements with
- the attribute <code>name</code> specifying the configuration option
- to be added and <code>value</code> 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.
- </p>
-
- The following XML snippet shows the syntax required in order to
- utilize
- <pre>
-<pool type="rbd" xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'>
- <name>myrbdpool</name>
-...
- <source>
-...
- </source>
-...
- <target>
-...
- </target>
-...
- <rbd:config_opts>
- <rbd:option name='client_mount_timeout' value='45'/>
- <rbd:option name='rados_mon_op_timeout' value='20'/>
- <rbd:option name='rados_osd_op_timeout' value='10'/>
- </rbd:config_opts>
-</pool>
-</pre>
-
- <span class="since">Since 5.1.0.</span></dd>
-
- </dl>
-
- <h2><a id="StorageVol">Storage volume XML</a></h2>
- <p>
- A storage volume will generally be either a file or a device
- node; <span class="since">since 1.2.0</span>, an optional
- output-only attribute <code>type</code> lists the actual type
- (file, block, dir, network, netdir or ploop), which is also available
- from <code>virStorageVolGetInfo()</code>. The storage volume
- XML format is available <span class="since">since 0.4.1</span>
- </p>
-
- <h3><a id="StorageVolFirst">General metadata</a></h3>
-
- <pre>
-<volume type='file'>
- <name>sparse.img</name>
- <key>/var/lib/xen/images/sparse.img</key>
- <allocation>0</allocation>
- <capacity unit="T">1</capacity>
- ...</pre>
-
- <dl>
- <dt><code>name</code></dt>
- <dd>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 <code>source</code> device path
- device and next partition number to be created. For example, if
- the <code>source</code> 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.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>key</code></dt>
- <dd>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.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>allocation</code></dt>
- <dd>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 <strong>option</strong> 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 <code>logical</code>
- 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.<br/>
- <br/>
- By default this is specified in bytes, but an optional attribute
- <code>unit</code> can be specified to adjust the passed value.
- Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes,
- 10<sup>3</sup> or 1000 bytes), 'K' or 'KiB' (kibibytes,
- 2<sup>10</sup> or 1024 bytes), 'MB' (megabytes, 10<sup>6</sup>
- or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 2<sup>20</sup>
- or 1,048,576 bytes), 'GB' (gigabytes, 10<sup>9</sup> or
- 1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 2<sup>30</sup>
- or 1,073,741,824 bytes), 'TB' (terabytes, 10<sup>12</sup> or
- 1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes,
- 2<sup>40</sup> or 1,099,511,627,776 bytes), 'PB' (petabytes,
- 10<sup>15</sup> or 1,000,000,000,000,000 bytes), 'P' or 'PiB'
- (pebibytes, 2<sup>50</sup> or 1,125,899,906,842,624 bytes),
- 'EB' (exabytes, 10<sup>18</sup> or 1,000,000,000,000,000,000
- bytes), or 'E' or 'EiB' (exbibytes, 2<sup>60</sup> or
- 1,152,921,504,606,846,976 bytes). <span class="since">Since
- 0.4.1, multi-character <code>unit</code> since
- 0.9.11</span></dd>
- <dt><code>capacity</code></dt>
- <dd>Providing the logical capacity for the volume. This value is
- in bytes by default, but a <code>unit</code> attribute can be
- specified with the same semantics as for <code>allocation</code>
- This is compulsory when creating a volume.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>physical</code></dt>
- <dd>This output only element provides the host physical size of
- the target storage volume. The default output <code>unit</code>
- will be in bytes.
- <span class="since">Since 3.0.0</span></dd>
- <dt><code>source</code></dt>
- <dd>Provides information about the underlying storage allocation
- of the volume. This may not be available for some pool types.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>target</code></dt>
- <dd>Provides information about the representation of the volume
- on the local host. <span class="since">Since 0.4.1</span></dd>
- </dl>
-
- <h3><a id="StorageVolTarget">Target elements</a></h3>
-
- <p>
- A single <code>target</code> element is contained within the top level
- <code>volume</code> element. This tag is used to describe the mapping of
- the storage volume into the host filesystem. It can contain the following
- child elements:
- </p>
-
- <pre>
-...
-<target>
- <path>/var/lib/virt/images/sparse.img</path>
- <format type='qcow2'/>
- <permissions>
- <owner>107</owner>
- <group>107</group>
- <mode>0744</mode>
- <label>virt_image_t</label>
- </permissions>
- <timestamps>
- <atime>1341933637.273190990</atime>
- <mtime>1341930622.047245868</mtime>
- <ctime>1341930622.047245868</ctime>
- </timestamps>
- <encryption type='...'>
- ...
- </encryption>
- <compat>1.1</compat>
- <nocow/>
- <clusterSize unit='KiB'>64</clusterSize>
- <features>
- <lazy_refcounts/>
- </features>
-</target></pre>
-
- <dl>
- <dt><code>path</code></dt>
- <dd>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.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>format</code></dt>
- <dd>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 <code>type</code> attribute. Consult the
- <a href="storage.html">storage driver page</a> for the list of valid
- volume format type values for each specific pool. The
- <code>format</code> will be ignored on input for pools without a
- volume format type value and the default pool format will be used.
- <span class="since">Since 0.4.1</span></dd>
- <dt><code>permissions</code></dt>
- <dd>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 <code>mode</code> element contains the octal permission set.
- The <code>mode</code> defaults to 0600 when not provided.
- The <code>owner</code> element contains the numeric user ID.
- The <code>group</code> element contains the numeric group ID.
- If <code>owner</code> or <code>group</code> aren't specified when
- creating a supported volume, the UID and GID of the libvirtd process
- are used. The <code>label</code> 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.
- <span class="since">Since 0.4.1</span>
- </dd>
- <dt><code>timestamps</code></dt>
- <dd>Provides timing information about the volume. Up to four
- sub-elements are present,
- where <code>atime</code>, <code>btime</code>, <code>ctime</code>
- and <code>mtime</code> 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.
- <span class="since">Since 0.10.0</span>
- </dd>
- <dt><code>encryption</code></dt>
- <dd>If present, specifies how the volume is encrypted. See
- the <a href="formatstorageencryption.html">Storage Encryption</a> page
- for more information.
- </dd>
- <dt><code>compat</code></dt>
- <dd>Specify compatibility level. So far, this is only used for
- <code>type='qcow2'</code> volumes. Valid values are <code>0.10</code>
- and <code>1.1</code> so far, specifying QEMU version the images should
- be compatible with. If the <code>feature</code> element is present,
- 1.1 is used.
- <span class="since">Since 1.1.0</span> If omitted, 0.10 is used.
- <span class="since">Since 1.1.2</span>
- </dd>
- <dt><code>nocow</code></dt>
- <dd>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. <span class="since">Since 1.2.7</span>
- </dd>
- <dt><code>clusterSize</code></dt>
- <dd>Changes the qcow2 cluster size which can affect image file size
- and performance.
- <span class="since">Since 7.4.0</span>
- </dd>
- <dt><code>features</code></dt>
- <dd>Format-specific features. Only used for <code>qcow2</code> now.
- Valid sub-elements are:
- <ul>
- <li><code><lazy_refcounts/></code> - allow delayed reference
- counter updates. <span class="since">Since 1.1.0</span></li>
- </ul>
- </dd>
- </dl>
-
- <h3><a id="StorageVolBacking">Backing store elements</a></h3>
-
- <p>
- A single <code>backingStore</code> element is contained within the top level
- <code>volume</code> 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:
- </p>
-
- <pre>
- ...
- <backingStore>
- <path>/var/lib/virt/images/master.img</path>
- <format type='raw'/>
- <permissions>
- <owner>107</owner>
- <group>107</group>
- <mode>0744</mode>
- <label>virt_image_t</label>
- </permissions>
- </backingStore>
-</volume></pre>
-
- <dl>
- <dt><code>path</code></dt>
- <dd>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.
- <span class="since">Since 0.6.0</span></dd>
- <dt><code>format</code></dt>
- <dd>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.
- <span class="since">Since 0.6.0</span></dd>
- <dt><code>permissions</code></dt>
- <dd>Provides information about the permissions of the backing file.
- See volume <code>permissions</code> documentation for explanation
- of individual fields.
- <span class="since">Since 0.6.0</span>
- </dd>
- </dl>
-
- <h2><a id="examples">Example configuration</a></h2>
-
- <p>
- Here are a couple of examples, for a more complete set demonstrating
- every type of storage pool, consult the <a href="storage.html">storage driver page</a>
- </p>
-
- <h3><a id="exampleFile">File based storage pool</a></h3>
-
- <pre>
-<pool type="dir">
- <name>virtimages</name>
- <target>
- <path>/var/lib/virt/images</path>
- </target>
-</pool></pre>
-
- <h3><a id="exampleISCSI">iSCSI based storage pool</a></h3>
-
- <pre>
-<pool type="iscsi">
- <name>virtimages</name>
- <source>
- <host name="iscsi.example.com"/>
- <device path="iqn.2013-06.com.example:iscsi-pool"/>
- <auth type='chap' username='myuser'>
- <secret usage='libvirtiscsi'/>
- </auth>
- </source>
- <target>
- <path>/dev/disk/by-path</path>
- </target>
-</pool></pre>
-
- <h3><a id="exampleVol">Storage volume</a></h3>
-
- <pre>
-<volume>
- <name>sparse.img</name>
- <allocation>0</allocation>
- <capacity unit="T">1</capacity>
- <target>
- <path>/var/lib/virt/images/sparse.img</path>
- <permissions>
- <owner>107</owner>
- <group>107</group>
- <mode>0744</mode>
- <label>virt_image_t</label>
- </permissions>
- </target>
-</volume></pre>
-
- <h3><a id="exampleLuks">Storage volume using LUKS</a></h3>
-
- <pre>
-<volume>
- <name>MyLuks.img</name>
- <capacity unit="G">5</capacity>
- <target>
- <path>/var/lib/virt/images/MyLuks.img</path>
- <format type='raw'/>
- <encryption format='luks'>
- <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
- </encryption>
- </target>
-</volume>
- </pre>
- </body>
-</html>
--- /dev/null
+.. 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="iscsi">
+ <name>virtimages</name>
+ <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
+ <allocation>10000000</allocation>
+ <capacity>50000000</capacity>
+ <available>40000000</available>
+ ...
+
+``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:
+
+::
+
+ ...
+ <features>
+ <cow state='no'>
+ </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:
+
+::
+
+ ...
+ <source>
+ <host name="iscsi.example.com"/>
+ <device path="iqn.2013-06.com.example:iscsi-pool"/>
+ <auth type='chap' username='myname'>
+ <secret usage='mycluster_myname'/>
+ </auth>
+ <vendor name="Acme"/>
+ <product name="model"/>
+ </source>
+ ...
+
+::
+
+ ...
+ <source>
+ <device path='/dev/mapper/mpatha' part_separator='no'/>
+ <format type='gpt'/>
+ </source>
+ ...
+
+::
+
+ ...
+ <source>
+ <adapter type='scsi_host' name='scsi_host1'/>
+ </source>
+ ...
+
+::
+
+ ...
+ <source>
+ <adapter type='scsi_host'>
+ <parentaddr unique_id='1'>
+ <address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/>
+ </parentaddr>
+ </adapter>
+ </source>
+ ...
+
+::
+
+ ...
+ <source>
+ <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/>
+ </source>
+ ...
+
+::
+
+ ...
+ <source>
+ <host name='localhost'/>
+ <dir path='/var/lib/libvirt/images'/>
+ <format type='nfs'/>
+ <protocol ver='3'/>
+ </source>
+ ...
+
+``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 <formatnode.html>`__ database
+ as the `NPIV <https://wiki.libvirt.org/page/NPIV_in_libvirt>`__ 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 <storage.html>`__ 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 <formatsecret.html>`__ 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:
+
+::
+
+ ...
+ <target>
+ <path>/dev/disk/by-path</path>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ </target>
+ </pool>
+
+``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:
+
+::
+
+ <pool type="rbd">
+ <name>myrbdpool</name>
+ ...
+ <source/>
+ ...
+ <refresh>
+ <volume allocation='capacity'/>
+ </refresh>
+ ...
+ </pool>
+
+: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:
+
+ ::
+
+ <pool type="netfs" xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'>
+ <name>nfsimages</name>
+ ...
+ <source>
+ ...
+ </source>
+ ...
+ <target>
+ ...
+ </target>
+ <fs:mount_opts>
+ <fs:option name='sync'/>
+ <fs:option name='lazytime'/>
+ </fs:mount_opts>
+ </pool>
+ ...
+
+ :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
+
+ ::
+
+ <pool type="rbd" xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'>
+ <name>myrbdpool</name>
+ ...
+ <source>
+ ...
+ </source>
+ ...
+ <target>
+ ...
+ </target>
+ ...
+ <rbd:config_opts>
+ <rbd:option name='client_mount_timeout' value='45'/>
+ <rbd:option name='rados_mon_op_timeout' value='20'/>
+ <rbd:option name='rados_osd_op_timeout' value='10'/>
+ </rbd:config_opts>
+ </pool>
+
+ :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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <volume type='file'>
+ <name>sparse.img</name>
+ <key>/var/lib/xen/images/sparse.img</key>
+ <allocation>0</allocation>
+ <capacity unit="T">1</capacity>
+ ...
+
+``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:
+
+::
+
+ ...
+ <target>
+ <path>/var/lib/virt/images/sparse.img</path>
+ <format type='qcow2'/>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ <timestamps>
+ <atime>1341933637.273190990</atime>
+ <mtime>1341930622.047245868</mtime>
+ <ctime>1341930622.047245868</ctime>
+ </timestamps>
+ <encryption type='...'>
+ ...
+ </encryption>
+ <compat>1.1</compat>
+ <nocow/>
+ <clusterSize unit='KiB'>64</clusterSize>
+ <features>
+ <lazy_refcounts/>
+ </features>
+ </target>
+
+``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 <storage.html>`__
+ 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 <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:`Since 0.10.0`
+``encryption``
+ If present, specifies how the volume is encrypted. See the `Storage
+ Encryption <formatstorageencryption.html>`__ 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:
+
+ - ``<lazy_refcounts/>`` - 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:
+
+::
+
+ ...
+ <backingStore>
+ <path>/var/lib/virt/images/master.img</path>
+ <format type='raw'/>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ </backingStore>
+ </volume>
+
+``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 <storage.html>`__
+
+File based storage pool
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="dir">
+ <name>virtimages</name>
+ <target>
+ <path>/var/lib/virt/images</path>
+ </target>
+ </pool>
+
+iSCSI based storage pool
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="iscsi">
+ <name>virtimages</name>
+ <source>
+ <host name="iscsi.example.com"/>
+ <device path="iqn.2013-06.com.example:iscsi-pool"/>
+ <auth type='chap' username='myuser'>
+ <secret usage='libvirtiscsi'/>
+ </auth>
+ </source>
+ <target>
+ <path>/dev/disk/by-path</path>
+ </target>
+ </pool>
+
+Storage volume
+~~~~~~~~~~~~~~
+
+::
+
+ <volume>
+ <name>sparse.img</name>
+ <allocation>0</allocation>
+ <capacity unit="T">1</capacity>
+ <target>
+ <path>/var/lib/virt/images/sparse.img</path>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ </target>
+ </volume>
+
+Storage volume using LUKS
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <volume>
+ <name>MyLuks.img</name>
+ <capacity unit="G">5</capacity>
+ <target>
+ <path>/var/lib/virt/images/MyLuks.img</path>
+ <format type='raw'/>
+ <encryption format='luks'>
+ <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
+ </encryption>
+ </target>
+ </volume>
projects / thirdparty / libvirt.git / commitdiff
