DownloadUnderstanding vol-file
From GlusterDocumentation
The volume file is like a GlusterFS configuration file: it defines your GlusterFS file system design layout, hence its behavior. Writing a volume (or vol) file is an advanced developer topic.
Each volume in the vol file selects an appropriate translator module with corresponding configuration options. Through this vol file, you can completely program the GlusterFS file system by arranging translators and modules in a graph with various options. Allowing this level of flexibility makes GlusterFS adapt to different storage needs.
Even with all these advanced features, GlusterFS is easy to setup and manage. The default vol file is sufficient to start with. You may just have to edit the IP addresses. They are placed under /etc/glusterfs/glusterfs.vol and /etc/glusterfs/glusterfsd.vol. Customize it to suit your needs. Additional examples are available under doc/examples directory.
Contents |
Vol File Syntax
- "#" is a comment character.
- Volume files are case sensitive.
- Options within a volume block can be in any order.
- Spaces or tabs are used as a delimiter within a line.
- Each option should end within a line. (no '\n')
- Missing or commented fields will assume default values.
- Blank/commented lines are allowed.
- Sub-volumes should be defined above/before being referenced.
Example Vol File
Let's take a look at the naming convention used when writing a volfile.
volume client type protocol/client # option remote-port 7000 option transport-type tcp option remote-host localhost option remote-subvolume brick end-volume volume iothreads type performance/io-threads option thread-count 4 subvolumes client end-volume volume writeback type performance/write-behind subvolumes iothreads end-volume # volume trace # type debug/trace # subvolumes writeback # end-volume
As you can seen in the example above, 'volume client' is defined before 'volume iothreads', which is in turn defined before 'volume writeback'. But when building a graph out of this spec file, the order of definition changes. In other words, fuse will attach to 'volume writeback' first, (hence it being called top most volume), and 'volume client' can be called bottom most volume.
Other than writing the vol file, the order that each of the volumes are used is bottom-up.
Snapshot of a single volume
1 volume unify 2 type cluster/distribute 3 option scheduler rr # check alu, random, nufa 4 option rr.limits.min-free-disk 5 # 5% of free disk is minimum. 5 option namespace namespace-child 6 subvolumes child1 child2 child3 child4 # client[1-n], n < 32bit number :D 7 end-volume
Line by line explanation of volume definition
The number at the beginning of each line is for reference, actual definition files do not have this number.
- LINE 1: "volume unify"
Here, 'volume' is an identifier for the parser, which starts definition of new translator. 'unify' is the name of the volume, which should be unique for a given volfile. Although examples here are given names that reflect the type of volume, the actual name can be arbitrarily given.
- LINE 2: "type cluster/distribute"
Here 'type' is an identifier for the parser, which is used to look for the type of the translator (there are many others, listed in this wiki or check source). 'cluster/distribute' is the path inside libdir for looking up the shared object file "/<libdir>/glusterfs/<gluster version>/xlator/cluster/distribute.so". (For example on Ubuntu for Gluster version 2.0.8, the location is /lib/glusterfs/2.0.8/xlator/cluster/distribute.so )
You can see here that any given translator in GlusterFS is loaded during run time after parsing through the spec file. So the behavior of the GlusterFS can be decided by the volfile.
- LINE 3: "option scheduler rr"
- LINE 4: "option rr.limits.min-free-disk 5"
- LINE 5: "option namespace namespace-child"
Here 'option' is an identifier for the parser, which is used to specify some of the configurable flags of the translator. 'option' always needs two more parameters after it, which can be treated as 'key', 'value' ('option key value'). These options will be different depending on which translator you use.
'scheduler' is an option for the distribute translator, which specifies which type of scheduler to use while creating a file. Remember that a file is created only in one of the child node, out of 'n' child nodes. There are already a few schedulers present in GlusterFS so go through wiki for further info, or check the 'schedulers/' directory in the release tarball.
'rr' is the name of the scheduler to be used ('rr' means round-robin). There are also other schedulers: 'alu', 'random', and 'nufa'.
NOTE: "option" is specific to each translator. So read more about it in the translator specific documentation.
- LINE 6: "subvolumes child1 child2 child3 child4"
'subvolumes' is a key word used to build a relation in the translator graph. Using the 'subvolumes' keyword you can define which translator should be loaded below this translator. All cluster translators have one or more subvolumes, whereas most of the other translators have just one subvolume. This key word is not used in the leaf node (ie, the last in the graph) translator. They are 'storage/posix' and 'protocol/client'.
- LINE 7: "end-volume"
Here 'end-volume' means that the definition of translator 'volume unify' is over.
Further Reading
"GlusterFS_1.2_Configuration_Example_for_Four_Bricks" tutorial written by Julien Perez gives a very nice understanding of volume file and its pictorial representation. The volume file options may be bit older, but still is a nice article to understand the GlusterFS volume file.
Editing volfiles
- emacs glusterfs mode - emacs mode of editing glusterfs
- vim glusterfs mode - vim mode of editing glusterfs
Refer
- Translators page gives an insight about each translators available in GlusterFS.
- Translators options gives a list of all the existing translator options.
