path: root/doc
diff options
authorM. Mohan Kumar <>2012-12-04 14:25:33 +0530
committerAnand Avati <>2012-12-05 21:36:16 -0800
commitefbc6349251ef32df8c5f670f550a0aaec8400f5 (patch)
tree30813c9304ed760f32e3653188841adb0e15d997 /doc
parent6801fc385d69a43d829b504adea299cce6057e25 (diff)
BD backend documentation update
BUG: 805138 Change-Id: I2b4eb3fb7bad59c5dadf7f22fcc4d2b2a783984a Signed-off-by: M. Mohan Kumar <> Reviewed-on: Reviewed-by: Anand Avati <> Tested-by: Anand Avati <>
Diffstat (limited to 'doc')
1 files changed, 130 insertions, 0 deletions
diff --git a/doc/bd.txt b/doc/bd.txt
new file mode 100644
index 00000000..c1ba006e
--- /dev/null
+++ b/doc/bd.txt
@@ -0,0 +1,130 @@
+1. Introduction
+2. Advantages
+3. Creating BD backend volume
+4. BD volume file
+5. Using BD backend gluster volume
+6. Limitations
+7. TODO
+1. Introduction
+Block Device translator(BD xlator) represented as storage/bd_map in
+volume file adds a new backend 'block' to GlusterFS. It enables
+GlusterFS to export block devices as regular files to the client.
+Currently BD xlator supports exporting of 'Volume Group(VG)' as
+directory and Logical Volumes(LV) within that VG as regular files to the
+The eventual goal of this work is to support thin provisioning,
+snapshot, copy etc of VM images seamlessly in GlusterFS storage
+The immediate goal of this translator is to use LVs to store
+VM images and expose them as files to QEMU/KVM. Given VG is represented
+as directory and its logical volumes as files.
+BD xlator uses lvm2-devel APIs for getting the list of VGs and LVs in
+the system and lvm binaries (such as lvcreate, lvresize etc) to perform
+the required LV operations.
+2. Advantages
+By exporting LVs as regular files, it becomes possible to:
+* Associate each VM to a LV so that there is no file system overhead.
+* Use file system commands like cp to take copy of VM images
+* Create linked clones of VM by doing LV snapshot at server
+* Implement thin provisioning by developing a qcow2 translator
+3. Creating BD backend volume
+New parameter "device vg" in volume create command is used to create BD
+backend gluster volumes.
+For example
+ $ gluster volume create my-volume device vg hostname:/my-vg
+creates gluster volume 'my-volume' with BD backend which uses the VG
+'my-vg' to store data. VG 'my-vg' should exist before creating this
+gluster volume.
+4. BD volume file
+BD backend volume file specifies which VG to export to the client. The
+section in the volume file that describes BD xlator looks like this.
+volume my-volume-bd_map
+type storage/bd_map
+option device vg
+option export volume-group
+option device=vg specifies that it should use VG as block backend. option
+export=volume-group specifies that it should export VG "volume-group"
+to the client.
+5. Using BD backend gluster volume
+ $ mount -t glusterfs hostname:/my-volume /media/bd
+ $ cd /media/bd
+From the mount point:
+* Creating a new file (ie LV) involves two steps
+ $ touch lv1
+ $ truncate -s <size> lv1
+ or
+ $ qemu-img create -f <format> gluster:/hostname/my-volume/path-to-image <size>
+* Cloning an LV
+ $ ln lv1 lv2
+* Snapshotting an LV
+ $ ln -s lv1 lv1-ss
+* Passing it to QEMU as one of the drives
+ $ qemu -drive file=<mount>/<file>,if=<if-type>
+* GlusterFS is one of the supported QEMU block drivers, the URI format
+ is
+ gluster[+transport]://[server[:port]]/my-volume/image[?socket=...]
+ ie
+ $ qemu -drive file=gluster:/hostname/my-volume/path-to-image,if=<if-type>
+Using Gluster CLI:
+* To create a new image of required size
+ $ gluster bd create my-volume:/path-to-image <size>
+* To delete an existing image
+ $ gluster bd delete my-volume:/path-to-image
+* To clone (full clone) an image
+ $ gluster bd clone my-volume:/path-to-image new-image
+* To take a snapshot of an image
+ $ gluster bd snapshot my-volume:/path-to-image snapshot-image <size>
+All gluster BD commands need size to specified in terms of KB, MB, etc.
+6. Limitations
+* No support to create multiple bricks
+* Image creation should be used with truncate to get proper size or use
+ qemu-img create
+* cp command can't be used to copy images, instead use ln command or
+ gluster bd clone command
+* ln -s command throws an error even if snapshot is successful
+* When ln command used on BD volumes, target file's inode is different
+ from target's
+* Creation/deletion of directories, xattr operations, mknod and readlink
+ operations are not supported.
+7. TODO
+Add support for exporting LUNs also as a regular files.
+Add support for xattr and multi brick support
+Include support for device mapper thin targets