docs/formatstorage.html.in

   1 <html>
   2   <body>
   3     <h1>Storage pool and volume XML format</h1>
   4
   5     <ul id="toc"></ul>
   6
   7     <h2><a name="StoragePool">Storage pool XML</a></h2>
   8
   9     <p>
  10       Although all storage pool backends share the same public APIs and
  11       XML format, they have varying levels of capabilities. Some may
  12       allow creation of volumes, others may only allow use of pre-existing
  13       volumes. Some may have constraints on volume size, or placement.
  14     </p>
  15     <p>
  16       The is the top level tag for a storage pool document is 'pool'. It has
  17       a single attribute <code>type</code>, which is one of <code>dir</code>,
  18       <code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
  19       <code>logical</code>. This corresponds to the storage backend drivers
  20       listed further along in this document.
  21       The storage pool XML format is available <span class="since">since 0.4.1</span>
  22     </p>
  23     <h3><a name="StoragePoolFirst">General metadata</a></h3>
  24
  25     <pre>
  26       &lt;pool type="iscsi"&gt;
  27         &lt;name&gt;virtimages&lt;/name&gt;
  28         &lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
  29         &lt;allocation&gt;10000000&lt;/allocation&gt;
  30         &lt;capacity&gt;50000000&lt;/capacity&gt;
  31         &lt;available&gt;40000000&lt;/available&gt;
  32         ...</pre>
  33
  34     <dl>
  35       <dt><code>name</code></dt>
  36       <dd>Providing a name for the pool which is unique to the host.
  37         This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
  38       <dt><code>uuid</code></dt>
  39       <dd>Providing an identifier for the pool which is globally unique.
  40         This is optional when defining a pool, a UUID will be generated if
  41         omitted. <span class="since">Since 0.4.1</span></dd>
  42       <dt><code>allocation</code></dt>
  43       <dd>Providing the total storage allocation for the pool. This may
  44         be larger than the sum of the allocation of all volumes due to
  45         metadata overhead. This value is in bytes. This is not applicable
  46         when creating a pool. <span class="since">Since 0.4.1</span></dd>
  47       <dt><code>capacity</code></dt>
  48       <dd>Providing the total storage capacity for the pool. Due to
  49         underlying device constraints it may not be possible to use the
  50         full capacity for storage volumes. This value is in bytes. This
  51         is not applicable when creating a pool. <span class="since">Since 0.4.1</span></dd>
  52       <dt><code>available</code></dt>
  53       <dd>Providing the free space available for allocating new volumes
  54         in the pool. Due to underlying device constraints it may not be
  55         possible to allocate the entire free space to a single volume.
  56         This value is in bytes. This is not applicable when creating a
  57         pool. <span class="since">Since 0.4.1</span></dd>
  58     </dl>
  59
  60     <h3><a name="StoragePoolSource">Source elements</a></h3>
  61
  62     <p>
  63       A single <code>source</code> element is contained within the top level
  64       <code>pool</code> element. This tag is used to describe the source of
  65       the storage pool. It can contain the following child elements:
  66     </p>
  67
  68     <pre>
  69         ...
  70         &lt;source&gt;
  71           &lt;host name="iscsi.example.com"/&gt;
  72           &lt;device path="demo-target"/&gt;
  73           &lt;vendor name="Acme"/&gt;
  74           &lt;product name="model"/&gt;
  75         &lt;/source&gt;
  76         ...</pre>
  77
  78     <dl>
  79       <dt><code>device</code></dt>
  80       <dd>Provides the source for pools backed by physical devices.
  81         May be repeated multiple times depending on backend driver. Contains
  82         a single attribute <code>path</code> which is the fully qualified
  83         path to the block device node. <span class="since">Since 0.4.1</span></dd>
  84       <dt><code>directory</code></dt>
  85       <dd>Provides the source for pools backed by directories. May
  86         only occur once. Contains a single attribute <code>path</code>
  87         which is the fully qualified path to the block device node.
  88         <span class="since">Since 0.4.1</span></dd>
  89       <dt><code>adapter</code></dt>
  90       <dd>Provides the source for pools backed by SCSI adapters. May
  91         only occur once. Contains a single attribute <code>name</code>
  92         which is the SCSI adapter name (ex. "host1").
  93         <span class="since">Since 0.6.2</span></dd>
  94       <dt><code>host</code></dt>
  95       <dd>Provides the source for pools backed by storage from a
  96         remote server. Will be used in combination with a <code>directory</code>
  97         or <code>device</code> element. Contains an attribute <code>name</code>
  98         which is the hostname or IP address of the server. May optionally
  99         contain a <code>port</code> attribute for the protocol specific
 100         port number. <span class="since">Since 0.4.1</span></dd>
 101       <dt><code>name</code></dt>
 102       <dd>Provides the source for pools backed by storage from a
 103         named element (e.g., a logical volume group name).
 104         remote server. Contains a string identifier.
 105         <span class="since">Since 0.4.5</span></dd>
 106       <dt><code>format</code></dt>
 107       <dd>Provides information about the format of the pool. This
 108         contains a single attribute <code>type</code> whose value is
 109         backend specific. This is typically used to indicate filesystem
 110         type, or network filesystem type, or partition table type, or
 111         LVM metadata type. All drivers are required to have a default
 112         value for this, so it is optional. <span class="since">Since 0.4.1</span></dd>
 113
 114       <dt><code>vendor</code></dt>
 115       <dd>Provides optional information about the vendor of the
 116         storage device. This contains a single
 117         attribute <code>name</code> whose value is backend
 118         specific. <span class="since">Since 0.8.4</span></dd>
 119       <dt><code>product</code></dt>
 120       <dd>Provides an optional product name of the storage device.
 121         This contains a single attribute <code>name</code> whose value
 122         is backend specific.  <span class="since">Since 0.8.4</span></dd>
 123     </dl>
 124
 125     <h3><a name="StoragePoolTarget">Target elements</a></h3>
 126
 127     <p>
 128       A single <code>target</code> element is contained within the top level
 129       <code>pool</code> element. This tag is used to describe the mapping of
 130       the storage pool into the host filesystem. It can contain the following
 131       child elements:
 132     </p>
 133
 134     <pre>
 135         ...
 136         &lt;target&gt;
 137           &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
 138           &lt;permissions&gt;
 139             &lt;owner&gt;107&lt;/owner&gt;
 140             &lt;group&gt;107&lt;/group&gt;
 141             &lt;mode&gt;0744&lt;/mode&gt;
 142             &lt;label&gt;virt_image_t&lt;/label&gt;
 143           &lt;/permissions&gt;
 144           &lt;encryption type='...'&gt;
 145             ...
 146           &lt;/encryption&gt;
 147         &lt;/target&gt;
 148       &lt;/pool&gt;</pre>
 149
 150     <dl>
 151       <dt><code>path</code></dt>
 152       <dd>Provides the location at which the pool will be mapped into
 153         the local filesystem namespace. For a filesystem/directory based
 154         pool it will be the name of the directory in which volumes will
 155         be created. For device based pools it will be the name of the directory in which
 156         devices nodes exist. For the latter <code>/dev/</code> may seem
 157         like the logical choice, however, devices nodes there are not
 158         guaranteed stable across reboots, since they are allocated on
 159         demand. It is preferable to use a stable location such as one
 160         of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
 161         <span class="since">Since 0.4.1</span>
 162       </dd>
 163       <dt><code>permissions</code></dt>
 164       <dd>Provides information about the default permissions to use
 165         when creating volumes. This is currently only useful for directory
 166         or filesystem based pools, where the volumes allocated are simple
 167         files. For pools where the volumes are device nodes, the hotplug
 168         scripts determine permissions. It contains 4 child elements. The
 169         <code>mode</code> element contains the octal permission set. The
 170         <code>owner</code> element contains the numeric user ID. The <code>group</code>
 171         element contains the numeric group ID. The <code>label</code> element
 172         contains the MAC (eg SELinux) label string.
 173         <span class="since">Since 0.4.1</span>
 174       </dd>
 175       <dt><code>encryption</code></dt>
 176       <dd>If present, specifies how the volume is encrypted.  See
 177         the <a href="formatstorageencryption.html">Storage Encryption</a> page
 178         for more information.
 179       </dd>
 180     </dl>
 181
 182     <h3><a name="StoragePoolExtents">Device extents</a></h3>
 183
 184     <p>
 185       If a storage pool exposes information about its underlying
 186       placement / allocation scheme, the <code>device</code> element
 187       within the <code>source</code> element may contain information
 188       about its available extents. Some pools have a constraint that
 189       a volume must be allocated entirely within a single constraint
 190       (eg disk partition pools). Thus the extent information allows an
 191       application to determine the maximum possible size for a new
 192       volume
 193     </p>
 194     <p>
 195       For storage pools supporting extent information, within each
 196       <code>device</code> element there will be zero or more <code>freeExtent</code>
 197       elements. Each of these elements contains two attributes, <code>start</code>
 198       and <code>end</code> which provide the boundaries of the extent on the
 199       device, measured in bytes.  <span class="since">Since 0.4.1</span>
 200     </p>
 201
 202     <h2><a name="StorageVol">Storage volume XML</a></h2>
 203     <p>
 204       A storage volume will be either a file or a device node.
 205       The storage volume XML format is available <span class="since">since 0.4.1</span>
 206     </p>
 207
 208     <h3><a name="StorageVolFirst">General metadata</a></h3>
 209
 210     <pre>
 211       &lt;volume&gt;
 212         &lt;name&gt;sparse.img&lt;/name&gt;
 213         &lt;key&gt;/var/lib/xen/images/sparse.img&lt;/key&gt;
 214         &lt;allocation&gt;0&lt;/allocation&gt;
 215         &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
 216         ...</pre>
 217
 218     <dl>
 219       <dt><code>name</code></dt>
 220       <dd>Providing a name for the volume which is unique to the pool.
 221         This is mandatory when defining a volume.  <span class="since">Since 0.4.1</span></dd>
 222       <dt><code>key</code></dt>
 223       <dd>Providing an identifier for the volume which is globally unique.
 224           This cannot be set when creating a volume: it is always generated.
 225         <span class="since">Since 0.4.1</span></dd>
 226       <dt><code>allocation</code></dt>
 227       <dd>Providing the total storage allocation for the volume. This
 228         may be smaller than the logical capacity if the volume is sparsely
 229         allocated. It may also be larger than the logical capacity if the
 230         volume has substantial metadata overhead. This value is in bytes.
 231         If omitted when creating a volume, the volume will be fully
 232         allocated at time of creation. If set to a value smaller than the
 233         capacity, the pool has the <strong>option</strong> of deciding
 234         to sparsely allocate a volume. It does not have to honour requests
 235         for sparse allocation though.<br/>
 236         <br/>
 237         By default this is specified in bytes, but an optional
 238         <code>unit</code> can be specified to adjust the passed value.
 239         Values can be: 'K' (kilobytes), 'M' (megabytes), 'G' (gigabytes),
 240         'T' (terabytes), 'P' (petabytes), or 'E' (exabytes).
 241         <span class="since">Since 0.4.1</span></dd>
 242       <dt><code>capacity</code></dt>
 243       <dd>Providing the logical capacity for the volume. This value is
 244         in bytes by default, but a <code>unit</code> attribute can be
 245         specified with the same semantics as for <code>allocation</code>
 246         This is compulsory when creating a volume.
 247         <span class="since">Since 0.4.1</span></dd>
 248       <dt><code>source</code></dt>
 249       <dd>Provides information about the underlying storage allocation
 250         of the volume. This may not be available for some pool types.
 251         <span class="since">Since 0.4.1</span></dd>
 252       <dt><code>target</code></dt>
 253       <dd>Provides information about the representation of the volume
 254         on the local host. <span class="since">Since 0.4.1</span></dd>
 255     </dl>
 256
 257     <h3><a name="StorageVolTarget">Target elements</a></h3>
 258
 259     <p>
 260       A single <code>target</code> element is contained within the top level
 261       <code>volume</code> element. This tag is used to describe the mapping of
 262       the storage volume into the host filesystem. It can contain the following
 263       child elements:
 264     </p>
 265
 266     <pre>
 267         ...
 268         &lt;target&gt;
 269           &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
 270           &lt;format type='qcow2'/&gt;
 271           &lt;permissions&gt;
 272             &lt;owner&gt;107&lt;/owner&gt;
 273             &lt;group&gt;107&lt;/group&gt;
 274             &lt;mode&gt;0744&lt;/mode&gt;
 275             &lt;label&gt;virt_image_t&lt;/label&gt;
 276           &lt;/permissions&gt;
 277         &lt;/target&gt;</pre>
 278
 279     <dl>
 280       <dt><code>path</code></dt>
 281       <dd>Provides the location at which the volume can be accessed on
 282         the local filesystem, as an absolute path. This is a readonly
 283         attribute, so shouldn't be specified when creating a volume.
 284         <span class="since">Since 0.4.1</span></dd>
 285       <dt><code>format</code></dt>
 286       <dd>Provides information about the pool specific volume format.
 287         For disk pools it will provide the partition type. For filesystem
 288         or directory pools it will provide the file format type, eg cow,
 289         qcow, vmdk, raw. If omitted when creating a volume, the pool's
 290         default format will be used. The actual format is specified via
 291         the <code>type</code> attribute. Consult the pool-specific docs for
 292         the list of valid values. <span class="since">Since 0.4.1</span></dd>
 293       <dt><code>permissions</code></dt>
 294       <dd>Provides information about the default permissions to use
 295         when creating volumes. This is currently only useful for directory
 296         or filesystem based pools, where the volumes allocated are simple
 297         files. For pools where the volumes are device nodes, the hotplug
 298         scripts determine permissions. It contains 4 child elements. The
 299         <code>mode</code> element contains the octal permission set. The
 300         <code>owner</code> element contains the numeric user ID. The <code>group</code>
 301         element contains the numeric group ID. The <code>label</code> element
 302         contains the MAC (eg SELinux) label string.
 303         <span class="since">Since 0.4.1</span>
 304       </dd>
 305     </dl>
 306
 307     <h3><a name="StorageVolBacking">Backing store elements</a></h3>
 308
 309     <p>
 310       A single <code>backingStore</code> element is contained within the top level
 311       <code>volume</code> element. This tag is used to describe the optional copy
 312       on write, backing store for the storage volume. It can contain the following
 313       child elements:
 314     </p>
 315
 316     <pre>
 317         ...
 318         &lt;backingStore&gt;
 319           &lt;path&gt;/var/lib/virt/images/master.img&lt;/path&gt;
 320           &lt;format type='raw'/&gt;
 321           &lt;permissions&gt;
 322             &lt;owner&gt;107&lt;/owner&gt;
 323             &lt;group&gt;107&lt;/group&gt;
 324             &lt;mode&gt;0744&lt;/mode&gt;
 325             &lt;label&gt;virt_image_t&lt;/label&gt;
 326           &lt;/permissions&gt;
 327         &lt;/backingStore&gt;
 328       &lt;/volume&gt;</pre>
 329
 330     <dl>
 331       <dt><code>path</code></dt>
 332       <dd>Provides the location at which the backing store can be accessed on
 333         the local filesystem, as an absolute path. If omitted, there is no
 334         backing store for this volume.
 335         <span class="since">Since 0.6.0</span></dd>
 336       <dt><code>format</code></dt>
 337       <dd>Provides information about the pool specific backing store format.
 338         For disk pools it will provide the partition type. For filesystem
 339         or directory pools it will provide the file format type, eg cow,
 340         qcow, vmdk, raw. The actual format is specified via the type attribute.
 341         Consult the pool-specific docs for the list of valid
 342         values. Most file formats require a backing store of the same format,
 343         however, the qcow2 format allows a different backing store format.
 344         <span class="since">Since 0.6.0</span></dd>
 345       <dt><code>permissions</code></dt>
 346       <dd>Provides information about the permissions of the backing file.
 347         It contains 4 child elements. The
 348         <code>mode</code> element contains the octal permission set. The
 349         <code>owner</code> element contains the numeric user ID. The <code>group</code>
 350         element contains the numeric group ID. The <code>label</code> element
 351         contains the MAC (eg SELinux) label string.
 352         <span class="since">Since 0.6.0</span>
 353       </dd>
 354     </dl>
 355
 356     <h2><a name="examples">Example configuration</a></h2>
 357
 358     <p>
 359       Here are a couple of examples, for a more complete set demonstrating
 360       every type of storage pool, consult the <a href="storage.html">storage driver page</a>
 361     </p>
 362
 363     <h3><a name="exampleFile">File based storage pool</a></h3>
 364
 365     <pre>
 366       &lt;pool type="dir"&gt;
 367         &lt;name&gt;virtimages&lt;/name&gt;
 368         &lt;target&gt;
 369           &lt;path&gt;/var/lib/virt/images&lt;/path&gt;
 370         &lt;/target&gt;
 371       &lt;/pool&gt;</pre>
 372
 373     <h3><a name="exampleISCSI">iSCSI based storage pool</a></h3>
 374
 375     <pre>
 376       &lt;pool type="iscsi"&gt;
 377         &lt;name&gt;virtimages&lt;/name&gt;
 378         &lt;source&gt;
 379           &lt;host name="iscsi.example.com"/&gt;
 380           &lt;device path="demo-target"/&gt;
 381         &lt;/source&gt;
 382         &lt;target&gt;
 383           &lt;path&gt;/dev/disk/by-path&lt;/path&gt;
 384         &lt;/target&gt;
 385       &lt;/pool&gt;</pre>
 386
 387     <h3><a name="exampleVol">Storage volume</a></h3>
 388
 389     <pre>
 390       &lt;volume&gt;
 391         &lt;name&gt;sparse.img&lt;/name&gt;
 392         &lt;allocation&gt;0&lt;/allocation&gt;
 393         &lt;capacity unit="T"&gt;1&lt;/capacity&gt;
 394         &lt;target&gt;
 395           &lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
 396           &lt;permissions&gt;
 397             &lt;owner&gt;107&lt;/owner&gt;
 398             &lt;group&gt;107&lt;/group&gt;
 399             &lt;mode&gt;0744&lt;/mode&gt;
 400             &lt;label&gt;virt_image_t&lt;/label&gt;
 401           &lt;/permissions&gt;
 402         &lt;/target&gt;
 403       &lt;/volume&gt;</pre>
 404   </body>
 405 </html>