From: Eric Blake Date: Tue, 15 Oct 2013 22:59:48 +0000 (-0600) Subject: storage: document existing pools X-Git-Tag: CVE-2013-4401~22 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=59dce8d278ba92d1b2d5863e770843a4281c2b2c;p=thirdparty%2Flibvirt.git storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake --- diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in index 3300d67801..90eeaa3ab3 100644 --- a/docs/formatstorage.html.in +++ b/docs/formatstorage.html.in @@ -18,9 +18,12 @@ The top level tag for a storage pool document is 'pool'. It has a single attribute type, which is one of dir, fs, netfs, disk, - iscsi, logical. This corresponds to the + iscsi, logical, scsi + (all since 0.4.1), mpath + (since 0.7.1), rbd + (since 0.9.13), or sheepdog + (since 0.10.0). This corresponds to the storage backend drivers listed further along in this document. - The storage pool XML format is available since 0.4.1

General metadata

@@ -64,7 +67,8 @@

A single source element is contained within the top level pool element. This tag is used to describe the source of - the storage pool. It can contain the following child elements: + the storage pool. The set of child elements that it will contain + depend on the pool type, but come from the following child elements: 

@@ -89,17 +93,21 @@
 
     

       
device

-      
Provides the source for pools backed by physical devices.
+      
Provides the source for pools backed by physical devices
+        (pool types fs, logical, disk,
+        iscsi).
         May be repeated multiple times depending on backend driver. Contains
         a single attribute path which is the fully qualified
         path to the block device node. Since 0.4.1

-      
directory

-      
Provides the source for pools backed by directories. May
+      
dir

+      
Provides the source for pools backed by directories (pool
+        type dir). May
         only occur once. Contains a single attribute path
         which is the fully qualified path to the backing directory.
         Since 0.4.1

       
adapter

-      
Provides the source for pools backed by SCSI adapters. May
+      
Provides the source for pools backed by SCSI adapters (pool
+        type scsi). May
         only occur once. Attribute name is the SCSI adapter
         name (ex. "scsi_host1".  NB, although a name such as "host1" is
         still supported for backwards compatibility, it is not recommended).
@@ -120,7 +128,9 @@
         Since 0.6.2

       
host

       
Provides the source for pools backed by storage from a
-        remote server. Will be used in combination with a directory
+        remote server (pool types netfs, iscsi,
+        rbd, sheepdog). Will be
+        used in combination with a directory
         or device element. Contains an attribute name
         which is the hostname or IP address of the server. May optionally
         contain a port attribute for the protocol specific
@@ -128,18 +138,19 @@
       
auth

       
If present, the auth element provides the
         authentication credentials needed to access the source by the
-        setting of the type attribute. The type
-        must be either "chap" or "ceph". Additionally a mandatory attribute
+        setting of the type attribute (pool
+        types iscsi, rbd). The type
+        must be either "chap" or "ceph". Use "ceph" for
+        Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
+        (Challenge-Handshake Authentication Protocol) iSCSI
+        targets. Additionally a mandatory attribute
         username identifies the username to use during
         authentication as well as a sub-element secret with
         a mandatory attribute type, to tie back to a
         libvirt secret object that
         holds the actual password or other credentials. The domain XML
         intentionally does not expose the password, only the reference
-        to the object that manages the password. The secret element
-        type must be either "ceph" or "iscsi". Use "ceph" for
-        Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
-        (Challenge-Handshake Authentication Protocol) iSCSI targets.
+        to the object that manages the password.
         The secret element requires either a uuid
         attribute with the UUID of the secret object or a usage
         attribute matching the key that was specified in the
@@ -148,11 +159,13 @@
       

       
name

       
Provides the source for pools backed by storage from a
-        named element (e.g., a logical volume group name).
-        Contains a string identifier.
+        named element (pool types logical, rbd,
+        sheepdog).  Contains a string identifier.
         Since 0.4.5

       
format

-      
Provides information about the format of the pool. This
+      
Provides information about the format of the pool (pool
+        types fs, netfs, disk,
+        logical). This
         contains a single attribute type whose value is
         backend specific. This is typically used to indicate filesystem
         type, or network filesystem type, or partition table type, or
@@ -174,7 +187,11 @@
 
     

       A single target element is contained within the top level
-      pool element. This tag is used to describe the mapping of
+      pool element for some types of pools (pool
+      types dir, fs, netfs,
+      logical, disk, iscsi,
+      scsi, mpath). This tag is used to
+      describe the mapping of
       the storage pool into the host filesystem. It can contain the following
       child elements: