From 694237c7b7857ff18b5057758b5550162cc85149 Mon Sep 17 00:00:00 2001
From: David Teigland <teigland@redhat.com>
Date: Fri, 15 Oct 2021 12:12:18 -0500
Subject: [PATCH 14/14] man page updates

---
 dlm_controld/dlm.conf.5 |  21 ++--
 dlm_tool/dlm_tool.8     | 224 ++++++++++++++--------------------------
 2 files changed, 81 insertions(+), 164 deletions(-)

diff --git a/dlm_controld/dlm.conf.5 b/dlm_controld/dlm.conf.5
index 99e302a92bd2..0eb226358100 100644
--- a/dlm_controld/dlm.conf.5
+++ b/dlm_controld/dlm.conf.5
@@ -22,7 +22,7 @@ for descriptions and dlm_controld -h for defaults.
 
 Format:
 
-key=val
+setting=value
 
 Example:
 
@@ -77,23 +77,14 @@ repeat_failed_fencing(*)
 enable_helper
 .br
 
-Option with tail (*) means this item can be reload on the fly by "dlm_tool reload_config". See \fB"Reload config"\fP for more examples.
+Options with (*) can be reloaded, see Reload config.
 
 .SH Reload config
 
-dlm.conf can be changed then reloaded some settings on the fly, it gives users more flexible and powerful ability to manage dlm.
-
-The supported reload operations:
-.br
-- add a new item
-.br
-- remove an exist item
-.br
-- commented out an item
-.br
-- change an item value
-
-After modifying settings in dlm.conf, run "dlm_tool reload_config" to take effect. User can use "dlm_tool dump_config" to check the result. Again, only reloadable item can be changed.
+Some dlm.conf settings can be changed while dlm_controld is running using
+dlm_tool reload_config.  Edit dlm.conf, adding, removing, commenting or
+changing values, then run dlm_tool reload_config to apply the changes in
+dlm_controld.  dlm_tool dump_config will show the new settings.
 
 .SH Fencing
 
diff --git a/dlm_tool/dlm_tool.8 b/dlm_tool/dlm_tool.8
index f6d869620822..2a14fe0292a7 100644
--- a/dlm_tool/dlm_tool.8
+++ b/dlm_tool/dlm_tool.8
@@ -32,45 +32,45 @@ dlm_tool \- a utility for the dlm and dlm_controld daemon
 .br
 	Reload dlm_controld config settings from dlm.conf.
 
-.B set_config
+.BI set_config " setting" = "value"
 .br
-	Set dlm_controld config settings on the fly.
+	Set dlm_controld config settings in the currently running daemon.
 
 .BI fence_ack " nodeid"
 .br
-	Quit trying to fence a node.
+	Cancel a waiting fencing operation and consider it successful.
 
 .B log_plock
 .br
 	Dump dlm_controld plock debug buffer.
 
-.BI plocks " name"
+.BI plocks " lockspace_name"
 .br
 	Dump posix locks from dlm_controld for the lockspace.
 
-.BI join " name"
+.BI join " lockspace_name"
 .br
 	Join a lockspace.
 
-.BI leave " name"
+.BI leave " lockspace_name"
 .br
 	Leave a lockspace.
 
-.BI joinleave " name"
+.BI joinleave " lockspace_name"
 .br
-	Do two actions: first Join then Leave a lockspace. (mainly for test)
+	Join then immediately leave a lockspace (for testing only.)
 
-.BI lockdebug " name"
+.BI lockdebug " lockspace_name"
 .br
 	Complete display of locks from the lockspace.
 
-.BI lockdump " name"
+.BI lockdump " lockspace_name"
 .br
 	Minimal display of locks from the lockspace (deprecated).
 
 .BI run " command"
 .br
-	Run command and check for result.
+	Run command and check for result (for lvmlockd only.)
 
 .BI run_start " command"
 .br
@@ -92,7 +92,7 @@ dlm_tool \- a utility for the dlm and dlm_controld daemon
 .SH OPTIONS
 
 .B \-n
