Bug 761814 (GLUSTER-82)

Summary: Glusterfs Volume Specification file - Translator options, spec-file snippets and comments
Product: [Community] GlusterFS Reporter: Basavanagowda Kanur <gowda>
Component: scriptsAssignee: Shehjar Tikoo <shehjart>
Status: CLOSED CURRENTRELEASE QA Contact:
Severity: low Docs Contact:
Priority: low    
Version: pre-2.0CC: gluster-bugs, gowda, guru, pavan
Target Milestone: ---   
Target Release: ---   
Hardware: All   
OS: Linux   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: Type: ---
Regression: RTNR Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Basavanagowda Kanur 2009-06-25 13:08:34 UTC 
[Migrated from RT] - ticket 753 [http://support.gluster.com/rt/Ticket/Display.html?id=753]

Sun Feb 01 01:21:44 2009  	 guru - Ticket created

Latest version as of now: glusterfs 2.0.0 qa14/881

I worked with Du and was able to finish a few translators. The idea is
to have spec-file snippets in the documentation which could be
copy-pasted onto user spec files.

The snippets need to be complete with all the options of the particular
translator (so that one needs to worry only about the values for an
option and not hunt for the option itself in the user docs).


Another concern is that the user documentation (and all other
documentation) needs to be in a user frienly format (read .doc) rather
than in the tex family.


Given below is what I am planning to include in the documentation. I
have marked comments/concerns with "???" and numbered them for further
follow up.

I request all of you to take a look and give me feedback. I will
conclude the activity with the remaining translators next week.

=======================================================================

volume replicate
type cluster/replicate

## option read-subvolume <SUBVOLUME>
## option favorite-child <SUBVOLUME>
option data-self-heal on
option metadata-self-heal on
option entry-self-heal on
option data-change-log on
option metadata-change-log off
option entry-change-log on
option data-lock-server-count 1
option metadata-lock-server-count 0
option entry-lock-server-count 1

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume


volume distribute
type cluster/distribute
option lookup-unhashed off

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume

volume ha
type cluster/ha

## option preferred-subvolume <INDEX> ???
??? (1) Why index and why not the subvolume name itself?

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume

volume stripe
type cluster/stripe

option use-xattr yes
option block-size *:128KB ??? default pattern. default value
??? (2) Takes just size as valid argument. Why not insist on correct
??? <PATTERN>:<SIZE> (ie dont assume implicit * for pattern)
??? Also, why 128 KB? With higher bandwidths, cant we increase?

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume

volume unify
type cluster/unify
## option scheduler <SCHEDULER>

## option namespace <SUBVOLUME>
option self-heal foreground
option optimist off

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume

volume unify-nufa
type cluster/unify
option scheduler nufa

## option namespace <SUBVOLUME>
option optimist off
option self-heal foreground

??? (3) INITIALISATION of free disk, disk usage, disk size, disk
speed, write usage, read usage, nr files, nr clients
??? (4) alu_limits.total_disk_size.default is not taken as option from
user (100%)

option scheduler.alu.order ??? (5)
??? (5) What is the default value?
option scheduler.alu.disk-usage.entry-threshold 1GB
option scheduler.alu.disk-usage.exit-threshold 512MB
option scheduler.alu.write-usage.entry-threshold 25 ??? (6)
??? (6) 25 what? Percentage? Is it not a good idea to insist on explicitly
??? mentioning the unit for any option - %,s,KB etc
option scheduler.alu.write-usage.exit-threshold 5 ??? (7)
??? (7) See above
option scheduler.alu.read-usage.entry-threshold 25 ??? (8)
??? (8) See above
option scheduler.alu.read-usage.exit-threshold 5 ??? (9)
??? (9) See above
option scheduler.alu.open-files-usage.entry-threshold 1000
option scheduler.alu.open-files-usage.exit-threshold 100
## option scheduler.read-only-subvolumes <SUBVOLUME>,.. ??? (10)
??? (10) The option name is not consistent. Should be
scheduler.alu.<OPTION>
option scheduler.refresh-interval 5 ??? (11)
??? (11) See above
option scheduler.limits.min-free-disk 0 ??? (12)
??? (12) See above
option scheduler.alu.stat-refresh.num-file-create 5
??? (13) Unit?

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume


volume unify-nufa
type cluster/unify
option scheduler nufa

## option namespace <SUBVOLUME>
option optimist off
option self-heal foreground

??? (14) options should be named scheduler.nufa.<>

option scheduler.refresh-interval 30
option scheduler.limits.min-free-disk 15
## option scheduler.local-volume-name <SUBVOLUME>

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume


volume unify-rr
type cluster/unify
option scheduler rr

## option namespace <SUBVOLUME>
option optimist off
option self-heal foreground

??? (15) options should be named scheduler.random.<>

option scheduler.refresh-interval 10
option scheduler.limits.min-free-disk 15%

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume


volume unify-rr
type cluster/unify
option scheduler rr

## option namespace <SUBVOLUME>
option optimist off
option self-heal foreground

??? (16) options should be named scheduler.rr.<>

option scheduler.limits.min-free-disk 15
option scheduler.refresh-interval 10
option scheduler.read-only-subvolumes ??? (17)
??? (17) What does this do? What are the defaults?

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume


volume unify-switch
type cluster/unify
option scheduler switch

## option namespace <SUBVOLUME>
option optimist off
option self-heal foreground

??? (18) options should be named scheduler.switch.<>

## <UNIFY_OPTIONS>
## option scheduler.read-only-subvolumes ??? (19)
??? (19) What does this do? What are the defaults?
## option scheduler.local-volume-name <SUBVOLUME>
## option scheduler.switch.case
<PATTERN1:subvolume1,subvolume2,subvolume3>;..

## subvolumes <SUBVOLUME1>,<SUBVOLUME2>,..
end-volume



volume trace
type debug/trace

??? (20) List of FOPS (to be mentioned in doc):
??? STAT READLINK MKNOD MKDIR UNLINK RMDIR SYMLINK RENAME LINK CHMOD
CHOWN TRUNCATE OPEN READ WRITE STATFS FLUSH FSYNC SETXATTR GETXATTR
REMOVEXATTR OPENDIR GETDENTS FSYNCDIR ACCESS CREATE FTRUNCATE FSTAT LK
UTIMENS FCHMOD FCHOWN LOOKUP SETDENTS READDIR INODELK FINODELK ENTRYLK
FENTRYLK CHECKSUM XATTROP

## option include-ops <FOPS>
## option exclude-ops <FOPS>

## subvolumes <SUBVOLUME>,..
end-volume


volume rot-13
type encryption/rot-13

option encrypt-write yes
option decrypt-read yes

## subvolumes <SUBVOLUME>,..
end-volume


volume filter
type features/filter

??? (21) wiki filter example wrong

option root-squashing disabled
option read-only off
## option fixed-uid <UID> ??? option not used if not mentioned
## option fixed-gid <GID> ??? option not used if not mentioned
## option translate-uid <FROM_UID-TO_UID=UID>,..
## option translate-gid <FROM_GID-TO_GID=GID>,..
## option filter-uid <FROM_UID-TO_UID>,..
## option filter-gid <FROM_UID-TO_UID>,..

## subvolumes <SUBVOLUME>,..
end-volume


volume locks
type features/locks

option mandatory-locks off

## subvolumes <SUBVOLUME>,..
end-volume


volume path-convertor
type features/path-convertor

??? (22) spelling mistake in convert'o'r. should be converter
??? (23) xlator code incomplete

option start-offset 0
option end-offset 0 ??? (24) Wrong default allowed range is 1 - 4096
## option replace-with <> ??? (25) Not clear how this works

## subvolumes <SUBVOLUME>,..
end-volume


volume quota
type features/quota
option min-free-disk-limit 0
option refresh-interval 20 ??? (26) 20s in case min-free-disk-limit is
given
??? (26) Make clear in documentation. Also units.
option disk-usage-limit 0

## subvolumes <SUBVOLUME>,..
end-volume


volume trash
type features/trash
option trash-dir /.trashcan ??? (27) better renamed as trashdir???
??? (27) Think about consistency - trashdir vs trashcan

## subvolumes <SUBVOLUME>,..
end-volume


volume fuse
type mount/fuse
option direct-io-mode enabled
option macfuse-local off
## option mountpoint <MOUNTPOINT>
option attribute-timeout 1
option entry-timeout 1

## subvolumes <SUBVOLUME>,..
end-volume

--------------------------------------------------------------------------------
#   	Sat Feb 07 10:51:22 2009 	guru - Correspondence added

The remaining translators (bdb has been excluded for now):


volume io-cache
type performance/io-cache
## option priority <PATTERN>:<PRIORITY> # filename_expansion:number
option cache-timeout # 0 - 60s
option cache-size 32mb # 4mb - 6gb
option page-size 128kb # 16kb - 8mb
end-volume


volume io-threads
type performance/io-threads
option thread-count 1 # 1 - 32
end-volume


volume read-ahead
type performance/read-ahead
option force-atime-update off
option page-size 256kb # 64kb - 2mb
option page-count 2 # 1 - 16
end-volume


volume symlink-cache
type performance/symlink-cache
end-volume


volume write-behind
type performance/write-behind
option flush-behind off
option block-size 0 # 128kb - 4mb
option cache-size 0 # 512kb - 1gb ??? (28) Default value out of range
??? (28) Default/Range needs to be fixed
option disable-for-first-nbytes 1
option enable-O_SYNC off
end-volume


volume client
type protocol/client
## option username <USERNAME>
## option password <PASSWORD>
## option remote-host <HOSTNAME>
## option remote-subvolume <SUBVOLUME>
option transport-timeout 42 # 5 - 1013
option ping-timeout 10 # 5 - 1013
option transport-type socket # (socket, ib-verbs), (tcp, socket,
ib-verbs, unix, ib-sdp, tcp/client, ib-verbs/client)
end-volume


