[Libvir] PATCH: 16/16: website documentation
Daniel P. Berrange
berrange at redhat.com
Tue Feb 12 04:42:10 UTC 2008
This patch adds a new 'storage.html' page to the website giving
examples of the XML format for each pool type, the XML format for
volumes, a description of all XML elements, and other storage pool
specific information.
libvir.html | 576 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
site.xsl | 3
2 files changed, 579 insertions(+)
diff -r 70e46e1711e1 docs/libvir.html
--- a/docs/libvir.html Fri Feb 08 10:04:07 2008 -0500
+++ b/docs/libvir.html Mon Feb 11 16:28:51 2008 -0500
@@ -3914,5 +3914,581 @@ first appeared in libvirt 0.2.0.
</tr>
</table>
+<h2><a name="Storage" id="Storage">Storage Management</a></h2>
+
+<p>
+This page describes the storage management capabilities in
+libvirt.
+</p>
+
+<ul>
+<li><a href="#StorageCore">Core concepts</a></li>
+<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>
+<li><a href="#StorageBackend">Storage backend drivers</a>
+ <ul>
+ <li><a href="#StorageBackendDir">Directory backend</a></li>
+ <li><a href="#StorageBackendFS">Local filesystem backend</a></li>
+ <li><a href="#StorageBackendNetFS">Network filesystem backend</a></li>
+ <li><a href="#StorageBackendLogical">Logical backend</a></li>
+ <li><a href="#StorageBackendDisk">Disk backend</a></li>
+ <li><a href="#StorageBackendISCSI">iSCSI backend</a></li>
+</ul>
+
+<h3><a name="StorageCore">Core concepts</a></h3>
+
+<p>
+The storage management APIs are based around 2 core concepts
+</p>
+
+<ol>
+<li><strong>Volume</strong> - a single storage volume which can
+be assigned to a guest, or used for creating further pools. A
+volume is either a block device, a raw file, or a special format
+file.</li>
+<li><strong>Pool</strong> - provides a means for taking a chunk
+of storage and carving it up into volumes. A pool can be used to
+manage things such as a physical disk, a NFS server, a iSCSI target,
+a host adapter, an LVM group.</li>
+</ol>
+
+<p>
+These two concepts are mapped through to two libvirt objects, a
+<code>virStorageVolPtr</code> and a <code>virStoragePoolPtr</code>,
+each with a collection of APIs for their management.
+</p>
+
+
+<h3><a name="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">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 volums
+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">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.</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">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 tbe directory in which
+devices nodes exist. For the latter <code>/dev/</code> may seem
+like the logical choice, however, devices nodes there are not
+guarenteed stable across reboots, since they are allocated on
+demand. It is preferrable 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">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 avilable 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">Storage volume XML</a></h3>
+
+<p>
+A storage volume will be either a file or a device node.
+</p>
+
+<h4><a name="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">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 tbe directory in which
+devices nodes exist. For the latter <code>/dev/</code> may seem
+like the logical choice, however, devices nodes there are not
+guarenteed stable across reboots, since they are allocated on
+demand. It is preferrable 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><a name="StorageBackend">Storage backend drivers</a></h3>
+
+<p>
+This section illustrates the capabilities / format for each of
+the different backend storage pool drivers
+</p>
+
+<h4><a name="StorageBackendDir">Directory pool</a></h4>
+
+<p>
+A pool with a type of <code>dir</code> provides the means to manage
+files within a directory. The files can be fully allocated raw files,
+sparsely allocated raw files, or one of the special disk formats
+such as <code>qcow</code>,<code>qcow2</code>,<code>vmdk</code>,
+<code>cow</code>, etc as supported by the <code>qemu-img</code>
+program. If the directory does not exist at the time the pool is
+defined, the <code>build</code> operation can be used to create it.
+</p>
+
+<h5>Example pool input definition</h5>
+
+<pre>
+<pool type="dir">
+ <name>virtimages</name>
+ <target>
+ <path>/var/lib/virt/images</path>
+ </target>
+</pool>
+</pre>
+
+<h5>Valid pool format types</h5>
+
+<p>
+The directory pool does not use the pool format type element.
+</p>
+
+<h5>Valid volume format types</h5>
+
+<p>
+One of the following options:
+</p>
+
+<ul>
+<li><code>raw</code>: a plain file</li>
+<li><code>bochs</code>: Bochs disk image format</li>
+<li><code>cloop</code>: compressed loopback disk image format</li>
+<li><code>cow</code>: User Mode Linux disk image format</li>
+<li><code>dmg</code>: Mac disk image format</li>
+<li><code>iso</code>: CDROM disk image format</li>
+<li><code>qcow</code>: QEMU v1 disk image format</li>
+<li><code>qcow2</code>: QEMU v2 disk image format</li>
+<li><code>vmdk</code>: VMWare disk image format</li>
+<li><code>vpc</code>: VirtualPC disk image format</li>
+</ul>
+
+<p>
+When listing existing volumes all these formats are supported
+natively. When creating new volumes, only a subset may be
+available. The <code>raw</code> type is guarenteed always
+available. The <code>qcow2</code> type can be created if
+either <code>qemu-img</code> or <code>qcow-create</code> tools
+are present. The others are dependant on support of the
+<code>qemu-img</code> tool.
+
+<h4><a name="StorageBackendFS">Filesystem pool</a></h4>
+
+<p>
+This is a variant of the directory pool. Instead of creating a
+directory on an existing mounted filesystem though, it expects
+a source block device to be named. This block device will be
+mounted and files managed in the directory of its mount point.
+It will default to allowing the kernel to automatically discover
+the filesystem type, though it can be specified manually if
+required.
+</p>
+
+<h5>Example pool input</h5>
+
+<pre>
+<pool type="fs">
+ <name>virtimages</name>
+ <source>
+ <device path="/dev/VolGroup00/VirtImages"/>
+ </source>
+ <target>
+ <path>/var/lib/virt/images</path>
+ </target>
+</pool>
+</pre>
+
+<h5>Valid pool format types</h5>
+
+<p>
+The fileystem pool supports the following formats:
+</p>
+
+<ul>
+<li><code>auto</code> - automatically determine format</li>
+<li><code>ext2</code></li>
+<li><code>ext3</code></li>
+<li><code>ext4</code></li>
+<li><code>ufs</code></li>
+<li><code>iso9660</code></li>
+<li><code>udf</code></li>
+<li><code>gfs</code></li>
+<li><code>gfs2</code></li>
+<li><code>vfat</code></li>
+<li><code>hfs+</code></li>
+<li><code>xfs</code></li>
+</ul>
+
+<h5>Valid volume format types</h5>
+
+<p>
+The valid volume types are the same as for the <code>directory</code>
+pool type.
+</p>
+
+<h4><a name="StorageBackendNetFS">Network filesystem pool</a></h4>
+
+<p>
+This is a variant of the filesystem pool. Instead of requiring
+a local block device as the source, it requires the name of a
+host and path of an exported directory. It will mount this network
+filesystem and manage files within the directory of its mount
+point. It will default to using NFS as the protocol.
+</p>
+
+<h5>Example pool input</h5>
+
+<pre>
+<pool type="netfs">
+ <name>virtimages</name>
+ <source>
+ <host name="nfs.example.com"/>
+ <dir path="/var/lib/virt/images"/>
+ </source>
+ <target>
+ <path>/var/lib/virt/images</path>
+ </target>
+</pool>
+</pre>
+
+<h5>Valid pool format types</h5>
+
+<p>
+The network fileystem pool supports the following formats:
+</p>
+
+<ul>
+<li><code>auto</code> - automatically determine format</li>
+<li><code>nfs</code></li>
+</ul>
+
+<h5>Valid volume format types</h5>
+
+<p>
+The valid volume types are the same as for the <code>directory</code>
+pool type.
+</p>
+
+<h4><a name="StorageBackendLogical">Logical volume pools</a></h4>
+
+<p>
+This provides a pool based on an LVM volume group. For a
+pre-defined LVM volume group, simply providing the group
+name is sufficient, while to build a new group requires
+providing a list of source devices to serve as physical
+volumes. Volumes will be allocated by carving out chunks
+of storage from the volume group.
+</p>
+
+<h5>Example pool input</h5>
+
+<pre>
+<pool type="logical">
+ <name>HostVG</name>
+ <source>
+ <device path="/dev/sda1"/>
+ <device path="/dev/sdb1"/>
+ <device path="/dev/sdc1"/>
+ </source>
+ <target>
+ <path>/dev/HostVG</path>
+ </target>
+</pool>
+</pre>
+
+<h5>Valid pool format types</h5>
+
+<p>
+The logical volume pool does not use the pool format type element.
+</p>
+
+<h5>Valid volume format types</h5>
+
+<p>
+The logical volume pool does not use the volume format type element.
+</p>
+
+
+<h4><a name="StorageBackendDisk">Disk volume pools</a></h4>
+
+<p>
+This provides a pool based on a physical disk. Volumes are created
+by adding partitions to the disk. Disk pools are have constraints
+on the size and placement of volumes. The 'free extents'
+information will detail the regions which are available for creating
+new volumes. A volume cannot span across 2 different free extents.
+</p>
+
+<h5>Example pool input</h5>
+
+<pre>
+<pool type="disk">
+ <name>sda</name>
+ <source>
+ <device path='/dev/sda'/>
+ </source>
+ <target>
+ <path>/dev</path>
+ </target>
+</pool>
+</pre>
+
+<h5>Valid pool format types</h5>
+
+<p>
+The disk volume pool accepts the following pool format types, representing
+the common partition table types:
+</p>
+
+<ul>
+<li><code>dos</code></li>
+<li><code>dvh</code></li>
+<li><code>gpt</code></li>
+<li><code>mac</code></li>
+<li><code>bsd</code></li>
+<li><code>pc98</code></li>
+<li><code>sun</code></li>
+</ul>
+
+<p>
+The <code>dos</code> or <code>gpt</code> formats are recommended for
+best portability - the latter is needed for disks larger than 2TB.
+</p>
+
+<h5>Valid volume format types</h5>
+
+<p>
+The disk volume pool accepts the following volume format types, representing
+the common partition entry types:
+</p>
+
+<ul>
+<li><code>none</code></li>
+<li><code>linux</code></li>
+<li><code>fat16</code></li>
+<li><code>fat32</code></li>
+<li><code>linux-swap</code></li>
+<li><code>linux-lvm</code></li>
+<li><code>linux-raid</code></li>
+<li><code>extended</code></li>
+</ul>
+
+
+<h4><a name="StorageBackendISCSI">iSCSI volume pools</a></h4>
+
+<p>
+This provides a pool based on an iSCSI target. Volumes must be
+pre-allocated on the iSCSI server, and cannot be created via
+the libvirt APIs. Since /dev/XXX names may change each time libvirt
+logs into the iSCSI target, it is recommended to configure the pool
+to use <code>/dev/disk/by-path</code> or <code>/dev/disk/by-id</code>
+for the target path. These provide persistent stable naming for LUNs
+</p>
+
+<h5>Example pool input</h5>
+
+<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>
+
+<h5>Valid pool format types</h5>
+
+<p>
+The logical volume pool does not use the pool format type element.
+</p>
+
+<h5>Valid volume format types</h5>
+
+<p>
+The logical volume pool does not use the volume format type element.
+</p>
+
+
+
</body>
</html>
diff -r 70e46e1711e1 docs/site.xsl
--- a/docs/site.xsl Fri Feb 08 10:04:07 2008 -0500
+++ b/docs/site.xsl Mon Feb 11 16:28:51 2008 -0500
@@ -65,6 +65,9 @@
</xsl:when>
<xsl:when test="$name = '#Windows'">
<xsl:text>windows.html</xsl:text>
+ </xsl:when>
+ <xsl:when test="$name = '#Storage'">
+ <xsl:text>storage.html</xsl:text>
</xsl:when>
<xsl:when test="$name = ''">
<xsl:text>unknown.html</xsl:text>
--
|=- Red Hat, Engineering, Emerging Technologies, Boston. +1 978 392 2496 -=|
|=- Perl modules: http://search.cpan.org/~danberr/ -=|
|=- Projects: http://freshmeat.net/~danielpb/ -=|
|=- GnuPG: 7D3B9505 F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 -=|
More information about the libvir-list
mailing list