</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.
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).
<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
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.
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.
</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.
</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
<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
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
<pre>
...
<bridge name="virbr0" />
- <forward type="nat"/>
+ <forward mode="nat" dev="eth0"/>
...</pre>
<dl>
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
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,
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
</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
</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
<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>
-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>
+ 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" 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>
- </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>
+ </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" 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>
+ </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>
- </h4>
+ </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>
+ 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>
+ 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>
- </h3>
+ </h2>
<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 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">
<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>
-
- <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>
+ <ul id="toc"></ul>
+ <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>
text-decoration: inherit;
font-size: 1.2em;
}
+
+span.since {
+ color: #3c857c;
+ font-style: italic;
+ font-weight: bold;
+}
</ul>\r
</xsl:template>\r
\r
+ <xsl:template name="toc">\r
+ <ul>\r
+ <xsl:for-each select="/html/body/h2[count(a) = 1]">\r
+ <xsl:variable name="thishead" select="."/>\r
+ <li>\r
+ <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>\r
+ <xsl:if test="count(./following-sibling::h3[preceding-sibling::h2[1] = $thishead and count(a) = 1]) > 0">\r
+ <ul>\r
+ <xsl:for-each select="./following-sibling::h3[preceding-sibling::h2[1] = $thishead and count(a) = 1]">\r
+ <xsl:variable name="thissubhead" select="."/>\r
+ <li>\r
+ <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>\r
+ <xsl:if test="count(./following-sibling::h4[preceding-sibling::h3[1] = $thissubhead and count(a) = 1]) > 0">\r
+ <ul>\r
+ <xsl:for-each select="./following-sibling::h4[preceding-sibling::h3[1] = $thissubhead and count(a) = 1]">\r
+ <li>\r
+ <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>\r
+ <xsl:if test="count(./following-sibling::h5[preceding-sibling::h4[1] = $thissubhead and count(a) = 1]) > 0">\r
+ <ul>\r
+ <xsl:for-each select="./following-sibling::h5[preceding-sibling::h4[1] = $thissubhead and count(a) = 1]">\r
+ <li>\r
+ <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>\r
+ <xsl:if test="count(./following-sibling::h6[preceding-sibling::h5[1] = $thissubhead and count(a) = 1]) > 0">\r
+ <ul>\r
+ <xsl:for-each select="./following-sibling::h6[preceding-sibling::h5[1] = $thissubhead and count(a) = 1]">\r
+ <li>\r
+ <a href="#{a/@name}"><xsl:value-of select="a/text()"/></a>\r
+ </li>\r
+ </xsl:for-each>\r
+ </ul>\r
+ </xsl:if>\r
+ </li>\r
+ </xsl:for-each>\r
+ </ul>\r
+ </xsl:if>\r
+ </li>\r
+ </xsl:for-each>\r
+ </ul>\r
+ </xsl:if>\r
+ </li>\r
+ </xsl:for-each>\r
+ </ul>\r
+ </xsl:if>\r
+ </li>\r
+ </xsl:for-each>\r
+ </ul>\r
+ </xsl:template>\r
+\r
<!-- This is the master page structure -->\r
<xsl:template match="/" mode="page">\r
<xsl:param name="pagename"/>\r
</xsl:apply-templates>\r
</div>\r
<div id="content">\r
- <xsl:copy-of select="html/body/*"/>\r
+ <xsl:for-each select="html/body/*">\r
+ <xsl:choose>\r
+ <xsl:when test="name() = 'ul' and @id = 'toc'">\r
+ <xsl:call-template name="toc"/>\r
+ </xsl:when>\r
+ <xsl:otherwise>\r
+ <xsl:copy-of select="."/>\r
+ </xsl:otherwise>\r
+ </xsl:choose>\r
+ </xsl:for-each>\r
</div>\r
</div>\r
<div id="footer">\r
projects / libvirt.git / commitdiff