Bug 676406

Description of problem:
There's a couple of inaccuracies in the "Configuration Example - NFS Over GFS" document that we should probably clear up.

This doc is very important to us and rather high profile. There's only one supported way to do NFS over GFS and we point people to that document as the only acceptable way to do it. If there are any inconsistencies in that doc then it can put customers in very bad positions.

The version of the doc I am referencing is the version publicly available here:
http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html-single/Configuration_Example_-_NFS_Over_GFS/index.html

Issue 1: The example cluster.conf should mention the localflocks option
Problem is here:
http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html-single/Configuration_Example_-_NFS_Over_GFS/index.html#NFS_GFS_Config_File

Does read:
<clusterfs device="/dev/myvg/myvol" force_unmount="0" fsid="39669" fstype="gfs" mountpoint="/mnt/gfs" name="mygfs" options="rw"/>

Should read:
<clusterfs device="/dev/myvg/myvol" force_unmount="0" fsid="39669" fstype="gfs" mountpoint="/mnt/gfs" name="mygfs" options="rw,localflocks"/>

----

Issue 2: The directions on how to add the GFS resource should mention localflocks
Problem is here:
http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html-single/Configuration_Example_-_NFS_Over_GFS/index.html#config_resource_gfs

Does read:
5. The Options field specifies the mount options for the GFS file system. For this example, we are mounting the file system with the rw (read-write) option. 

Should read:
5. The Options field specifies the mount options for the GFS file system. For this example, we are mounting the file system with the rw (read-write) and localflocks options. 

----

Issue 3: The "Locking Considerations" warning is slightly innacurate in its wording with regards to plocks vs. flocks
Problem is here:
http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html-single/Configuration_Example_-_NFS_Over_GFS/index.html#locking_considerations

Does read:
If the GFS or GFS2 file system is NFS exported, and NFS client applications use POSIX locks, then you must mount the file system with the localflocks option. The intended effect of this is to force POSIX locks from each server to be local: i.e., non-clustered, independent of each other. (A number of problems exist if GFS/GFS2 attempts to implement POSIX locks from NFS across the nodes of a cluster.) For applications running on NFS clients, localized POSIX locks means that two clients can hold the same lock concurrently if the two clients are mounting from different servers. If all clients mount NFS from one server, then the problem of separate servers granting the same locks independently goes away.
If you are unsure whether an application uses fcntl()/POSIX locks, for safety's sake you should mount your file system with the localflocks option. 

Should read:
When a GFS or GFS2 filesystem is exported via NFS then you must mount the filesystem with the localflocks option. The intended effect of this is to allow the NFS server to manage locks on the GFS or GFS2 filesystem without the extra overhead of passing through the GFS and GFS2 locking layers. 

Issue 4: Mention the localflocks mount option in the "Additional Configuration Considerations" section
Problem is here:
http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/5/html-single/Configuration_Example_-_NFS_Over_GFS/index.html#additional_configuration_considerations

Does read:
- Red Hat supports only Red Hat Cluster Suite configurations using NFSv3 with locking in an active/passive configuration with the following characteristics:
- The backend file system is a GFS or GFS2 file system running on a 2 to 16 node cluster.
- An NFSv3 server is defined as a service exporting the entire GFS/GFS2 file system from a single cluster node at a time.
- The NFS server can fail over from one cluster node to another (active/passive configuration).
- No access to the GFS/GFS2 file system is allowed except through the NFS server. This includes both local GFS/GFS2 file system access as well as access through Samba or Clustered Samba.
- There is no NFS quota support on the system. 

Should read:
- Red Hat supports only Red Hat Cluster Suite configurations using NFSv3 with locking in an active/passive configuration with the following characteristics:
- The backend file system is a GFS or GFS2 file system running on a 2 to 16 node cluster.
- An NFSv3 server is defined as a service exporting the entire GFS/GFS2 file system from a single cluster node at a time.
- The NFS server can fail over from one cluster node to another (active/passive configuration).
- No access to the GFS/GFS2 file system is allowed except through the NFS server. This includes both local GFS/GFS2 file system access as well as access through Samba or Clustered Samba.
- The GFS or GFS2 filesystem must be mounted with the localflocks option 
- There is no NFS quota support on the system.