commit b200a8c861c6f81ae872b1cf51cbec4db2a64a2a
Author: Ken Gaillot <kgaillot@redhat.com>
Date:   Fri Oct 7 10:53:36 2016 -0500

    Doc: mcp: improve comments for sysconfig options

Index: pacemaker/mcp/pacemaker.sysconfig
===================================================================
--- pacemaker.orig/mcp/pacemaker.sysconfig
+++ pacemaker/mcp/pacemaker.sysconfig
@@ -1,96 +1,128 @@
 # For non-systemd based systems, prefix export to each enabled line
 
-# Turn on special handling for CMAN clusters in the init script
-# Without this, fenced (and by inference, cman) cannot reliably be made to shut down
+# If pacemaker is started via init script, the script may attempt to detect the
+# cluster layer in use. This option forces it to recognize a particular type,
+# in case its detection is inaccurate. Currently, the only value that is
+# significant is "cman", which will cause the init script to start and stop
+# important ancillary services so that services such as fenced and cman can
+# reliably shut down. Any other value is ignored. The default is unset.
 # PCMK_STACK=cman
 
 #==#==# Variables that control logging
 
-# Enable debug logging globally or per-subsystem
-# Multiple subsystems may me listed separated by commas
-# eg. PCMK_debug=crmd,pengine
+# Enable debug logging globally or per-subsystem.
+# Multiple subsystems may be listed separated by commas,
+# e.g. PCMK_debug=crmd,pengine
 # PCMK_debug=yes|no|crmd|pengine|cib|stonith-ng|attrd|pacemakerd
 
-# Send INFO (and higher) messages to the named log file
-# Additional messages may also appear here depending on any configured debug and trace settings
-# By default Pacemaker will inherit the logfile specified in corosync.conf
+# Send detailed log messages to the specified file. Compared to messages logged
+# via syslog, messages in this file may have extended information, and will
+# include messages of "info" severity (and, if debug and/or trace logging
+# has been enabled, those as well). This log is of more use to developers and
+# advanced system administrators, and when reporting problems. By default,
+# Pacemaker will use the value of logfile in corosync.conf, if found.
 # PCMK_logfile=/var/log/pacemaker.log
 
-# Specify an alternate syslog target for NOTICE (and higher) messages
-# Use 'none' to disable - not recommended
-# The default value is 'daemon'
+# Enable logging via syslog, using the specified syslog facility. Messages sent
+# here are of value to all Pacemaker users. This can be disabled using "none",
+# but that is not recommended. The default is "daemon".
 # PCMK_logfacility=none|daemon|user|local0|local1|local2|local3|local4|local5|local6|local7
 
-# Send all messages up-to-and-including the configured priority to syslog
-# A value of 'info' will be far too verbose for most installations and 'debug' is almost certain to send you blind
-# The default value is 'notice'
+# Unless syslog logging is disabled using PCMK_logfacility=none, messages of
+# the specified severity and higher will be sent to syslog. The default value
+# of "notice" is appropriate for most installations; "info" is highly verbose
+# and "debug" is almost certain to send you blind (which is why there is a
+# separate detail log specified by PCMK_logfile).
 # PCMK_logpriority=emerg|alert|crit|error|warning|notice|info|debug
 
-# Log all messages from a comma-separated list of functions
+# Log all messages from a comma-separated list of functions.
 # PCMK_trace_functions=function1,function2,function3
 
-# Log all messages from a comma-separated list of files (no path)
-# Supports wildcards eg. PCMK_trace_files=prefix*.c
+# Log all messages from a comma-separated list of files (no path).
+# Wildcards are supported, e.g. PCMK_trace_files=prefix*.c
 # PCMK_trace_files=file.c,other.h
 
-# Log all messages matching comma-separated list of formats
+# Log all messages matching comma-separated list of formats.
 # PCMK_trace_formats="Sent delete %d"
 
-# Log all messages from a comma-separated list of tags
+# Log all messages from a comma-separated list of tags.
 # PCMK_trace_tags=tag1,tag2
 
-# Dump the blackbox whenever the message at function and line is printed
-# eg. PCMK_trace_blackbox=te_graph_trigger:223,unpack_clone:81
+# Dump the blackbox whenever the message at function and line is printed,
+# e.g. PCMK_trace_blackbox=te_graph_trigger:223,unpack_clone:81
 # PCMK_trace_blackbox=fn:line,fn2:line2,...
 
