From 0e8ed42baa0ce53d54091c8325ac919e94e3429b Mon Sep 17 00:00:00 2001

Message-Id: <0e8ed42baa0ce53d54091c8325ac919e94e3429b@dist-git>

From: Eric Blake <eblake@redhat.com>

Date: Wed, 26 Feb 2014 14:54:21 +0100

Subject: [PATCH] storage: document existing pools

https://bugzilla.redhat.com/show_bug.cgi?id=1032370

We forgot to document several pool types.

* docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and

sheepdog.

Signed-off-by: Eric Blake <eblake@redhat.com>

(cherry picked from commit 59dce8d278ba92d1b2d5863e770843a4281c2b2c)

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>

---

 docs/formatstorage.html.in | 53 ++++++++++++++++++++++++++++++----------------

 1 file changed, 35 insertions(+), 18 deletions(-)

diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in

index 30ae538..2bb29b1 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:

-- 

1.9.0