Skip to content

L
libvirt

openeuler / libvirt

通知 3
Star 0
Fork 0
L
libvirt

体验新版 GitCode，发现更多精彩内容 >>

切换分支/标签
查找文件 普通视图历史永久链接Permalink
formatstorage.html.in 30.7 KB
Newer Older
D
Fix multiple formatting problems in HTML docs  
Daniel P. Berrange 已提交
1 2 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">
D
Split website out into one file per page. APply new layout and styling  
Daniel P. Berrange 已提交
4 5 6 
  <body>
    <h1>Storage pool and volume XML format</h1>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
7 
    <ul id="toc"></ul>
D
Split website out into one file per page. APply new layout and styling  
Daniel P. Berrange 已提交
8
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
9 10 11 12 13 14 15 16 17 
    <h2><a name="StoragePool">Storage pool XML</a></h2>

    <p>
      Although all storage pool backends share the same public APIs and
      XML format, they have varying levels of capabilities. Some may
      allow creation of volumes, others may only allow use of pre-existing
      volumes. Some may have constraints on volume size, or placement.
    </p>
    <p>
C
Fix typo in storage pool documentation  
Christophe Fergeau 已提交
18 
      The top level tag for a storage pool document is 'pool'. It has
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
19 
      a single attribute <code>type</code>, which is one of <code>dir</code>,
J
docs: add spaces to formatstorage.html  
Ján Tomko 已提交
20 
      <code>fs</code>, <code>netfs</code>, <code>disk</code>,
E
storage: document existing pools  
Eric Blake 已提交
21 22 23 
      <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>
E
storage: document gluster pool  
Eric Blake 已提交
24 25 26 27 
      (<span class="since">since 0.9.13</span>), <code>sheepdog</code>
      (<span class="since">since 0.10.0</span>),
      or <code>gluster</code> (<span class="since">since
      1.2.0</span>). This corresponds to the
J
docs: add spaces to formatstorage.html  
Ján Tomko 已提交
28 
      storage backend drivers listed further along in this document.
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 
    </p>
    <h3><a name="StoragePoolFirst">General metadata</a></h3>

    <pre>
      &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.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
44 
        This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
45 46 
      <dt><code>uuid</code></dt>
      <dd>Providing an identifier for the pool which is globally unique.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
47 48 
        This is optional when defining a pool, a UUID will be generated if
        omitted. <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
49 50 
      <dt><code>allocation</code></dt>
      <dd>Providing the total storage allocation for the pool. This may
M
Cleanup whitespace in docs  
Matthew Booth 已提交
51 52 53 
        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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
54 55 
      <dt><code>capacity</code></dt>
      <dd>Providing the total storage capacity for the pool. Due to
M
Cleanup whitespace in docs  
Matthew Booth 已提交
56 57 58 
        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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
59 60 
      <dt><code>available</code></dt>
      <dd>Providing the free space available for allocating new volumes
M
Cleanup whitespace in docs  
Matthew Booth 已提交
61 62 63 64 
        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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
65 66 67 68 69 70 71 
    </dl>

    <h3><a name="StoragePoolSource">Source elements</a></h3>

    <p>
      A single <code>source</code> element is contained within the top level
      <code>pool</code> element. This tag is used to describe the source of
E
storage: document existing pools  
Eric Blake 已提交
72 73 
      the storage pool. The set of child elements that it will contain
      depend on the pool type, but come from the following child elements:
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
74 75 76 77 78 79 80 
    </p>

    <pre>
        ...
        &lt;source&gt;
          &lt;host name="iscsi.example.com"/&gt;
          &lt;device path="demo-target"/&gt;
J
storage_pool: Rework chap XML to mimic ceph  
John Ferlan 已提交
81 82 83 
          &lt;auth type='chap' username='myname'&gt;
            &lt;secret type='iscsi' usage='mycluster_myname'/&gt;
          &lt;/auth&gt;
P
storage: add support for Vendor and Model in XML  
Patrick Dignan 已提交
84 
          &lt;vendor name="Acme"/&gt;
P
Fix broken XML entity for '>'  
Philipp Hahn 已提交
85 
          &lt;product name="model"/&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
86 
        &lt;/source&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
87 
        ...</pre>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
