mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 17:34:18 +03:00
Added autogenerated TOC for network and storage XML reference docs
This commit is contained in:
Daniel P. Berrange
parent
2afd1db4a2
commit
ff2ea6de4e
@ -114,17 +114,41 @@
|
||||
</div>
|
||||
<div id="content">
|
||||
<h1>Network XML format</h1>
|
||||
<ul><li>
|
||||
<a href="#elements">Element and attribute overview</a>
|
||||
<ul><li>
|
||||
<a href="#elementsMetadata">General metadata</a>
|
||||
</li><li>
|
||||
<a href="#elementsConnect">Connectivity</a>
|
||||
</li><li>
|
||||
<a href="#elementsAddress">Addressing</a>
|
||||
</li></ul>
|
||||
</li><li>
|
||||
<a href="#examples">Example configuration</a>
|
||||
<ul><li>
|
||||
<a href="#examplesNAT">NAT based network</a>
|
||||
</li><li>
|
||||
<a href="#examplesRoute">Routed network config</a>
|
||||
</li><li>
|
||||
<a href="#examplesPrivate">Isolated network config</a>
|
||||
</li></ul>
|
||||
</li></ul>
|
||||
<p>
|
||||
This page provides an introduction to the network XML format. For background
|
||||
information on the concepts referred to here, consult the <a href="archnetwork.html">network driver architecture</a>
|
||||
page.
|
||||
</p>
|
||||
<h2>Element and attribute overview</h2>
|
||||
<h2>
|
||||
<a name="elements" id="elements">Element and attribute overview</a>
|
||||
</h2>
|
||||
<p>
|
||||
The root element required for all virtual networks is
|
||||
named <code>network</code> and has no attributes.
|
||||
The network XML format is available <span class="since">since 0.3.0</span>
|
||||
</p>
|
||||
<h3>General metadata</h3>
|
||||
<h3>
|
||||
<a name="elementsMetadata" id="elementsMetadata">General metadata</a>
|
||||
</h3>
|
||||
<p>
|
||||
The first elements provide basic metadata about the virtual
|
||||
network.
|
||||
@ -139,12 +163,14 @@
|
||||
consist only of alpha-numeric characters and is required
|
||||
to be unique within the scope of a single host. It is
|
||||
used to form the filename for storing the persistent
|
||||
configuration file.</dd><dt><code>uuid</code></dt><dd>The content of the <code>uuid</code> element provides
|
||||
configuration file. <span class="since">Since 0.3.0</span></dd><dt><code>uuid</code></dt><dd>The content of the <code>uuid</code> element provides
|
||||
a globally unique identifier for the virtual network.
|
||||
The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
|
||||
If omitted when defining/creating a new network, a random
|
||||
UUID is generated.</dd></dl>
|
||||
<h3>Connectivity</h3>
|
||||
UUID is generated. <span class="since">Since 0.3.0</span></dd></dl>
|
||||
<h3>
|
||||
<a name="elementsConnect" id="elementsConnect">Connectivity</a>
|
||||
</h3>
|
||||
<p>
|
||||
The next set of elements control how a virtual network is
|
||||
provided connectivity to the physical LAN (if at all).
|
||||
@ -152,7 +178,7 @@
|
||||
<pre>
|
||||
...
|
||||
<bridge name="virbr0" />
|
||||
<forward type="nat"/>
|
||||
<forward mode="nat" dev="eth0"/>
|
||||
...</pre>
|
||||
<dl><dt><code>bridge</code></dt><dd>The <code>name</code> attribute on the <code>bridge</code> element
|
||||
defines the name of a bridge device which will be used to construct
|
||||
@ -161,18 +187,22 @@
|
||||
may also be connected to the LAN. It is recommended that bridge
|
||||
device names started with the prefix <code>vir</code>, but the name
|
||||
<code>virbr0</code> is reserved for the "default" virtual network.
|
||||
This element should always be provided when defining a new network
|
||||
This element should always be provided when defining a new network.
|
||||
<span class="since">Since 0.3.0</span>
|
||||
</dd><dt><code>forward</code></dt><dd>Inclusion of the <code>forward</code> element indicates that
|
||||
the virtual network is to be connected to the physical LAN. If
|
||||
no attributes are set, NAT forwarding will be used for connectivity.
|
||||
Firewall rules will allow forwarding to any other network device whether
|
||||
ethernet, wireless, dialup, or VPN. If the <code>dev</code> attribute
|
||||
is set, the firewall rules will restrict forwarding to the named
|
||||
device only. If the <code>type</code> attribute is set to <code>route</code>
|
||||
device only. If the <code>mode</code> attribute is set to <code>route</code>
|
||||
then the traffic will not have NAT applied. This presumes that the
|
||||
local LAN router has suitable routing table entries to return traffic
|
||||
to this host.</dd></dl>
|
||||
<h3>Addressing</h3>
|
||||
to this host. <span class="since">Since 0.3.0; 'mode' attribute since
|
||||
0.4.2</span></dd></dl>
|
||||
<h3>
|
||||
<a name="elementsAddress" id="elementsAddress">Addressing</a>
|
||||
</h3>
|
||||
<p>
|
||||
The final set of elements define the IPv4 address range available,
|
||||
and optionally enable DHCP sevices.
|
||||
@ -190,19 +220,24 @@
|
||||
device associated with the virtual network. To the guests this
|
||||
address will be their default route. The <code>netmask</code>
|
||||
attribute defines the significant bits of the network address,
|
||||
again specified in dotted-decimal format.
|
||||
again specified in dotted-decimal format. <span class="since">Since 0.3.0</span>
|
||||
</dd><dt><code>dhcp</code></dt><dd>Immediately within the <code>ip</code> element there is an
|
||||
optional <code>dhcp</code> element. The presence of this element
|
||||
enables DHCP services on the virtual network. It will further
|
||||
contain one or more <code>range</code> elements.
|
||||
<span class="since">Since 0.3.0</span>
|
||||
</dd><dt><code>range</code></dt><dd>The <code>start</code> and <code>end</code> attributes on the
|
||||
<code>range</code> element specify the boundaries of a pool of
|
||||
IPv4 addresses to be provided to DHCP clients. These two addresses
|
||||
must lie within the scope of the network defined on the parent
|
||||
<code>ip</code> element.
|
||||
<code>ip</code> element. <span class="since">Since 0.3.0</span>
|
||||
</dd></dl>
|
||||
<h2>Example configuration</h2>
|
||||
<h3>NAT based network</h3>
|
||||
<h2>
|
||||
<a name="examples" id="examples">Example configuration</a>
|
||||
</h2>
|
||||
<h3>
|
||||
<a name="examplesNAT" id="examplesNAT">NAT based network</a>
|
||||
</h3>
|
||||
<p>
|
||||
This example is the so called "default" virtual network. It is
|
||||
provided and enabled out-of-the-box for all libvirt installations.
|
||||
@ -223,7 +258,9 @@
|
||||
</dhcp>
|
||||
</ip>
|
||||
</network></pre>
|
||||
<h3>Routed network config</h3>
|
||||
<h3>
|
||||
<a name="examplesRoute" id="examplesRoute">Routed network config</a>
|
||||
</h3>
|
||||
<p>
|
||||
This is a variant on the default network which routes traffic
|
||||
from the virtual network to the LAN without applying any NAT.
|
||||
@ -243,7 +280,9 @@
|
||||
</dhcp>
|
||||
</ip>
|
||||
</network></pre>
|
||||
<h3>Isolated network config</h3>
|
||||
<h3>
|
||||
<a name="examplesPrivate" id="examplesPrivate">Isolated network config</a>
|
||||
</h3>
|
||||
<p>
|
||||
This variant provides a completely isolated private network
|
||||
for guests. The guests can talk to each other, and the host
|
||||
|
||||
@ -2,20 +2,24 @@
|
||||
<body>
|
||||
<h1>Network XML format</h1>
|
||||
|
||||
<ul id="toc">
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
This page provides an introduction to the network XML format. For background
|
||||
information on the concepts referred to here, consult the <a href="archnetwork.html">network driver architecture</a>
|
||||
page.
|
||||
</p>
|
||||
|
||||
<h2>Element and attribute overview</h2>
|
||||
<h2><a name="elements">Element and attribute overview</a></h2>
|
||||
|
||||
<p>
|
||||
The root element required for all virtual networks is
|
||||
named <code>network</code> and has no attributes.
|
||||
The network XML format is available <span class="since">since 0.3.0</span>
|
||||
</p>
|
||||
|
||||
<h3>General metadata</h3>
|
||||
<h3><a name="elementsMetadata">General metadata</a></h3>
|
||||
|
||||
<p>
|
||||
The first elements provide basic metadata about the virtual
|
||||
@ -35,16 +39,16 @@
|
||||
consist only of alpha-numeric characters and is required
|
||||
to be unique within the scope of a single host. It is
|
||||
used to form the filename for storing the persistent
|
||||
configuration file.</dd>
|
||||
configuration file. <span class="since">Since 0.3.0</span></dd>
|
||||
<dt><code>uuid</code></dt>
|
||||
<dd>The content of the <code>uuid</code> element provides
|
||||
a globally unique identifier for the virtual network.
|
||||
The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
|
||||
If omitted when defining/creating a new network, a random
|
||||
UUID is generated.</dd>
|
||||
UUID is generated. <span class="since">Since 0.3.0</span></dd>
|
||||
</dl>
|
||||
|
||||
<h3>Connectivity</h3>
|
||||
<h3><a name="elementsConnect">Connectivity</a></h3>
|
||||
|
||||
<p>
|
||||
The next set of elements control how a virtual network is
|
||||
@ -54,7 +58,7 @@
|
||||
<pre>
|
||||
...
|
||||
<bridge name="virbr0" />
|
||||
<forward type="nat"/>
|
||||
<forward mode="nat" dev="eth0"/>
|
||||
...</pre>
|
||||
|
||||
<dl>
|
||||
@ -66,7 +70,8 @@
|
||||
may also be connected to the LAN. It is recommended that bridge
|
||||
device names started with the prefix <code>vir</code>, but the name
|
||||
<code>virbr0</code> is reserved for the "default" virtual network.
|
||||
This element should always be provided when defining a new network
|
||||
This element should always be provided when defining a new network.
|
||||
<span class="since">Since 0.3.0</span>
|
||||
</dd>
|
||||
<dt><code>forward</code></dt>
|
||||
<dd>Inclusion of the <code>forward</code> element indicates that
|
||||
@ -75,13 +80,14 @@
|
||||
Firewall rules will allow forwarding to any other network device whether
|
||||
ethernet, wireless, dialup, or VPN. If the <code>dev</code> attribute
|
||||
is set, the firewall rules will restrict forwarding to the named
|
||||
device only. If the <code>type</code> attribute is set to <code>route</code>
|
||||
device only. If the <code>mode</code> attribute is set to <code>route</code>
|
||||
then the traffic will not have NAT applied. This presumes that the
|
||||
local LAN router has suitable routing table entries to return traffic
|
||||
to this host.</dd>
|
||||
to this host. <span class="since">Since 0.3.0; 'mode' attribute since
|
||||
0.4.2</span></dd>
|
||||
</dl>
|
||||
|
||||
<h3>Addressing</h3>
|
||||
<h3><a name="elementsAddress">Addressing</a></h3>
|
||||
|
||||
<p>
|
||||
The final set of elements define the IPv4 address range available,
|
||||
@ -104,26 +110,27 @@
|
||||
device associated with the virtual network. To the guests this
|
||||
address will be their default route. The <code>netmask</code>
|
||||
attribute defines the significant bits of the network address,
|
||||
again specified in dotted-decimal format.
|
||||
again specified in dotted-decimal format. <span class="since">Since 0.3.0</span>
|
||||
</dd>
|
||||
<dt><code>dhcp</code></dt>
|
||||
<dd>Immediately within the <code>ip</code> element there is an
|
||||
optional <code>dhcp</code> element. The presence of this element
|
||||
enables DHCP services on the virtual network. It will further
|
||||
contain one or more <code>range</code> elements.
|
||||
<span class="since">Since 0.3.0</span>
|
||||
</dd>
|
||||
<dt><code>range</code></dt>
|
||||
<dd>The <code>start</code> and <code>end</code> attributes on the
|
||||
<code>range</code> element specify the boundaries of a pool of
|
||||
IPv4 addresses to be provided to DHCP clients. These two addresses
|
||||
must lie within the scope of the network defined on the parent
|
||||
<code>ip</code> element.
|
||||
<code>ip</code> element. <span class="since">Since 0.3.0</span>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h2>Example configuration</h2>
|
||||
<h2><a name="examples">Example configuration</a></h2>
|
||||
|
||||
<h3>NAT based network</h3>
|
||||
<h3><a name="examplesNAT">NAT based network</a></h3>
|
||||
|
||||
<p>
|
||||
This example is the so called "default" virtual network. It is
|
||||
@ -147,7 +154,7 @@
|
||||
</ip>
|
||||
</network></pre>
|
||||
|
||||
<h3>Routed network config</h3>
|
||||
<h3><a name="examplesRoute">Routed network config</a></h3>
|
||||
|
||||
<p>
|
||||
This is a variant on the default network which routes traffic
|
||||
@ -170,7 +177,7 @@
|
||||
</ip>
|
||||
</network></pre>
|
||||
|
||||
<h3>Isolated network config</h3>
|
||||
<h3><a name="examplesPrivate">Isolated network config</a></h3>
|
||||
|
||||
<p>
|
||||
This variant provides a completely isolated private network
|
||||
|
||||
@ -115,171 +115,300 @@
|
||||
<div id="content">
|
||||
<h1>Storage pool and volume XML format</h1>
|
||||
<ul><li>
|
||||
<a href="#StoragePool">Storage pool XML</a>
|
||||
<ul><li>
|
||||
<a href="#StoragePoolFirst">First level elements</a>
|
||||
<a href="#StoragePool">Storage pool XML</a>
|
||||
<ul><li>
|
||||
<a href="#StoragePoolFirst">General metadata</a>
|
||||
</li><li>
|
||||
<a href="#StoragePoolSource">Source elements</a>
|
||||
</li><li>
|
||||
<a href="#StoragePoolTarget">Target elements</a>
|
||||
</li><li>
|
||||
<a href="#StoragePoolExtents">Device extents</a>
|
||||
</li></ul>
|
||||
</li><li>
|
||||
<a href="#StoragePoolSource">Source elements</a>
|
||||
<a href="#StorageVol">Storage volume XML</a>
|
||||
<ul><li>
|
||||
<a href="#StorageVolFirst">General metadata</a>
|
||||
</li><li>
|
||||
<a href="#StorageVolTarget">Target elements</a>
|
||||
</li></ul>
|
||||
</li><li>
|
||||
<a href="#StoragePoolTarget">Target elements</a>
|
||||
</li><li>
|
||||
<a href="#StoragePoolExtents">Device extents</a>
|
||||
</li></ul></li><li>
|
||||
<a href="#StorageVol">Storage volume XML</a>
|
||||
<ul><li>
|
||||
<a href="#StorageVolFirst">First level elements</a>
|
||||
</li><li>
|
||||
<a href="#StorageVolSource">Source elements</a>
|
||||
</li><li>
|
||||
<a href="#StorageVolTarget">Target elements</a>
|
||||
</li></ul></li></ul>
|
||||
<h3>
|
||||
<a href="#examples">Example configuration</a>
|
||||
<ul><li>
|
||||
<a href="#exampleFile">File based storage pool</a>
|
||||
</li><li>
|
||||
<a href="#exampleISCSI">iSCSI based storage pool</a>
|
||||
</li><li>
|
||||
<a href="#exampleVol">Storage volume</a>
|
||||
</li></ul>
|
||||
</li></ul>
|
||||
<h2>
|
||||
<a name="StoragePool" id="StoragePool">Storage pool XML</a>
|
||||
</h3>
|
||||
</h2>
|
||||
<p>
|
||||
Although all storage pool backends share the same public APIs and
|
||||
XML format, they have varying levels of capabilities. Some may
|
||||
allow creation of volumes, others may only allow use of pre-existing
|
||||
volumes. Some may have constraints on volume size, or placement.
|
||||
</p>
|
||||
<p>The is the top level tag for a storage pool document is 'pool'. It has
|
||||
a single attribute <code>type</code>, which is one of <code>dir</code>,
|
||||
<code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
|
||||
<code>logical</code>. This corresponds to the storage backend drivers
|
||||
listed further along in this document.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="StoragePoolFirst" id="StoragePoolFirst">First level elements</a>
|
||||
</h4>
|
||||
<dl><dt>name</dt><dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool</dd><dt>uuid</dt><dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted</dd><dt>allocation</dt><dd>Providing the total storage allocation for the pool. This may
|
||||
be larger than the sum of the allocation of all volumes due to
|
||||
metadata overhead. This value is in bytes. This is not applicable
|
||||
when creating a pool.</dd><dt>capacity</dt><dd>Providing the total storage capacity for the pool. Due to
|
||||
underlying device constraints it may not be possible to use the
|
||||
full capacity for storage volumes. This value is in bytes. This
|
||||
is not applicable when creating a pool.</dd><dt>available</dt><dd>Providing the free space available for allocating new volumes
|
||||
in the pool. Due to underlying device constraints it may not be
|
||||
possible to allocate the entire free space to a single volume.
|
||||
This value is in bytes. This is not applicable when creating a
|
||||
pool.</dd><dt>source</dt><dd>Provides information about the source of the pool, such as
|
||||
the underlying host devices, or remote server</dd><dt>target</dt><dd>Provides information about the representation of the pool
|
||||
on the local host.</dd></dl>
|
||||
<h4>
|
||||
<a name="StoragePoolSource" id="StoragePoolSource">Source elements</a>
|
||||
</h4>
|
||||
<dl><dt>device</dt><dd>Provides the source for pools backed by physical devices.
|
||||
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.</dd><dt>directory</dt><dd>Provides the source for pools backed by directories. May
|
||||
only occur once. Contains a single attribute <code>path</code>
|
||||
which is the fully qualified path to the block device node.</dd><dt>host</dt><dd>Provides the source for pools backed by storage from a
|
||||
remote server. Will be used in combination with a <code>directory</code>
|
||||
or <code>device</code> element. Contains an attribute <code>name<code>
|
||||
which is the hostname or IP address of the server. May optionally
|
||||
contain a <code>port</code> attribute for the protocol specific
|
||||
port number.</code></code></dd><dt>format</dt><dd>Provides information about the format of the pool. This
|
||||
contains a single attribute <code>type</code> whose value is
|
||||
backend specific. This is typically used to indicate filesystem
|
||||
type, or network filesystem type, or partition table type, or
|
||||
LVM metadata type. All drivers are required to have a default
|
||||
value for this, so it is optional.</dd></dl>
|
||||
<h4>
|
||||
<a name="StoragePoolTarget" id="StoragePoolTarget">Target elements</a>
|
||||
</h4>
|
||||
<dl><dt>path</dt><dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
</dd><dt>permissions</dt><dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
</dd></dl>
|
||||
<h4>
|
||||
<a name="StoragePoolExtents" id="StoragePoolExtents">Device extents</a>
|
||||
</h4>
|
||||
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>
|
||||
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.
|
||||
</p>
|
||||
The is the top level tag for a storage pool document is 'pool'. It has
|
||||
a single attribute <code>type</code>, which is one of <code>dir</code>,
|
||||
<code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
|
||||
<code>logical</code>. This corresponds to the storage backend drivers
|
||||
listed further along in this document.
|
||||
The storage pool XML format is available <span class="since">since 0.4.1</span>
|
||||
</p>
|
||||
<h3>
|
||||
<a name="StorageVol" id="StorageVol">Storage volume XML</a>
|
||||
<a name="StoragePoolFirst" id="StoragePoolFirst">General metadata</a>
|
||||
</h3>
|
||||
<pre>
|
||||
<pool type="iscsi">
|
||||
<name>virtimages</name>
|
||||
<uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
|
||||
<allocation>10000000</allocation>
|
||||
<capacity>50000000</capacity>
|
||||
<available>40000000</available>
|
||||
...</pre>
|
||||
<dl><dt><code>name</code></dt><dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd><dt><code>uuid</code></dt><dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted. <span class="since">Since 0.4.1</span></dd><dt><code>allocation</code></dt><dd>Providing the total storage allocation for the pool. This may
|
||||
be larger than the sum of the allocation of all volumes due to
|
||||
metadata overhead. This value is in bytes. This is not applicable
|
||||
when creating a pool. <span class="since">Since 0.4.1</span></dd><dt><code>capacity</code></dt><dd>Providing the total storage capacity for the pool. Due to
|
||||
underlying device constraints it may not be possible to use the
|
||||
full capacity for storage volumes. This value is in bytes. This
|
||||
is not applicable when creating a pool. <span class="since">Since 0.4.1</span></dd><dt><code>available</code></dt><dd>Providing the free space available for allocating new volumes
|
||||
in the pool. Due to underlying device constraints it may not be
|
||||
possible to allocate the entire free space to a single volume.
|
||||
This value is in bytes. This is not applicable when creating a
|
||||
pool. <span class="since">Since 0.4.1</span></dd></dl>
|
||||
<h3>
|
||||
<a name="StoragePoolSource" id="StoragePoolSource">Source elements</a>
|
||||
</h3>
|
||||
<p>
|
||||
A storage volume will be either a file or a device node.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="StorageVolFirst" id="StorageVolFirst">First level elements</a>
|
||||
</h4>
|
||||
<dl><dt>name</dt><dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool</dd><dt>uuid</dt><dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted</dd><dt>allocation</dt><dd>Providing the total storage allocation for the volume. This
|
||||
may be smaller than the logical capacity if the volume is sparsely
|
||||
allocated. It may also be larger than the logical capacity if the
|
||||
volume has substantial metadata overhead. This value is in bytes.
|
||||
If omitted when creating a volume, the volume will be fully
|
||||
allocated at time of creation. If set to a value smaller than the
|
||||
capacity, the pool has the <strong>option</strong> of deciding
|
||||
to sparsely allocate a volume. It does not have to honour requests
|
||||
for sparse allocation though.</dd><dt>capacity</dt><dd>Providing the logical capacity for the volume. This value is
|
||||
in bytes. This is compulsory when creating a volume</dd><dt>source</dt><dd>Provides information about the underlying storage allocation
|
||||
of the volume. This may not be available for some pool types.</dd><dt>target</dt><dd>Provides information about the representation of the volume
|
||||
on the local host.</dd></dl>
|
||||
<h4>
|
||||
A single <code>source</code> element is contained within the top level
|
||||
<code>pool</code> element. This tag is used to describe the source of
|
||||
the storage pool. It can contain the following child elements:
|
||||
</p>
|
||||
<pre>
|
||||
...
|
||||
<source>
|
||||
<host name="iscsi.example.com"/>
|
||||
<device path="demo-target"/>
|
||||
</source>
|
||||
...</pre>
|
||||
<dl><dt><code>device</code></dt><dd>Provides the source for pools backed by physical devices.
|
||||
May be repeated multiple times depending on backend driver. Contains
|
||||
a single attribute <code>path</code> which is the fully qualified
|
||||
path to the block device node. <span class="since">Since 0.4.1</span></dd><dt><code>directory</code></dt><dd>Provides the source for pools backed by directories. May
|
||||
only occur once. Contains a single attribute <code>path</code>
|
||||
which is the fully qualified path to the block device node.
|
||||
<span class="since">Since 0.4.1</span></dd><dt><code>host</code></dt><dd>Provides the source for pools backed by storage from a
|
||||
remote server. Will be used in combination with a <code>directory</code>
|
||||
or <code>device</code> element. Contains an attribute <code>name</code>
|
||||
which is the hostname or IP address of the server. May optionally
|
||||
contain a <code>port</code> attribute for the protocol specific
|
||||
port number. <span class="since">Since 0.4.1</span></dd><dt><code>format</code></dt><dd>Provides information about the format of the pool. This
|
||||
contains a single attribute <code>type</code> whose value is
|
||||
backend specific. This is typically used to indicate filesystem
|
||||
type, or network filesystem type, or partition table type, or
|
||||
LVM metadata type. All drivers are required to have a default
|
||||
value for this, so it is optional. <span class="since">Since 0.4.1</span></dd></dl>
|
||||
<h3>
|
||||
<a name="StoragePoolTarget" id="StoragePoolTarget">Target elements</a>
|
||||
</h3>
|
||||
<p>
|
||||
A single <code>target</code> element is contained within the top level
|
||||
<code>pool</code> element. This tag is used to describe the mapping of
|
||||
the storage pool into the host filesystem. It can contain the following
|
||||
child elements:
|
||||
</p>
|
||||
<pre>
|
||||
...
|
||||
<target>
|
||||
<path>/dev/disk/by-path</path>
|
||||
<permissions>
|
||||
<owner>0744</owner>
|
||||
<group>0744</group>
|
||||
<mode>0744</mode>
|
||||
<label>virt_image_t</label>
|
||||
</permissions>
|
||||
</target>
|
||||
</pool></pre>
|
||||
<dl><dt><code>path</code></dt><dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd><dt><code>permissions</code></dt><dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd></dl>
|
||||
<h3>
|
||||
<a name="StoragePoolExtents" id="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" id="StorageVol">Storage volume XML</a>
|
||||
</h2>
|
||||
<p>
|
||||
A storage volume will be either a file or a device node.
|
||||
The storage volume XML format is available <span class="since">since 0.4.1</span>
|
||||
</p>
|
||||
<h3>
|
||||
<a name="StorageVolFirst" id="StorageVolFirst">General metadata</a>
|
||||
</h3>
|
||||
<pre>
|
||||
<volume type="file">
|
||||
<name>sparse.img</name>
|
||||
<key>/var/lib/xen/images/sparse.img</key>
|
||||
<allocation>0</allocation>
|
||||
<capacity unit="T">1</capacity>
|
||||
...</pre>
|
||||
<dl><dt><code>name</code></dt><dd>Providing a name for the volume which is unique to the pool.
|
||||
This is mandatory when defining a volume. <span class="since">Since 0.4.1</span></dd><dt><code>key</code></dt><dd>Providing an identifier for the volume which is globally unique.
|
||||
This is optional when defining a volume, a key will be generated if
|
||||
omitted. <span class="since">Since 0.4.1</span></dd><dt><code>allocation</code></dt><dd>Providing the total storage allocation for the volume. This
|
||||
may be smaller than the logical capacity if the volume is sparsely
|
||||
allocated. It may also be larger than the logical capacity if the
|
||||
volume has substantial metadata overhead. This value is in bytes.
|
||||
If omitted when creating a volume, the volume will be fully
|
||||
allocated at time of creation. If set to a value smaller than the
|
||||
capacity, the pool has the <strong>option</strong> of deciding
|
||||
to sparsely allocate a volume. It does not have to honour requests
|
||||
for sparse allocation though. <span class="since">Since 0.4.1</span></dd><dt><code>capacity</code></dt><dd>Providing the logical capacity for the volume. This value is
|
||||
in bytes. This is compulsory when creating a volume.
|
||||
<span class="since">Since 0.4.1</span></dd><dt><code>source</code></dt><dd>Provides information about the underlying storage allocation
|
||||
of the volume. This may not be available for some pool types.
|
||||
<span class="since">Since 0.4.1</span></dd><dt><code>target</code></dt><dd>Provides information about the representation of the volume
|
||||
on the local host. <span class="since">Since 0.4.1</span></dd></dl>
|
||||
<h3>
|
||||
<a name="StorageVolTarget" id="StorageVolTarget">Target elements</a>
|
||||
</h4>
|
||||
<dl><dt>path</dt><dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
</dd><dt>format</dt><dd>Provides information about the pool specific volume format.
|
||||
For disk pools it will provide the partition type. For filesystem
|
||||
or directory pools it will provide the file format type, eg cow,
|
||||
qcow, vmdk, raw. If omitted when creating a volume, the pool's
|
||||
default format will be used. The actual format is specified via
|
||||
the <code>type</code>. Consult the pool-specific docs for the
|
||||
list of valid values.</dd><dt>permissions</dt><dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
</dd></dl>
|
||||
</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>
|
||||
...
|
||||
<target>
|
||||
<path>/var/lib/virt/images/sparse.img</path>
|
||||
<permissions>
|
||||
<owner>0744</owner>
|
||||
<group>0744</group>
|
||||
<mode>0744</mode>
|
||||
<label>virt_image_t</label>
|
||||
</permissions>
|
||||
</target>
|
||||
</volume></pre>
|
||||
<dl><dt><code>path</code></dt><dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd><dt><code>format</code></dt><dd>Provides information about the pool specific volume format.
|
||||
For disk pools it will provide the partition type. For filesystem
|
||||
or directory pools it will provide the file format type, eg cow,
|
||||
qcow, vmdk, raw. If omitted when creating a volume, the pool's
|
||||
default format will be used. The actual format is specified via
|
||||
the <code>type</code>. Consult the pool-specific docs for the
|
||||
list of valid values. <span class="since">Since 0.4.1</span></dd><dt><code>permissions</code></dt><dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd></dl>
|
||||
<h2>
|
||||
<a name="examples" id="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" id="exampleFile">File based storage pool</a>
|
||||
</h3>
|
||||
<pre>
|
||||
<pool type="dir">
|
||||
<name>virtimages</name>
|
||||
<target>
|
||||
<path>/var/lib/virt/images</path>
|
||||
</target>
|
||||
</pool></pre>
|
||||
<h3>
|
||||
<a name="exampleISCSI" id="exampleISCSI">iSCSI based storage pool</a>
|
||||
</h3>
|
||||
<pre>
|
||||
<pool type="iscsi">
|
||||
<name>virtimages</name>
|
||||
<source>
|
||||
<host name="iscsi.example.com"/>
|
||||
<device path="demo-target"/>
|
||||
</source>
|
||||
<target>
|
||||
<path>/dev/disk/by-path</path>
|
||||
</target>
|
||||
</pool></pre>
|
||||
<h3>
|
||||
<a name="exampleVol" id="exampleVol">Storage volume</a>
|
||||
</h3>
|
||||
<pre>
|
||||
<volume type="file">
|
||||
<name>sparse.img</name>
|
||||
<allocation>0</allocation>
|
||||
<capacity unit="T">1</capacity>
|
||||
<target>
|
||||
<path>/var/lib/virt/images/sparse.img</path>
|
||||
<permissions>
|
||||
<owner>0744</owner>
|
||||
<group>0744</group>
|
||||
<mode>0744</mode>
|
||||
<label>virt_image_t</label>
|
||||
</permissions>
|
||||
</target>
|
||||
</volume></pre>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footer">
|
||||
|
||||
@ -2,236 +2,324 @@
|
||||
<body>
|
||||
<h1>Storage pool and volume XML format</h1>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<a href="#StoragePool">Storage pool XML</a>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="#StoragePoolFirst">First level elements</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#StoragePoolSource">Source elements</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#StoragePoolTarget">Target elements</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#StoragePoolExtents">Device extents</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#StorageVol">Storage volume XML</a>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="#StorageVolFirst">First level elements</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#StorageVolSource">Source elements</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#StorageVolTarget">Target elements</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul id="toc"></ul>
|
||||
|
||||
<h3>
|
||||
<a name="StoragePool" id="StoragePool">Storage pool XML</a>
|
||||
</h3>
|
||||
<p>
|
||||
Although all storage pool backends share the same public APIs and
|
||||
XML format, they have varying levels of capabilities. Some may
|
||||
allow creation of volumes, others may only allow use of pre-existing
|
||||
volumes. Some may have constraints on volume size, or placement.
|
||||
</p>
|
||||
<p>The is the top level tag for a storage pool document is 'pool'. It has
|
||||
a single attribute <code>type</code>, which is one of <code>dir</code>,
|
||||
<code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
|
||||
<code>logical</code>. This corresponds to the storage backend drivers
|
||||
listed further along in this document.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="StoragePoolFirst" id="StoragePoolFirst">First level elements</a>
|
||||
</h4>
|
||||
<dl>
|
||||
<dt>name</dt>
|
||||
<dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool</dd>
|
||||
<dt>uuid</dt>
|
||||
<dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted</dd>
|
||||
<dt>allocation</dt>
|
||||
<dd>Providing the total storage allocation for the pool. This may
|
||||
be larger than the sum of the allocation of all volumes due to
|
||||
metadata overhead. This value is in bytes. This is not applicable
|
||||
when creating a pool.</dd>
|
||||
<dt>capacity</dt>
|
||||
<dd>Providing the total storage capacity for the pool. Due to
|
||||
underlying device constraints it may not be possible to use the
|
||||
full capacity for storage volumes. This value is in bytes. This
|
||||
is not applicable when creating a pool.</dd>
|
||||
<dt>available</dt>
|
||||
<dd>Providing the free space available for allocating new volumes
|
||||
in the pool. Due to underlying device constraints it may not be
|
||||
possible to allocate the entire free space to a single volume.
|
||||
This value is in bytes. This is not applicable when creating a
|
||||
pool.</dd>
|
||||
<dt>source</dt>
|
||||
<dd>Provides information about the source of the pool, such as
|
||||
the underlying host devices, or remote server</dd>
|
||||
<dt>target</dt>
|
||||
<dd>Provides information about the representation of the pool
|
||||
on the local host.</dd>
|
||||
</dl>
|
||||
<h4>
|
||||
<a name="StoragePoolSource" id="StoragePoolSource">Source elements</a>
|
||||
</h4>
|
||||
<dl>
|
||||
<dt>device</dt>
|
||||
<dd>Provides the source for pools backed by physical devices.
|
||||
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.</dd>
|
||||
<dt>directory</dt>
|
||||
<dd>Provides the source for pools backed by directories. May
|
||||
only occur once. Contains a single attribute <code>path</code>
|
||||
which is the fully qualified path to the block device node.</dd>
|
||||
<dt>host</dt>
|
||||
<dd>Provides the source for pools backed by storage from a
|
||||
remote server. Will be used in combination with a <code>directory</code>
|
||||
or <code>device</code> element. Contains an attribute <code>name<code>
|
||||
which is the hostname or IP address of the server. May optionally
|
||||
contain a <code>port</code> attribute for the protocol specific
|
||||
port number.</code></code></dd>
|
||||
<dt>format</dt>
|
||||
<dd>Provides information about the format of the pool. This
|
||||
contains a single attribute <code>type</code> whose value is
|
||||
backend specific. This is typically used to indicate filesystem
|
||||
type, or network filesystem type, or partition table type, or
|
||||
LVM metadata type. All drivers are required to have a default
|
||||
value for this, so it is optional.</dd>
|
||||
</dl>
|
||||
<h4>
|
||||
<a name="StoragePoolTarget" id="StoragePoolTarget">Target elements</a>
|
||||
</h4>
|
||||
<dl>
|
||||
<dt>path</dt>
|
||||
<dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
</dd>
|
||||
<dt>permissions</dt>
|
||||
<dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
</dd>
|
||||
</dl>
|
||||
<h4>
|
||||
<a name="StoragePoolExtents" id="StoragePoolExtents">Device extents</a>
|
||||
</h4>
|
||||
<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.
|
||||
</p>
|
||||
<h3>
|
||||
<a name="StorageVol" id="StorageVol">Storage volume XML</a>
|
||||
</h3>
|
||||
<p>
|
||||
A storage volume will be either a file or a device node.
|
||||
</p>
|
||||
<h4>
|
||||
<a name="StorageVolFirst" id="StorageVolFirst">First level elements</a>
|
||||
</h4>
|
||||
<dl>
|
||||
<dt>name</dt>
|
||||
<dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool</dd>
|
||||
<dt>uuid</dt>
|
||||
<dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted</dd>
|
||||
<dt>allocation</dt>
|
||||
<dd>Providing the total storage allocation for the volume. This
|
||||
may be smaller than the logical capacity if the volume is sparsely
|
||||
allocated. It may also be larger than the logical capacity if the
|
||||
volume has substantial metadata overhead. This value is in bytes.
|
||||
If omitted when creating a volume, the volume will be fully
|
||||
allocated at time of creation. If set to a value smaller than the
|
||||
capacity, the pool has the <strong>option</strong> of deciding
|
||||
to sparsely allocate a volume. It does not have to honour requests
|
||||
for sparse allocation though.</dd>
|
||||
<dt>capacity</dt>
|
||||
<dd>Providing the logical capacity for the volume. This value is
|
||||
in bytes. This is compulsory when creating a volume</dd>
|
||||
<dt>source</dt>
|
||||
<dd>Provides information about the underlying storage allocation
|
||||
of the volume. This may not be available for some pool types.</dd>
|
||||
<dt>target</dt>
|
||||
<dd>Provides information about the representation of the volume
|
||||
on the local host.</dd>
|
||||
</dl>
|
||||
<h4>
|
||||
<a name="StorageVolTarget" id="StorageVolTarget">Target elements</a>
|
||||
</h4>
|
||||
<dl>
|
||||
<dt>path</dt>
|
||||
<dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
</dd>
|
||||
<dt>format</dt>
|
||||
<dd>Provides information about the pool specific volume format.
|
||||
For disk pools it will provide the partition type. For filesystem
|
||||
or directory pools it will provide the file format type, eg cow,
|
||||
qcow, vmdk, raw. If omitted when creating a volume, the pool's
|
||||
default format will be used. The actual format is specified via
|
||||
the <code>type</code>. Consult the pool-specific docs for the
|
||||
list of valid values.</dd>
|
||||
<dt>permissions</dt>
|
||||
<dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
</dd>
|
||||
</dl>
|
||||
<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>
|
||||
The is the top level tag for a storage pool document is 'pool'. It has
|
||||
a single attribute <code>type</code>, which is one of <code>dir</code>,
|
||||
<code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
|
||||
<code>logical</code>. This corresponds to the storage backend drivers
|
||||
listed further along in this document.
|
||||
The storage pool XML format is available <span class="since">since 0.4.1</span>
|
||||
</p>
|
||||
<h3><a name="StoragePoolFirst">General metadata</a></h3>
|
||||
|
||||
<pre>
|
||||
<pool type="iscsi">
|
||||
<name>virtimages</name>
|
||||
<uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
|
||||
<allocation>10000000</allocation>
|
||||
<capacity>50000000</capacity>
|
||||
<available>40000000</available>
|
||||
...</pre>
|
||||
|
||||
<dl>
|
||||
<dt><code>name</code></dt>
|
||||
<dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>uuid</code></dt>
|
||||
<dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>allocation</code></dt>
|
||||
<dd>Providing the total storage allocation for the pool. This may
|
||||
be larger than the sum of the allocation of all volumes due to
|
||||
metadata overhead. This value is in bytes. This is not applicable
|
||||
when creating a pool. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>capacity</code></dt>
|
||||
<dd>Providing the total storage capacity for the pool. Due to
|
||||
underlying device constraints it may not be possible to use the
|
||||
full capacity for storage volumes. This value is in bytes. This
|
||||
is not applicable when creating a pool. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>available</code></dt>
|
||||
<dd>Providing the free space available for allocating new volumes
|
||||
in the pool. Due to underlying device constraints it may not be
|
||||
possible to allocate the entire free space to a single volume.
|
||||
This value is in bytes. This is not applicable when creating a
|
||||
pool. <span class="since">Since 0.4.1</span></dd>
|
||||
</dl>
|
||||
|
||||
<h3><a name="StoragePoolSource">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
|
||||
the storage pool. It can contain the following child elements:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
...
|
||||
<source>
|
||||
<host name="iscsi.example.com"/>
|
||||
<device path="demo-target"/>
|
||||
</source>
|
||||
...</pre>
|
||||
|
||||
<dl>
|
||||
<dt><code>device</code></dt>
|
||||
<dd>Provides the source for pools backed by physical devices.
|
||||
May be repeated multiple times depending on backend driver. Contains
|
||||
a single attribute <code>path</code> which is the fully qualified
|
||||
path to the block device node. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>directory</code></dt>
|
||||
<dd>Provides the source for pools backed by directories. May
|
||||
only occur once. Contains a single attribute <code>path</code>
|
||||
which is the fully qualified path to the block device node.
|
||||
<span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>host</code></dt>
|
||||
<dd>Provides the source for pools backed by storage from a
|
||||
remote server. Will be used in combination with a <code>directory</code>
|
||||
or <code>device</code> element. Contains an attribute <code>name</code>
|
||||
which is the hostname or IP address of the server. May optionally
|
||||
contain a <code>port</code> attribute for the protocol specific
|
||||
port number. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>format</code></dt>
|
||||
<dd>Provides information about the format of the pool. This
|
||||
contains a single attribute <code>type</code> whose value is
|
||||
backend specific. This is typically used to indicate filesystem
|
||||
type, or network filesystem type, or partition table type, or
|
||||
LVM metadata type. All drivers are required to have a default
|
||||
value for this, so it is optional. <span class="since">Since 0.4.1</span></dd>
|
||||
</dl>
|
||||
|
||||
<h3><a name="StoragePoolTarget">Target elements</a></h3>
|
||||
|
||||
<p>
|
||||
A single <code>target</code> element is contained within the top level
|
||||
<code>pool</code> element. This tag is used to describe the mapping of
|
||||
the storage pool into the host filesystem. It can contain the following
|
||||
child elements:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
...
|
||||
<target>
|
||||
<path>/dev/disk/by-path</path>
|
||||
<permissions>
|
||||
<owner>0744</owner>
|
||||
<group>0744</group>
|
||||
<mode>0744</mode>
|
||||
<label>virt_image_t</label>
|
||||
</permissions>
|
||||
</target>
|
||||
</pool></pre>
|
||||
|
||||
<dl>
|
||||
<dt><code>path</code></dt>
|
||||
<dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd>
|
||||
<dt><code>permissions</code></dt>
|
||||
<dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd>
|
||||
</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>
|
||||
A storage volume will be either a file or a device node.
|
||||
The storage volume XML format is available <span class="since">since 0.4.1</span>
|
||||
</p>
|
||||
|
||||
<h3><a name="StorageVolFirst">General metadata</a></h3>
|
||||
|
||||
<pre>
|
||||
<volume type="file">
|
||||
<name>sparse.img</name>
|
||||
<key>/var/lib/xen/images/sparse.img</key>
|
||||
<allocation>0</allocation>
|
||||
<capacity unit="T">1</capacity>
|
||||
...</pre>
|
||||
|
||||
<dl>
|
||||
<dt><code>name</code></dt>
|
||||
<dd>Providing a name for the volume which is unique to the pool.
|
||||
This is mandatory when defining a volume. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>key</code></dt>
|
||||
<dd>Providing an identifier for the volume which is globally unique.
|
||||
This is optional when defining a volume, a key will be generated if
|
||||
omitted. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>allocation</code></dt>
|
||||
<dd>Providing the total storage allocation for the volume. This
|
||||
may be smaller than the logical capacity if the volume is sparsely
|
||||
allocated. It may also be larger than the logical capacity if the
|
||||
volume has substantial metadata overhead. This value is in bytes.
|
||||
If omitted when creating a volume, the volume will be fully
|
||||
allocated at time of creation. If set to a value smaller than the
|
||||
capacity, the pool has the <strong>option</strong> of deciding
|
||||
to sparsely allocate a volume. It does not have to honour requests
|
||||
for sparse allocation though. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>capacity</code></dt>
|
||||
<dd>Providing the logical capacity for the volume. This value is
|
||||
in bytes. This is compulsory when creating a volume.
|
||||
<span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>source</code></dt>
|
||||
<dd>Provides information about the underlying storage allocation
|
||||
of the volume. This may not be available for some pool types.
|
||||
<span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>target</code></dt>
|
||||
<dd>Provides information about the representation of the volume
|
||||
on the local host. <span class="since">Since 0.4.1</span></dd>
|
||||
</dl>
|
||||
|
||||
<h3><a name="StorageVolTarget">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>
|
||||
...
|
||||
<target>
|
||||
<path>/var/lib/virt/images/sparse.img</path>
|
||||
<permissions>
|
||||
<owner>0744</owner>
|
||||
<group>0744</group>
|
||||
<mode>0744</mode>
|
||||
<label>virt_image_t</label>
|
||||
</permissions>
|
||||
</target>
|
||||
</volume></pre>
|
||||
|
||||
<dl>
|
||||
<dt><code>path</code></dt>
|
||||
<dd>Provides the location at which the pool will be mapped into
|
||||
the local filesystem namespace. For a filesystem/directory based
|
||||
pool it will be the name of the directory in which volumes will
|
||||
be created. For device based pools it will be the name of the directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guaranteed stable across reboots, since they are allocated on
|
||||
demand. It is preferable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd>
|
||||
<dt><code>format</code></dt>
|
||||
<dd>Provides information about the pool specific volume format.
|
||||
For disk pools it will provide the partition type. For filesystem
|
||||
or directory pools it will provide the file format type, eg cow,
|
||||
qcow, vmdk, raw. If omitted when creating a volume, the pool's
|
||||
default format will be used. The actual format is specified via
|
||||
the <code>type</code>. Consult the pool-specific docs for the
|
||||
list of valid values. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>permissions</code></dt>
|
||||
<dd>Provides information about the default permissions to use
|
||||
when creating volumes. This is currently only useful for directory
|
||||
or filesystem based pools, where the volumes allocated are simple
|
||||
files. For pools where the volumes are device nodes, the hotplug
|
||||
scripts determine permissions. It contains 4 child elements. The
|
||||
<code>mode</code> element contains the octal permission set. The
|
||||
<code>owner</code> element contains the numeric user ID. The <code>group</code>
|
||||
element contains the numeric group ID. The <code>label</code> element
|
||||
contains the MAC (eg SELinux) label string.
|
||||
<span class="since">Since 0.4.1</span>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<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>
|
||||
<pool type="dir">
|
||||
<name>virtimages</name>
|
||||
<target>
|
||||
<path>/var/lib/virt/images</path>
|
||||
</target>
|
||||
</pool></pre>
|
||||
|
||||
<h3><a name="exampleISCSI">iSCSI based storage pool</a></h3>
|
||||
|
||||
<pre>
|
||||
<pool type="iscsi">
|
||||
<name>virtimages</name>
|
||||
<source>
|
||||
<host name="iscsi.example.com"/>
|
||||
<device path="demo-target"/>
|
||||
</source>
|
||||
<target>
|
||||
<path>/dev/disk/by-path</path>
|
||||
</target>
|
||||
</pool></pre>
|
||||
|
||||
<h3><a name="exampleVol">Storage volume</a></h3>
|
||||
|
||||
<pre>
|
||||
<volume type="file">
|
||||
<name>sparse.img</name>
|
||||
<allocation>0</allocation>
|
||||
<capacity unit="T">1</capacity>
|
||||
<target>
|
||||
<path>/var/lib/virt/images/sparse.img</path>
|
||||
<permissions>
|
||||
<owner>0744</owner>
|
||||
<group>0744</group>
|
||||
<mode>0744</mode>
|
||||
<label>virt_image_t</label>
|
||||
</permissions>
|
||||
</target>
|
||||
</volume></pre>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -348,3 +348,9 @@ head:first-child+body #projects dl {
|
||||
text-decoration: inherit;
|
||||
font-size: 1.2em;
|
||||
}
|
||||
|
||||
span.since {
|
||||
color: #3c857c;
|
||||
font-style: italic;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
@ -59,6 +59,54 @@
|
||||
</ul>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template name="toc">
|
||||
<ul>
|
||||
<xsl:for-each select="/html/body/h2[count(a) = 1]">
|
||||
<xsl:variable name="thishead" select="."/>
|
||||
<li>
|
||||
<a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
|
||||
<xsl:if test="count(./following-sibling::h3[preceding-sibling::h2[1] = $thishead and count(a) = 1]) > 0">
|
||||
<ul>
|
||||
<xsl:for-each select="./following-sibling::h3[preceding-sibling::h2[1] = $thishead and count(a) = 1]">
|
||||
<xsl:variable name="thissubhead" select="."/>
|
||||
<li>
|
||||
<a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
|
||||
<xsl:if test="count(./following-sibling::h4[preceding-sibling::h3[1] = $thissubhead and count(a) = 1]) > 0">
|
||||
<ul>
|
||||
<xsl:for-each select="./following-sibling::h4[preceding-sibling::h3[1] = $thissubhead and count(a) = 1]">
|
||||
<li>
|
||||
<a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
|
||||
<xsl:if test="count(./following-sibling::h5[preceding-sibling::h4[1] = $thissubhead and count(a) = 1]) > 0">
|
||||
<ul>
|
||||
<xsl:for-each select="./following-sibling::h5[preceding-sibling::h4[1] = $thissubhead and count(a) = 1]">
|
||||
<li>
|
||||
<a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
|
||||
<xsl:if test="count(./following-sibling::h6[preceding-sibling::h5[1] = $thissubhead and count(a) = 1]) > 0">
|
||||
<ul>
|
||||
<xsl:for-each select="./following-sibling::h6[preceding-sibling::h5[1] = $thissubhead and count(a) = 1]">
|
||||
<li>
|
||||
<a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>
|
||||
</li>
|
||||
</xsl:for-each>
|
||||
</ul>
|
||||
</xsl:if>
|
||||
</li>
|
||||
</xsl:for-each>
|
||||
</ul>
|
||||
</xsl:if>
|
||||
</li>
|
||||
</xsl:for-each>
|
||||
</ul>
|
||||
</xsl:if>
|
||||
</li>
|
||||
</xsl:for-each>
|
||||
</ul>
|
||||
</xsl:if>
|
||||
</li>
|
||||
</xsl:for-each>
|
||||
</ul>
|
||||
</xsl:template>
|
||||
|
||||
<!-- This is the master page structure -->
|
||||
<xsl:template match="/" mode="page">
|
||||
<xsl:param name="pagename"/>
|
||||
@ -93,7 +141,16 @@
|
||||
</xsl:apply-templates>
|
||||
</div>
|
||||
<div id="content">
|
||||
<xsl:copy-of select="html/body/*"/>
|
||||
<xsl:for-each select="html/body/*">
|
||||
<xsl:choose>
|
||||
<xsl:when test="name() = 'ul' and @id = 'toc'">
|
||||
<xsl:call-template name="toc"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:copy-of select="."/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:for-each>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footer">
|
||||
|
||||
Loading…
Reference in New Issue
Block a user