DownloadUnderstanding Vol Files
From GlusterDocumentation
Contents |
About Volume Files
The volume file acts like a configuration file: it defines your GlusterFS file system design layout and so 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. This level of flexibility allows GlusterFS to adapt to different storage needs.
The default vol file is sufficient to start with. You may only need to edit the IP addresses. The vol files are placed under:
- /etc/glusterfs/glusterfs.vol
- /etc/glusterfs/glusterfsd.vol
Edit the files to suit your needs. Additional examples are available under the doc/examples directory.
For simple ready-made volume files, see NFS_Like_Standalone_Storage_Server.
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 conventions used in 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
In the example above, volume client is defined before volume iothreads, which is 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 (why it is called the top most volume), and volume client can be called the bottom most volume.
Other than when writing the vol file, the order that each of the volumes are used is bottom-up.
Detailed Description of a Single Volume
1 volume unify 2 type cluster/unify 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
== The following is a line by line explanation of a volume definition. The line numbering is to aid in the explanation. The actual definition files are unnumbered.
- Line 1: volume unify
- Line 2: type cluster/unify
- Line 3: "option scheduler rr"
- Line 4: "option rr.limits.min-free-disk 5"
- Line 5: "option namespace namespace-child"
- Line 6: subvolumes child1 child2 child3 child4
- Line 7: end-volume
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 vol file. Although examples here are given names that reflect the type of volume, the actual name can be arbitrarily given.
'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/unify' is the path inside libdir for looking up the shared object file /<libdir>/glusterfs/xlators/cluster/unify.so.
From the example, you can see 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 vol file.
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). The actual options depend on which translator you use.
scheduler is an option for the unify 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 nodes, out of n child nodes. GlusterFS. See the wiki for further information, or check the schedulers/ directory in the release tarball.
rr is the name of the scheduler to be used (rr means round-robin). Other schedulers are: alu, random, and nufa.
Note: The option values available are specific to each translator. Refer to the translator specific documentation for more information.
The key word subvolumes is used to build a relation in the translator graph. Using the subvolumes, you can define which translator to load below this translator. All cluster translators have one or more subvolumes; most of the other translators have just one subvolume. This key word is not used in the leaf node (that is, the last in the graph) translator. They are storage/posix and protocol/client.
The line end-volume means that the definition of translator volume unify is complete.
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 Volume Files
- emacs glusterfs mode - emacs mode of editing glusterfs
- vim glusterfs mode - vim mode of editing glusterfs
About Translators
- Translators page provides insights about each translators available in GlusterFS.
- Translators options provides a list of all the existing translator options.
