Skip to content

L
libvirt

openeuler / libvirt

通知 3
Star 0
Fork 0
L
libvirt

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

切换分支/标签
查找文件 普通视图历史永久链接Permalink
formatstorage.html.in 31.0 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 
      (<span class="since">since 0.9.13</span>), <code>sheepdog</code>
      (<span class="since">since 0.10.0</span>),
R
docs: update zfs documentation  
Roman Bogorodskiy 已提交
26 27 28 
      <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
J
docs: add spaces to formatstorage.html  
Ján Tomko 已提交
29 
      storage backend drivers listed further along in this document.
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 
    </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 已提交
45 
        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 已提交
46 47 
      <dt><code>uuid</code></dt>
      <dd>Providing an identifier for the pool which is globally unique.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
48 49 
        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 已提交
50 51 
      <dt><code>allocation</code></dt>
      <dd>Providing the total storage allocation for the pool. This may
M
Cleanup whitespace in docs  
Matthew Booth 已提交
52 53 54 
        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 已提交
55 56 
      <dt><code>capacity</code></dt>
      <dd>Providing the total storage capacity for the pool. Due to
M
Cleanup whitespace in docs  
Matthew Booth 已提交
57 58 59 
        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 已提交
60 61 
      <dt><code>available</code></dt>
      <dd>Providing the free space available for allocating new volumes
M
Cleanup whitespace in docs  
Matthew Booth 已提交
62 63 64 65 
        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 已提交
66 67 68 69 70 71 72 
    </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 已提交
73 74 
      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 已提交
75 76 77 78 79 80 81 
    </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 已提交
82 83 84 
          &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 已提交
85 
          &lt;vendor name="Acme"/&gt;
P
Fix broken XML entity for '>'  
Philipp Hahn 已提交
86 
          &lt;product name="model"/&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
87 
        &lt;/source&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
88 
        ...</pre>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
89
O
storage: Introduce parentaddr into virStoragePoolSourceAdapter  
Osier Yang 已提交
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 
    <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 已提交
108 109 110 111 112 113 114 
    <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 已提交
115 116 
    <dl>
      <dt><code>device</code></dt>
E
storage: document existing pools  
Eric Blake 已提交
117 118 
      <dd>Provides the source for pools backed by physical devices
        (pool types <code>fs</code>, <code>logical</code>, <code>disk</code>,
R
docs: update zfs documentation  
Roman Bogorodskiy 已提交
119 
        <code>iscsi</code>, <code>zfs</code>).
M
Cleanup whitespace in docs  
Matthew Booth 已提交
120 121 122 
        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 已提交
123 124 
      <dt><code>dir</code></dt>
      <dd>Provides the source for pools backed by directories (pool
E
storage: document gluster pool  
Eric Blake 已提交
125 126 127 
        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 已提交
128 
        only occur once. Contains a single attribute <code>path</code>
C
Fix /pool/storage/directory@path documentation  
Christophe Fergeau 已提交
129 
        which is the fully qualified path to the backing directory.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
130 
        <span class="since">Since 0.4.1</span></dd>
C
docs: storage: Document SCSI pools  
Cole Robinson 已提交
131 
      <dt><code>adapter</code></dt>
E
storage: document existing pools  
Eric Blake 已提交
132 
      <dd>Provides the source for pools backed by SCSI adapters (pool
O
storage: Introduce parentaddr into virStoragePoolSourceAdapter  
Osier Yang 已提交
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 229 
        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 已提交
230 231 232 233 
                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 已提交
234 235 236 237 238 
              </dd>
            </dl>
          </dd>
        </dl>
      </dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
239 240 
      <dt><code>host</code></dt>
      <dd>Provides the source for pools backed by storage from a
E
storage: document existing pools  
Eric Blake 已提交
241 
        remote server (pool types <code>netfs</code>, <code>iscsi</code>,
E
storage: document gluster pool  
Eric Blake 已提交
242 
        <code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
E
storage: document existing pools  
Eric Blake 已提交
243 
        used in combination with a <code>directory</code>
M
Cleanup whitespace in docs  
Matthew Booth 已提交
244 245 246 247 
        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 已提交
248 249 250 
      <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 已提交
251 252 253 254 255 256 
        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 已提交
257 258 259 260 261 262 
        <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 已提交
263 
        to the object that manages the password.
J
storage_pool: Rework chap XML to mimic ceph  
John Ferlan 已提交
264 265 266 267 268 269 
        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 已提交
270 271 
      <dt><code>name</code></dt>
      <dd>Provides the source for pools backed by storage from a
E
storage: document existing pools  
Eric Blake 已提交
272 
        named element (pool types <code>logical</code>, <code>rbd</code>,
E
storage: document gluster pool  
Eric Blake 已提交
273 274 
        <code>sheepdog</code>, <code>gluster</code>).  Contains a
        string identifier.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
275 
        <span class="since">Since 0.4.5</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
276 
      <dt><code>format</code></dt>
E
storage: document existing pools  
Eric Blake 已提交
277 278 279 
      <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 已提交
280 281 282 283 284 
        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 已提交
285 286 287 288 289 290 291 292 293 294 

      <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 已提交
295 296 297 298 299 300 
    </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 已提交
301 302 303 304 305 
      <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 已提交
306 307 308 309 310 311 312 313 314 
      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 已提交
315 316 
            &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 已提交
317 318 319 
            &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 已提交
320 321 322 323 324 
          &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č 已提交
325 326 327 
          &lt;encryption type='...'&gt;
            ...
          &lt;/encryption&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
328 329 330 331 332 333 
        &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 已提交
334 335 336 337 338 339 340 341 342 
        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 已提交
343 344 
      </dd>
      <dt><code>permissions</code></dt>
P
doc: storage pool permission copy-paste fix  
Philipp Hahn 已提交
345 346 347 348 
      <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 已提交
349 350 351 352 353 
        <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 已提交
354 
      </dd>
H
Added timestamps to storage volumes  
Hendrik Schwartke 已提交
355 356 357 358 359 360 361 362 363 364 365 366 367 
      <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č 已提交
368 369 370 371 372 
      <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 已提交
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 
    </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 已提交
397 398 399 
      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 已提交
400 
      (file, block, dir, network, or netdir), which is also available
E
storage: expose volume meta-type in XML  
Eric Blake 已提交
401 402 
      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 已提交
403 404 405 406 407 
    </p>

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

    <pre>
E
storage: expose volume meta-type in XML  
Eric Blake 已提交
408 
      &lt;volume type='file'&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
409 410 
        &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 已提交
411 
        &lt;allocation&gt;0&lt;/allocation&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
412 
        &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
413 414 415 416 417 
        ...</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 已提交
418 
        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 已提交
419 
      <dt><code>key</code></dt>
P
doc: storage: Explicitly state that it's possible to have non-unique key  
Peter Krempa 已提交
420 421 422 423 
      <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 已提交
424 
        <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
425 426 
      <dt><code>allocation</code></dt>
      <dd>Providing the total storage allocation for the volume. This
M
Cleanup whitespace in docs  
Matthew Booth 已提交
427 428 429 430 431 432 433 
        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 已提交
434 435 436 437 438 
        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 已提交
439 
        <br/>
E
docs: use correct terminology for 1024 bytes  
Eric Blake 已提交
440 
        By default this is specified in bytes, but an optional attribute
C
docs: storage: Document capacity/alloc 'unit'  
Cole Robinson 已提交
441 
        <code>unit</code> can be specified to adjust the passed value.
E
storage: support more scaling suffixes  
Eric Blake 已提交
442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 
        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 已提交
458 459 
      <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 已提交
460 461 462 
        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 已提交
463 
        <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
464 465 
      <dt><code>source</code></dt>
      <dd>Provides information about the underlying storage allocation
M
Cleanup whitespace in docs  
Matthew Booth 已提交
466 467 
        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 已提交
468 469 
      <dt><code>target</code></dt>
      <dd>Provides information about the representation of the volume
M
Cleanup whitespace in docs  
Matthew Booth 已提交
470 
        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 已提交
471 472 473 474 475 476 477 478 479 480 481 482 483 
    </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 已提交
484 
        &lt;target&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
485 
          &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 已提交
486 
          &lt;format type='qcow2'/&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
487 
          &lt;permissions&gt;
M
Fix owner and group in example volume XML  
Matthew Booth 已提交
488 489 
            &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 已提交
490 491 492 
            &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 已提交
493 
          &lt;compat&gt;1.1&lt;/compat&gt;
C
storagevol: add nocow to vol xml  
Chunyan Liu 已提交
494 
          &lt;nocow/&gt;
J
conf: add features to volume target XML  
Ján Tomko 已提交
495 496 497 
          &lt;features&gt;
            &lt;lazy_refcounts/&gt;
          &lt;/features&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
498 
        &lt;/target&gt;</pre>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
499 500 501 

    <dl>
      <dt><code>path</code></dt>
C
Fix documentation cut and paste errors, and a virsh typo.  
Cole Robinson 已提交
502 
      <dd>Provides the location at which the volume can be accessed on
M
Cleanup whitespace in docs  
Matthew Booth 已提交
503 504 505 
        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 已提交
506 507 
      <dt><code>format</code></dt>
      <dd>Provides information about the pool specific volume format.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
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
J
docs: Point to list of valid pool target volume formats  
John Ferlan 已提交
512 513 514 515 516 517 
        the <code>type</code> attribute. Consult the
        <a href="storage.html">storage driver page</a> for the list of valid
        volume format type values for each specific pool. The
        <code>format</code> will be ignored on input for pools without a
        volume format type value and the default pool format will be used.
        <span class="since">Since 0.4.1</span></dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
518 519 
      <dt><code>permissions</code></dt>
      <dd>Provides information about the default permissions to use
M
Cleanup whitespace in docs  
Matthew Booth 已提交
520 521 522 523 524 525 526 527 528 
        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 已提交
529 
      </dd>
J
conf: add features to volume target XML  
Ján Tomko 已提交
530 531 532 533 534 535 
      <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 已提交
536 
        <span class="since">Since 1.1.0</span>
J
conf: add features to volume target XML  
Ján Tomko 已提交
537 
      </dd>
C
storagevol: add nocow to vol xml  
Chunyan Liu 已提交
538 539 540 541 542 543 
      <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 已提交
544 545 546 547 548 
      <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 已提交
549 
          counter updates. <span class="since">Since 1.1.0</span></li>
J
conf: add features to volume target XML  
Ján Tomko 已提交
550 551 
        </ul>
      </dd>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
552 553 
    </dl>
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
554 555 556 557 558 559 560 561 562 563 564 565 566 
    <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 已提交
567 
          &lt;format type='raw'/&gt;
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
568 
          &lt;permissions&gt;
M
Fix owner and group in example volume XML  
Matthew Booth 已提交
569 570 
            &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 已提交
571 572 573 574 575 576 577 578 579 
            &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 已提交
580 
        the local filesystem, as an absolute path. If omitted, there is no
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
581 
        backing store for this volume.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
582 
        <span class="since">Since 0.6.0</span></dd>
D
Add support for copy-on-write storage volumes  
Daniel P. Berrange 已提交
583 584 
      <dt><code>format</code></dt>
      <dd>Provides information about the pool specific backing store format.
M
Cleanup whitespace in docs  
Matthew Booth 已提交
585 586 
        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 已提交
587 588 
        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 已提交
589 590 591 592 593 594 
        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 已提交
595 596 597 598 599 
        <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 已提交
600 601 602 
      </dd>
    </dl>
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 
    <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 已提交
627 628 629 630 
          &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 已提交
631 632 633 634 635 636 637 638 639 
        &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 已提交
640 
      &lt;volume&gt;
M
Cleanup whitespace in docs  
Matthew Booth 已提交
641 642 643 644 
        &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 已提交
645 646 
          &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 已提交
647 648 
            &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 已提交
649 650 651 
            &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 已提交
652 
        &lt;/target&gt;
D
Added autogenerated TOC for network and storage XML reference docs  
Daniel P. Berrange 已提交
653 
      &lt;/volume&gt;</pre>
D
Split website out into one file per page. APply new layout and styling  
Daniel P. Berrange 已提交
654 655 
  </body>
</html>