88
O
storage: Introduce parentaddr into virStoragePoolSourceAdapter  
Osier Yang 已提交
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 
    <pre>
        ...
        &lt;source&gt;
          &lt;adapter type='scsi_host' name='scsi_host1'/&gt;
        &lt;/source&gt;
        ...</pre>

    <pre>
        ...
        &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>
O
New XML attributes for storage pool source adapter  
Osier Yang 已提交
107 108 109 110 111 112 113 
    <pre>
        ...
        &lt;source&gt;
          &lt;adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/&gt;
        &lt;/source&gt;
        ...</pre>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
114 115 
    <dl>
      <dt><code>device</code></dt>
E
storage: document existing pools  
Eric Blake 已提交
116 117 118 
      <dd>Provides the source for pools backed by physical devices
        (pool types <code>fs</code>, <code>logical</code>, <code>disk</code>,
        <code>iscsi</code>).
M
Cleanup whitespace in docs  
Matthew Booth 已提交
119 120 121 
        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>
E
storage: document existing pools  
Eric Blake 已提交
122 123 
      <dt><code>dir</code></dt>
      <dd>Provides the source for pools backed by directories (pool
E
storage: document gluster pool  
Eric Blake 已提交
124 125 126 
        type <code>dir</code>), or optionally to select a subdirectory
        within a pool that resembles a filesystem (pool
        type <code>gluster</code>). May
M
Cleanup whitespace in docs  
Matthew Booth 已提交
127 
        only occur once. Contains a single attribute <code>path</code>
C
Fix /pool/storage/directory@path documentation  
Christophe Fergeau 已提交
128 
        which is the fully qualified path to the backing directory.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
129 
        <span class="since">Since 0.4.1</span></dd>
C
docs: storage: Document SCSI pools  
Cole Robinson 已提交
130 
      <dt><code>adapter</code></dt>
