LU-888 lctl: remove perilous lctl {get,set,list}_param behavior.

[fs/lustre-release.git] / lustre / doc / lctl.8

diff --git a/lustre/doc/lctl.8 b/lustre/doc/lctl.8
index fca7631..dca672d 100644 (file)
--- a/lustre/doc/lctl.8
+++ b/lustre/doc/lctl.8
@@ -92,12 +92,155 @@ Show all the local Lustre OBDs. AKA
 .PP
 .SS Device Operations
 .TP 
-.BI conf_param " <device> <parameter>"
+.BI list_param " [-F|-R] <param_search ...>"
+List the Lustre or LNet parameter name
+.B -F
+Add '/', '@' or '=' for dirs, symlinks and writeable files, respectively.
+.br
+.B -R
+Recursively list all parameters under the specified parameter search string. If
+.I param_search
+is unspecified, all the parameters will be shown.
+.br
+.B Examples:
+.br
+.B
+# lctl list_param ost.*
+.br
+  ost.OSS
+.br
+  ost.num_refs
+.br
+.B
+# lctl list_param -F ost.* debug
+.br
+  ost.OSS/
+.br
+  ost.num_refs
+.br
+  debug=
+.br
+.B
+# lctl list_param -R mdt
+.br
+  mdt
+.br
+  mdt.lustre-MDT0000
+.br
+  mdt.lustre-MDT0000.capa
+.br
+  mdt.lustre-MDT0000.capa_count
+.br
+  mdt.lustre-MDT0000.capa_key_timeout
+.br
+  mdt.lustre-MDT0000.capa_timeout
+.br
+  mdt.lustre-MDT0000.commit_on_sharing
+.br
+  mdt.lustre-MDT0000.evict_client
+.br
+  ...
+.TP
+.BI get_param " [-n|-N|-F] <parameter ...>"
+Get the value of Lustre or LNET parameter.
+.br
+.B -n
+Print only the value and not parameter name.
+.br
+.B -N
+Print only matched parameter names and not the values. (Especially useful when using patterns.)
+.br
+.B -F
+When -N specified, add '/', '@' or '=' for directories, symlinks and writeable files, respectively.
+.br
+.B Examples:
+.br
+.B
+# lctl get_param ost.*
+.br
+  ost.OSS
+.br
+  ost.num_refs
+.br
+.B
+# lctl get_param -n debug timeout
+.br
+  super warning dlmtrace error emerg ha rpctrace vfstrace config console
+.br
+  20
+.br
+.B
+# lctl get_param -N ost.* debug
+.br
+  ost.OSS
+.br
+  ost.num_refs
+.br
+  debug
+.br
+lctl "get_param -NF" is equivalent to "list_param -F".
+.TP
+.BI set_param " [-n] <parameter=value ...>"
+Set the value of Lustre or LNET parameter.
+.br
+.B -n
+Disable printing of the key name when printing values.
+.br
+.B Examples:
+.br
+.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
+.TP
+.BI conf_param " [-d] <device|fsname>.<parameter>=<value>"
 Set a permanent configuration parameter for any device via the MGS.  This
-command must be run on the MGS node. 
+command must be run on the MGS node.
+.br
+.B -d <device|fsname>.<parameter>
+Delete a parameter setting (use the default value at the next restart).  A null value for <value> also deletes the parameter setting.
+.br
+.B Parameters:
+.br
+All of the writable parameters under 
+.B lctl list_param
+(e.g. 
+.I lctl list_param -F osc.*.* | grep =
+) can be permanently set using
+.B lctl conf_param
+, but the format is slightly different.  For conf_param, the device is specified first, then the obdtype. (See examples below.)  Wildcards are not supported.
+.br
+Additionally, failover nodes may be added (or removed), and some system-wide parameters may be set as well (sys.at_max, sys.at_min, sys.at_extra, sys.at_early_margin, sys.at_history, sys.timeout, sys.ldlm_timeout.)  <device> is ignored for system wide parameters.
+.br
+.B Examples:
+.br 
+# lctl conf_param testfs.sys.at_max=1200
+.br
+# lctl conf_param testfs.llite.max_read_ahead_mb=16 
+.br
+# lctl conf_param testfs-MDT0000.lov.stripesize=2M
+.br
+# lctl conf_param lustre-OST0001.osc.active=0 
+.br
+# lctl conf_param testfs-OST0000.osc.max_dirty_mb=29.15 
+.br
+# lctl conf_param testfs-OST0000.ost.client_cache_seconds=15 
+.br
+# lctl conf_param testfs-OST0000.failover.node=1.2.3.4@tcp1
 .TP 
 .BI activate 
-Reactivate an import after deactivating, below.
+Reactivate an import after deactivating, below.  This setting is only effective until the next restart (see 
+.B conf_param
+).
 .TP 
 .BI deactivate 
 Deactivate an import, in particular meaning do not assign new file stripes
@@ -170,7 +313,7 @@ number. See
 .TP
 .B --ignore_errors | ignore_errors 
 Ignore errors during script processing
-.TP
+
 .SH EXAMPLES
 # lctl
 .br
@@ -183,8 +326,6 @@ lctl > dk /tmp/log
 Debug log: 87 lines, 87 kept, 0 dropped.
 .br
 lctl > quit
-.PP
-# lctl conf_param testfs-MDT0000 sys.timeout=40
 
 .SH BUGS
 Please report all bugs to Sun Microsystems, Inc. http://bugzilla.lustre.org/