docs/formatstorage.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>Storage pool and volume XML format</h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <h2><a id="StoragePool">Storage pool XML</a></h2>
  10
  11     <p>
  12       Although all storage pool backends share the same public APIs and
  13       XML format, they have varying levels of capabilities. Some may
  14       allow creation of volumes, others may only allow use of pre-existing
  15       volumes. Some may have constraints on volume size, or placement.
  16     </p>
  17     <p>
  18       The top level tag for a storage pool document is 'pool'. It has
  19       a single attribute <code>type</code>, which is one of <code>dir</code>,
  20       <code>fs</code>, <code>netfs</code>, <code>disk</code>,
  21       <code>iscsi</code>, <code>logical</code>, <code>scsi</code>
  22       (all <span class="since">since 0.4.1</span>),
  23       <code>mpath</code> (<span class="since">since 0.7.1</span>),
  24       <code>rbd</code> (<span class="since">since 0.9.13</span>),
  25       <code>sheepdog</code> (<span class="since">since 0.10.0</span>),
  26       <code>gluster</code> (<span class="since">since 1.2.0</span>),
  27       <code>zfs</code> (<span class="since">since 1.2.8</span>),
  28       <code>vstorage</code> (<span class="since">since 3.1.0</span>),
  29       or <code>iscsi-direct</code> (<span class="since">since 4.7.0</span>).
  30       This corresponds to the
  31       storage backend drivers listed further along in this document.
  32     </p>
  33     <h3><a id="StoragePoolFirst">General metadata</a></h3>
  34
  35     <pre>
  36 &lt;pool type="iscsi"&gt;
  37   &lt;name&gt;virtimages&lt;/name&gt;
  38   &lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
  39   &lt;allocation&gt;10000000&lt;/allocation&gt;
  40   &lt;capacity&gt;50000000&lt;/capacity&gt;
  41   &lt;available&gt;40000000&lt;/available&gt;
  42   ...</pre>
  43
  44     <dl>
  45       <dt><code>name</code></dt>
  46       <dd>Providing a name for the pool which is unique to the host.
  47         This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
  48       <dt><code>uuid</code></dt>
  49       <dd>Providing an identifier for the pool which is globally unique.
  50         This is optional when defining a pool, a UUID will be generated if
  51         omitted. <span class="since">Since 0.4.1</span></dd>
  52       <dt><code>allocation</code></dt>
  53       <dd>Providing the total storage allocation for the pool. This may
  54         be larger than the sum of the allocation of all volumes due to
  55         metadata overhead. This value is in bytes. This is not applicable
  56         when creating a pool. <span class="since">Since 0.4.1</span></dd>
  57       <dt><code>capacity</code></dt>
  58       <dd>Providing the total storage capacity for the pool. Due to
  59         underlying device constraints it may not be possible to use the
  60         full capacity for storage volumes. This value is in bytes. This
  61         is not applicable when creating a pool. <span class="since">Since 0.4.1</span></dd>
  62       <dt><code>available</code></dt>
  63       <dd>Providing the free space available for allocating new volumes
  64         in the pool. Due to underlying device constraints it may not be
  65         possible to allocate the entire free space to a single volume.
  66         This value is in bytes. This is not applicable when creating a
  67         pool. <span class="since">Since 0.4.1</span></dd>
  68     </dl>
  69
  70     <h3><a id="StoragePoolSource">Source elements</a></h3>
  71
  72     <p>
  73       A single <code>source</code> element is contained within the top level
  74       <code>pool</code> element. This tag is used to describe the source of
  75       the storage pool. The set of child elements that it will contain
  76       depend on the pool type, but come from the following child elements:
  77     </p>
  78
  79     <pre>
  80 ...
  81 &lt;source&gt;
  82   &lt;host name="iscsi.example.com"/&gt;
  83   &lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
  84   &lt;auth type='chap' username='myname'&gt;
  85     &lt;secret usage='mycluster_myname'/&gt;
  86   &lt;/auth&gt;
  87   &lt;vendor name="Acme"/&gt;
  88   &lt;product name="model"/&gt;
  89 &lt;/source&gt;
  90 ...</pre>
  91
  92     <pre>
  93 ...
  94 &lt;source&gt;
  95   &lt;device path='/dev/mapper/mpatha' part_separator='no'/&gt;
  96   &lt;format type='gpt'/&gt;
  97 &lt;/source&gt;
  98 ...</pre>
  99
 100     <pre>
 101 ...
 102 &lt;source&gt;
 103   &lt;adapter type='scsi_host' name='scsi_host1'/&gt;
 104 &lt;/source&gt;
 105 ...</pre>
 106
 107     <pre>
 108 ...
 109 &lt;source&gt;
 110   &lt;adapter type='scsi_host'&gt;
 111     &lt;parentaddr unique_id='1'&gt;
 112       &lt;address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/&gt;
 113     &lt;/parentaddr&gt;
 114   &lt;/adapter&gt;
 115 &lt;/source&gt;
 116 ...</pre>
 117
 118     <pre>
 119 ...
 120 &lt;source&gt;
 121   &lt;adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/&gt;
 122 &lt;/source&gt;
 123 ...</pre>
 124
 125     <pre>
 126 ...
 127   &lt;source&gt;
 128     &lt;host name='localhost'/&gt;
 129     &lt;dir path='/var/lib/libvirt/images'/&gt;
 130     &lt;format type='nfs'/&gt;
 131     &lt;protocol ver='3'/&gt;
 132   &lt;/source&gt;
 133 ...</pre>
 134
 135     <dl>
 136       <dt><code>device</code></dt>
 137       <dd>Provides the source for pools backed by physical devices
 138         (pool types <code>fs</code>, <code>logical</code>, <code>disk</code>,
 139         <code>iscsi</code>, <code>iscsi-direct</code>, <code>zfs</code>,
 140         <code>vstorage</code>).
 141         May be repeated multiple times depending on backend driver. Contains
 142         a required attribute <code>path</code> which is either the fully
 143         qualified path to the block device node or for <code>iscsi</code>
 144         or <code>iscsi-direct</code> the iSCSI Qualified Name (IQN).
 145         <span class="since">Since 0.4.1</span>
 146         <p>An optional attribute <code>part_separator</code> for each
 147         <code>path</code> may be supplied. Valid values for the attribute
 148         may be either "yes" or "no". This attribute is to be used for a
 149         <code>disk</code> pool type using a <code>path</code> to a
 150         device mapper multipath device. Setting the attribute to "yes"
 151         causes libvirt to attempt to generate and find target volume path's
 152         using a "p" separator. The default algorithm used by device mapper
 153         is to add the "p" separator only when the source device path ends
 154         with a number; however, it's possible to configure the devmapper
 155         device to not use 'user_friendly_names' thus creating partitions
 156         with the "p" separator even when the device source path does not
 157         end with a number.
 158         <span class="since">Since 1.3.1</span></p></dd>
 159       <dt><code>dir</code></dt>
 160       <dd>Provides the source for pools backed by directories (pool
 161         types <code>dir</code>, <code>netfs</code>, <code>gluster</code>),
 162         or optionally to select a subdirectory
 163         within a pool that resembles a filesystem (pool
 164         type <code>gluster</code>). May
 165         only occur once. Contains a single attribute <code>path</code>
 166         which is the fully qualified path to the backing directory or
 167         for a <code>netfs</code> pool type using <code>format</code>
 168         type "cifs", the path to the Samba share without the leading slash.
 169         <span class="since">Since 0.4.1</span></dd>
 170       <dt><code>adapter</code></dt>
 171       <dd>Provides the source for pools backed by SCSI adapters (pool
 172         type <code>scsi</code>). May only occur once.
 173         <dl>
 174           <dt><code>name</code></dt>
 175           <dd>The SCSI adapter name (e.g. "scsi_host1", although a name
 176             such as "host1" is still supported for backwards compatibility,
 177             it is not recommended). The scsi_host name to be used can be
 178             determined from the output of a <code>virsh nodedev-list
 179             scsi_host</code> command followed by a combination of
 180             <code>lspci</code> and <code>virsh nodedev-dumpxml
 181             scsi_hostN</code> commands to find the <code>scsi_hostN</code>
 182             to be used. <span class="since">Since 0.6.2</span>
 183             <p>
 184             It is further recommended to utilize the
 185             <code>parentaddr</code> element since it's possible to have
 186             the path to which the scsi_hostN uses change between system
 187             reboots. <span class="since">Since 1.2.7</span>
 188             </p>
 189           </dd>
 190         </dl>
 191         <dl>
 192           <dt><code>type</code></dt>
 193           <dd>Specifies the adapter type. Valid values are "scsi_host" or
 194             "fc_host". If omitted and the <code>name</code> attribute is
 195             specified, then it defaults to "scsi_host". To keep backwards
 196             compatibility, this attribute is optional <b>only</b> for the
 197             "scsi_host" adapter, but is mandatory for the "fc_host" adapter.
 198             <span class="since">Since 1.0.5</span>
 199             A "fc_host" capable scsi_hostN can be determined by using
 200             <code>virsh nodedev-list --cap fc_host</code>.
 201             <span class="since">Since 1.2.8</span>
 202             <p>
 203             Note: Regardless of whether a "scsi_host" adapter type is defined
 204             using a <code>name</code> or a <code>parentaddr</code>, it
 205             should refer to a real scsi_host adapter as found through a
 206             <code>virsh nodedev-list scsi_host</code> and <code>virsh
 207             nodedev-dumpxml scsi_hostN</code> on one of the scsi_host's
 208             displayed. It should not refer to a "fc_host" capable scsi_hostN
 209             nor should it refer to the vHBA created for some "fc_host"
 210             adapter. For a vHBA the <code>nodedev-dumpxml</code>
 211             output parent setting will be the "fc_host" capable scsi_hostN
 212             value. Additionally, do not refer to an iSCSI scsi_hostN for the
 213             "scsi_host" source. An iSCSI scsi_hostN's
 214             <code>nodedev-dumpxml</code> output parent field is generally
 215             "computer". This is a libvirt created parent value indicating
 216             no parent was defined for the node device.
 217             </p>
 218             </dd>
 219         </dl>
 220         <dl>
 221           <dt><code>wwnn</code> and <code>wwpn</code></dt>
 222           <dd>The required "World Wide Node Name" (<code>wwnn</code>) and
 223             "World Wide Port Name" (<code>wwpn</code>) are used by the
 224             "fc_host" adapter to uniquely identify the vHBA device in the
 225             Fibre Channel storage fabric. If the vHBA device already exists
 226             as a Node Device, then libvirt will use it; otherwise, the vHBA
 227             will be created using the provided values. It is considered a
 228             configuration error use the values from the HBA as those would
 229             be for a "scsi_host" <code>type</code> pool instead. The
 230             <code>wwnn</code> and <code>wwpn</code> have very specific
 231             format requirements based on the hypervisor being used, thus
 232             care should be taken if you decide to generate your own to
 233             follow the standards; otherwise, the pool will fail to start
 234             with an opaque error message indicating failure to write to
 235             the vport_create file during vport create/delete due to
 236             "No such file or directory".
 237             <span class="since">Since 1.0.4</span>
 238           </dd>
 239         </dl>
 240         <dl>
 241           <dt><code>parent</code></dt>
 242           <dd>Used by the "fc_host" adapter type to optionally specify the
 243             parent scsi_host device defined in the
 244             <a href="formatnode.html">Node Device</a> database as the
 245             <a href="http://wiki.libvirt.org/page/NPIV_in_libvirt">NPIV</a>
 246             virtual Host Bus Adapter (vHBA). The value provided must be
 247             a vport capable scsi_host. The value is not the scsi_host of
 248             the vHBA created by 'virsh nodedev-create', rather it is
 249             the parent of that vHBA. If the value is not provided, libvirt
 250             will determine the parent based either finding the wwnn,wwpn
 251             defined for an existing scsi_host or by creating a vHBA. Providing
 252             the parent attribute is also useful for the duplicate pool
 253             definition checks. This is more important in environments where
 254             both the "fc_host" and "scsi_host" source adapter pools are being
 255             used in order to ensure a new definition doesn't duplicate using
 256             the scsi_hostN of some existing storage pool.
 257             <span class="since">Since 1.0.4</span>
 258           </dd>
 259           <dt><code>parent_wwnn</code> and <code>parent_wwpn</code></dt>
 260           <dd>Instead of the <code>parent</code> to specify which scsi_host
 261             to use by name, it's possible to provide the wwnn and wwpn of
 262             the parent to be used for the vHBA in order to ensure that
 263             between reboots or after a hardware configuration change that
 264             the scsi_host parent name doesn't change. Both the parent_wwnn
 265             and parent_wwpn must be provided.
 266             <span class="since">Since 3.0.0</span>
 267           </dd>
 268           <dt><code>parent_fabric_wwn</code></dt>
 269           <dd>Instead of the <code>parent</code> to specify which scsi_host
 270             to use by name, it's possible to provide the fabric_wwn on which
 271             the scsi_host exists. This provides flexibility for choosing
 272             a scsi_host that may be available on the fabric rather than
 273             requiring a specific parent by wwnn or wwpn to be available.
 274             <span class="since">Since 3.0.0</span>
 275           </dd>
 276           <dt><code>managed</code></dt>
 277           <dd>An optional attribute to instruct the SCSI storage backend to
 278             manage destroying the vHBA when the pool is destroyed. For
 279             configurations that do not provide an already created vHBA
 280             from a 'virsh nodedev-create', libvirt will set this property
 281             to "yes". For configurations that have already created a vHBA
 282             via 'virsh nodedev-create' and are using the wwnn/wwpn from
 283             that vHBA and optionally the scsi_host parent, setting this
 284             attribute to "yes" will allow libvirt to destroy the node device
 285             when the pool is destroyed. If this attribute is set to "no" or
 286             not defined in the XML, then libvirt will not destroy the vHBA.
 287             <span class="since">Since 1.2.11</span>
 288           </dd>
 289         </dl>
 290         <dl>
 291           <dt><code>parentaddr</code></dt>
 292           <dd>Used by the "scsi_host" adapter type instead of the
 293             <code>name</code> attribute to more uniquely identify the
 294             SCSI host. Using a combination of the <code>unique_id</code>
 295             attribute and the <code>address</code> element to formulate
 296             a PCI address, a search will be performed of the
 297             <code>/sys/class/scsi_host/hostNN</code> links for a
 298             matching PCI address with a matching <code>unique_id</code>
 299             value in the <code>/sys/class/scsi_host/hostNN/unique_id</code>
 300             file. The value in the "unique_id" file will be unique enough
 301             for the specific PCI address. The <code>hostNN</code> will be
 302             used by libvirt as the basis to define which SCSI host is to
 303             be used for the currently booted system.
 304             <span class="since">Since 1.2.7</span>
 305             <dl>
 306               <dt><code>address</code></dt>
 307               <dd>The PCI address of the scsi_host device to be used. Using
 308                 a PCI address provides consistent naming across system reboots
 309                 and kernel reloads. The address will have four attributes:
 310                 <code>domain</code> (a 2-byte hex integer, not currently used
 311                 by qemu), <code>bus</code> (a hex value between 0 and 0xff,
 312                 inclusive), <code>slot</code> (a hex value between 0x0 and
 313                 0x1f, inclusive), and <code>function</code> (a value between
 314                 0 and 7, inclusive). The PCI address can be determined by
 315                 listing the <code>/sys/bus/pci/devices</code> and the
 316                 <code>/sys/class/scsi_host</code> directories in order to
 317                 find the expected scsi_host device. The address will be
 318                 provided in a format such as "0000:00:1f:2" which can be
 319                 used to generate the expected PCI address
 320                 "domain='0x0000' bus='0x00' slot='0x1f' function='0x0'".
 321                 Optionally, using the combination of the commands 'virsh
 322                 nodedev-list scsi_host' and 'virsh nodedev-dumpxml' for a
 323                 specific list entry and converting the resulting
 324                 <code>path</code> element as the basis to formulate the
 325                 correctly formatted PCI address.
 326               </dd>
 327             </dl>
 328             <dl>
 329               <dt><code>unique_id</code></dt>
 330               <dd>Required <code>parentaddr</code> attribute used to determine
 331                 which of the scsi_host adapters for the provided PCI address
 332                 should be used. The value is determine by contents of the
 333                 <code>unique_id</code> file for the specific scsi_host adapter.
 334                 For a PCI address of "0000:00:1f:2", the unique identifer files
 335                 can be found using the command
 336                 <code>find -H /sys/class/scsi_host/host*/unique_id |
 337                 xargs grep '[0-9]'</code>. Optionally, the
 338                 <code>virsh nodedev-dumpxml scsi_hostN</code>' of a
 339                 specific scsi_hostN list entry will list the
 340                 <code>unique_id</code> value.
 341               </dd>
 342             </dl>
 343           </dd>
 344         </dl>
 345       </dd>
 346       <dt><code>host</code></dt>
 347       <dd>Provides the source for pools backed by storage from a
 348         remote server (pool types <code>netfs</code>, <code>iscsi</code>,
 349         <code>iscsi-direct</code>,
 350         <code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
 351         used in combination with a <code>directory</code>
 352         or <code>device</code> element. Contains an attribute <code>name</code>
 353         which is the hostname or IP address of the server. May optionally
 354         contain a <code>port</code> attribute for the protocol specific
 355         port number. Duplicate storage pool definition checks may perform
 356         a cursory check that the same host name by string comparison in the
 357         new pool does not match an existing pool's source host name when
 358         combined with the <code>directory</code> or <code>device</code>
 359         element. Name resolution of the provided hostname or IP address
 360         is left to the storage driver backend interactions with the remote
 361         server. See the <a href="storage.html">storage driver page</a> for
 362         any restrictions for specific storage backends.
 363         <span class="since">Since 0.4.1</span></dd>
 364       <dt><code>initiator</code></dt>
 365       <dd>Required by the <code>iscsi-direct</code> pool in order to provide
 366         the iSCSI Qualified Name (IQN) to communicate with the pool's
 367         <code>device</code> target IQN. There is one sub-element
 368         <code>iqn</code> with the <code>name</code> attribute to describe
 369         the IQN for the initiator.
 370         <span class="since">Since 4.7.0</span></dd>
 371       <dt><code>auth</code></dt>
 372       <dd>If present, the <code>auth</code> element provides the
 373         authentication credentials needed to access the source by the
 374         setting of the <code>type</code> attribute (pool
 375         types <code>iscsi</code>, <code>iscsi-direct</code>, <code>rbd</code>).
 376         The <code>type</code>
 377         must be either "chap" or "ceph". Use "ceph" for
 378         Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
 379         (Challenge-Handshake Authentication Protocol) iSCSI
 380         targets. Additionally a mandatory attribute
 381         <code>username</code> identifies the username to use during
 382         authentication as well as a sub-element <code>secret</code> with
 383         a mandatory attribute <code>type</code>, to tie back to a
 384         <a href="formatsecret.html">libvirt secret object</a> that
 385         holds the actual password or other credentials. The domain XML
 386         intentionally does not expose the password, only the reference
 387         to the object that manages the password.
 388         The <code>secret</code> element requires either a <code>uuid</code>
 389         attribute with the UUID of the secret object or a <code>usage</code>
 390         attribute matching the key that was specified in the
 391         secret object.  <span class="since">Since 0.9.7 for "ceph" and
 392         1.1.1 for "chap"</span>
 393       </dd>
 394       <dt><code>name</code></dt>
 395       <dd>Provides the source for pools backed by storage from a
 396         named element (pool types <code>logical</code>, <code>rbd</code>,
 397         <code>sheepdog</code>, <code>gluster</code>).  Contains a
 398         string identifier.
 399         <span class="since">Since 0.4.5</span></dd>
 400       <dt><code>format</code></dt>
 401       <dd>Provides information about the format of the pool (pool
 402         types <code>fs</code>, <code>netfs</code>, <code>disk</code>,
 403         <code>logical</code>). This
 404         contains a single attribute <code>type</code> whose value is
 405         backend specific. This is typically used to indicate filesystem
 406         type, or network filesystem type, or partition table type, or
 407         LVM metadata type. All drivers are required to have a default
 408         value for this, so it is optional. <span class="since">Since 0.4.1</span></dd>
 409
 410       <dt><code>protocol</code></dt>
 411       <dd>For a <code>netfs</code> Storage Pool provide a mechanism to
 412         define which NFS protocol version number will be used to contact
 413         the server's NFS service. The attribute <code>ver</code> accepts
 414         an unsigned integer as the version number to use.
 415         <span class="since">Since 5.1.0</span></dd>
 416       <dt><code>vendor</code></dt>
 417       <dd>Provides optional information about the vendor of the
 418         storage device. This contains a single
 419         attribute <code>name</code> whose value is backend
 420         specific. <span class="since">Since 0.8.4</span></dd>
 421       <dt><code>product</code></dt>
 422       <dd>Provides an optional product name of the storage device.
 423         This contains a single attribute <code>name</code> whose value
 424         is backend specific.  <span class="since">Since 0.8.4</span></dd>
 425     </dl>
 426
 427     <h3><a id="StoragePoolTarget">Target elements</a></h3>
 428
 429     <p>
 430       A single <code>target</code> element is contained within the top level
 431       <code>pool</code> element for some types of pools (pool
 432       types <code>dir</code>, <code>fs</code>, <code>netfs</code>,
 433       <code>logical</code>, <code>disk</code>, <code>iscsi</code>,
 434       <code>scsi</code>, <code>mpath</code>, <code>zfs</code>).
 435       This tag is used to describe the mapping of
 436       the storage pool into the host filesystem. It can contain the following
 437       child elements:
 438     </p>
 439
 440     <pre>
 441   ...
 442   &lt;target&gt;
 443     &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
 444     &lt;permissions&gt;
 445       &lt;owner&gt;107&lt;/owner&gt;
 446       &lt;group&gt;107&lt;/group&gt;
 447       &lt;mode&gt;0744&lt;/mode&gt;
 448       &lt;label&gt;virt_image_t&lt;/label&gt;
 449     &lt;/permissions&gt;
 450   &lt;/target&gt;
 451 &lt;/pool&gt;</pre>
 452
 453     <dl>
 454       <dt><code>path</code></dt>
 455       <dd>Provides the location at which the pool will be mapped into
 456         the local filesystem namespace, as an absolute path. For a
 457         filesystem/directory based pool it will be a fully qualified name of
 458         the directory in which volumes will be created. For device based pools
 459         it will be a fully qualified name of the directory in which
 460         devices nodes exist. For the latter <code>/dev/</code> may seem
 461         like the logical choice, however, devices nodes there are not
 462         guaranteed stable across reboots, since they are allocated on
 463         demand. It is preferable to use a stable location such as one
 464         of the <code>/dev/disk/by-{path|id|uuid|label}</code> locations.
 465         For <code>logical</code> and <code>zfs</code> pool types, a
 466         provided value is ignored and a default path generated.
 467         For a Multipath pool (type <code>mpath</code>), the provided
 468         value is ignored and the default value of "/dev/mapper" is used.
 469         <span class="since">Since 0.4.1</span>
 470       </dd>
 471       <dt><code>permissions</code></dt>
 472       <dd>This is currently only useful for directory or filesystem based
 473         pools, which are mapped as a directory into the local filesystem
 474         namespace. It provides information about the permissions to use for the
 475         final directory when the pool is built. There are 4 child elements.
 476         The <code>mode</code> element contains the octal permission set.
 477         The <code>mode</code> defaults to 0711 when not provided.
 478         The <code>owner</code> element contains the numeric user ID.
 479         The <code>group</code> element contains the numeric group ID.
 480         If <code>owner</code> or <code>group</code> aren't specified when
 481         creating a directory, the UID and GID of the libvirtd process are used.
 482         The <code>label</code> element contains the MAC (eg SELinux)
 483         label string.
 484         <span class="since">Since 0.4.1</span>
 485         For running directory or filesystem based pools, these fields
 486         will be filled with the values used by the existing directory.
 487         <span class="since">Since 1.2.16</span>
 488       </dd>
 489     </dl>
 490
 491     <h3><a id="StoragePoolExtents">Device extents</a></h3>
 492
 493     <p>
 494       If a storage pool exposes information about its underlying
 495       placement / allocation scheme, the <code>device</code> element
 496       within the <code>source</code> element may contain information
 497       about its available extents. Some pools have a constraint that
 498       a volume must be allocated entirely within a single constraint
 499       (eg disk partition pools). Thus the extent information allows an
 500       application to determine the maximum possible size for a new
 501       volume
 502     </p>
 503     <p>
 504       For storage pools supporting extent information, within each
 505       <code>device</code> element there will be zero or more <code>freeExtent</code>
 506       elements. Each of these elements contains two attributes, <code>start</code>
 507       and <code>end</code> which provide the boundaries of the extent on the
 508       device, measured in bytes.  <span class="since">Since 0.4.1</span>
 509     </p>
 510
 511     <h3><a id="StoragePoolRefresh">Refresh overrides</a></h3>
 512
 513     <p>
 514       The optional <code>refresh</code> element can control how the pool and
 515       associated volumes are refreshed (pool type <code>rbd</code>). The
 516       <code>allocation</code> attribute of the <code>volume</code> child element
 517       controls the method used for computing the allocation of a volume. The
 518       valid attribute values are <code>default</code> to compute the actual
 519       usage or <code>capacity</code> to use the logical capacity for cases where
 520       computing the allocation is too expensive. The following XML snippet
 521       shows the syntax:
 522       <pre>
 523 &lt;pool type="rbd"&gt;
 524   &lt;name&gt;myrbdpool&lt;/name&gt;
 525 ...
 526   &lt;source/&gt;
 527 ...
 528   &lt;refresh&gt;
 529     &lt;volume allocation='capacity'/&gt;
 530   &lt;/refresh&gt;
 531 ...
 532 &lt;/pool&gt;
 533 </pre>
 534       <span class="since">Since 5.2.0</span>
 535     </p>
 536
 537     <h3><a id="StoragePoolNamespaces">Storage Pool Namespaces</a></h3>
 538
 539     <p>
 540       Usage of Storage Pool Namespaces provides a mechanism to provide
 541       pool type specific data in a free form or arbitrary manner via
 542       XML syntax targeted solely for the needs of the specific pool type
 543       which is not otherwise supported in standard XML. For the "fs" and
 544       "netfs" pool types this provides a mechanism to provide additional
 545       mount options on the command line. For the "rbd" pool this provides
 546       a mechanism to override default settings for RBD configuration options.
 547     </p>
 548     <p>
 549       Usage of namespaces comes with no support guarantees. It is intended
 550       for developers testing out a concept prior to requesting an explicitly
 551       supported XML option in libvirt, and thus should never be used in
 552       production.
 553     </p>
 554     <dl>
 555       <dt><code>fs:mount_opts</code></dt>
 556       <dd>Provides an XML namespace mechanism to optionally utilize
 557         specifically named options for the mount command via the "-o"
 558         option for the <code>fs</code> or <code>netfs</code> type storage
 559         pools. In order to designate that the Storage Pool will be using
 560         the mechanism, the <code>pool</code> element must be modified to
 561         provide the XML namespace attribute syntax as follows:
 562
 563         <p>
 564         xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'
 565         </p>
 566
 567         <p>
 568         The <code>fs:mount_opts</code> defines the mount options by
 569         specifying multiple <code>fs:option</code> subelements with
 570         the attribute <code>name</code> specifying the mount option to
 571         be added. The value of the named option is not checked since
 572         it's possible options don't exist on all distributions. It is
 573         expected that proper and valid options will be supplied for the
 574         target host.
 575         </p>
 576
 577         The following XML snippet shows the syntax required in order to
 578         utilize for a netfs pool:
 579       <pre>
 580 &lt;pool type="netfs" xmlns:fs='http://libvirt.org/schemas/storagepool/fs/1.0'&gt;
 581   &lt;name&gt;nfsimages&lt;/name&gt;
 582 ...
 583   &lt;source&gt;
 584 ...
 585   &lt;/source&gt;
 586 ...
 587   &lt;target&gt;
 588 ...
 589   &lt;/target&gt;
 590   &lt;fs:mount_opts&gt;
 591     &lt;fs:option name='sync'/&gt;
 592     &lt;fs:option name='lazytime'/&gt;
 593   &lt;/fs:mount_opts&gt;
 594 &lt;/pool&gt;
 595 ...</pre>
 596
 597       <span class="since">Since 5.1.0.</span></dd>
 598
 599       <dt><code>rbd:config_opts</code></dt>
 600       <dd>Provides an XML namespace mechanism to optionally utilize
 601         specifically named options for the RBD configuration options
 602         via the rados_conf_set API for the <code>rbd</code> type
 603         storage pools. In order to designate that the Storage Pool
 604         will be using the mechanism, the <code>pool</code> element
 605         must be modified to provide the XML namespace attribute
 606         syntax as follows:
 607
 608         <p>
 609         xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'
 610         </p>
 611
 612         <p>
 613         The <code>rbd:config_opts</code> defines the configuration options
 614         by specifying multiple <code>rbd:option</code> subelements with
 615         the attribute <code>name</code> specifying the configuration option
 616         to be added and <code>value</code> specifying the configuration
 617         option value. The name and value for each option is only checked
 618         to be not empty. The name and value provided are not checked since
 619         it's possible options don't exist on all distributions. It is
 620         expected that proper and valid options will be supplied for the
 621         target host.
 622         </p>
 623
 624         The following XML snippet shows the syntax required in order to
 625         utilize
 626       <pre>
 627 &lt;pool type="rbd" xmlns:rbd='http://libvirt.org/schemas/storagepool/rbd/1.0'&gt;
 628   &lt;name&gt;myrbdpool&lt;/name&gt;
 629 ...
 630   &lt;source&gt;
 631 ...
 632   &lt;/source&gt;
 633 ...
 634   &lt;target&gt;
 635 ...
 636   &lt;/target&gt;
 637 ...
 638   &lt;rbd:config_opts&gt;
 639     &lt;rbd:option name='client_mount_timeout' value='45'/&gt;
 640     &lt;rbd:option name='rados_mon_op_timeout' value='20'/&gt;
 641     &lt;rbd:option name='rados_osd_op_timeout' value='10'/&gt;
 642   &lt;/rbd:config_opts&gt;
 643 &lt;/pool&gt;
 644 </pre>
 645
 646       <span class="since">Since 5.1.0.</span></dd>
 647
 648     </dl>
 649
 650     <h2><a id="StorageVol">Storage volume XML</a></h2>
 651     <p>
 652       A storage volume will generally be either a file or a device
 653       node; <span class="since">since 1.2.0</span>, an optional
 654       output-only attribute <code>type</code> lists the actual type
 655       (file, block, dir, network, netdir or ploop), which is also available
 656       from <code>virStorageVolGetInfo()</code>.  The storage volume
 657       XML format is available <span class="since">since 0.4.1</span>
 658     </p>
 659
 660     <h3><a id="StorageVolFirst">General metadata</a></h3>
 661
 662     <pre>
 663 &lt;volume type='file'&gt;
 664   &lt;name&gt;sparse.img&lt;/name&gt;
 665   &lt;key&gt;/var/lib/xen/images/sparse.img&lt;/key&gt;
 666   &lt;allocation&gt;0&lt;/allocation&gt;
 667   &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
 668   ...</pre>
 669
 670     <dl>
 671       <dt><code>name</code></dt>
 672       <dd>Providing a name for the volume which is unique to the pool.
 673         This is mandatory when defining a volume. For a disk pool, the
 674         name must be combination of the <code>source</code> device path
 675         device and next partition number to be created. For example, if
 676         the <code>source</code> device path is /dev/sdb and there are no
 677         partitions on the disk, then the name must be sdb1 with the next
 678         name being sdb2 and so on.
 679         <span class="since">Since 0.4.1</span></dd>
 680       <dt><code>key</code></dt>
 681       <dd>Providing an identifier for the volume which identifies a
 682           single volume. In some cases it's possible to have two distinct keys
 683           identifying a single volume. This field cannot be set when creating
 684           a volume: it is always generated.
 685         <span class="since">Since 0.4.1</span></dd>
 686       <dt><code>allocation</code></dt>
 687       <dd>Providing the total storage allocation for the volume. This
 688         may be smaller than the logical capacity if the volume is sparsely
 689         allocated. It may also be larger than the logical capacity if the
 690         volume has substantial metadata overhead. This value is in bytes.
 691         If omitted when creating a volume, the volume will be fully
 692         allocated at time of creation. If set to a value smaller than the
 693         capacity, the pool has the <strong>option</strong> of deciding
 694         to sparsely allocate a volume. It does not have to honour requests
 695         for sparse allocation though. Different types of pools may treat
 696         sparse volumes differently. For example, the <code>logical</code>
 697         pool will not automatically expand volume's allocation when it
 698         gets full; the user is responsible for doing that or configuring
 699         dmeventd to do so automatically.<br/>
 700         <br/>
 701         By default this is specified in bytes, but an optional attribute
 702         <code>unit</code> can be specified to adjust the passed value.
 703         Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes,
 704         10<sup>3</sup> or 1000 bytes), 'K' or 'KiB' (kibibytes,
 705         2<sup>10</sup> or 1024 bytes), 'MB' (megabytes, 10<sup>6</sup>
 706         or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 2<sup>20</sup>
 707         or 1,048,576 bytes), 'GB' (gigabytes, 10<sup>9</sup> or
 708         1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 2<sup>30</sup>
 709         or 1,073,741,824 bytes), 'TB' (terabytes, 10<sup>12</sup> or
 710         1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes,
 711         2<sup>40</sup> or 1,099,511,627,776 bytes), 'PB' (petabytes,
 712         10<sup>15</sup> or 1,000,000,000,000,000 bytes), 'P' or 'PiB'
 713         (pebibytes, 2<sup>50</sup> or 1,125,899,906,842,624 bytes),
 714         'EB' (exabytes, 10<sup>18</sup> or 1,000,000,000,000,000,000
 715         bytes), or 'E' or 'EiB' (exbibytes, 2<sup>60</sup> or
 716         1,152,921,504,606,846,976 bytes).  <span class="since">Since
 717         0.4.1, multi-character <code>unit</code> since
 718         0.9.11</span></dd>
 719       <dt><code>capacity</code></dt>
 720       <dd>Providing the logical capacity for the volume. This value is
 721         in bytes by default, but a <code>unit</code> attribute can be
 722         specified with the same semantics as for <code>allocation</code>
 723         This is compulsory when creating a volume.
 724         <span class="since">Since 0.4.1</span></dd>
 725       <dt><code>physical</code></dt>
 726       <dd>This output only element provides the host physical size of
 727         the target storage volume. The default output <code>unit</code>
 728         will be in bytes.
 729         <span class="since">Since 3.0.0</span></dd>
 730       <dt><code>source</code></dt>
 731       <dd>Provides information about the underlying storage allocation
 732         of the volume. This may not be available for some pool types.
 733         <span class="since">Since 0.4.1</span></dd>
 734       <dt><code>target</code></dt>
 735       <dd>Provides information about the representation of the volume
 736         on the local host. <span class="since">Since 0.4.1</span></dd>
 737     </dl>
 738
 739     <h3><a id="StorageVolTarget">Target elements</a></h3>
 740
 741     <p>
 742       A single <code>target</code> element is contained within the top level
 743       <code>volume</code> element. This tag is used to describe the mapping of
 744       the storage volume into the host filesystem. It can contain the following
 745       child elements:
 746     </p>
 747
 748     <pre>
 749 ...
 750 &lt;target&gt;
 751   &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
 752   &lt;format type='qcow2'/&gt;
 753   &lt;permissions&gt;
 754     &lt;owner&gt;107&lt;/owner&gt;
 755     &lt;group&gt;107&lt;/group&gt;
 756     &lt;mode&gt;0744&lt;/mode&gt;
 757     &lt;label&gt;virt_image_t&lt;/label&gt;
 758   &lt;/permissions&gt;
 759   &lt;timestamps&gt;
 760     &lt;atime&gt;1341933637.273190990&lt;/atime&gt;
 761     &lt;mtime&gt;1341930622.047245868&lt;/mtime&gt;
 762     &lt;ctime&gt;1341930622.047245868&lt;/ctime&gt;
 763   &lt;/timestamps&gt;
 764   &lt;encryption type='...'&gt;
 765     ...
 766   &lt;/encryption&gt;
 767   &lt;compat&gt;1.1&lt;/compat&gt;
 768   &lt;nocow/&gt;
 769   &lt;features&gt;
 770     &lt;lazy_refcounts/&gt;
 771   &lt;/features&gt;
 772 &lt;/target&gt;</pre>
 773
 774     <dl>
 775       <dt><code>path</code></dt>
 776       <dd>Provides the location at which the volume can be accessed on
 777         the local filesystem, as an absolute path. This is a readonly
 778         attribute, so shouldn't be specified when creating a volume.
 779         <span class="since">Since 0.4.1</span></dd>
 780       <dt><code>format</code></dt>
 781       <dd>Provides information about the pool specific volume format.
 782         For disk pools it will provide the partition table format type, but is
 783         not preserved after a pool refresh or libvirtd restart. Use extended
 784         in order to create an extended disk extent partition. For filesystem
 785         or directory pools it will provide the file format type, eg cow,
 786         qcow, vmdk, raw. If omitted when creating a volume, the pool's
 787         default format will be used. The actual format is specified via
 788         the <code>type</code> attribute. Consult the
 789         <a href="storage.html">storage driver page</a> for the list of valid
 790         volume format type values for each specific pool. The
 791         <code>format</code> will be ignored on input for pools without a
 792         volume format type value and the default pool format will be used.
 793         <span class="since">Since 0.4.1</span></dd>
 794       <dt><code>permissions</code></dt>
 795       <dd>Provides information about the permissions to use
 796         when creating volumes. This is currently only useful for directory
 797         or filesystem based pools, where the volumes allocated are simple
 798         files. For pools where the volumes are device nodes, the hotplug
 799         scripts determine permissions. There are 4 child elements.
 800         The <code>mode</code> element contains the octal permission set.
 801         The <code>mode</code> defaults to 0600 when not provided.
 802         The <code>owner</code> element contains the numeric user ID.
 803         The <code>group</code> element contains the numeric group ID.
 804         If <code>owner</code> or <code>group</code> aren't specified when
 805         creating a supported volume, the UID and GID of the libvirtd process
 806         are used. The <code>label</code> element contains the MAC (eg SELinux)
 807         label string.
 808         For existing directory or filesystem based volumes, these fields
 809         will be filled with the values used by the existing file.
 810         <span class="since">Since 0.4.1</span>
 811       </dd>
 812       <dt><code>timestamps</code></dt>
 813       <dd>Provides timing information about the volume. Up to four
 814         sub-elements are present,
 815         where <code>atime</code>, <code>btime</code>, <code>ctime</code>
 816         and <code>mtime</code> hold the access, birth, change and
 817         modification time of the volume, where known. The used time
 818         format is &lt;seconds&gt;.&lt;nanoseconds&gt; since the
 819         beginning of the epoch (1 Jan 1970). If nanosecond resolution
 820         is 0 or otherwise unsupported by the host OS or filesystem,
 821         then the nanoseconds part is omitted.  This is a readonly
 822         attribute and is ignored when creating a volume.
 823         <span class="since">Since 0.10.0</span>
 824       </dd>
 825       <dt><code>encryption</code></dt>
 826       <dd>If present, specifies how the volume is encrypted.  See
 827         the <a href="formatstorageencryption.html">Storage Encryption</a> page
 828         for more information.
 829       </dd>
 830       <dt><code>compat</code></dt>
 831       <dd>Specify compatibility level. So far, this is only used for
 832         <code>type='qcow2'</code> volumes. Valid values are <code>0.10</code>
 833         and <code>1.1</code> so far, specifying QEMU version the images should
 834         be compatible with. If the <code>feature</code> element is present,
 835         1.1 is used.
 836         <span class="since">Since 1.1.0</span> If omitted, 0.10 is used.
 837         <span class="since">Since 1.1.2</span>
 838       </dd>
 839       <dt><code>nocow</code></dt>
 840       <dd>Turn off COW of the newly created volume. So far, this is only valid
 841         for a file image in btrfs file system. It will improve performance when
 842         the file image is used in VM. To create non-raw file images, it
 843         requires QEMU version since 2.1. <span class="since">Since 1.2.7</span>
 844       </dd>
 845       <dt><code>features</code></dt>
 846       <dd>Format-specific features. Only used for <code>qcow2</code> now.
 847         Valid sub-elements are:
 848         <ul>
 849           <li><code>&lt;lazy_refcounts/&gt;</code> - allow delayed reference
 850           counter updates. <span class="since">Since 1.1.0</span></li>
 851         </ul>
 852       </dd>
 853     </dl>
 854
 855     <h3><a id="StorageVolBacking">Backing store elements</a></h3>
 856
 857     <p>
 858       A single <code>backingStore</code> element is contained within the top level
 859       <code>volume</code> element. This tag is used to describe the optional copy
 860       on write, backing store for the storage volume. It can contain the following
 861       child elements:
 862     </p>
 863
 864     <pre>
 865   ...
 866   &lt;backingStore&gt;
 867     &lt;path&gt;/var/lib/virt/images/master.img&lt;/path&gt;
 868     &lt;format type='raw'/&gt;
 869     &lt;permissions&gt;
 870       &lt;owner&gt;107&lt;/owner&gt;
 871       &lt;group&gt;107&lt;/group&gt;
 872       &lt;mode&gt;0744&lt;/mode&gt;
 873       &lt;label&gt;virt_image_t&lt;/label&gt;
 874     &lt;/permissions&gt;
 875   &lt;/backingStore&gt;
 876 &lt;/volume&gt;</pre>
 877
 878     <dl>
 879       <dt><code>path</code></dt>
 880       <dd>Provides the location at which the backing store can be accessed on
 881         the local filesystem, as an absolute path. If omitted, there is no
 882         backing store for this volume.
 883         <span class="since">Since 0.6.0</span></dd>
 884       <dt><code>format</code></dt>
 885       <dd>Provides information about the pool specific backing store format.
 886         For disk pools it will provide the partition type. For filesystem
 887         or directory pools it will provide the file format type, eg cow,
 888         qcow, vmdk, raw. The actual format is specified via the type attribute.
 889         Consult the pool-specific docs for the list of valid
 890         values. Most file formats require a backing store of the same format,
 891         however, the qcow2 format allows a different backing store format.
 892         <span class="since">Since 0.6.0</span></dd>
 893       <dt><code>permissions</code></dt>
 894       <dd>Provides information about the permissions of the backing file.
 895           See volume <code>permissions</code> documentation for explanation
 896           of individual fields.
 897         <span class="since">Since 0.6.0</span>
 898       </dd>
 899     </dl>
 900
 901     <h2><a id="examples">Example configuration</a></h2>
 902
 903     <p>
 904       Here are a couple of examples, for a more complete set demonstrating
 905       every type of storage pool, consult the <a href="storage.html">storage driver page</a>
 906     </p>
 907
 908     <h3><a id="exampleFile">File based storage pool</a></h3>
 909
 910     <pre>
 911 &lt;pool type="dir"&gt;
 912   &lt;name&gt;virtimages&lt;/name&gt;
 913   &lt;target&gt;
 914     &lt;path&gt;/var/lib/virt/images&lt;/path&gt;
 915   &lt;/target&gt;
 916 &lt;/pool&gt;</pre>
 917
 918     <h3><a id="exampleISCSI">iSCSI based storage pool</a></h3>
 919
 920     <pre>
 921 &lt;pool type="iscsi"&gt;
 922   &lt;name&gt;virtimages&lt;/name&gt;
 923   &lt;source&gt;
 924     &lt;host name="iscsi.example.com"/&gt;
 925     &lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
 926     &lt;auth type='chap' username='myuser'&gt;
 927       &lt;secret usage='libvirtiscsi'/&gt;
 928     &lt;/auth&gt;
 929   &lt;/source&gt;
 930   &lt;target&gt;
 931     &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
 932   &lt;/target&gt;
 933 &lt;/pool&gt;</pre>
 934
 935     <h3><a id="exampleVol">Storage volume</a></h3>
 936
 937     <pre>
 938 &lt;volume&gt;
 939   &lt;name&gt;sparse.img&lt;/name&gt;
 940   &lt;allocation&gt;0&lt;/allocation&gt;
 941   &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
 942   &lt;target&gt;
 943     &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
 944     &lt;permissions&gt;
 945       &lt;owner&gt;107&lt;/owner&gt;
 946       &lt;group&gt;107&lt;/group&gt;
 947       &lt;mode&gt;0744&lt;/mode&gt;
 948       &lt;label&gt;virt_image_t&lt;/label&gt;
 949     &lt;/permissions&gt;
 950   &lt;/target&gt;
 951 &lt;/volume&gt;</pre>
 952
 953     <h3><a id="exampleLuks">Storage volume using LUKS</a></h3>
 954
 955     <pre>
 956 &lt;volume&gt;
 957   &lt;name&gt;MyLuks.img&lt;/name&gt;
 958   &lt;capacity unit="G"&gt;5&lt;/capacity&gt;
 959   &lt;target&gt;
 960     &lt;path&gt;/var/lib/virt/images/MyLuks.img&lt;/path&gt;
 961     &lt;format type='raw'/&gt;
 962     &lt;encryption format='luks'&gt;
 963       &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
 964     &lt;/encryption&gt;
 965   &lt;/target&gt;
 966 &lt;/volume&gt;
 967     </pre>
 968   </body>
 969 </html>