GlusterFS Volume Specification v1.3

From GlusterDocumentation

(Redirected from GlusterFS Volume Specification)

Volume specification defines your GlusterFS file system design layout, hence its behavior. So, its very important that you understand clearly about writing a volume spec file.

Each volume in the spec file selects an appropriate translator module with corresponding configuration options. Through this volume spec file, you can completely program the GlusterFS filesystem 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 very easy to setup and manage. The default volume specification file is good enough to start with. You may just have to edit the IP addresses. They are placed under /etc/glusterfs/glusterfs-client.vol and /etc/glusterfs/glusterfs-server.vol. Customize it to suit your needs. Additional examples are available under doc/examples directory.

1 Rules of writing spec file
2 Example volume spec file
3 Snapshot of a single volume
4 Line by line explanation of volume definition
5 Editing volume spec files
6 GlusterFS Translators

[edit]

Rules of writing spec file

"#" is a comment character.
Volume spec files are case sensitive.
Options within a volume block can be in any order.
Spaces or tabs are used as a delimitter 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.

[edit]

Example volume spec file

Lets take a look at the naming convention used when writing a spec file.

As you can seen in the example below, '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 spec file, the order that each of the volumes are used is bottom-up.

volume client
 type protocol/client
#  option remote-port 7000
 option transport-type tcp/client
 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

[edit]

Snapshot 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

[edit]

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 spec file. Although examples here are given names that reflect the type of volume, the actual name can be arbitrarily given.

LINE 2: "type cluster/unify"

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/unify' is the path inside libdir for looking up the shared object file "/<libdir>/glusterfs/xlators/cluster/unify.so".

You can see here that any given translator in GlusterFS is loaded during run time after parsing through the spec file. So the behaviour of the GlusterFS can be decided by the spec file.

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 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 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'.