commit 75934649b85259d1559eabca40be820095643239
Author: Andrew Price <anprice@redhat.com>
Date:   Tue Feb 12 09:58:11 2019 +0000

    gfs2.5: General updates and layout improvements
    
    - Update the manpage to mention lvmlockd and don't mention gfs2_quota
      or gfs_controld (both obsolete).
    - Simplify the setup instructions and refer to distribution-specific
      docs and support requirements.
    - Rearrange the "See also" section for relevance and incorporate the
      references from the setup section.
    
    Signed-off-by: Andrew Price <anprice@redhat.com>

diff --git a/gfs2/man/gfs2.5 b/gfs2/man/gfs2.5
index 56d1a008..436abc09 100644
--- a/gfs2/man/gfs2.5
+++ b/gfs2/man/gfs2.5
@@ -21,6 +21,20 @@ mounts which are equivalent to mounting a read-only block device and as
 such can neither recover a journal or write to the filesystem, so do not
 require a journal assigned to them.
 
+The GFS2 documentation has been split into a number of sections:
+
+\fBmkfs.gfs2\fP(8) Create a GFS2 filesystem
+.br
+\fBfsck.gfs2\fP(8) The GFS2 filesystem checker
+.br
+\fBgfs2_grow\fP(8) Growing a GFS2 filesystem
+.br
+\fBgfs2_jadd\fP(8) Adding a journal to a GFS2 filesystem
+.br
+\fBtunegfs2\fP(8) Tool to manipulate GFS2 superblocks
+.br
+\fBgfs2_edit\fP(8) A GFS2 debug tool (use with caution)
+
 .SH MOUNT OPTIONS
 
 .TP
@@ -200,220 +214,55 @@ versa.  Finally, when first enabling this option on a filesystem that had been
 previously mounted without it, you must make sure that there are no outstanding
 cookies being cached by other software, such as NFS.
 
-.SH BUGS
-
-GFS2 doesn't support \fBerrors=\fP\fIremount-ro\fR or \fBdata=\fP\fIjournal\fR.
-It is not possible to switch support for user and group quotas on and
-off independently of each other. Some of the error messages are rather
-cryptic, if you encounter one of these messages check firstly that gfs_controld
-is running and secondly that you have enough journals on the filesystem
-for the number of nodes in use.
-
-.SH SEE ALSO
-
-\fBmount\fP(8) for general mount options,
-\fBchmod\fP(1) and \fBchmod\fP(2) for access permission flags,
-\fBacl\fP(5) for access control lists,
-\fBlvm\fP(8) for volume management,
-\fBccs\fP(7) for cluster management,
-\fBumount\fP(8),
-\fBinitrd\fP(4).
-
-The GFS2 documentation has been split into a number of sections:
-
-\fBgfs2_edit\fP(8) A GFS2 debug tool (use with caution)
-\fBfsck.gfs2\fP(8) The GFS2 file system checker
-\fBgfs2_grow\fP(8) Growing a GFS2 file system
-\fBgfs2_jadd\fP(8) Adding a journal to a GFS2 file system
-\fBmkfs.gfs2\fP(8) Make a GFS2 file system
-\fBgfs2_quota\fP(8) Manipulate GFS2 disk quotas 
-\fBgfs2_tool\fP(8) Tool to manipulate a GFS2 file system (obsolete)
-\fBtunegfs2\fP(8) Tool to manipulate GFS2 superblocks
-
 .SH SETUP
 
-GFS2 clustering is driven by the dlm, which depends on dlm_controld to
-provide clustering from userspace.  dlm_controld clustering is built on
-corosync cluster/group membership and messaging.
-
-Follow these steps to manually configure and run gfs2/dlm/corosync.
-
-.B 1. create /etc/corosync/corosync.conf and copy to all nodes
-
-In this sample, replace cluster_name and IP addresses, and add nodes as
-needed.  If using only two nodes, uncomment the two_node line.
-See corosync.conf(5) for more information.
-
-.nf
-totem {
-        version: 2
-        secauth: off
-        cluster_name: abc
-}
-
-nodelist {
-        node {
-                ring0_addr: 10.10.10.1
-                nodeid: 1
-        }
-        node {
-                ring0_addr: 10.10.10.2
-                nodeid: 2
-        }
-        node {
-                ring0_addr: 10.10.10.3
-                nodeid: 3
-        }
-}
-
-quorum {
-        provider: corosync_votequorum
-#       two_node: 1
-}
-
-logging {
-        to_syslog: yes
-}
-.fi
-
-.PP
-
-.B 2. start corosync on all nodes
-
-.nf
-systemctl start corosync
-.fi
-
-Run corosync-quorumtool to verify that all nodes are listed.
-
-.PP
-
-.B 3. create /etc/dlm/dlm.conf and copy to all nodes
-
-.B *
-To use no fencing, use this line:
+GFS2 clustering is driven by the dlm, which depends on dlm_controld to provide
+clustering from userspace.  dlm_controld clustering is built on corosync
+cluster/group membership and messaging. GFS2 also requires clustered lvm which
+is provided by lvmlockd or, previously, clvmd. Refer to the documentation for
+each of these components and ensure that they are configured before setting up
+a GFS2 filesystem. Also refer to your distribution's documentation for any
+specific support requirements.
 
