cluster: STABLE3 - man pages: cluster.conf, groupd

[David Teigland <teigland at fedoraproject dot org>]

Gitweb:        http://git.fedorahosted.org/git/cluster.git?p=cluster.git;a=commitdiff;h=a7cd2dc21064447c673bb93f398e2ca006e27643
Commit:        a7cd2dc21064447c673bb93f398e2ca006e27643
Parent:        6a06bdb5f64f394f141c3848e7d7534a0e4ee695
Author:        David Teigland <teigland@redhat.com>
AuthorDate:    Thu Feb 19 16:44:41 2009 -0600
Committer:     David Teigland <teigland@redhat.com>
CommitterDate: Thu Feb 19 16:53:58 2009 -0600

man pages: cluster.conf, groupd

The cluster.conf logging info still needs some work, not sure
if all the corosync services are included.  Also, not sure what
level messages corosync services send to syslog, if any, I've not
seen any.

Signed-off-by: David Teigland <teigland@redhat.com>
---
 config/man/cluster.conf.5 |  207 ++++++++++++++++++++++++++++++++++++++++-----
 group/man/groupd.8        |   66 ++++++++++++--
 2 files changed, 240 insertions(+), 33 deletions(-)

diff --git a/config/man/cluster.conf.5 b/config/man/cluster.conf.5
index b45d410..e951815 100644
--- a/config/man/cluster.conf.5
+++ b/config/man/cluster.conf.5
@@ -5,30 +5,52 @@ cluster.conf - configuration file for cman, fence, dlm, gfs, rgmanager
 
 .SH DESCRIPTION
 
-The \fBcluster.conf\fP file is located in the /etc/cluster directory.  It
-is the source of information used by cman, fence, dlm, gfs and rgmanager.
-It's accessed indirectly through libccs (see \fBccs(7)\fP).  This file
-contains all the information needed for the cluster to operate, such as
-what nodes are in the cluster and how to I/O fence those nodes.
-
-This man page describes the generic contents of the \fBcluster.conf\fP
-file.  For other information see man pages for cman(5), fenced(8) and
-dlm_controld(8).
-
-\fBcluster.conf\fP is an XML file.  It has one top-level \fIcluster\fP
-section containing everything else.  The cluster section has two mandatory
-attributes: \fIname\fP and \fIconfig_version\fP.  \fIname\fP can be up to
-16 characters long and specifies the name of the cluster.  It is important
-that this name is unique from other clusters the user might set up.
-\fIconfig_version\fP is a number used to identify the revision level of
-the \fBcluster.conf\fP file.  Given this information, your
-\fBcluster.conf\fP file might look something like:
+The /etc/cluster/cluster.conf file contains configuration for:
+
+.B cman(5)
+for corosync and quorum configuration
+.br
+.B qdisk(5)
+for quorum disk configuration
+.br
+.B groupd(8)
+for daemon configuration
+.br
+.B fenced(8)
+for daemon and fence device configuration
+.br
+.B dlm_controld(8)
+for daemon configuration
+.br
+.B gfs_controld(8)
+for daemon configuration
+.br
+.B rgmanager(8)
+for daemon and resource configuration
+
+The same cluster.conf file must exist on each cluster node.
+
+When cman_tool starts corosync, the contents of cluster.conf are loaded into
+the corosync in-memory configuration database (confdb).  Daemons and programs
+listed above use the libccs library to read cluster.conf data from the
+corosync confdb.  (The libconfdb library can also be used for more general,
+non-xml confdb queries.)
+
+When cman configures corosync using cluster.conf, the corosync.conf file is
+not used.
+
+.SS Cluster Nodes
+
+cluster.conf is an XML file.  It has one top-level \fIcluster\fP section
+containing everything else.  The cluster section has two mandatory attributes:
+\fIname\fP and \fIconfig_version\fP.  \fIname\fP can be up to 16 characters
+long and specifies the name of the cluster.  It is important that this name is
+unique from other clusters.  \fIconfig_version\fP is a number used to identify
+the revision level of the cluster.conf file.
 
   <cluster name="alpha" config_version="1">
   </cluster>
 
