File: formatstorage.html

package info (click to toggle)
libvirt 1.2.9-9%2Bdeb8u5
links: PTS, VCS
area: main
in suites: jessie
size: 174,832 kB
sloc: ansic: 463,173; xml: 68,283; sh: 16,393; makefile: 4,580; python: 3,705; perl: 3,675; ml: 470; sed: 16
file content (754 lines) | stat: -rw-r--r-- 42,396 bytes
parent folder | download | duplicates (3)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
        This file is autogenerated from formatstorage.html.in
        Do not edit this file. Changes will be lost.
      -->
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" type="text/css" href="main.css" />
    <link rel="SHORTCUT ICON" href="32favicon.png" />
    <title>libvirt: Storage pool and volume XML format</title>
    <meta name="description" content="libvirt, virtualization, virtualization API" />
  </head>
  <body>
    <div id="header">
      <div id="headerLogo"></div>
      <div id="headerSearch">
        <form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
            <input id="query" name="query" type="text" size="12" value="" />
            <input id="submit" name="submit" type="submit" value="Search" />
          </div></form>
      </div>
    </div>
    <div id="body">
      <div id="menu">
        <ul class="l0"><li>
            <div>
              <a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
            </div>
          </li><li>
            <div>
              <a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
            </div>
          </li><li>
            <div>
              <a title="Applications known to use libvirt" class="inactive" href="apps.html">Applications</a>
            </div>
          </li><li>
            <div>
              <a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
            </div>
          </li><li>
            <div>
              <a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
              <ul class="l1"><li>
                  <div>
                    <a title="How to compile libvirt" class="inactive" href="compiling.html">Compiling</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Description of the XML formats used in libvirt" class="active" href="format.html">XML format</a>
                    <ul class="l2"><li>
                        <div>
                          <a title="The domain XML format" class="inactive" href="formatdomain.html">Domains</a>
                        </div>
                      </li><li>
                        <div>
                          <a title="The virtual network XML format" class="inactive" href="formatnetwork.html">Networks</a>
                        </div>
                      </li><li>
                        <div>
                          <a title="Network filter XML format" class="inactive" href="formatnwfilter.html">Network Filtering</a>
                        </div>
                      </li><li>
                        <div>
                          <span class="active">Storage</span>
                        </div>
                      </li><li>
                        <div>
                          <a title="Storage volume encryption XML format" class="inactive" href="formatstorageencryption.html">Storage Encryption</a>
                        </div>
                      </li><li>
                        <div>
                          <a title="The driver capabilities XML format" class="inactive" href="formatcaps.html">Capabilities</a>
                        </div>
                      </li><li>
                        <div>
                          <a title="The domain capabilities XML format" class="inactive" href="formatdomaincaps.html">Domain capabilities</a>
                        </div>
                      </li><li>
                        <div>
                          <a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
                        </div>
                      </li><li>
                        <div>
                          <a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
                        </div>
                      </li><li>
                        <div>
                          <a title="The snapshot XML format" class="inactive" href="formatsnapshot.html">Snapshots</a>
                        </div>
                      </li></ul>
                  </div>
                </li><li>
                  <div>
                    <a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
                  </div>
                </li><li>
                  <div>
                    <a title="A guide and reference for developing with libvirt" class="inactive" href="devguide.html">Development Guide</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Command reference for virsh" class="inactive" href="virshcmdref.html">Virsh Commands</a>
                  </div>
                </li><li>
                  <div>
                    <a title="Project governance and code of conduct" class="inactive" href="governance.html">Governance</a>
                  </div>
                </li></ul>
            </div>
          </li><li>
            <div>
              <a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
            </div>
          </li><li>
            <div>
              <a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a>
            </div>
          </li><li>
            <div>
              <a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
            </div>
          </li><li>
            <div>
              <a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
            </div>
          </li><li>
            <div>
              <a title="Available test suites for libvirt" class="inactive" href="testsuites.html">Test suites</a>
            </div>
          </li><li>
            <div>
              <a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
            </div>
          </li><li>
            <div>
              <a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
            </div>
          </li></ul>
      </div>
      <div id="content">
        <h1>Storage pool and volume XML format</h1>
        <ul><li>
            <a href="#StoragePool">Storage pool XML</a>
            <ul><li>
                <a href="#StoragePoolFirst">General metadata</a>
              </li><li>
                <a href="#StoragePoolSource">Source elements</a>
              </li><li>
                <a href="#StoragePoolTarget">Target elements</a>
              </li><li>
                <a href="#StoragePoolExtents">Device extents</a>
              </li></ul>
          </li><li>
            <a href="#StorageVol">Storage volume XML</a>
            <ul><li>
                <a href="#StorageVolFirst">General metadata</a>
              </li><li>
                <a href="#StorageVolTarget">Target elements</a>
              </li><li>
                <a href="#StorageVolBacking">Backing store elements</a>
              </li></ul>
          </li><li>
            <a href="#examples">Example configuration</a>
            <ul><li>
                <a href="#exampleFile">File based storage pool</a>
              </li><li>
                <a href="#exampleISCSI">iSCSI based storage pool</a>
              </li><li>
                <a href="#exampleVol">Storage volume</a>
              </li></ul>
          </li></ul>
        <h2>
          <a name="StoragePool" shape="rect" id="StoragePool">Storage pool XML</a>
          <a class="headerlink" href="#StoragePool" title="Permalink to this headline">¶</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>) or <code>zfs</code> (<span class="since">since
      1.2.8</span>). This corresponds to the
      storage backend drivers listed further along in this document.
    </p>
        <h3>
          <a name="StoragePoolFirst" shape="rect" id="StoragePoolFirst">General metadata</a>
          <a class="headerlink" href="#StoragePoolFirst" title="Permalink to this headline">¶</a>
        </h3>
        <pre xml:space="preserve">
      &lt;pool type="iscsi"&gt;
        &lt;name&gt;virtimages&lt;/name&gt;
        &lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
        &lt;allocation&gt;10000000&lt;/allocation&gt;
        &lt;capacity&gt;50000000&lt;/capacity&gt;
        &lt;available&gt;40000000&lt;/available&gt;
        ...</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 name="StoragePoolSource" shape="rect" id="StoragePoolSource">Source elements</a>
          <a class="headerlink" href="#StoragePoolSource" title="Permalink to this headline">¶</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 xml:space="preserve">
        ...
        &lt;source&gt;
          &lt;host name="iscsi.example.com"/&gt;
          &lt;device path="demo-target"/&gt;
          &lt;auth type='chap' username='myname'&gt;
            &lt;secret type='iscsi' usage='mycluster_myname'/&gt;
          &lt;/auth&gt;
          &lt;vendor name="Acme"/&gt;
          &lt;product name="model"/&gt;
        &lt;/source&gt;
        ...</pre>
        <pre xml:space="preserve">
        ...
        &lt;source&gt;
          &lt;adapter type='scsi_host' name='scsi_host1'/&gt;
        &lt;/source&gt;
        ...</pre>
        <pre xml:space="preserve">
        ...
        &lt;source&gt;
          &lt;adapter type='scsi_host'&gt;
            &lt;parentaddr unique_id='1'&gt;
              &lt;address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/&gt;
            &lt;/parentaddr&gt;
          &lt;/adapter&gt;
        &lt;/source&gt;
        ...</pre>
        <pre xml:space="preserve">
        ...
        &lt;source&gt;
          &lt;adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/&gt;
        &lt;/source&gt;
        ...</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>zfs</code>).
        May be repeated multiple times depending on backend driver. Contains
        a single attribute <code>path</code> which is the fully qualified
        path to the block device node. <span class="since">Since 0.4.1</span></dd><dt><code>dir</code></dt><dd>Provides the source for pools backed by directories (pool
        type <code>dir</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.
        <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>
            </dd></dl>
        <dl><dt><code>wwwn</code> and <code>wwpn</code></dt><dd>The "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 device in the Fibre Channel storage fabric
            (the device can be either a HBA or vHBA). Both wwnn and wwpn should
            be specified. Use the command 'virsh nodedev-dumpxml' to determine
            how to set the values for the wwnn/wwpn of a (v)HBA.
            <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" shape="rect">Node Device</a> database as the
            <a href="http://wiki.libvirt.org/page/NPIV_in_libvirt" shape="rect">NPIV</a>
            virtual Host Bus Adapter (vHBA).
            <span class="since">Since 1.0.4</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 identifer 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>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. <span class="since">Since 0.4.1</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>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" shape="rect">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>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 name="StoragePoolTarget" shape="rect" id="StoragePoolTarget">Target elements</a>
          <a class="headerlink" href="#StoragePoolTarget" title="Permalink to this headline">¶</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>). 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 xml:space="preserve">
        ...
        &lt;target&gt;
          &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
          &lt;permissions&gt;
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
            &lt;mode&gt;0744&lt;/mode&gt;
            &lt;label&gt;virt_image_t&lt;/label&gt;
          &lt;/permissions&gt;
          &lt;timestamps&gt;
            &lt;atime&gt;1341933637.273190990&lt;/atime&gt;
            &lt;mtime&gt;1341930622.047245868&lt;/mtime&gt;
            &lt;ctime&gt;1341930622.047245868&lt;/ctime&gt;
          &lt;/timestamps&gt;
          &lt;encryption type='...'&gt;
            ...
          &lt;/encryption&gt;
        &lt;/target&gt;
      &lt;/pool&gt;</pre>
        <dl><dt><code>path</code></dt><dd>Provides the location at which the pool will be mapped into
        the local filesystem namespace. For a filesystem/directory based
        pool it will be the name of the directory in which volumes will
        be created. For device based pools it will be the name of the directory in which
        devices nodes exist. For the latter <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.
        <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. The
        <code>mode</code> element contains the octal permission set. The
        <code>owner</code> element contains the numeric user ID. The <code>group</code>
        element contains the numeric group ID. The <code>label</code> element
        contains the MAC (eg SELinux) label string.
        <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 &lt;seconds&gt;.&lt;nanoseconds&gt; 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" shape="rect">Storage Encryption</a> page
        for more information.
      </dd></dl>
        <h3>
          <a name="StoragePoolExtents" shape="rect" id="StoragePoolExtents">Device extents</a>
          <a class="headerlink" href="#StoragePoolExtents" title="Permalink to this headline">¶</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>
        <h2>
          <a name="StorageVol" shape="rect" id="StorageVol">Storage volume XML</a>
          <a class="headerlink" href="#StorageVol" title="Permalink to this headline">¶</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, or netdir), 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 name="StorageVolFirst" shape="rect" id="StorageVolFirst">General metadata</a>
          <a class="headerlink" href="#StorageVolFirst" title="Permalink to this headline">¶</a>
        </h3>
        <pre xml:space="preserve">
      &lt;volume type='file'&gt;
        &lt;name&gt;sparse.img&lt;/name&gt;
        &lt;key&gt;/var/lib/xen/images/sparse.img&lt;/key&gt;
        &lt;allocation&gt;0&lt;/allocation&gt;
        &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
        ...</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.  <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>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 name="StorageVolTarget" shape="rect" id="StorageVolTarget">Target elements</a>
          <a class="headerlink" href="#StorageVolTarget" title="Permalink to this headline">¶</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 xml:space="preserve">
        ...
        &lt;target&gt;
          &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
          &lt;format type='qcow2'/&gt;
          &lt;permissions&gt;
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
            &lt;mode&gt;0744&lt;/mode&gt;
            &lt;label&gt;virt_image_t&lt;/label&gt;
          &lt;/permissions&gt;
          &lt;compat&gt;1.1&lt;/compat&gt;
          &lt;nocow/&gt;
          &lt;features&gt;
            &lt;lazy_refcounts/&gt;
          &lt;/features&gt;
        &lt;/target&gt;</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 type. For filesystem
        or directory pools it will provide the file format type, eg cow,
        qcow, vmdk, raw. If omitted when creating a volume, the pool's
        default format will be used. The actual format is specified via
        the <code>type</code> attribute. Consult the
        <a href="storage.html" shape="rect">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 default permissions to use
        when creating volumes. This is currently only useful for directory
        or filesystem based pools, where the volumes allocated are simple
        files. For pools where the volumes are device nodes, the hotplug
        scripts determine permissions. It contains 4 child elements. The
        <code>mode</code> element contains the octal permission set. The
        <code>owner</code> element contains the numeric user ID. The <code>group</code>
        element contains the numeric group ID. The <code>label</code> element
        contains the MAC (eg SELinux) label string.
        <span class="since">Since 0.4.1</span>
      </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. If omitted, qemu-img default is used.
        <span class="since">Since 1.1.0</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>features</code></dt><dd>Format-specific features. Only used for <code>qcow2</code> now.
        Valid sub-elements are:
        <ul><li><code>&lt;lazy_refcounts/&gt;</code> - allow delayed reference
          counter updates. <span class="since">Since 1.1.0</span></li></ul>
      </dd></dl>
        <h3>
          <a name="StorageVolBacking" shape="rect" id="StorageVolBacking">Backing store elements</a>
          <a class="headerlink" href="#StorageVolBacking" title="Permalink to this headline">¶</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 xml:space="preserve">
        ...
        &lt;backingStore&gt;
          &lt;path&gt;/var/lib/virt/images/master.img&lt;/path&gt;
          &lt;format type='raw'/&gt;
          &lt;permissions&gt;
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
            &lt;mode&gt;0744&lt;/mode&gt;
            &lt;label&gt;virt_image_t&lt;/label&gt;
          &lt;/permissions&gt;
        &lt;/backingStore&gt;
      &lt;/volume&gt;</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.
        It contains 4 child elements. The
        <code>mode</code> element contains the octal permission set. The
        <code>owner</code> element contains the numeric user ID. The <code>group</code>
        element contains the numeric group ID. The <code>label</code> element
        contains the MAC (eg SELinux) label string.
        <span class="since">Since 0.6.0</span>
      </dd></dl>
        <h2>
          <a name="examples" shape="rect" id="examples">Example configuration</a>
          <a class="headerlink" href="#examples" title="Permalink to this headline">¶</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" shape="rect">storage driver page</a>
    </p>
        <h3>
          <a name="exampleFile" shape="rect" id="exampleFile">File based storage pool</a>
          <a class="headerlink" href="#exampleFile" title="Permalink to this headline">¶</a>
        </h3>
        <pre xml:space="preserve">
      &lt;pool type="dir"&gt;
        &lt;name&gt;virtimages&lt;/name&gt;
        &lt;target&gt;
          &lt;path&gt;/var/lib/virt/images&lt;/path&gt;
        &lt;/target&gt;
      &lt;/pool&gt;</pre>
        <h3>
          <a name="exampleISCSI" shape="rect" id="exampleISCSI">iSCSI based storage pool</a>
          <a class="headerlink" href="#exampleISCSI" title="Permalink to this headline">¶</a>
        </h3>
        <pre xml:space="preserve">
      &lt;pool type="iscsi"&gt;
        &lt;name&gt;virtimages&lt;/name&gt;
        &lt;source&gt;
          &lt;host name="iscsi.example.com"/&gt;
          &lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
          &lt;auth type='chap' username='myuser'&gt;
            &lt;secret usage='libvirtiscsi'/&gt;
          &lt;/auth&gt;
        &lt;/source&gt;
        &lt;target&gt;
          &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
        &lt;/target&gt;
      &lt;/pool&gt;</pre>
        <h3>
          <a name="exampleVol" shape="rect" id="exampleVol">Storage volume</a>
          <a class="headerlink" href="#exampleVol" title="Permalink to this headline">¶</a>
        </h3>
        <pre xml:space="preserve">
      &lt;volume&gt;
        &lt;name&gt;sparse.img&lt;/name&gt;
        &lt;allocation&gt;0&lt;/allocation&gt;
        &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
        &lt;target&gt;
          &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
          &lt;permissions&gt;
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
            &lt;mode&gt;0744&lt;/mode&gt;
            &lt;label&gt;virt_image_t&lt;/label&gt;
          &lt;/permissions&gt;
        &lt;/target&gt;
      &lt;/volume&gt;</pre>
      </div>
    </div>
    <div id="footer">
      <p id="sponsor">
	    Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
    </div>
  </body>
</html>