-Show all node information in ls.
+Show all node information from dlm_tool ls.
 
 .B \-d
 0|1 Resource directory off/on in join, default 0
@@ -103,6 +103,9 @@ Show all node information in ls.
 .B \-f
 0|1 FS (filesystem) flag off/on in join, default 0
 
+.BI \-i " sec"
+Seconds to wait in run_check.
+
 .BI \-m " mode"
 Permission mode for lockspace device (octal), default 0600
 
@@ -110,7 +113,7 @@ Permission mode for lockspace device (octal), default 0600
 Summary following lockdebug output (experiemental)
 
 .B \-v
-Verbose lockdebug output
+Verbose lockdebug or status output
 
 .B \-w
 Wide lockdebug output
@@ -124,102 +127,20 @@ Print help, then exit
 .B \-V
 Print program version information, then exit
 
-.SH USAGE
-
-.B dlm_tool ls [-n] [ls_name]
-
--
-
-.B dlm_tool status [-v]
-
--
-
-.B dlm_tool dump
-
--
-
-.B dlm_tool dump_config
-
--
-
-.B dlm_tool reload_config
-
-* see examples in \fBdlm.conf(5)\fP
-
--
-
-.B dlm_tool set_config "dlm_controld-config-item=x"
-
-* see below \fBset_config EXAMPLES\fP section
-
--
-
-.B dlm_tool fence_ack \fInodeid\fP
-
-* run "dlm_tool status -v" to get \fInodeid\fP
-
--
-
-.B dlm_tool log_plock
-
--
-
-.B dlm_tool plocks \fIls-name\fP
-
--
-
-.B dlm_tool join [-e 0|1] [-f 0|1] \fIls-name\fP
-
--
-
-.B dlm_tool leave \fIls-name\fP
 
--
-
-.B dlm_tool joinleave [-e 0|1] [-f 0|1] \fIls-name\fP
-
--
-
-.B dlm_tool lockdebug [-s] [-v] [-w] \fIls-name\fP
-
--
-
-.B dlm_tool lockdump [-M] \fIls-name\fP
-
--
-
-.B dlm_tool run|run_start [-n] \fIcommand\fP
-
-* current run & run_start support \fIcommand\fP:
-.
-  - "lvm lvchange --refresh"
-.
-  - "lvm lvs"
-
--
-
-.B dlm_tool run_check|run_cancel [-i "sec"] \fIuuid\fP
-
--
-
-.B dlm_tool run_list
-
--
-
-.B dlm_tool -h
-
--
+.SH USAGE
 
-.B dlm_tool -V
+.SS fence_ack
 
-.SH set_config EXAMPLES
+See dlm_tool status for information about waiting fencing operations for
+specific nodeid's.
 
-\fIdlm_tool set_config "xxx"\fP can do the dynamic config job. It makes possible to debug, or to do flexible operations on the fly.
+.SS set_config
 
-supported option items
+dlm_tool set_config can change certain config settings in the currently
+running dlm_controld.  Supported options:
 
-.RS
-.EX
+.nf
 daemon_debug
 log_debug
 debug_logfile
@@ -232,101 +153,106 @@ post_join_delay
 enable_quorum_fencing
 enable_quorum_lockspace
 repeat_failed_fencing
-.EE
-.RE
+.fi
 
-.SS display style
+Special cases to revert a previous set_config and restore the previous
+value (from default or dlm.conf):
 
-Currently, there are 5 ways of setting: default, cli, dlm.conf, reload_config, set_config
+\fBdlm_tool set_config\fP \fIsetting\fP=\fBrestore\fP
+.br
+restores a single setting.
 
-The "dlm_tool dump_config" shows the config item by 4 styles.
+\fBdlm_tool set_config restore_all\fP
+.br
+restores all settings.
 
