Bug 764796 (GLUSTER-3064)

I had several comments regarding this document.

Section 4.3, page 8:
GlusterFS works with other common Linux distribution like RHEL 5.1 or higher, Ubuntu 8.04 or higher, and Fedora 11 or higher, but has not been tested extensively.

This implies that gluster has not been extensively tested on any platform.  We should clarify that we have tested extensively in RHEL based OS’es.  Under the packages, we should also list readline as an additional package since it is used by the CLI.

Section 5.4.1, page 9:
We should not imply that upgrading is a non-disruptive operation.  Upgrading the rpm’s does not reload the running instances of gluster in memory, a restart of the glusterd process is required on each storage node in order to load the newer version.  

In the same section, the sentence “The method to install from Gluster 3.1.x to 3.1.5 is RPM <--> RPM, or source <--> source” is unclear.  We should specifically state “Use the  same installation method for the upgrade as the original gluster installation.  Possible methodes are source, RPM, or dpkg.

Section 7, page 12:
“In GlusterFS replicated setup, if the user is inside a directory of replicated volume and from another node deletes a file inside that particular directory. And then if a 'stat' operation is performed on the same file name creates the file. (that is, a proper directory self-heal is not triggered when process has done ‘cd' into a path).”

This paragraph is unclear.  It might be better to state the problem in a simple fashion and show an example.

 "glusterd - Manual edits to the volume files are not preserved. Volume file gets overwritten with glusterd operations. 
From 3.1.x onwards, glusterfs volume file is automatically generated by the ‘glusterd’ daemon. The auto-generated volume file may not have all possible options which GlusterFS can support (or does not involve all the translators which are supported/available in GlusterFS). So, if you manually change the parameters in volume file, it is not preserved in next volume edit due to some 'gluster volume set' operations."

We can simplify this to state that modifying the volume files is not supported as of 3.1.5.  We must use the specific verbiage "not supported" to very clearly state that we do not support this.  We can also clarify that the volume files are optimized for each configuration, so modifications are more likely to decrease performance than provide any benefit.

" 	glusterfsd - Return error code is not proper after daemonizing the process.
Currently, there are some challenges in returning the error code after all the translators are initialized. Due to this, scripts that mount glusterfs or start glusterfs process, must not depend on its return value to understand whether they are running fine."

Change description header to "Error return codes are not proper in all instances".  The description itself can be changed to "Due to this, scripts that mount glusterfs or start glusterfs process must not depend on its return value."

" 	glusterd - Parallel rebalance 
With the current rebalance mechanism, the machine issuing the rebalance is becoming a bottleneck as all the data migrations are happening through that machine. An enhancement to this is possible by doing a parallel 'pull' operations from all the bricks which should get data migrated to themself. This reduces the bottleneck on one node and rebalance of data can happen much faster."

We should change the wording to something like:

"With the current rebalance mechanism, the machine issuing the rebalance can become a bottleneck as all the data migrations happen through that machine. In such instances, a possible workaround is to issue parallel 'pull' operations from all the bricks which require data to be migrated. This reduces the bottleneck on one node and rebalance of data can happen much faster."

We also need to give a specific example of doing so, or else define what "pull operation" means, and how to identify which bricks require data to be migrated.


" 	After committing replace-brick command, few file system operations are known to fail due to clients accessing that particular brick during replace brick operation."

We need to define which operations can fail.  The word "few" should be replaced with "certain", i.e., "...certain file system operations..."

" 	The following are few known missing (minor) features:
•	access-control – POSIX ACLs 
The limitation is that the application depending on POSIX ACLs for their working will not work on GlusterFS."

This sentence does not make sense as presented.  We should change this to "...application operations which require POSIX ACL's to function properly will not work in GlusterFS."

As before, these suggestions are made in good faith to improve the experience for our end users.