E
storage: document existing pools  
Eric Blake 已提交
131 
      <dd>Provides the source for pools backed by SCSI adapters (pool
O
storage: Introduce parentaddr into virStoragePoolSourceAdapter  
Osier Yang 已提交
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 
        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">Node Device</a> database as the
            <a href="http://wiki.libvirt.org/page/NPIV_in_libvirt">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 |
J
scsi_host: Introduce virFindSCSIHostByPCI  
John Ferlan 已提交
229 230 231 232 
                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.
O
storage: Introduce parentaddr into virStoragePoolSourceAdapter  
Osier Yang 已提交
233 234 235 236 237 
              </dd>
            </dl>
          </dd>
        </dl>
      </dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
238 239 
      <dt><code>host</code></dt>
      <dd>Provides the source for pools backed by storage from a
E
storage: document existing pools  
Eric Blake 已提交
240 
        remote server (pool types <code>netfs</code>, <code>iscsi</code>,
E
storage: document gluster pool  
Eric Blake 已提交
241 
        <code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
E
storage: document existing pools  
Eric Blake 已提交
242 
        used in combination with a <code>directory</code>
M
Cleanup whitespace in docs  
Matthew Booth 已提交
243 244 245 246 
        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>
J
storage_pool: Rework chap XML to mimic ceph  
John Ferlan 已提交
247 248 249 
      <dt><code>auth</code></dt>
      <dd>If present, the <code>auth</code> element provides the
        authentication credentials needed to access the source by the
E
storage: document existing pools  
Eric Blake 已提交
250 251 252 253 254 255 
        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
J
storage_pool: Rework chap XML to mimic ceph  
John Ferlan 已提交
256 257 258 259 260 261 
        <code>username</code> identifies the username to use during
        authentication as well as a sub-element <code>secret</code> with
        a mandatory attribute <code>type</code>, to tie back to a
        <a href="formatsecret.html">libvirt secret object</a> that
        holds the actual password or other credentials. The domain XML
        intentionally does not expose the password, only the reference
E
storage: document existing pools  
Eric Blake 已提交
262 
        to the object that manages the password.
J
storage_pool: Rework chap XML to mimic ceph  
John Ferlan 已提交
263 264 265 266 267 268 
        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>
D
Adds storage source element for pools  
Daniel Veillard 已提交
269 270 
      <dt><code>name</code></dt>
      <dd>Provides the source for pools backed by storage from a
E
storage: document existing pools  
Eric Blake 已提交
271 
        named element (pool types <code>logical</code>, <code>rbd</code>,
E
storage: document gluster pool  
Eric Blake 已提交
272 273 
        <code>sheepdog</code>, <code>gluster</code>).  Contains a
        string identifier.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
274 
        <span class="since">Since 0.4.5</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
275 
      <dt><code>format</code></dt>
E
storage: document existing pools  
Eric Blake 已提交
276 277 278 
      <dd>Provides information about the format of the pool (pool
        types <code>fs</code>, <code>netfs</code>, <code>disk</code>,
        <code>logical</code>). This
M
Cleanup whitespace in docs  
Matthew Booth 已提交
279 280 281 282 283 
        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>
P
storage: add support for Vendor and Model in XML  
Patrick Dignan 已提交
284 285 286 287 288 289 290 291 292 293 

      <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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
294 295 296 297 298 299 
    </dl>

    <h3><a name="StoragePoolTarget">Target elements</a></h3>

    <p>
      A single <code>target</code> element is contained within the top level
E
storage: document existing pools  
Eric Blake 已提交
300 301 302 303 304 
      <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
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
305 306 307 308 309 310 311 312 313 
      the storage pool into the host filesystem. It can contain the following
      child elements:
    </p>

    <pre>
        ...
        &lt;target&gt;
          &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
          &lt;permissions&gt;
M
Fix owner and group in example volume XML  
Matthew Booth 已提交
314 315 
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
316 317 318 
            &lt;mode&gt;0744&lt;/mode&gt;
            &lt;label&gt;virt_image_t&lt;/label&gt;
          &lt;/permissions&gt;
H
Added timestamps to storage volumes  
Hendrik Schwartke 已提交
319 320 321 322 323 
          &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;
M
Attach encryption information to virStorageVolDef.  
Miloslav Trmač 已提交
324 325 326 
          &lt;encryption type='...'&gt;
            ...
          &lt;/encryption&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
327 328 329 330 331 332 
        &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
M
Cleanup whitespace in docs  
Matthew Booth 已提交
333 334 335 336 337 338 339 340 341 
        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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
342 343 
      </dd>
      <dt><code>permissions</code></dt>
P
doc: storage pool permission copy-paste fix  
Philipp Hahn 已提交
344 345 346 347 
      <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
M
Cleanup whitespace in docs  
Matthew Booth 已提交
348 349 350 351 352 
        <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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
353 
      </dd>
H
Added timestamps to storage volumes  
Hendrik Schwartke 已提交
354 355 356 357 358 359 360 361 362 363 364 365 366 
      <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>
M
Attach encryption information to virStorageVolDef.  
Miloslav Trmač 已提交
367 368 369 370 371 
      <dt><code>encryption</code></dt>
      <dd>If present, specifies how the volume is encrypted.  See
        the <a href="formatstorageencryption.html">Storage Encryption</a> page
        for more information.
      </dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 
    </dl>

    <h3><a name="StoragePoolExtents">Device extents</a></h3>

    <p>
      If a storage pool exposes information about its underlying
      placement / allocation scheme, the <code>device</code> element
      within the <code>source</code> element may contain information
      about its available extents. Some pools have a constraint that
      a volume must be allocated entirely within a single constraint
      (eg disk partition pools). Thus the extent information allows an
      application to determine the maximum possible size for a new
      volume
    </p>
    <p>
      For storage pools supporting extent information, within each
      <code>device</code> element there will be zero or more <code>freeExtent</code>
      elements. Each of these elements contains two attributes, <code>start</code>
      and <code>end</code> which provide the boundaries of the extent on the
      device, measured in bytes.  <span class="since">Since 0.4.1</span>
    </p>

    <h2><a name="StorageVol">Storage volume XML</a></h2>
    <p>
E
storage: expose volume meta-type in XML  
Eric Blake 已提交
396 397 398 
      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
E
storage: add network-dir as new storage volume type  
Eric Blake 已提交
399 
      (file, block, dir, network, or netdir), which is also available
E
storage: expose volume meta-type in XML  
Eric Blake 已提交
400 401 
      from <code>virStorageVolGetInfo()</code>.  The storage volume
      XML format is available <span class="since">since 0.4.1</span>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
402 403 404 405 406 
    </p>

    <h3><a name="StorageVolFirst">General metadata</a></h3>

    <pre>
E
storage: expose volume meta-type in XML  
Eric Blake 已提交
407 
      &lt;volume type='file'&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
408 409 
        &lt;name&gt;sparse.img&lt;/name&gt;
        &lt;key&gt;/var/lib/xen/images/sparse.img&lt;/key&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
410 
        &lt;allocation&gt;0&lt;/allocation&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
411 
        &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
412 413 414 415 416 
        ...</pre>

    <dl>
      <dt><code>name</code></dt>
      <dd>Providing a name for the volume which is unique to the pool.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
417 
        This is mandatory when defining a volume.  <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
418 
      <dt><code>key</code></dt>
P
doc: storage: Explicitly state that it's possible to have non-unique key  
Peter Krempa 已提交
419 420 421 422 
      <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.
C
docs: storage: <volume><key> is always generated.  
Cole Robinson 已提交
423 
        <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
424 425 
      <dt><code>allocation</code></dt>
      <dd>Providing the total storage allocation for the volume. This
M
Cleanup whitespace in docs  
Matthew Booth 已提交
426 427 428 429 430 431 432 
        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
J
docs: Clarify semantics of sparse storage volumes  
Jiri Denemark 已提交
433 434 435 436 437 
        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/>
C
docs: storage: Document capacity/alloc 'unit'  
Cole Robinson 已提交
438 
        <br/>
E
docs: use correct terminology for 1024 bytes  
Eric Blake 已提交
439 
        By default this is specified in bytes, but an optional attribute
C
docs: storage: Document capacity/alloc 'unit'  
Cole Robinson 已提交
440 
        <code>unit</code> can be specified to adjust the passed value.
E
storage: support more scaling suffixes  
Eric Blake 已提交
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 
        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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
457 458 
      <dt><code>capacity</code></dt>
      <dd>Providing the logical capacity for the volume. This value is
C
docs: storage: Document capacity/alloc 'unit'  
Cole Robinson 已提交
459 460 461 
        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.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
462 
        <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
463 464 
      <dt><code>source</code></dt>
      <dd>Provides information about the underlying storage allocation
M
Cleanup whitespace in docs  
Matthew Booth 已提交
465 466 
        of the volume. This may not be available for some pool types.
        <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
467 468 
      <dt><code>target</code></dt>
      <dd>Provides information about the representation of the volume
M
Cleanup whitespace in docs  
Matthew Booth 已提交
469 
        on the local host. <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
470 471 472 473 474 475 476 477 478 479 480 481 482 
    </dl>

    <h3><a name="StorageVolTarget">Target elements</a></h3>

    <p>
      A single <code>target</code> element is contained within the top level
      <code>volume</code> element. This tag is used to describe the mapping of
      the storage volume into the host filesystem. It can contain the following
      child elements:
    </p>

    <pre>
        ...
M
Cleanup whitespace in docs  
Matthew Booth 已提交
483 
        &lt;target&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
484 
          &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
D
* docs/formatstorage.html[.in]: fix a error in format type example  
Daniel Veillard 已提交
485 
          &lt;format type='qcow2'/&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
486 
          &lt;permissions&gt;
M
Fix owner and group in example volume XML  
Matthew Booth 已提交
487 488 
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
489 490 491 
            &lt;mode&gt;0744&lt;/mode&gt;
            &lt;label&gt;virt_image_t&lt;/label&gt;
          &lt;/permissions&gt;
J
conf: add features to volume target XML  
Ján Tomko 已提交
492 
          &lt;compat&gt;1.1&lt;/compat&gt;
C
storagevol: add nocow to vol xml  
Chunyan Liu 已提交
493 
          &lt;nocow/&gt;
J
conf: add features to volume target XML  
Ján Tomko 已提交
494 495 496 
          &lt;features&gt;
            &lt;lazy_refcounts/&gt;
          &lt;/features&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
497 
        &lt;/target&gt;</pre>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
498 499 500 

    <dl>
      <dt><code>path</code></dt>
C
Fix documentation cut and paste errors, and a virsh typo.  
Cole Robinson 已提交
501 
      <dd>Provides the location at which the volume can be accessed on
M
Cleanup whitespace in docs  
Matthew Booth 已提交
502 503 504 
        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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
505 506 
      <dt><code>format</code></dt>
      <dd>Provides information about the pool specific volume format.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
507 508 509 510 511 
        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 pool-specific docs for
D
* docs/formatstorage.html[.in]: fix a error in format type example  
Daniel Veillard 已提交
512 
        the list of valid values. <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
513 514 
      <dt><code>permissions</code></dt>
      <dd>Provides information about the default permissions to use
M
Cleanup whitespace in docs  
Matthew Booth 已提交
515 516 517 518 519 520 521 522 523 
        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>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
524 
      </dd>
J
conf: add features to volume target XML  
Ján Tomko 已提交
525 526 527 528 529 530 
      <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.
J
Use 1.1.0 everywhere in the documentation  
Ján Tomko 已提交
531 
        <span class="since">Since 1.1.0</span>
J
conf: add features to volume target XML  
Ján Tomko 已提交
532 
      </dd>
C
storagevol: add nocow to vol xml  
Chunyan Liu 已提交
533 534 535 536 537 538 
      <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>
J
conf: add features to volume target XML  
Ján Tomko 已提交
539 540 541 542 543 
      <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
J
Use 1.1.0 everywhere in the documentation  
Ján Tomko 已提交
544 
          counter updates. <span class="since">Since 1.1.0</span></li>
J
conf: add features to volume target XML  
Ján Tomko 已提交
545 546 
        </ul>
      </dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
547 548 
    </dl>
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
549 550 551 552 553 554 555 556 557 558 559 560 561 
    <h3><a name="StorageVolBacking">Backing store elements</a></h3>

    <p>
      A single <code>backingStore</code> element is contained within the top level
      <code>volume</code> element. This tag is used to describe the optional copy
      on write, backing store for the storage volume. It can contain the following
      child elements:
    </p>

    <pre>
        ...
        &lt;backingStore&gt;
          &lt;path&gt;/var/lib/virt/images/master.img&lt;/path&gt;
C
docs: storage: Fix backingStore <format> docs  
Cole Robinson 已提交
562 
          &lt;format type='raw'/&gt;
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
563 
          &lt;permissions&gt;
M
Fix owner and group in example volume XML  
Matthew Booth 已提交
564 565 
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
566 567 568 569 570 571 572 573 574 
            &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
M
Cleanup whitespace in docs  
Matthew Booth 已提交
575 
        the local filesystem, as an absolute path. If omitted, there is no
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
576 
        backing store for this volume.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
577 
        <span class="since">Since 0.6.0</span></dd>
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
578 579 
      <dt><code>format</code></dt>
      <dd>Provides information about the pool specific backing store format.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
580 581 
        For disk pools it will provide the partition type. For filesystem
        or directory pools it will provide the file format type, eg cow,
C
docs: storage: Fix backingStore <format> docs  
Cole Robinson 已提交
582 583 
        qcow, vmdk, raw. The actual format is specified via the type attribute.
        Consult the pool-specific docs for the list of valid
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
584 585 586 587 588 589 
        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
M
Cleanup whitespace in docs  
Matthew Booth 已提交
590 591 592 593 594 
        <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>
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
595 596 597 
      </dd>
    </dl>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 
    <h2><a name="examples">Example configuration</a></h2>

    <p>
      Here are a couple of examples, for a more complete set demonstrating
      every type of storage pool, consult the <a href="storage.html">storage driver page</a>
    </p>

    <h3><a name="exampleFile">File based storage pool</a></h3>

    <pre>
      &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">iSCSI based storage pool</a></h3>

    <pre>
      &lt;pool type="iscsi"&gt;
        &lt;name&gt;virtimages&lt;/name&gt;
        &lt;source&gt;
          &lt;host name="iscsi.example.com"/&gt;
J
docs: Update iSCSI storage pool example  
John Ferlan 已提交
622 623 624 625 
          &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;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
626 627 628 629 630 631 632 633 634 
        &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">Storage volume</a></h3>

    <pre>
D
fix storage volume inconsistencies in schema and doc  
Daniel Veillard 已提交
635 
      &lt;volume&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
636 637 638 639 
        &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;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
640 641 
          &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
          &lt;permissions&gt;
M
Fix owner and group in example volume XML  
Matthew Booth 已提交
642 643 
            &lt;owner&gt;107&lt;/owner&gt;
            &lt;group&gt;107&lt;/group&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
644 645 646 
            &lt;mode&gt;0744&lt;/mode&gt;
            &lt;label&gt;virt_image_t&lt;/label&gt;
          &lt;/permissions&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
647 
        &lt;/target&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
648 
      &lt;/volume&gt;</pre>
D
Split website out into one file per page. APply new layout and styling  
Daniel P. Berrange 已提交
649 650 
  </body>
</html>