LU-4315 doc: split lctl get_param and set_param man pages

Split the "lctl get_param" and "lctl set_param" commands from
"lctl.8" into their own man pages, and improve the description
and examples for each.

Still need to split "lctl list_param" and "lctl conf_param" in
a separate patch.

Test-Parameters: trivial
Signed-off-by: Andreas Dilger <adilger@whamcloud.com>
Change-Id: Ia03fe707af9bbcaad7a3c4da903d8dfbd23ebbe5
Reviewed-on: https://review.whamcloud.com/35242
Tested-by: jenkins <devops@whamcloud.com>
Reviewed-by: Joseph Gmitter <jgmitter@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: Olaf Faaland-LLNL <faaland1@llnl.gov>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am
index 987b25f..cedb602 100644 (file)
--- a/lustre/doc/Makefile.am
+++ b/lustre/doc/Makefile.am
@@ -34,7 +34,9 @@
 
 MANFILES =                                     \
        lctl.8                                  \
+       lctl-get_param.8                        \
        lctl-network.8                          \
+       lctl-set_param.8                        \
        ldev.8                                  \
        ldev.conf.5                             \
        lfs.1                                   \

diff --git a/lustre/doc/lctl-get_param.8 b/lustre/doc/lctl-get_param.8
new file mode 100644 (file)
index 0000000..59449ed
--- /dev/null
+++ b/lustre/doc/lctl-get_param.8
@@ -0,0 +1,79 @@
+.TH lctl 8 "2019 Jun 17" Lustre "configuration utilities"
+.SH NAME
+lctl get_param \- retrieve tunable parameters
+.SH SYNOPSIS
+.br
+.IR "\fBlctl get_param " [ -F "] [" -n | -N "] [" -R "] <" parameter ...>
+.br
+.SH DESCRIPTION
+Get the value of the named Lustre or LNet
+.I parameter
+on the local node.  Parameter names consist of one or more components,
+separated by a '.' (period).  Each component may be specified by plain text
+or by a wildcard in the
+.BR glob (7)
+format.  When wildcards are used, more than one parameter may match and
+be returned.  Parameters are often, but not always, of the form
+.IR obd_name.obd_instance.parameter_name ,
+where
+.I obd_name
+is one of the OBD object types, like
+.BR ldlm ", " llite ", " lmv ", " lov ", " mdc ", " osc ,
+etc., and
+.I obd_instance
+is the name of a Lustre device, like
+.BR testfs-OST0000 ,
+but may be a specific component, or contain wildcards to match some or all
+devices on the node.  Many parameters are readable as a regular user, though
+some of them are accessible only by the root user for security or
+implementation reasons.
+.SH OPTIONS
+.TP
+.B -F
+Append a '/', '@', or '=' suffix for directories, symlinks, and writeable
+parameters, respectively.
+.B "lctl get_param -NF"
+is equivalent to
+.BR "lctl list_param -F" .
+.TP
+.B -n
+Print only the parameter value and not parameter name.  This may be confusing
+if multiple parameter names are specified, as the parameters are not
+identified, and may not be returned in the order that they are specified.
+.TP
+.B -N
+Print only matched parameter names and not the values. This is especially
+useful when using patterns.
+.TP
+.B -R
+Recursively show all of the parameter names below the specified name.
+.SH EXAMPLES
+.B $ lctl get_param osc.*.max_pages_per_rpc
+.br
+osc.myth-OST0000-osc-ffff8803c9c0f000.max_pages_per_rpc=1024
+.br
+osc.myth-OST0001-osc-ffff8803c9c0f000.max_pages_per_rpc=1024
+.br
+osc.testfs-OST0000-osc-ffff8803c9c0f000.max_pages_per_rpc=1024
+.br
+osc.testfs-OST0001-osc-ffff8803c9c0f000.max_pages_per_rpc=1024
+.br
+osc.testfs-OST0002-osc-ffff8803c9c0f000.max_pages_per_rpc=1024
+.br
+.B $ lctl get_param -n debug
+.br
+super warning dlmtrace error emerg rpctrace vfstrace config console
+.br
+.B $ lctl get_param {mdc,osc}.testfs-*.max_rpcs_in_flight
+.br
+mdc.testfs-MDT0000-mdc-ffff8803c9c0f000.max_rpcs_in_flight=16
+.br
+osc.testfs-OST0000-osc-ffff8803c9c0f000.max_rpcs_in_flight=8
+.br
+osc.testfs-OST0001-osc-ffff8803c9c0f000.max_rpcs_in_flight=8
+.br
+osc.testfs-OST0002-osc-ffff8803c9c0f000.max_rpcs_in_flight=8
+.SH SEE ALSO
+.BR lustre (7),
+.BR lctl (8),
+.BR lctl-set_param (8)

diff --git a/lustre/doc/lctl-set_param.8 b/lustre/doc/lctl-set_param.8
new file mode 100644 (file)
index 0000000..033df02
--- /dev/null
+++ b/lustre/doc/lctl-set_param.8
@@ -0,0 +1,96 @@
+.TH lctl 8 "2019 Jun 17" Lustre "configuration utilities"
+.SH NAME
+lctl set_param \- Low level Lustre filesystem configuration utility
+.SH SYNOPSIS
+.IR "\fBlctl set_param " [ -n "] [" -P "] [" -d "] <" parameter \B= value ...>
+.br
+.IR "\fBlctl set_param -F " < filename >
+.SH DESCRIPTION
+Set the value of the named Lustre or LNet
+.I parameter
+to
+.I value
+on the local node.  Parameter names consist of one or more components,
+separated by a '.' (period).  Each component may be specified by plain text
+or by a wildcard in the
+.BR glob (7)
+format.  When wildcards are used, more than one parameter may match and
+be changed.  Parameters are often, but not always, of the form
+.IR obd_name.obd_instance.parameter_name ,
+where
+.I obd_name
+is one of the OBD object types, like
+.BR ldlm ", " llite ", " lmv ", " lov ", " mdc ", " osc ,
+etc., and
+.I obd_instance
+is the name of a Lustre device, like
+.BR testfs-OST0000 ,
+but may be a specific component, or contain wildcards to match some or all
+devices on the node.  Parameters can only be modified by the root user for
+security reasons.
+.TP
+.B -d
+Remove the permanent setting (only for parameters set with the
+.B -P
+option).
+.TP
+.B -F
+Set parameters from
+.I filename
+instead of from the command-line.  The contents of
+.I filename
+is YAML format, created as an output from
+.BR "lctl --device MGS llog_print " < \fIfsname >- client
+fR or any other valid llog configuration log as listed by
+.B lctl --device MGS llog_catlist
+.TP
+.B -n
+Disable printing of the parameter name after setting it.
+.TP
+.B -P
+Set
+.I parameter
+permanently on
+.B all
+nodes connected to the MGS on which the command is run.  To limit wildcard
+.I parameter
+matching to specific filesystems or parameters, ensure that
+.I parameter
+contains a suitably-specific expression for the
+.I obd_name
+and
+.IR obd_instance ,
+such as the filesystem and/or target name.  This option is only available
+in Lustre 2.5.0 and later clients, older clients cannot set persistent
+parameters, nor will they see them.
+.SH EXAMPLES
+.B # lctl set_param fail_loc=0 timeout=20
+.br
+fail_loc=0
+.br
+timeout=20
+.br
+.B # lctl set_param -n fail_loc=0 timeout=20
+.br
+0
+.br
+20
+.br
+.B # lctl set_param -P osc.testfs-OST*.max_dirty_mb=512
+.br
+osc.testfs-OST0000-osc-ffff8803c9c0f000.max_dirty_mb=512
+.br
+osc.testfs-OST0001-osc-ffff8803c9c0f000.max_dirty_mb=512
+.br
+osc.testfs-OST0002-osc-ffff8803c9c0f000.max_dirty_mb=512
+.br
+osc.testfs-OST0003-osc-ffff8803c9c0f000.max_dirty_mb=512
+.br
+osc.testfs-OST0004-osc-ffff8803c9c0f000.max_dirty_mb=512
+.br
+.SH SEE ALSO
+.BR lustre (7),
+.BR lctl (8),
+.BR lctl-get_param (8),
+.BR lctl-llog_catlist (8),
+.BR lctl-llog_print (8)