-.TP
-key=val
-For default values that have not been set by cli or config file or dynamically.
+.SS dump_config
+
+A config setting may have been set from: the default, the dlm_controld
+command line, dlm.conf at startup, dlm.conf from reload_config, dlm_tool
+set_config.  The dump_config output indicates how values were set:
 
 .TP
-key=val (cli option)
-For values that have been last set from a command line option.
+setting=value
+default value.
 
 .TP
-key=val (dlm.conf)
-For values that have been last set from dlm.conf. (reload_config also belongs to this style)
+setting=value (cli option)
+Set from a dlm_controld command line option.
 
 .TP
-key=val (set_config)
-For values that have been last set by dlm_tool set_config.
+setting=value (dlm.conf)
+Set from dlm.conf (at startup or reload.)
 
 .TP
-i.e.
+setting=value (set_config)
+Set from dlm_tool set_config.
 
-.EX
-# dlm_tool dump_config | head -n 5
+
+.SH EXAMPLES
+
+.SS dump_config
+
+.nf
+$ dlm_tool dump_config | head -n 5
 daemon_debug=1 (set_config)
 foreground=0
 log_debug=1 (dlm.conf)
 timewarn=0
 protocol=detect
-.EE
+.fi
 
-In this case, the "daemon_debug" is set by set_config, the "log_debug" is set by dlm.conf.
-meanwhile foreground, timewarn & protocol are using default values.
+In this case, daemon_debug is set by set_config, log_debug is set from
+dlm.conf, foreground, timewarn and protocol are using default values.
 
-.SS set_config usage
+.SS set_config
 
-log_debug is set by dlm.conf (value is 1), then run "set_config" to change to 0. at last use "restore" to restore to dlm.conf setting.
-
-.RS
-.EX
-# dlm_tool dump_config | grep log_debug
+.nf
+$ dlm_tool dump_config | grep log_debug
 log_debug=1 (dlm.conf)
 
-# dlm_tool set_config "log_debug=0"
+$ dlm_tool set_config "log_debug=0"
 set_config done
 
-# dlm_tool dump_config | grep log_debug
+$ dlm_tool dump_config | grep log_debug
 log_debug=0 (set_config)
 
-# dlm_tool set_config "log_debug=restore"
+$ dlm_tool set_config "log_debug=restore"
 set_config done
 
-# dlm_tool dump_config | grep log_debug
+$ dlm_tool dump_config | grep log_debug
 log_debug=1 (dlm.conf)
-.EE
-.RE
-
-restore method
+.fi
 
-Once user uses "set_config key=val" to change value, whatever user sets 0 or 1, the related item belongs to "set_config" type. There are 2 ways to do restoration job: key=restore, restore_all
+log_debug is set by dlm.conf (value is 1), then run set_config to change
+to 0, then use restore to restore to dlm.conf setting.
 
-restore - to reset single option item (see above example)
 
-restore_all -  to reset all set_config items.
+.SS set_config
 
-.RS
-.EX
-# dlm_tool dump_config | grep _debug
+.nf
+$ dlm_tool dump_config | grep _debug
 daemon_debug=0
 log_debug=1 (dlm.conf)
 plock_debug=0
 
-# dlm_tool set_config "daemon_debug=1 log_debug=1 plock_debug=1"
+$ dlm_tool set_config "daemon_debug=1 log_debug=1 plock_debug=1"
 set_config done
 
-# dlm_tool dump_config | grep _debug
+$ dlm_tool dump_config | grep _debug
 daemon_debug=1 (set_config)
 log_debug=1 (set_config)
 plock_debug=1 (set_config)
 
-# dlm_tool set_config "restore_all"
+$ dlm_tool set_config "restore_all"
 set_config done
 
-# dlm_tool dump_config | grep _debug
+$ dlm_tool dump_config | grep _debug
 daemon_debug=0
 log_debug=1 (dlm.conf)
 plock_debug=0
-.EE
-.RE
+.fi
+
 
 .SH SEE ALSO
 .BR dlm_controld (8),
-- 
2.33.0

