[PATCH 04/15] docs: Convert 'storage' page to rst
Peter Krempa
pkrempa at redhat.com
Fri Apr 22 12:23:20 UTC 2022
From: Pavel Hrdina <phrdina at redhat.com>
Signed-off-by: Pavel Hrdina <phrdina at redhat.com>
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/meson.build | 2 +-
docs/storage.html.in | 833 -------------------------------------------
docs/storage.rst | 790 ++++++++++++++++++++++++++++++++++++++++
3 files changed, 791 insertions(+), 834 deletions(-)
delete mode 100644 docs/storage.html.in
create mode 100644 docs/storage.rst
diff --git a/docs/meson.build b/docs/meson.build
index eff3813cd6..a18def58a4 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -20,7 +20,6 @@ docs_assets = [
docs_html_in_files = [
'index',
'remote',
- 'storage',
'uri',
]
@@ -99,6 +98,7 @@ docs_rst_files = [
'programming-languages',
'python',
'securityprocess',
+ 'storage',
'strategy',
'styleguide',
'submitting-patches',
diff --git a/docs/storage.html.in b/docs/storage.html.in
deleted file mode 100644
index 8fb2cec9bd..0000000000
--- a/docs/storage.html.in
+++ /dev/null
@@ -1,833 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1 >Storage Management</h1>
- <p>
- Libvirt provides storage management on the physical host through
- storage pools and volumes.
- </p>
- <p>
- A storage pool is a quantity of storage set aside by an
- administrator, often a dedicated storage administrator, for use
- by virtual machines. Storage pools are divided into storage
- volumes either by the storage administrator or the system
- administrator, and the volumes are assigned to VMs as block
- devices.
- </p>
- <p>
- For example, the storage administrator responsible for an NFS
- server creates a share to store virtual machines' data. The
- system administrator defines a pool on the virtualization host
- with the details of the share
- (e.g. nfs.example.com:/path/to/share should be mounted on
- /vm_data). When the pool is started, libvirt mounts the share
- on the specified directory, just as if the system administrator
- logged in and executed 'mount nfs.example.com:/path/to/share
- /vmdata'. If the pool is configured to autostart, libvirt
- ensures that the NFS share is mounted on the directory specified
- when libvirt is started.
- </p>
- <p>
- Once the pool is started, the files in the NFS share are
- reported as volumes, and the storage volumes' paths may be
- queried using the libvirt APIs. The volumes' paths can then be
- copied into the section of a VM's XML definition describing the
- source storage for the VM's block devices. In the case of NFS,
- an application using the libvirt APIs can create and delete
- volumes in the pool (files in the NFS share) up to the limit of
- the size of the pool (the storage capacity of the share). Not
- all pool types support creating and deleting volumes. Stopping
- the pool (somewhat unfortunately referred to by virsh and the
- API as "pool-destroy") undoes the start operation, in this case,
- unmounting the NFS share. The data on the share is not modified
- by the destroy operation, despite the name. See man virsh for
- more details.
- </p>
- <p>
- A second example is an iSCSI pool. A storage administrator
- provisions an iSCSI target to present a set of LUNs to the host
- running the VMs. When libvirt is configured to manage that
- iSCSI target as a pool, libvirt will ensure that the host logs
- into the iSCSI target and libvirt can then report the available
- LUNs as storage volumes. The volumes' paths can be queried and
- used in VM's XML definitions as in the NFS example. In this
- case, the LUNs are defined on the iSCSI server, and libvirt
- cannot create and delete volumes.
- </p>
- <p>
- Storage pools and volumes are not required for the proper
- operation of VMs. Pools and volumes provide a way for libvirt
- to ensure that a particular piece of storage will be available
- for a VM, but some administrators will prefer to manage their
- own storage and VMs will operate properly without any pools or
- volumes defined. On systems that do not use pools, system
- administrators must ensure the availability of the VMs' storage
- using whatever tools they prefer, for example, adding the NFS
- share to the host's fstab so that the share is mounted at boot
- time.
- </p>
- <p>
- If at this point the value of pools and volumes over traditional
- system administration tools is unclear, note that one of the
- features of libvirt is its remote protocol, so it's possible to
- manage all aspects of a virtual machine's lifecycle as well as
- the configuration of the resources required by the VM. These
- operations can be performed on a remote host entirely within the
- libvirt API. In other words, a management application using
- libvirt can enable a user to perform all the required tasks for
- configuring the host for a VM: allocating resources, running the
- VM, shutting it down and deallocating the resources, without
- requiring shell access or any other control channel.
- </p>
- <p>
- Libvirt supports the following storage pool types:
- </p>
- <ul id="toc"></ul>
-
- <h2><a id="StorageBackendDir">Directory pool</a></h2>
- <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>qcow2</code>, <code>vmdk</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>
-
- <h3>Example directory pool input definition</h3>
- <pre>
-<pool type="dir">
- <name>virtimages</name>
- <target>
- <path>/var/lib/virt/images</path>
- </target>
-</pool></pre>
-
- <h3>Valid directory pool format types</h3>
- <p>
- The directory pool does not use the pool format type element.
- </p>
-
- <h3>Valid directory volume format types</h3>
- <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>qed</code>: QEMU Enhanced 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 guaranteed always
- available. The <code>qcow2</code> type can be created if
- the <code>qemu-img</code> tool is present. The others are
- dependent on support of the <code>qemu-img</code> tool.
-
- </p>
-
- <h2><a id="StorageBackendFS">Filesystem pool</a></h2>
- <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>
-
- <h3>Example filesystem pool input</h3>
- <pre>
-<pool type="fs">
- <name>virtimages</name>
- <source>
- <device path="/dev/VolGroup00/VirtImages"/>
- </source>
- <target>
- <path>/var/lib/virt/images</path>
- </target>
-</pool></pre>
-
- <h3>Valid filesystem pool format types</h3>
- <p>
- The filesystem 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>
- <li>
- <code>ocfs2</code>
- </li>
- <li>
- <code>vmfs</code>
- </li>
- </ul>
-
- <h3>Valid filesystem volume format types</h3>
- <p>
- The valid volume types are the same as for the <code>directory</code>
- pool type.
- </p>
-
-
- <h2><a id="StorageBackendNetFS">Network filesystem pool</a></h2>
- <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 <code>auto</code> as the
- protocol, which generally tries a mount via NFS first.
- </p>
-
- <h3>Example network filesystem pool input</h3>
- <pre>
-<pool type="netfs">
- <name>virtimages</name>
- <source>
- <host name="nfs.example.com"/>
- <dir path="/var/lib/virt/images"/>
- <format type='nfs'/>
- </source>
- <target>
- <path>/var/lib/virt/images</path>
- </target>
-</pool></pre>
-
- <h3>Valid network filesystem pool format types</h3>
- <p>
- The network filesystem pool supports the following formats:
- </p>
- <ul>
- <li><code>auto</code> - automatically determine format</li>
- <li>
- <code>nfs</code>
- </li>
- <li>
- <code>glusterfs</code> - use the glusterfs FUSE file system.
- For now, the <code>dir</code> specified as the source can only
- be a gluster volume name, as gluster does not provide a way to
- directly mount subdirectories within a volume. (To bypass the
- file system completely, see
- the <a href="#StorageBackendGluster">gluster</a> pool.)
- </li>
- <li>
- <code>cifs</code> - use the SMB (samba) or CIFS file system.
- The mount will use "-o guest" to mount the directory anonymously.
- </li>
- </ul>
-
- <h3>Valid network filesystem volume format types</h3>
- <p>
- The valid volume types are the same as for the <code>directory</code>
- pool type.
- </p>
-
-
- <h2><a id="StorageBackendLogical">Logical volume pool</a></h2>
- <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>
-
- <h3>Example logical pool input</h3>
- <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>
-
- <h3>Valid logical pool format types</h3>
- <p>
- The logical volume pool supports only the <code>lvm2</code> format,
- although not supplying a format value will result in automatic
- selection of the<code>lvm2</code> format.
- </p>
-
- <h3>Valid logical volume format types</h3>
- <p>
- The logical volume pool does not use the volume format type element.
- </p>
-
-
- <h2><a id="StorageBackendDisk">Disk pool</a></h2>
- <p>
- This provides a pool based on a physical disk. Volumes are created
- by adding partitions to the disk. Disk pools 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 two different free extents.
- It will default to using <code>dos</code> as the pool source format.
- </p>
-
- <h3>Example disk pool input</h3>
- <pre>
-<pool type="disk">
- <name>sda</name>
- <source>
- <device path='/dev/sda'/>
- </source>
- <target>
- <path>/dev</path>
- </target>
-</pool></pre>
-
- <h3>Valid disk pool format types</h3>
- <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>
- <li>
- <code>lvm2</code>
- </li>
- </ul>
- <p>
- The formats <code>dos</code> ("msdos" in parted terminology,
- good for BIOS systems) or <code>gpt</code> (good for UEFI
- systems) are recommended for best portability - the latter is
- needed for disks larger than 2TB. Note that the <code>lvm2</code>
- format refers to the physical volume format (i.e. the whole
- disk is a physical volume - not the usual usage of LVM where
- physical volumes are partitions). This is not really
- a partition table and such pool cannot be built by libvirt,
- only detected.
- </p>
- <p>
- Building a pool of a certain format depends on its availability
- in <code>parted</code>.
- </p>
-
- <h3>Valid disk volume format types</h3>
- <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>
-
-
- <h2><a id="StorageBackendISCSI">iSCSI pool</a></h2>
- <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>
- <p>
- The libvirt iSCSI storage backend does not resolve the provided
- host name or IP address when finding the available target IQN's
- on the host; therefore, defining two pools to use the same IQN
- on the same host will fail the duplicate source pool checks.
- </p>
-
- <h3>Example iSCSI pool input</h3>
- <pre>
-<pool type="iscsi">
- <name>virtimages</name>
- <source>
- <host name="iscsi.example.com"/>
- <device path="iqn.2013-06.com.example:iscsi-pool"/>
- </source>
- <target>
- <path>/dev/disk/by-path</path>
- </target>
-</pool></pre>
-
- <h3>Valid iSCSI pool format types</h3>
- <p>
- The iSCSI volume pool does not use the pool format type element.
- </p>
-
- <h3>Valid iSCSI volume format types</h3>
- <p>
- The iSCSI volume pool does not use the volume format type element.
- </p>
-
- <h2><a id="StorageBackendISCSIDirect">iSCSI direct pool</a></h2>
- <p>
- This is a variant of the iSCSI pool. Instead of using iscsiadm, it uses
- libiscsi.
- It requires a host, a path which is the target IQN, and an initiator IQN.
- </p>
-
- <h3>Example iSCSI direct pool input</h3>
- <pre>
-<pool type="iscsi-direct">
- <name>virtimages</name>
- <source>
- <host name="iscsi.example.com"/>
- <device path="iqn.2013-06.com.example:iscsi-pool"/>
- <initiator>
- <iqn name="iqn.2013-06.com.example:iscsi-initiator"/>
- </initiator>
- </source>
-</pool></pre>
-
- <h3>Valid iSCSI direct pool format types</h3>
- <p>
- The iSCSI direct volume pool does not use the pool format type element.
- </p>
-
- <h3>Valid iSCSI direct volume format types</h3>
- <p>
- The iSCSI direct volume pool does not use the volume format type element.
- </p>
-
- <h2><a id="StorageBackendSCSI">SCSI pool</a></h2>
- <p>
- This provides a pool based on a SCSI HBA. Volumes are preexisting SCSI
- LUNs, and cannot be created via the libvirt APIs. Since /dev/XXX names
- aren't generally stable, 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
- <span class="since">Since 0.6.2</span>
- </p>
-
- <h3>Example SCSI pool input</h3>
- <pre>
-<pool type="scsi">
- <name>virtimages</name>
- <source>
- <adapter name="host0"/>
- </source>
- <target>
- <path>/dev/disk/by-path</path>
- </target>
-</pool></pre>
-
- <h3>Valid SCSI pool format types</h3>
- <p>
- The SCSI volume pool does not use the pool format type element.
- </p>
-
- <h3>Valid SCSI volume format types</h3>
- <p>
- The SCSI volume pool does not use the volume format type element.
- </p>
-
- <h2><a id="StorageBackendMultipath">Multipath pool</a></h2>
- <p>
- This provides a pool that contains all the multipath devices on the
- host. Therefore, only one Multipath pool may be configured per host.
- Volume creating is not supported via the libvirt APIs.
- The target element is actually ignored, but one is required to appease
- the libvirt XML parser.<br/>
- <br/>
- Configuring multipathing is not currently supported, this just covers
- the case where users want to discover all the available multipath
- devices, and assign them to guests.
- <span class="since">Since 0.7.1</span>
- </p>
-
- <h3>Example multipath pool input</h3>
- <pre>
-<pool type="mpath">
- <name>virtimages</name>
- <target>
- <path>/dev/mapper</path>
- </target>
-</pool></pre>
-
- <h3>Valid multipath pool format types</h3>
- <p>
- The Multipath volume pool does not use the pool format type element.
- </p>
-
- <h3>Valid multipath volume format types</h3>
- <p>
- The Multipath volume pool does not use the volume format type element.
- </p>
-
- <h2><a id="StorageBackendRBD">RBD pool</a></h2>
- <p>
- This storage driver provides a pool which contains all RBD
- images in a RADOS pool. RBD (RADOS Block Device) is part
- of the Ceph distributed storage project.<br/>
- This backend <i>only</i> supports QEMU with RBD support. Kernel RBD
- which exposes RBD devices as block devices in /dev is <i>not</i>
- supported. RBD images created with this storage backend
- can be accessed through kernel RBD if configured manually, but
- this backend does not provide mapping for these images.<br/>
- Images created with this backend can be attached to QEMU guests
- when QEMU is build with RBD support (Since QEMU 0.14.0). The
- backend supports cephx authentication for communication with the
- Ceph cluster. Storing the cephx authentication key is done with
- the libvirt secret mechanism. The UUID in the example pool input
- refers to the UUID of the stored secret.<br />
- The port attribute for a Ceph monitor does not have to be provided.
- If not provided librados will use the default Ceph monitor port.
- <span class="since">Since 0.9.13</span>
- </p>
-
- <h3>Example RBD pool input</h3>
- <pre>
-<pool type="rbd">
- <name>myrbdpool</name>
- <source>
- <name>rbdpool</name>
- <host name='1.2.3.4'/>
- <host name='my.ceph.monitor'/>
- <host name='third.ceph.monitor' port='6789'/>
- <auth username='admin' type='ceph'>
- <secret uuid='2ec115d7-3a88-3ceb-bc12-0ac909a6fd87'/>
- </auth>
- </source>
-</pool></pre>
-
- <h3>Example RBD volume output</h3>
- <pre>
-<volume>
- <name>myvol</name>
- <key>rbd/myvol</key>
- <source>
- </source>
- <capacity unit='bytes'>53687091200</capacity>
- <allocation unit='bytes'>53687091200</allocation>
- <target>
- <path>rbd:rbd/myvol</path>
- <format type='unknown'/>
- <permissions>
- <mode>00</mode>
- <owner>0</owner>
- <group>0</group>
- </permissions>
- </target>
-</volume></pre>
-
- <h3>Example RBD disk attachment</h3>
- <p>RBD images can be attached to QEMU guests when QEMU is built
- with RBD support. Information about attaching a RBD image to a
- guest can be found
- at <a href="formatdomain.html#elementsDisks">format domain</a>
- page.</p>
-
- <h3>Valid RBD pool format types</h3>
- <p>
- The RBD pool does not use the pool format type element.
- </p>
-
- <h3>Valid RBD volume format types</h3>
- <p>
- Only raw volumes are supported.
- </p>
-
- <h2><a id="StorageBackendSheepdog">Sheepdog pool</a></h2>
- <p>
- This provides a pool based on a Sheepdog Cluster.
- Sheepdog is a distributed storage system for QEMU/KVM.
- It provides highly available block level storage volumes that
- can be attached to QEMU/KVM virtual machines.
-
- The cluster must already be formatted.
-
- <span class="since">Since 0.9.13</span>
- </p>
-
- <h3>Example Sheepdog pool input</h3>
- <pre>
-<pool type="sheepdog">
- <name>mysheeppool</name>
- <source>
- <name>mysheeppool</name>
- <host name='localhost' port='7000'/>
- </source>
-</pool></pre>
-
- <h3>Example Sheepdog volume output</h3>
- <pre>
-<volume>
- <name>myvol</name>
- <key>sheep/myvol</key>
- <source>
- </source>
- <capacity unit='bytes'>53687091200</capacity>
- <allocation unit='bytes'>53687091200</allocation>
- <target>
- <path>sheepdog:myvol</path>
- <format type='unknown'/>
- <permissions>
- <mode>00</mode>
- <owner>0</owner>
- <group>0</group>
- </permissions>
- </target>
-</volume></pre>
-
- <h3>Example Sheepdog disk attachment</h3>
- <p>Sheepdog images can be attached to QEMU guests.
- Information about attaching a Sheepdog image to a
- guest can be found
- at the <a href="formatdomain.html#elementsDisks">format domain</a>
- page.</p>
-
- <h3>Valid Sheepdog pool format types</h3>
- <p>
- The Sheepdog pool does not use the pool format type element.
- </p>
-
- <h3>Valid Sheepdog volume format types</h3>
- <p>
- The Sheepdog pool does not use the volume format type element.
- </p>
-
- <h2><a id="StorageBackendGluster">Gluster pool</a></h2>
- <p>
- This provides a pool based on native Gluster access. Gluster is
- a distributed file system that can be exposed to the user via
- FUSE, NFS or SMB (see the <a href="#StorageBackendNetfs">netfs</a>
- pool for that usage); but for minimal overhead, the ideal access
- is via native access (only possible for QEMU/KVM compiled with
- libgfapi support).
-
- The cluster and storage volume must already be running, and it
- is recommended that the volume be configured with <code>gluster
- volume set $volname storage.owner-uid=$uid</code>
- and <code>gluster volume set $volname
- storage.owner-gid=$gid</code> for the uid and gid that qemu will
- be run as. It may also be necessary to
- set <code>rpc-auth-allow-insecure on</code> for the glusterd
- service, as well as <code>gluster set $volname
- server.allow-insecure on</code>, to allow access to the gluster
- volume.
-
- <span class="since">Since 1.2.0</span>
- </p>
-
- <h3>Example Gluster pool input</h3>
- <p>A gluster volume corresponds to a libvirt storage pool. If a
- gluster volume could be mounted as <code>mount -t glusterfs
- localhost:/volname /some/path</code>, then the following example
- will describe the same pool without having to create a local
- mount point. Remember that with gluster, the mount point can be
- through any machine in the cluster, and gluster will
- automatically pick the ideal transport to the actual bricks
- backing the gluster volume, even if on a different host than the
- one named in the <code>host</code> designation.
- The <code><name></code> element is always the volume name
- (no slash). The pool source also supports an
- optional <code><dir></code> element with
- a <code>path</code> attribute that lists the absolute name of a
- subdirectory relative to the gluster volume to use instead of
- the top-level directory of the volume.</p>
- <pre>
-<pool type="gluster">
- <name>myglusterpool</name>
- <source>
- <name>volname</name>
- <host name='localhost'/>
- <dir path='/'/>
- </source>
-</pool></pre>
-
- <h3>Example Gluster volume output</h3>
- <p>Libvirt storage volumes associated with a gluster pool
- correspond to the files that can be found when mounting the
- gluster volume. The <code>name</code> is the path relative to
- the effective mount specified for the pool; and
- the <code>key</code> is a string that identifies a single volume
- uniquely. Currently the <code>key</code> attribute consists of the
- URI of the volume but it may be changed to a UUID of the volume
- in the future.</p>
- <pre>
-<volume>
- <name>myfile</name>
- <key>gluster://localhost/volname/myfile</key>
- <source>
- </source>
- <capacity unit='bytes'>53687091200</capacity>
- <allocation unit='bytes'>53687091200</allocation>
-</volume></pre>
-
- <h3>Example Gluster disk attachment</h3>
- <p>Files within a gluster volume can be attached to QEMU guests.
- Information about attaching a Gluster image to a
- guest can be found
- at the <a href="formatdomain.html#elementsDisks">format domain</a>
- page.</p>
-
- <h3>Valid Gluster pool format types</h3>
- <p>
- The Gluster pool does not use the pool format type element.
- </p>
-
- <h3>Valid Gluster volume format types</h3>
- <p>
- The valid volume types are the same as for the <code>directory</code>
- pool type.
- </p>
-
- <h2><a id="StorageBackendZFS">ZFS pool</a></h2>
- <p>
- This provides a pool based on the ZFS filesystem. Initially it was developed
- for FreeBSD, and <span class="since">since 1.3.2</span> experimental support
- for <a href="https://zfsonlinux.org/">ZFS on Linux</a> version 0.6.4 or newer
- is available.
- </p>
-
- <p>A pool could either be created manually using the <code>zpool create</code>
- command and its name specified in the source section or <span class="since">
- since 1.2.9</span> source devices could be specified to create a pool using
- libvirt.
- </p>
-
- <p>Please refer to the ZFS documentation for details on a pool creation.</p>
-
- <p><span class="since">Since 1.2.8</span></p>.
-
- <h3>Example ZFS pool input</h3>
- <pre>
-<pool type="zfs">
- <name>myzfspool</name>
- <source>
- <name>zpoolname</name>
- <device path="/dev/ada1"/>
- <device path="/dev/ada2"/>
- </source>
-</pool></pre>
-
- <h3>Valid ZFS pool format types</h3>
- <p>
- The ZFS volume pool does not use the pool format type element.
- </p>
-
- <h3>Valid ZFS volume format types</h3>
- <p>
- The ZFS volume pool does not use the volume format type element.
- </p>
- <h2><a id="StorageBackendVstorage">Vstorage pool</a></h2>
- <p>
- This provides a pool based on Virtuozzo storage. Virtuozzo Storage is
- a highly available distributed software-defined storage with built-in
- replication and disaster recovery. More detailed information about
- Virtuozzo storage and its management can be found here:
-
- <a href="https://openvz.org/Virtuozzo_Storage">Virtuozzo Storage</a>).
- </p>
- <p>Please refer to the Virtuozzo Storage documentation for details
- on storage management and usage.</p>
- <h3>Example vstorage pool input</h3>
- <p>In order to create storage pool with Virtuozzo Storage backend you
- have to provide cluster name and be authorized within the cluster.</p>
- <pre>
-<pool type="vstorage">
- <name>myvstoragepool</name>
- <source>
- <name>clustername</name>
- </source>
- <target>
- <path>/mnt/clustername</path>
- </target>
-</pool></pre>
-
- <h3>Valid vstorage pool format types</h3>
- <p>
- The Vstorage volume pool does not use the pool format type element.
- </p>
-
- <h3>Valid vstorage volume format types</h3>
- <p>The valid volume types are the same as for the directory pool.</p>
- </body>
-</html>
diff --git a/docs/storage.rst b/docs/storage.rst
new file mode 100644
index 0000000000..b860648628
--- /dev/null
+++ b/docs/storage.rst
@@ -0,0 +1,790 @@
+.. role:: since
+
+==================
+Storage Management
+==================
+
+Libvirt provides storage management on the physical host through storage pools
+and volumes.
+
+A storage pool is a quantity of storage set aside by an administrator, often a
+dedicated storage administrator, for use by virtual machines. Storage pools are
+divided into storage volumes either by the storage administrator or the system
+administrator, and the volumes are assigned to VMs as block devices.
+
+For example, the storage administrator responsible for an NFS server creates a
+share to store virtual machines' data. The system administrator defines a pool
+on the virtualization host with the details of the share (e.g.
+nfs.example.com:/path/to/share should be mounted on /vm_data). When the pool is
+started, libvirt mounts the share on the specified directory, just as if the
+system administrator logged in and executed 'mount
+nfs.example.com:/path/to/share /vmdata'. If the pool is configured to autostart,
+libvirt ensures that the NFS share is mounted on the directory specified when
+libvirt is started.
+
+Once the pool is started, the files in the NFS share are reported as volumes,
+and the storage volumes' paths may be queried using the libvirt APIs. The
+volumes' paths can then be copied into the section of a VM's XML definition
+describing the source storage for the VM's block devices. In the case of NFS, an
+application using the libvirt APIs can create and delete volumes in the pool
+(files in the NFS share) up to the limit of the size of the pool (the storage
+capacity of the share). Not all pool types support creating and deleting
+volumes. Stopping the pool (somewhat unfortunately referred to by virsh and the
+API as "pool-destroy") undoes the start operation, in this case, unmounting the
+NFS share. The data on the share is not modified by the destroy operation,
+despite the name. See man virsh for more details.
+
+A second example is an iSCSI pool. A storage administrator provisions an iSCSI
+target to present a set of LUNs to the host running the VMs. When libvirt is
+configured to manage that iSCSI target as a pool, libvirt will ensure that the
+host logs into the iSCSI target and libvirt can then report the available LUNs
+as storage volumes. The volumes' paths can be queried and used in VM's XML
+definitions as in the NFS example. In this case, the LUNs are defined on the
+iSCSI server, and libvirt cannot create and delete volumes.
+
+Storage pools and volumes are not required for the proper operation of VMs.
+Pools and volumes provide a way for libvirt to ensure that a particular piece of
+storage will be available for a VM, but some administrators will prefer to
+manage their own storage and VMs will operate properly without any pools or
+volumes defined. On systems that do not use pools, system administrators must
+ensure the availability of the VMs' storage using whatever tools they prefer,
+for example, adding the NFS share to the host's fstab so that the share is
+mounted at boot time.
+
+If at this point the value of pools and volumes over traditional system
+administration tools is unclear, note that one of the features of libvirt is its
+remote protocol, so it's possible to manage all aspects of a virtual machine's
+lifecycle as well as the configuration of the resources required by the VM.
+These operations can be performed on a remote host entirely within the libvirt
+API. In other words, a management application using libvirt can enable a user to
+perform all the required tasks for configuring the host for a VM: allocating
+resources, running the VM, shutting it down and deallocating the resources,
+without requiring shell access or any other control channel.
+
+Libvirt supports the following storage pool types:
+
+.. contents::
+
+Directory pool
+--------------
+
+A pool with a type of ``dir`` 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 ``qcow2``, ``vmdk``, etc as
+supported by the ``qemu-img`` program. If the directory does not exist at the
+time the pool is defined, the ``build`` operation can be used to create it.
+
+Example directory pool input definition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="dir">
+ <name>virtimages</name>
+ <target>
+ <path>/var/lib/virt/images</path>
+ </target>
+ </pool>
+
+Valid directory pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The directory pool does not use the pool format type element.
+
+Valid directory volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of the following options:
+
+- ``raw``: a plain file
+
+- ``bochs``: Bochs disk image format
+
+- ``cloop``: compressed loopback disk image format
+
+- ``cow``: User Mode Linux disk image format
+
+- ``dmg``: Mac disk image format
+
+- ``iso``: CDROM disk image format
+
+- ``qcow``: QEMU v1 disk image format
+
+- ``qcow2``: QEMU v2 disk image format
+
+- ``qed``: QEMU Enhanced Disk image format
+
+- ``vmdk``: VMware disk image format
+
+- ``vpc``: VirtualPC disk image format
+
+When listing existing volumes all these formats are supported natively. When
+creating new volumes, only a subset may be available. The ``raw`` type is
+guaranteed always available. The ``qcow2`` type can be created if the
+``qemu-img`` tool is present. The others are dependent on support of the
+``qemu-img`` tool.
+
+Filesystem pool
+---------------
+
+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.
+
+Example filesystem pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="fs">
+ <name>virtimages</name>
+ <source>
+ <device path="/dev/VolGroup00/VirtImages"/>
+ </source>
+ <target>
+ <path>/var/lib/virt/images</path>
+ </target>
+ </pool>
+
+Valid filesystem pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The filesystem pool supports the following formats:
+
+- ``auto`` - automatically determine format
+
+- ``ext2``
+
+- ``ext3``
+
+- ``ext4``
+
+- ``ufs``
+
+- ``iso9660``
+
+- ``udf``
+
+- ``gfs``
+
+- ``gfs2``
+
+- ``vfat``
+
+- ``hfs+``
+
+- ``xfs``
+
+- ``ocfs2``
+
+- ``vmfs``
+
+Valid filesystem volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The valid volume types are the same as for the ``directory`` pool type.
+
+Network filesystem pool
+-----------------------
+
+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 ``auto`` as the protocol,
+which generally tries a mount via NFS first.
+
+Example network filesystem pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="netfs">
+ <name>virtimages</name>
+ <source>
+ <host name="nfs.example.com"/>
+ <dir path="/var/lib/virt/images"/>
+ <format type='nfs'/>
+ </source>
+ <target>
+ <path>/var/lib/virt/images</path>
+ </target>
+ </pool>
+
+Valid network filesystem pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The network filesystem pool supports the following formats:
+
+- ``auto`` - automatically determine format
+
+- ``nfs``
+
+- ``glusterfs`` - use the glusterfs FUSE file system. For now, the ``dir``
+ specified as the source can only be a gluster volume name, as gluster does
+ not provide a way to directly mount subdirectories within a volume. (To
+ bypass the file system completely, see the `Gluster pool`_).
+
+- ``cifs`` - use the SMB (samba) or CIFS file system. The mount will use "-o
+ guest" to mount the directory anonymously.
+
+Valid network filesystem volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The valid volume types are the same as for the ``directory`` pool type.
+
+Logical volume pool
+-------------------
+
+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.
+
+Example logical pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <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>
+
+Valid logical pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The logical volume pool supports only the ``lvm2`` format, although not
+supplying a format value will result in automatic selection of the\ ``lvm2``
+format.
+
+Valid logical volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The logical volume pool does not use the volume format type element.
+
+Disk pool
+---------
+
+This provides a pool based on a physical disk. Volumes are created by adding
+partitions to the disk. Disk pools 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 two different
+free extents. It will default to using ``dos`` as the pool source format.
+
+Example disk pool input
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="disk">
+ <name>sda</name>
+ <source>
+ <device path='/dev/sda'/>
+ </source>
+ <target>
+ <path>/dev</path>
+ </target>
+ </pool>
+
+Valid disk pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The disk volume pool accepts the following pool format types, representing the
+common partition table types:
+
+- ``dos``
+
+- ``dvh``
+
+- ``gpt``
+
+- ``mac``
+
+- ``bsd``
+
+- ``pc98``
+
+- ``sun``
+
+- ``lvm2``
+
+The formats ``dos`` ("msdos" in parted terminology, good for BIOS systems) or
+``gpt`` (good for UEFI systems) are recommended for best portability - the
+latter is needed for disks larger than 2TB. Note that the ``lvm2`` format refers
+to the physical volume format (i.e. the whole disk is a physical volume - not
+the usual usage of LVM where physical volumes are partitions). This is not
+really a partition table and such pool cannot be built by libvirt, only
+detected.
+
+Building a pool of a certain format depends on its availability in ``parted``.
+
+Valid disk volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The disk volume pool accepts the following volume format types, representing the
+common partition entry types:
+
+- ``none``
+
+- ``linux``
+
+- ``fat16``
+
+- ``fat32``
+
+- ``linux-swap``
+
+- ``linux-lvm``
+
+- ``linux-raid``
+
+- ``extended``
+
+iSCSI pool
+----------
+
+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 ``/dev/disk/by-path`` or ``/dev/disk/by-id`` for
+the target path. These provide persistent stable naming for LUNs
+
+The libvirt iSCSI storage backend does not resolve the provided host name or IP
+address when finding the available target IQN's on the host; therefore, defining
+two pools to use the same IQN on the same host will fail the duplicate source
+pool checks.
+
+Example iSCSI pool input
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="iscsi">
+ <name>virtimages</name>
+ <source>
+ <host name="iscsi.example.com"/>
+ <device path="iqn.2013-06.com.example:iscsi-pool"/>
+ </source>
+ <target>
+ <path>/dev/disk/by-path</path>
+ </target>
+ </pool>
+
+Valid iSCSI pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The iSCSI volume pool does not use the pool format type element.
+
+Valid iSCSI volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The iSCSI volume pool does not use the volume format type element.
+
+iSCSI direct pool
+-----------------
+
+This is a variant of the iSCSI pool. Instead of using iscsiadm, it uses
+libiscsi. It requires a host, a path which is the target IQN, and an initiator
+IQN.
+
+Example iSCSI direct pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="iscsi-direct">
+ <name>virtimages</name>
+ <source>
+ <host name="iscsi.example.com"/>
+ <device path="iqn.2013-06.com.example:iscsi-pool"/>
+ <initiator>
+ <iqn name="iqn.2013-06.com.example:iscsi-initiator"/>
+ </initiator>
+ </source>
+ </pool>
+
+Valid iSCSI direct pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The iSCSI direct volume pool does not use the pool format type element.
+
+Valid iSCSI direct volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The iSCSI direct volume pool does not use the volume format type element.
+
+SCSI pool
+---------
+
+This provides a pool based on a SCSI HBA. Volumes are preexisting SCSI LUNs, and
+cannot be created via the libvirt APIs. Since /dev/XXX names aren't generally
+stable, it is recommended to configure the pool to use ``/dev/disk/by-path`` or
+``/dev/disk/by-id`` for the target path. These provide persistent stable naming
+for LUNs :since:`Since 0.6.2`
+
+Example SCSI pool input
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="scsi">
+ <name>virtimages</name>
+ <source>
+ <adapter name="host0"/>
+ </source>
+ <target>
+ <path>/dev/disk/by-path</path>
+ </target>
+ </pool>
+
+Valid SCSI pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SCSI volume pool does not use the pool format type element.
+
+Valid SCSI volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SCSI volume pool does not use the volume format type element.
+
+Multipath pool
+--------------
+
+This provides a pool that contains all the multipath devices on the host.
+Therefore, only one Multipath pool may be configured per host. Volume creating
+is not supported via the libvirt APIs. The target element is actually ignored,
+but one is required to appease the libvirt XML parser.
+
+Configuring multipathing is not currently supported, this just covers the case
+where users want to discover all the available multipath devices, and assign
+them to guests. :since:`Since 0.7.1`
+
+Example multipath pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="mpath">
+ <name>virtimages</name>
+ <target>
+ <path>/dev/mapper</path>
+ </target>
+ </pool>
+
+Valid multipath pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Multipath volume pool does not use the pool format type element.
+
+Valid multipath volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Multipath volume pool does not use the volume format type element.
+
+RBD pool
+--------
+
+This storage driver provides a pool which contains all RBD images in a RADOS
+pool. RBD (RADOS Block Device) is part of the Ceph distributed storage project.
+
+This backend *only* supports QEMU with RBD support. Kernel RBD which exposes RBD
+devices as block devices in /dev is *not* supported. RBD images created with
+this storage backend can be accessed through kernel RBD if configured manually,
+but this backend does not provide mapping for these images.
+
+Images created with this backend can be attached to QEMU guests when QEMU is
+build with RBD support (Since QEMU 0.14.0). The backend supports cephx
+authentication for communication with the Ceph cluster. Storing the cephx
+authentication key is done with the libvirt secret mechanism. The UUID in the
+example pool input refers to the UUID of the stored secret.
+
+The port attribute for a Ceph monitor does not have to be provided. If not
+provided librados will use the default Ceph monitor port. :since:`Since 0.9.13`
+
+Example RBD pool input
+~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="rbd">
+ <name>myrbdpool</name>
+ <source>
+ <name>rbdpool</name>
+ <host name='1.2.3.4'/>
+ <host name='my.ceph.monitor'/>
+ <host name='third.ceph.monitor' port='6789'/>
+ <auth username='admin' type='ceph'>
+ <secret uuid='2ec115d7-3a88-3ceb-bc12-0ac909a6fd87'/>
+ </auth>
+ </source>
+ </pool>
+
+Example RBD volume output
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <volume>
+ <name>myvol</name>
+ <key>rbd/myvol</key>
+ <source>
+ </source>
+ <capacity unit='bytes'>53687091200</capacity>
+ <allocation unit='bytes'>53687091200</allocation>
+ <target>
+ <path>rbd:rbd/myvol</path>
+ <format type='unknown'/>
+ <permissions>
+ <mode>00</mode>
+ <owner>0</owner>
+ <group>0</group>
+ </permissions>
+ </target>
+ </volume>
+
+Example RBD disk attachment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+RBD images can be attached to QEMU guests when QEMU is built with RBD support.
+Information about attaching a RBD image to a guest can be found at `format
+domain <formatdomain.html#elementsDisks>`__ page.
+
+Valid RBD pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The RBD pool does not use the pool format type element.
+
+Valid RBD volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Only raw volumes are supported.
+
+Sheepdog pool
+-------------
+
+This provides a pool based on a Sheepdog Cluster. Sheepdog is a distributed
+storage system for QEMU/KVM. It provides highly available block level storage
+volumes that can be attached to QEMU/KVM virtual machines. The cluster must
+already be formatted. :since:`Since 0.9.13`
+
+Example Sheepdog pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="sheepdog">
+ <name>mysheeppool</name>
+ <source>
+ <name>mysheeppool</name>
+ <host name='localhost' port='7000'/>
+ </source>
+ </pool>
+
+Example Sheepdog volume output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <volume>
+ <name>myvol</name>
+ <key>sheep/myvol</key>
+ <source>
+ </source>
+ <capacity unit='bytes'>53687091200</capacity>
+ <allocation unit='bytes'>53687091200</allocation>
+ <target>
+ <path>sheepdog:myvol</path>
+ <format type='unknown'/>
+ <permissions>
+ <mode>00</mode>
+ <owner>0</owner>
+ <group>0</group>
+ </permissions>
+ </target>
+ </volume>
+
+Example Sheepdog disk attachment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sheepdog images can be attached to QEMU guests. Information about attaching a
+Sheepdog image to a guest can be found at the `format
+domain <formatdomain.html#elementsDisks>`__ page.
+
+Valid Sheepdog pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Sheepdog pool does not use the pool format type element.
+
+Valid Sheepdog volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Sheepdog pool does not use the volume format type element.
+
+Gluster pool
+------------
+
+This provides a pool based on native Gluster access. Gluster is a distributed
+file system that can be exposed to the user via FUSE, NFS or SMB (see the
+`Network filesystem pool`_ for that usage); but for minimal overhead,
+the ideal access is via native access (only possible for QEMU/KVM compiled with
+libgfapi support). The cluster and storage volume must already be running, and
+it is recommended that the volume be configured with
+``gluster volume set $volname storage.owner-uid=$uid`` and
+``gluster volume set $volname storage.owner-gid=$gid`` for the uid and gid
+that qemu will be run as. It may also be necessary to set
+``rpc-auth-allow-insecure on`` for the glusterd service, as well as
+``gluster set $volname server.allow-insecure on``, to allow access to the
+gluster volume. :since:`Since 1.2.0`
+
+Example Gluster pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A gluster volume corresponds to a libvirt storage pool. If a gluster volume
+could be mounted as ``mount -t glusterfs localhost:/volname /some/path``,
+then the following example will describe the same pool without having to create
+a local mount point. Remember that with gluster, the mount point can be through
+any machine in the cluster, and gluster will automatically pick the ideal
+transport to the actual bricks backing the gluster volume, even if on a
+different host than the one named in the ``host`` designation. The ``<name>``
+element is always the volume name (no slash). The pool source also supports an
+optional ``<dir>`` element with a ``path`` attribute that lists the absolute
+name of a subdirectory relative to the gluster volume to use instead of the
+top-level directory of the volume.
+
+::
+
+ <pool type="gluster">
+ <name>myglusterpool</name>
+ <source>
+ <name>volname</name>
+ <host name='localhost'/>
+ <dir path='/'/>
+ </source>
+ </pool>
+
+Example Gluster volume output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Libvirt storage volumes associated with a gluster pool correspond to the files
+that can be found when mounting the gluster volume. The ``name`` is the path
+relative to the effective mount specified for the pool; and the ``key`` is a
+string that identifies a single volume uniquely. Currently the ``key`` attribute
+consists of the URI of the volume but it may be changed to a UUID of the volume
+in the future.
+
+::
+
+ <volume>
+ <name>myfile</name>
+ <key>gluster://localhost/volname/myfile</key>
+ <source>
+ </source>
+ <capacity unit='bytes'>53687091200</capacity>
+ <allocation unit='bytes'>53687091200</allocation>
+ </volume>
+
+Example Gluster disk attachment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files within a gluster volume can be attached to QEMU guests. Information about
+attaching a Gluster image to a guest can be found at the `format
+domain <formatdomain.html#elementsDisks>`__ page.
+
+Valid Gluster pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Gluster pool does not use the pool format type element.
+
+Valid Gluster volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The valid volume types are the same as for the ``directory`` pool type.
+
+ZFS pool
+--------
+
+This provides a pool based on the ZFS filesystem. Initially it was developed for
+FreeBSD, and :since:`since 1.3.2` experimental support for `ZFS on
+Linux <https://zfsonlinux.org/>`__ version 0.6.4 or newer is available.
+
+A pool could either be created manually using the ``zpool create`` command and
+its name specified in the source section or :since:` since 1.2.9` source devices
+could be specified to create a pool using libvirt.
+
+Please refer to the ZFS documentation for details on a pool creation.
+
+:since:`Since 1.2.8`
+
+Example ZFS pool input
+~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <pool type="zfs">
+ <name>myzfspool</name>
+ <source>
+ <name>zpoolname</name>
+ <device path="/dev/ada1"/>
+ <device path="/dev/ada2"/>
+ </source>
+ </pool>
+
+Valid ZFS pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ZFS volume pool does not use the pool format type element.
+
+Valid ZFS volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ZFS volume pool does not use the volume format type element.
+
+Vstorage pool
+-------------
+
+This provides a pool based on Virtuozzo storage. Virtuozzo Storage is a highly
+available distributed software-defined storage with built-in replication and
+disaster recovery. More detailed information about Virtuozzo storage and its
+management can be found here: `Virtuozzo
+Storage <https://openvz.org/Virtuozzo_Storage>`__).
+
+Please refer to the Virtuozzo Storage documentation for details on storage
+management and usage.
+
+Example vstorage pool input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to create storage pool with Virtuozzo Storage backend you have to
+provide cluster name and be authorized within the cluster.
+
+::
+
+ <pool type="vstorage">
+ <name>myvstoragepool</name>
+ <source>
+ <name>clustername</name>
+ </source>
+ <target>
+ <path>/mnt/clustername</path>
+ </target>
+ </pool>
+
+Valid vstorage pool format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Vstorage volume pool does not use the pool format type element.
+
+Valid vstorage volume format types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The valid volume types are the same as for the directory pool.
--
2.35.1
More information about the libvir-list
mailing list