volume server
type protocol/server
option transport-type socket
## option volume-filename.<KEY> <PATH>
option inode-lru-limit 1024
option client-volume-filename /CONFDIR/glusterfs-client.vol
end-volume


volume client-socket
type protocol/client
## option username <USERNAME>
## option password <PASSWORD>
## option remote-host <HOSTNAME>
## option remote-subvolume <SUBVOLUME>
option transport-timeout 42 # 5 - 1013
option ping-timeout 10 # 5 - 1013

option transport-type socket

option transport.socket.address-family inet # (inet, inet6,
inet/inet6, inet6/inet, unix, inet-sdp)
option transport.socket.remote-port ??? (29) do we need transport.socket?
??? (29) Why not "option remote-port <PORT>"
## option transport.socket.connect-path <PATH>
## option transport.socket.bind-path <PATH>
end-volume


volume server-socket
type protocol/server
option transport-type socket
## option volume-filename.<KEY> <PATH>
option inode-lru-limit 1024
option client-volume-filename /CONFDIR/glusterfs-client.vol

option transport-type socket

option transport.socket.address-family inet # (inet, inet6,
inet/inet6, inet6/inet, unix, inet-sdp)
option transport.socket.remote-port
option transport.socket.bind-address localhost
option transport.socket.listen-port 6996
## option transport.socket.listen-path <PATH>
end-volume