-.SS Nodes
-
 The set of nodes that make up the cluster are defined under the
 \fIclusternodes\fP section.  A \fIclusternode\fP section defines each
 node.  A clusternode has two mandatory attributes:
@@ -53,9 +75,148 @@ communication.  Nodeid's must be greater than zero and unique.
           </clusternodes>
   </cluster>
 
-The next step in completing cluster.conf is adding fencing information;
-see fenced(8).
+.SS Logging
+
+All daemons listed above use the <logging> section to configure loggging.
+Global settings apply to all:
+.br
+  <logging debug="on"/>
+
+Per-daemon/subsys settings override the corresponding global setting:
+.br
+  <logging>
+      <logging_subsys["foo"] debug="on"/>
+      <logging_subsys["bar"] debug="on"/>
+  </logging>
+
+.B Subsystems
+
+The logging_subsys daemons/subsystems that can be configured include
+
+daemon names:
+.br
+qdiskd, groupd, fenced, dlm_controld, gfs_controld, rgmanager
+
+corosync subsystems:
+.br
+CLM, CPG, MAIN, SERV, CMAN, TOTEM, QUORUM, CONFDB
+
+.B Settings
+
+The settings available both at the global and subsystem level are
+
+.B to_syslog
+.br
+enable/disable messages to syslog (yes/no)
+.br
+default "yes"
+
+.B to_logfile
+.br
+enable/disable messages to log file (yes/no)
+.br
+default "yes"
+
+.B syslog_facility
+.br
+facility used for syslog messages
+.br
+default "daemon"
+
+.B syslog_priority
+.br
+messages at this level and up will be sent to syslog
+.br
+default "info"
+
+.B logfile_priority
+.br
+messages at this level and up will be written to log file
+.br
+default "info"
+
+.B logfile
+.br
+the log file name, default /var/log/cluster/<daemon>.log
+
+.B debug="on"
+.br
+is a shortcut for logfile_priority="debug"
+
+.B Defaults
+
+An explicit configuration for the default settings would be:
+
+<logging to_syslog="yes" to_logfile="yes" syslog_facility="daemon"
+         syslog_priority="info" logfile_priority="info">
+.br
+    <logging_subsys["groupd"]
+             logfile="/var/log/cluster/groupd.log"/>
+.br
+    <logging_subsys["fenced"]
+             logfile="/var/log/cluster/fenced.log"/>
+.br
+    <logging_subsys["dlm_controld"]
+             logfile="/var/log/cluster/dlm_controld.log"/>
+.br
+    <logging_subsys["gfs_controld"]
+             logfile="/var/log/cluster/gfs_controld.log"/>
+.br
+    <logging_subsys["rgmanager"]
+             logfile="/var/log/cluster/rgmanager.log"/>
+.br
+    <logging_subsys["CLM"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+    <logging_subsys["CPG"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+    <logging_subsys["MAIN"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+    <logging_subsys["SERV"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+    <logging_subsys["CMAN"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+    <logging_subsys["TOTEM"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+    <logging_subsys["QUORUM"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+    <logging_subsys["CONFDB"]
+             logfile="/var/log/cluster/cman.log"/>
+.br
+</logging>
+
+.B Examples
+
+To include LOG_DEBUG messages (and above) from all daemons/subsystems in their default log files, either
+.in +7
+<logging debug="on"/> or
+.in -7
+.in +7
+<logging logfile_priority="debug"/>
+.in -7
+
+To exclude all log messages from syslog
+.in +7
+<logging to_syslog="no"/>
+.in -7
+
+To disable logging to all log files
+.in +7
+<logging to_file="no"/>
+.in -7
+
+To include LOG_DEBUG messages (and above) from all daemons/subsystems in syslog
+.in +7
+<logging syslog_priority="debug"/>
+.in -7
+
 
 .SH SEE ALSO
-ccs(7), ccs_tool(8), ccsd(8), cman(5), fenced(8), dlm_controld(8)
+cman(5), qdisk(5), groupd(8), fenced(8), dlm_controld(8), gfs_controld(8), rgmanager(8)
 
diff --git a/group/man/groupd.8 b/group/man/groupd.8
index 634d0a0..3a0677e 100644
--- a/group/man/groupd.8
+++ b/group/man/groupd.8
@@ -11,22 +11,68 @@ groupd
 .SH DESCRIPTION
 
 The group daemon, groupd, provides a compatibility layer between the
-openais closed process group (CPG) service and the fenced, dlm_controld
-and gfs_controld daemons.  groupd and its associated libgroup interface
-will go away in the future as the fencing, dlm and gfs daemons are ported
-to use the libcpg interfaces directly.  groupd translates and buffers cpg
-events between openais's cpg service and the fence/dlm/gfs systems that
-use it.  CPG's are used to represent the membership of the fence domain,
-dlm lockspaces and gfs mount groups.
+corosync closed process group (CPG) service and the fenced, dlm_controld
+and gfs_controld daemons.  New versions of fenced/dlm_controld/gfs_controld
+no longer require this compat layer, and can run without groupd.  They use
+libcpg directly, making them much more robust.  This makes them incompatible
+with old (cluster2) versions.  Enable this new mode with:
 
-groupd is also a convenient place to query the status of the fence, dlm
-and gfs groups.  This is done by the group_tool program.
+	<groupd groupd_compat="0"/>
 
+This should be added to the configuration (cluster.conf) before a cluster is
+restarted following an upgrade of all nodes.
+
+If compatibility with old (cluster2) nodes is necessary (mixing cluster2 and
+cluster3 nodes should be avoided), the daemons can be run in the old mode,
+using groupd as before.  Enable this mode with:
+
+	<groupd groupd_compat="1"/>
+
+.B Rolling Upgrades
+
+In the absence of any groupd_compat setting,
+groupd/fenced/dlm_controld/gfs_controld default to a third option,
+groupd_compat="2", which supports rolling upgrades.  In this mode, groupd
+initially tries to detect nodes running an old cluster2 version of groupd.  If
+any are found, it will run in the compat mode (groupd_compat="1"), otherwise
+it will run in the new mode (groupd_compat="0").  The other daemons will take
+the final groupd_compat result (0 or 1) from groupd.
+
+This groupd_compat="2" mode only supports rolling upgrades, and will not
+support mixing cluster2 and cluster3 nodes in general.  Once all nodes are
+upgraded, the first full cluster restart should be used to specify the new
+mode <groupd groupd_compat="0"/> in the configuration (cluster.conf).
+
+.B Logging
+
+By default, log messages at INFO level and above are sent to both
+\fBsyslog\fP(3) and /var/log/cluster/groupd.log.  For complete logging
+configuration options see \fBcluster.conf\fP(5).
 
 .SH OPTIONS
 .TP
 \fB-D\fP
-Run the daemon in the foreground and print debug statements to stdout.
+Enable debugging to stderr and don't fork
+.TP
+\fB-L\fP
+Enable debugging to log file (see above)
+.TP
+\fB-g <num>\fP
+group compatibility mode, 0 off, 1 on, 2 detect
+.br
+0: use libcpg, no backward compat, best performance
+.br
+1: use libgroup for compat with cluster2/rhel5
+.br
+2: detect old, or mode 1, nodes that require compat
+.TP
+\fB-w <secs>\fP
+seconds to wait for a node's version message before
+assuming an old version requiring compat mode
+.TP
+\fB-d <secs>\fP
+seconds to delay the mode selection to give time
+for an old version to join and force compat mode
 .TP
 \fB-V\fP
 Print the version information and exit.