doc: Add 'expose volume capabilities' details of bd-xlator

Change-Id: If7a89a36c2eca653e4fa7f59597ac8b03e4bc747
BUG: 1086749
Signed-off-by: Humble Chirammal <hchiramm@redhat.com>
Signed-off-by: Bharata B Rao <bharata.rao@gmail.com>
Reviewed-on: http://review.gluster.org/7844
Reviewed-by: Vijay Bellur <vbellur@redhat.com>
Tested-by: Vijay Bellur <vbellur@redhat.com>

1 files changed, 65 insertions, 2 deletions

diff --git a/doc/features/bd-xlator.md b/doc/features/bd-xlator.md
index 743e78b1eb0..1771fb6e24b 100644
--- a/doc/features/bd-xlator.md
+++ b/doc/features/bd-xlator.md
@@ -309,8 +309,6 @@ Now /mnt/thin-lv is a thin provisioned file that is backed by a thin LV and size
 
 As can be seen from above, creation of a file resulted in creation of a thin LV in the brick.
 
-For more information on bd translator wrt snapshots and clones,
-refer #  http://raobharata.wordpress.com/2013/11/27/glusterfs-block-device-translator/
 
 ###Improvisation on BD translator:
 
@@ -404,3 +402,68 @@ bricks/volumes. After deleting a gluster volume, one has to manually
 remove the associated tag using vgchange <vg-name> --deltag
 `<trusted.glusterfs.volume-id:<volume-id>>`
 
+
+#### Exposing volume capabilities
+
+With multiple storage translators (posix and bd) being supported in GlusterFS, it becomes
+necessary to know the volume type so that user can issue appropriate calls that are relevant
+only to the a given volume type. Hence there needs to be a way to expose the type of
+the storage translator of the volume to the user.
+
+BD xlator is capable of providing server offloaded file copy, server/storage offloaded
+zeroing of a file etc. This capabilities should be visible to the client/user, so that these
+features can be exploited.
+
+BD xlator exports capability information through gluster volume info (and --xml) output. For eg:
+
+`snip of gluster volume info output for a BD based volume`
+
+        Xlator 1: BD
+        Capability 1: thin
+
+`snip of gluster volume info --xml output for a BD based volume`
+
+        <xlators>
+          <xlator>
+                <name>BD</name>
+                <capabilities>
+                        <capability>thin</capability>
+                </capabilities>
+          </xlator>
+        </xlators>
+
+But this capability information should also exposed through some other means so that a host
+which is not part of Gluster peer could also avail this capabilities.
+
+* Type
+
+BD translator supports both regular files and block device, i,e., one can create files on
+GlusterFS volume backed by BD translator and this file could end up as regular posix file or
+a logical volume (block device) based on the user''s choice. User can do a setxattr on the
+created file to convert it to a logical volume.
+
+Users of BD backed volume like QEMU would like to know that it is working with BD type of volume
+so that it can issue an additional setxattr call after creating a VM image on GlusterFS backend.
+This is necessary to ensure that the created VM image is backed by LV instead of file.
+
+There are different ways to expose this information (BD type of volume) to user.
+One way is to export it via a `getxattr` call. That said, When a client issues getxattr("volume_type")
+on a root gfid, bd xlator will return 1 implying its BD xlator. But posix xlator will return ENODATA
+and client code can interpret this as posix xlator. Also capability list can be returned via
+getxattr("caps") for root gfid.
+
+* Capabilities
+
+BD xlator supports new features such as server offloaded file copy, thin provisioned VM images etc.
+
+There is no standard way of exploiting these features from client side (such as syscall
+to exploit server offloaded copy). So these features need to be exported to the client so that
+they can be used. BD xlator latest version exports these capabilities information through
+gluster volume info (and --xml) output. But if a client is not part of GlusterFS peer
+it can''t run volume info command to get the list of capabilities of a given GlusterFS volume.
+For example, GlusterFS block driver in qemu need to get the capability list so that these features are used.
+
+
+
+Parts of this documentation were originally published here
+#http://raobharata.wordpress.com/2013/11/27/glusterfs-block-device-translator/