-.nf
-enable_fencing=0
-.fi
+Ensure that gfs2-utils is installed on all nodes which mount the filesystem as
+it provides scripts required for correct withdraw event response.
 
-.B *
-To use no fencing, but exercise fencing functions, use this line:
-
-.nf
-fence_all /bin/true
-.fi
-
-The "true" binary will be executed for all nodes and will succeed (exit 0)
-immediately.
-
-.B *
-To use manual fencing, use this line:
-
-.nf
-fence_all /bin/false
-.fi
-
-The "false" binary will be executed for all nodes and will fail (exit 1)
-immediately.
-
-When a node fails, manually run: dlm_tool fence_ack <nodeid>
-
-.B *
-To use stonith/pacemaker for fencing, use this line:
-
-.nf
-fence_all /usr/sbin/dlm_stonith
-.fi
-
-The "dlm_stonith" binary will be executed for all nodes.  If
-stonith/pacemaker systems are not available, dlm_stonith will fail and
-this config becomes the equivalent of the previous /bin/false config.
-
-.B *
-To use an APC power switch, use these lines:
-
-.nf
-device  apc /usr/sbin/fence_apc ipaddr=1.1.1.1 login=admin password=pw
-connect apc node=1 port=1
-connect apc node=2 port=2
-connect apc node=3 port=3
-.fi
-
-Other network switch based agents are configured similarly.
-
-.B *
-To use sanlock/watchdog fencing, use these lines:
-
-.nf
-device wd /usr/sbin/fence_sanlock path=/dev/fence/leases
-connect wd node=1 host_id=1
-connect wd node=2 host_id=2
-unfence wd
-.fi
-
-See fence_sanlock(8) for more information.
-
-.B *
-For other fencing configurations see dlm.conf(5) man page.
-
-.PP
-
-.B 4. start dlm_controld on all nodes
-
-.nf
-systemctl start dlm
-.fi
-
-Run "dlm_tool status" to verify that all nodes are listed.
-
-.PP
-
-.B 5. if using clvm, start clvmd on all nodes
-
-systemctl clvmd start
-
-.PP
-
-.B 6. make new gfs2 file systems
+.B 1. Create the gfs2 filesystem
 
 mkfs.gfs2 -p lock_dlm -t cluster_name:fs_name -j num /path/to/storage
 
-The cluster_name must match the name used in step 1 above.
-The fs_name must be a unique name in the cluster.
-The -j option is the number of journals to create, there must
-be one for each node that will mount the fs.
+The cluster_name must match the name configured in corosync (and thus dlm).
+The fs_name must be a unique name for the filesystem in the cluster.
+The -j option is the number of journals to create; there must
+be one for each node that will mount the filesystem.
 
 .PP
+.B 2. Mount the gfs2 filesystem
 
-.B 7. mount gfs2 file systems
+If you are using a clustered resource manager, see its documentation for
+enabling a gfs2 filesystem resource. Otherwise, run:
 
 mount /path/to/storage /mountpoint
 
 Run "dlm_tool ls" to verify the nodes that have each fs mounted.
 
 .PP
+.B 3. Shut down
 
-.B 8. shut down
+If you are using a clustered resource manager, see its documentation for
+disabling a gfs2 filesystem resource. Otherwise, run:
 
-.nf
 umount -a -t gfs2
-systemctl clvmd stop
-systemctl dlm stop
-systemctl corosync stop
-.fi
 
 .PP
+.SH SEE ALSO
 
-.B More setup information:
-.br
-.BR dlm_controld (8),
-.br
-.BR dlm_tool (8),
-.br
-.BR dlm.conf (5),
-.br
-.BR corosync (8),
-.br
-.BR corosync.conf (5)
-.br
+\fBmount\fP(8) and \fBumount\fP(8) for general mount information,
+\fBchmod\fP(1) and \fBchmod\fP(2) for access permission flags,
+\fBacl\fP(5) for access control lists,
+\fBlvm\fP(8) for volume management,
+\fBdlm_controld\fP(8),
+\fBdlm_tool\fP(8),
+\fBdlm.conf\fP(5),
+\fBcorosync\fP(8),
+\fBcorosync.conf\fP(5),