-# Enable blackbox logging globally or per-subsystem
-# The blackbox contains a rolling buffer of all logs (including info+debug+trace)
-# and is written after a crash, assertion failure and/or when SIGTRAP is received
-#
-# The blackbox recorder can also be enabled for Pacemaker daemons at runtime by 
-# sending SIGUSR1 (or SIGTRAP), and disabled by sending SIGUSR2
-#
-# Multiple subsystems may me listed separated by commas
-# eg. PCMK_blackbox=crmd,pengine
+# Enable blackbox logging globally or per-subsystem. The blackbox contains a
+# rolling buffer of all logs (including info, debug, and trace) and is written
+# after a crash or assertion failure, and/or when SIGTRAP is received. The
+# blackbox recorder can also be enabled for Pacemaker daemons at runtime by
+# sending SIGUSR1 (or SIGTRAP), and disabled by sending SIGUSR2. Multiple
+# subsystems may me listed separated by commas, e.g. PCMK_blackbox=crmd,pengine
 # PCMK_blackbox=yes|no|crmd|pengine|cib|stonith-ng|attrd|pacemakerd
 
 #==#==# Advanced use only
 
-# Enable this for compatibility with older corosync (prior to 2.0)
-# based clusters which used the nodes uname as its uuid also
-# PCMK_uname_is_uuid=no
+# If the cluster uses an older version of corosync (prior to 2.0), set this to
+# "true", which will use a node's uname as its UUID. The default, "false", is
+# appropriate for newer versions of corosync, and will use a node's corosync ID
+# as its UUID. It is ignored by clusters that do not use corosync.
+# PCMK_uname_is_uuid=false
 
-# Specify an alternate location for RNG schemas and XSL transforms
-# Mostly only useful for developer testing
+# Specify an alternate location for RNG schemas and XSL transforms.
+# (This is of use only to developers.)
 # PCMK_schema_directory=/some/path
 
-# Enable this for rebooting this machine at the time of process (subsystem) failure
+# Pacemaker consists of a master process with multiple subsidiary daemons. If
+# one of the daemons crashes, the master process will normally attempt to
+# restart it. If this is set to "true", the master process will instead panic
+# the host. The default is unset.
 # PCMK_fail_fast=no
 
 #==#==# Pacemaker Remote
-# Use a custom directory for finding the authkey.
+# Use the contents of this file as the authorization key to use with Pacemaker
+# Remote connections. This file must be readable by Pacemaker daemons (that is,
+# it must allow read permissions to either the hacluster user or the haclient
+# group), and its contents must be identical on all nodes. The default is
+# "/etc/pacemaker/authkey".
 # PCMK_authkey_location=/etc/pacemaker/authkey
-#
-# Specify a custom port for Pacemaker Remote connections
+
+# Use this TCP port number when connecting to a Pacemaker Remote node. This
+# value must be the same on all nodes. The default is "3121".
 # PCMK_remote_port=3121
 
 #==#==# IPC
 
-# Force use of a particular class of IPC connection
+# Force use of a particular class of IPC connection.
 # PCMK_ipc_type=shared-mem|socket|posix|sysv
 
-# Specify an IPC buffer size in bytes
-# Useful when connecting to really big clusters that exceed the default 128k buffer
+# Specify an IPC buffer size in bytes. This is useful when connecting to really
+# big clusters that exceed the default 128KB buffer.
 # PCMK_ipc_buffer=131072
 
-#==#==# Profiling and memory leak testing
+#==#==# Profiling and memory leak testing (mainly useful to developers)
 
-# Variables for running child daemons under valgrind and/or checking for memory problems
+# Affect the behavior of glib's memory allocator. Setting to "always-malloc"
+# when running under valgrind will help valgrind track malloc/free better;
+# setting to "debug-blocks" when not running under valgrind will perform
+# (somewhat expensive) memory checks.
 # G_SLICE=always-malloc
-# MALLOC_PERTURB_=221 # or 0
-# MALLOC_CHECK_=3     # or 0,1,2
+
+# Uncommenting this will make malloc() initialize newly allocated memory
+# and free() wipe it (to help catch uninitialized-memory/use-after-free).
+# MALLOC_PERTURB_=221
+
+# Uncommenting this will make malloc() and friends print to stderr and abort
+# for some (inexpensive) memory checks.
+# MALLOC_CHECK_=3
+
+# Set to yes/no or cib,crmd etc. to run some or all daemons under valgrind.
 # PCMK_valgrind_enabled=yes
 # PCMK_valgrind_enabled=cib,crmd
+
+# Set to yes/no or cib,crmd etc. to run some or all daemons under valgrind with
+# the callgrind tool enabled.
 # PCMK_callgrind_enabled=yes
 # PCMK_callgrind_enabled=cib,crmd
+
+# Set the options to pass to valgrind, when valgrind is enabled.
 # VALGRIND_OPTS="--leak-check=full --trace-children=no --num-callers=25 --log-file=/var/lib/pacemaker/valgrind-%p --suppressions=/usr/share/pacemaker/tests/valgrind-pcmk.suppressions --gen-suppressions=all"