volume client-ib-verbs
type protocol/client
## option username <USERNAME>
## option password <PASSWORD>
## option remote-host <HOSTNAME>
## option remote-subvolume <SUBVOLUME>
option transport-timeout 42 # 5 - 1013
option ping-timeout 10 # 5 - 1013

option transport-type ib-verbs

option transport.ib-verbs.address-family inet # (inet, inet6,
inet/inet6, inet6/inet, unix, inet-sdp)
option transport.ib-verbs.mtu 2048
option transport.ib-verbs.port 1 # 1 - 4
## option transport.ib-verbs.device-name <DEVICE> # Default: first
available device
option transport.ib-verbs.work-request-send-size 1048576 ??? (30) Type
is INT not SIZE. (1mb default)
??? (30) Either rename option name or change input type
option transport.ib-verbs.work-request-recv-size 1048576
option transport.ib-verbs.work-request-send-count 16
option transport.ib-verbs.work-request-recv-count 16
option transport.ib-verbs.remote-port 6996
## option transport.ib-verbs.connect-path <PATH> ??? (31)
??? (31) Does PATH make sense for ib-verbs?
## option transport.ib-verbs.bind-path <PATH> ??? (32)
??? (32) Does PATH make sense for ib-verbs?
## option transport.ib-verbs.listen-path <PATH> ??? (33)
??? (33) Does PATH make sense for ib-verbs?
end-volume


volume server-ib-verbs
type protocol/server
option transport-type socket
option volume-filename.<KEY> <PATH>
option inode-lru-limit 1024
option client-volume-filename /CONFDIR/glusterfs-client.vol

option transport-type ib-verbs

option transport.ib-verbs.address-family inet # (inet, inet6,
inet/inet6, inet6/inet, unix, inet-sdp)
option transport.ib-verbs.mtu 2048
option transport.ib-verbs.port 1 # 1 - 4
## option transport.ib-verbs.device-name <DEVICE> # Default: first
available device
option transport.ib-verbs.work-request-send-size 1048576
option transport.ib-verbs.work-request-recv-size 1048576
option transport.ib-verbs.work-request-send-count 16
option transport.ib-verbs.work-request-recv-count 16
option transport.ib-verbs.listen-port 6996
## option transport.ib-verbs.listen-path <PATH> ??? (34)
??? (34) Does PATH make sense for ib-verbs?
end-volume


volume posix
type storage/posix
option o-direct disabled
## option directory <DIRECTORY>
option export-statfs-size enabled
option mandate-attribute enabled ??? (35) "mandate-xattr" used in code
??? (35) The code is inconsistent with the option name
end-volume

--------------------------------------------------------------------------------
#   	Mon Apr 13 16:10:14 2009 	gowda - Correspondence added

Shehjar,
Please put all the translator options into one single file, with
relevant comments and post the volume specification file to this ticket.
The volume specification files should also go into the source
repository and the wiki documentation.

-- 
gowda
Comment 1 Shehjar Tikoo 2009-11-12 03:27:07 UTC 
I am closing this because we now have some pretty good documentation which does a better job than I ever will for this bug.