From a7acf56fadf0ffb10ca4454b1024da9720863967 Mon Sep 17 00:00:00 2001 From: Frederick Dilger Date: Tue, 13 Aug 2024 23:42:04 -0600 Subject: [PATCH] LU-4315 doc: updating lctl-[li-ne] man page style Updating files to match the new code style for Lustre manual pages as enforced by 'contrib/scripts/checkpatch-man.pl'. This also includes other changes like removing < > or { } for singular required arguments and placing [ ] around optional ones as well as making all arguments CAPITAL and italicized, literal arguments are bolded. Lines over 80 characters should be split at the natural line end rather than the word that goes over the limit as fewer lines will need to be modified when making changes if each sentence is on it's own line. Only using features that appear in groff 1.22.3 as this is the available version is CentOS 8. Checked files: - lctl-list_param.8 - lctl-llog_cancel.8 - lctl-llog_catlist.8 - lctl-llog_info.8 - lctl-llog_print.8 - lctl-network.8 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: I97cd7e8665794ea80eac4c90c472826057cc71c7 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56055 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin --- lustre/doc/lctl-list_param.8 | 188 ++++++++++++++++++++++++----------------- lustre/doc/lctl-llog_cancel.8 | 56 ++++++------ lustre/doc/lctl-llog_catlist.8 | 46 +++++----- lustre/doc/lctl-llog_info.8 | 35 ++++---- lustre/doc/lctl-llog_print.8 | 88 +++++++++---------- lustre/doc/lctl-network.8 | 112 ++++++++++++++---------- 6 files changed, 290 insertions(+), 235 deletions(-) diff --git a/lustre/doc/lctl-list_param.8 b/lustre/doc/lctl-list_param.8 index 7fdf442..ac3bfb6 100644 --- a/lustre/doc/lctl-list_param.8 +++ b/lustre/doc/lctl-list_param.8 @@ -1,15 +1,16 @@ -.TH LCTL-LIST_PARAM 8 "2019-06-16" Lustre "configuration utilities" +.TH LCTL-LIST_PARAM 8 2024-08-13 Lustre "Lustre Configuration Utilities" .SH NAME lctl-list_param \- list configuration parameter names .SH SYNOPSIS -.B "\fBlctl list_param " +.SY "lctl list_param" .RB [ --dir-only | -D ] .RB [ --classify | -F ] .RB [ --links | -l ] .RB [ --no-links | -L ] .RB [ --path | -p ] .RB [ --recursive | -R ] -.IR PARAM_PATH1 " " PARAM_PATH2 " ..." +.IR PARAM_PATH1 " [" PARAM_PATH2 " ...]" +.YS .SH DESCRIPTION List the Lustre or LNet parameter name(s) matching .IR param_search . @@ -18,98 +19,127 @@ The parameter name(s) may contain wildcards using pathname patterns. .SH OPTIONS The various options supported by -.B lctl list_param +.BR lctl list_param are listed and explained below: .TP -.B -D ", " --dir-only +.BR -D ", " --dir-only Only list directories. .TP -.B -F ", " --classify +.BR -F ", " --classify Append '/', '@' or '=' for dirs, symlinks and writeable files, respectively. .TP -.B -l ", " --links +.BR -l ", " --links Follow symlinks while searching for parameters. (enabled by default) .TP -.B -L ", " --no-links +.BR -L ", " --no-links Do not follow symlinks while searching for parameters. .TP -.b -p ", " --path +.BR -p ", " --path Print the path name instead of the parameter name. .TP -.B -R ", " --recursive +.BR -R ", " --recursive Recursively list all parameters under the specified parameter search string. If .I param_search is unspecified, all the parameters will be shown. .SH EXAMPLES -.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 -p ost.* -.br - /sys/fs/lustre/ost/OSS -.br - /sys/fs/lustre/ost/num_refs -.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 - ... -.br -.B -# lctl list_param -L -R mgs.MGS | grep -c .osd -.br - 0 -.br -# mgs.MGS.osd is a \fIsymlink\fR -> ../../osd-ldiskfs/lustre-MDT0000 -.br -Compare this to the same command with --links enabled -.br -.B -# lctl list_param -l -R mgs.MGS | grep .osd -.br - mgs.MGS.osd -.br - mgs.MGS.osd.auto_scrub -.br - mgs.MGS.osd.blocksize -.br - mgs.MGS.osd.enable_projid.xattr -.br - mgs.MGS.osd.extent_bytes_allocation -.br - ... +Use wildcards to obtain all matching parameters: +.RS +.EX +.B # lctl list_param ost.* +ost.OSS +ost.num_refs +.EE +.RE +.PP +Show the file type with +.BR -F , +this can be useful in combination with +.B grep +to find certain types of parameters: +.RS +.EX +.B # lctl list_param -F ost.* debug +ost.OSS/ +ost.num_refs +debug= +.EE +.RE +.PP +Since there are multiple location that hold paramters, use +.B -p +to get the full filepath for more efficient use by external mornitoring tools: +.RS +.EX +.B # lctl list_param -p ost.* +/sys/fs/lustre/ost/OSS +/sys/fs/lustre/ost/num_refs +.EE +.RE +.PP +Search recursively through the directory tree with +.B -R +to get the full list of both directories and parameters in the tree: +.RS +.EX +.B # lctl list_param -R mdt +mdt +mdt.lustre-MDT0000 +mdt.lustre-MDT0000.capa +mdt.lustre-MDT0000.capa_count +mdt.lustre-MDT0000.capa_key_timeout +mdt.lustre-MDT0000.capa_timeout +mdt.lustre-MDT0000.commit_on_sharing +mdt.lustre-MDT0000.evict_client +.B ... +.EE +.RE +.PP +To avoid following symlinks which can lead to duplicate output use +.BR --no-links . +Note that +.I mgs.MGS.osd +is a symlink to +.I ../../ost-ldiskfs/lustre-MDT0000: +.RS +.EX +.B # lctl list_param -L -R mgs.MGS +.B ... +mgs.MGS.mgs.timeouts +mgs.MGS.mntdev +mgs.MGS.num_exports +mgs.MGS.uuid +mgs.MGS.filesystems +mgs.MGS.gss +.B ... +.EE +.RE +Compare this to the same command with --links enabled: +.RS +.EX +.B # lctl list_param -l -R mgs.MGS +.B ... +mgs.MGS.mgs.timeouts +mgs.MGS.mntdev +mgs.MGS.num_exports +mgs.MGS.osd +mgs.MGS.osd.auto_scrub +.B ... +mgs.MGS.osd.quota_slave_md.root_prj_enable +mgs.MGS.osd.quota_slave_md.timeout +mgs.MGS.uuid +mgs.MGS.filesystems +mgs.MGS.gss +.B ... +.EE +.RE +.SH AVAILABILITY +.B lctl list_param +is part of the +.BR lustre (7) +filesystem package since release 1.7.0 +.\" Added in commit 1.6.1-3050-g04248c9069 .SH SEE ALSO +.BR lfs (1), .BR lustre (7), .BR lctl-get_param (8), -.BR lctl-set_param (8), -.BR lfs (1) +.BR lctl-set_param (8) diff --git a/lustre/doc/lctl-llog_cancel.8 b/lustre/doc/lctl-llog_cancel.8 index 50f279c..3cfba16 100644 --- a/lustre/doc/lctl-llog_cancel.8 +++ b/lustre/doc/lctl-llog_cancel.8 @@ -1,20 +1,20 @@ -.TH LCTL-LLOG_CANCEL 8 "2020-06-12" Lustre "configuration utilities" +.TH LCTL-LLOG_CANCEL 8 2024-08-14 Lustre "Lustre Configuration Utilities" .SH NAME lctl-llog_cancel \- cancel a record in a Lustre log file .SH SYNOPSIS -.B lctl -.B llog_cancel --log_idx -.RI < index > -.RI < logname > - +.SY "lctl llog_cancel" +.B --log_idx +.I INDEX +.I LOGNAME +.YS .SH DESCRIPTION .B lctl llog_cancel is used to cancel the configuration record given by -.I index +.I INDEX from the -.I logname -configuration log, typically on the MGS. This is useful if a persistent -configuration record was set incorrectly or is no longer needed. Note +.I LOGNAME +configuration log, typically on the MGS. This is useful if a persistent +configuration record was set incorrectly or is no longer needed. Note that cancelling a record does not "undo" any effect it had on currently mounted clients, it only prevents the record from being seen in the future. See @@ -22,32 +22,40 @@ See for a list of configuration logs. .SH OPTIONS .TP -.B --log_idx -.I index +.BI --log_idx " INDEX" The record -.I index +.I INDEX number to cancel, as printed by .B lctl llog_print for that log. -.TP .SH EXAMPLES -.TP -To cancel record 15 from the \fBtestfs-client\fR conf_param log: -.br -# lctl llog_cancel --log_idx=15 testfs-client -.TP -To cancel record 22 from the \fBparams\fR set_param log: -.br -# lctl llog_cancel --log_idx=22 params +To cancel record 15 from the +.B testfs-client +conf_param log: +.RS +.EX +.B # lctl llog_cancel --log_idx=15 testfs-client +.EE +.RE +.PP +To cancel record 22 from the +.B params +set_param log: +.RS +.EX +.B # lctl llog_cancel --log_idx=22 params +.EE +.RE .SH AVAILABILITY .B lctl llog_cancel is a subcommand of .BR lctl (8) and is distributed as part of the .BR lustre (7) -filesystem package. +filesystem package since release 0.10.0 +.\" Added in commit 0.0.0-3210-gc5050e4125 .SH SEE ALSO .BR lctl (8), -.BR lctl-llog_info (8), .BR lctl-llog_catlist (8), +.BR lctl-llog_info (8), .BR lctl-llog_print (8) diff --git a/lustre/doc/lctl-llog_catlist.8 b/lustre/doc/lctl-llog_catlist.8 index e0fdc7f..9669716 100644 --- a/lustre/doc/lctl-llog_catlist.8 +++ b/lustre/doc/lctl-llog_catlist.8 @@ -1,20 +1,21 @@ -.TH LCTL-LLOG_CATLIST 8 "2020-06-12" Lustre "configuration utilities" +.TH LCTL-LLOG_CATLIST 8 2024-08-14 Lustre "Lustre Configuration Utilities" .SH NAME lctl-llog_catlist \- list Lustre configuration log files .SH SYNOPSIS -.B lctl -[--device <\fIdevice\fR>] -.B llog_catlist +.SY "lctl llog_catlist" +.RB [ --device +.IR device ] +.YS .SH DESCRIPTION .B lctl llog_catlist is used to list the configuration log files on the MGS, or other target. This is useful to find the names of all the configuration files available. The -.IR fsname -client +.IR FSNAME -client logs contains configuration records for the client nodes, the -.IR fsname -MDT xxxx +.IR FSNAME -MDT XXXX logs contain records for the MDT(s), the -.IR fsname -OST xxxx +.IR FSNAME -OST XXXX logs contain records for the OSTs. The .B lctl conf_param parameters are stored in these log files for the specified filesystem. The @@ -24,43 +25,40 @@ log file contains the parameters for all filesystems serviced by this MGS. .SH OPTIONS .TP -.B --device \fIdevice\fR +.BI --device " device" The .I device to be used. By default MGS device is used for this operation. .SH EXAMPLES -.TP To list all of the configuration logs on the MGS: -.br -# lctl llog_catlist -.br +.RS +.EX +.B # lctl llog_catlist config_log: testfs-OST0000 -.br config_log: testfs-MDT0000 -.br config_log: testfs-OST0001 -.br config_log: testfs-client -.br config_log: params -.br -.TP +.EE +.RE +.PP To list all of the recovery llog files on the MGS: -.br -# lctl --device testfs-MDT0000 llog_catlist -.br +.RS +.EX +.B # lctl --device testfs-MDT0000 llog_catlist catalog_log: [0x5:0x1:0x0]:0 -.br catalog_log: [0x6:0x1:0x0]:0 -.br catalog_log: [0x7:0x1:0x0]:0 +.EE +.RE .SH AVAILABILITY .B lctl llog_catlist is a subcommand of .BR lctl (8) and is distributed as part of the .BR lustre (7) -filesystem package. +filesystem package since release 0.9.0 +.\" Added in commit 0.0.0-3210-gc5050e4125 .SH SEE ALSO .BR lctl (8), .BR lctl-llog_cancel (8), diff --git a/lustre/doc/lctl-llog_info.8 b/lustre/doc/lctl-llog_info.8 index f581550..db20a8c 100644 --- a/lustre/doc/lctl-llog_info.8 +++ b/lustre/doc/lctl-llog_info.8 @@ -1,44 +1,45 @@ -.TH LCTL-LLOG_INFO 8 "2020-06-12" Lustre "configuration utilities" +.TH LCTL-LLOG_INFO 8 2024-08-14" Lustre "Lustre Configuration Utilities" .SH NAME lctl-llog_info \- print information about a Lustre configuration log .SH SYNOPSIS -.B lctl llog_info -.RI < logname > - +.SY "lctl llog_info" +.I LOGNAME +.YS .SH DESCRIPTION .B lctl llog_info is used to print information about the configuration log given by -.IR logname . +.IR LOGNAME . .SH OPTIONS .TP -.I logname +.I LOGNAME The name of the configuration log, in the form -.IR fsname - target , -like \fBtestfs-client\fR or \fBlustrefs-MDT0000\fR. See +.IR FSNAME - TARGET , +like +.BR testfs-client or lustrefs-MDT0000 . +See .BR lctl-llog_catlist (8) for a list of configuration logs. .SH EXAMPLES -.TP To print all of the records from the testfs-client configuration log: -.br -# lctl llog_info testfs-client -.br +.RS +.EX +.B # lctl llog_info testfs-client logid: [0x4:0xa:0x0]:0 -.br flags: 4 (plain) -.br records_count: 48 -.br last_index: 47 +.EE +.RE .SH AVAILABILITY .B lctl llog_info is a subcommand of .BR lctl (8) and is distributed as part of the .BR lustre (7) -filesystem package. +filesystem package since release 0.10.0 +.\" Added in commit 0.0.0-3210-gc5050e4125 .SH SEE ALSO .BR lctl (8), -.BR lctl-llog_catlist (8), .BR lctl-llog_cancel (8), +.BR lctl-llog_catlist (8), .BR lctl-llog_print (8) diff --git a/lustre/doc/lctl-llog_print.8 b/lustre/doc/lctl-llog_print.8 index d2c49f7..4333a69 100644 --- a/lustre/doc/lctl-llog_print.8 +++ b/lustre/doc/lctl-llog_print.8 @@ -1,93 +1,89 @@ -.TH LCTL-LLOG_PRINT 8 "2020-06-12" Lustre "configuration utilities" +.TH LCTL-LLOG_PRINT 8 2024-08-14 Lustre "Lustre Configuration Utilities" .SH NAME lctl-llog_print \- print the content of a configuration log .SH SYNOPSIS -.B lctl llog_print +.SY "lctl llog_print" .RB [ --start -.IR start_index ] +.IR START_INDEX ] .RB [ --end -.IR end_index ] -.RI < logname > - +.IR END_INDEX ] +.I LOGNAME +.YS .SH DESCRIPTION .B lctl llog_print is used to dump the contents of the -.I logname -configuration log on the MGS in YAML format. This is useful for debugging +.I LOGNAME +configuration log on the MGS in YAML format. This is useful for debugging configuration problems and to list any permanent configuration options saved via .B lctl conf_param -on the MGS. The +on the MGS. The .B lctl llog_catlist command can be used to list the different configuration logs, and the .B lctl llog_cancel command can be used to cancel configuration records. .SH OPTIONS .TP -.B --end +.BI --end " END_INDEX" Stop printing records at -.IR end_index . +.IR END_INDEX . +.I END_INDEX +is the last record number in the config log to dump, +including the specified index number. .TP -.B --start +.BI --start " START_INDEX" Start printing records at -.IR start_index . +.IR START_INDEX . +.I START_INDEX +is the first record number in the config log to dump. +Note that deactivated records and comment records will not be printed. .TP -.B logname +.I LOGNAME The name of the configuration log, in the form -.IR fsname - target , +.IR FSNAME - TARGET , like .B testfs-client or .BR lustrefs-MDT0000 . -.TP -.I start_index -The first record number in the config log to dump. Note that deactivated -records and comment records will not be printed. -.TP -.I end_index -The last record number in the config log to dump, including the specified -index number. .SH EXAMPLES -.TP -To print the configuration records from the \fBtestfs-client\fR logfile: -.br -# lctl llog_print testfs-client -.br +To print the configuration records from the +.BR testfs-client logfile: +.RS +.EX +.B # lctl llog_print testfs-client - { index: 3, event: attach, device: testfs-clilov, type: lov, -.br UUID: testfs-clilov_UUID } -.br - { index: 6, event: setup, device: testfs-clilov, UUID: } -.br - { index: 9, event: attach, device: testfs-clilmv, type: lov, -.br UUID: testfs-clilmv_UUID } -.br - { index: 12, event: setup, device: testfs-clilmv, UUID: } -.br - { index: 15, add_uuid: nid: 10.211.55.6@tcp(0x200000ad33706), -.br node: 10.211.55.6@tcp } -.br -: -.br : -.TP -To print the first 10 \fBset_param -P\fR records from \fBparams\fR: -# lctl llog_print --end=10 params -.br +.EE +.RE +.PP +To print the first 10 +.B set_param -P +records from +.B params: +.RS +.EX +.B # lctl llog_print --end=10 params - { index: 2, event: set_param, device: general, parameter: osc.*.max_dirty_mb, value: 32 } -.br - { index: 4, event: set_param, device: general, parameter: osc.*.checksum_type, value: crc32c } +.EE +.RE .SH AVAILABILITY .B lctl llog_print is a subcommand of .BR lctl (8) and is distributed as part of the .BR lustre (7) -filesystem package. +filesystem package since release 0.10.0 +.\" Added in commit 0.0.0-3210-gc5050e4125 .SH SEE ALSO .BR lctl (8), -.BR lctl-llog_info (8), .BR lctl-llog_cancel (8), -.BR lctl-llog_catlist (8) +.BR lctl-llog_catlist (8), +.BR lctl-llog_info (8) diff --git a/lustre/doc/lctl-network.8 b/lustre/doc/lctl-network.8 index fa6c99e..7ae1c31 100644 --- a/lustre/doc/lctl-network.8 +++ b/lustre/doc/lctl-network.8 @@ -1,26 +1,30 @@ -.TH LCTL-NETWORK 8 "2016-09-06" Lustre "configuration utilities" +.TH LCTL-NETWORK 8 2024-08-14 Lustre "Lustre Configuration Utilities" .SH NAME lctl-network \- start or stop an LNet network or set network type .SH SYNOPSIS -.B lctl network -.I up -| -.I down +.SY "lctl network" +.RB { up | down } | -.I configure +.RB { configure | unconfigure } | -.I unconfigure -| -.RI < tcp / o2ib > - -.B net -can be substituted for -.B network +.RB { tcp | o2ib } +.YS .SH DESCRIPTION -.B lfs network -is used to start or stop LNet and LNet configuration on a client, server, or router. +.B lctl network +is used to start or stop LNet and LNet configuration on a client, server, +or router. +.B lctl net +is an alias for +.BR "lctl network" . +However, +.B netctl lnet +is the preferred command for configuring and unconfiguring network interfaces. .P -The Lustre software automatically starts and stops LNet, but it can also be manually stopped or started in a standalone manner. This is particularly useful to verify that your networking setup is working correctly before you attempt to start the Lustre file system, or necessary for Lustre routers which only need the LND and LNet modules. +The Lustre software automatically starts and stops LNet, +but it can also be manually stopped or started in a standalone manner. +This is particularly useful to verify that your networking setup is working +correctly before you attempt to start the Lustre file system, +or necessary for Lustre routers which only need the LND and LNet modules. .SH OPTIONS .TP .B up @@ -33,34 +37,16 @@ Stops LNet Loads LNet configuration .TP .B unconfigure -Clears LNet configuration. This step is necessary for standalone routers to remove LNet references before the LNet modules can be removed. -.SH EXAMPLES -.TP -To load the module and start LNet -# modprobe lnet -.br -# lctl network up -.br -LNet configured -.TP -To stop LNet and remove the module -# lctl network down -.br -LNet ready to unload -.br -# rmmod lnet -.TP -To load LNet configuration in standalone mode -# lctl network configure -.br -LNet configured -.TP -To clear the LNet configuration -# lctl network unconfigure -LNet ready to unload +Clears LNet configuration. +This step is necessary for standalone routers to remove +LNet references before the LNet modules can be removed. .SH NOTES -.P -The lustre_rmmod utility does not work if you have manually run the +Since Lustre 2.15.0 the lustre_rmmod script calls +.B lnetctl lnet unconfigure +or +.B lctl network down +command internally to stop the LNet network interfaces. +Otherwise the lustre_rmmod utility does not work if you have manually run the .B lctl network .I up command. @@ -70,12 +56,48 @@ Attempting to remove modules prior to stopping the network may result in a crash or an LNet hang. If this occurs, the node must be rebooted (in most cases). Make sure that the Lustre network and file system are stopped prior to unloading the modules. +.SH EXAMPLES +To load the module and start LNet: +.RS +.EX +.B # modprobe lnet +.B # lctl network up +LNet configured +.EE +.RE +.PP +To stop LNet and remove the module: +.RS +.EX +.B # lctl network down +LNet ready to unload +.B # rmmod lnet +.EE +.RE +.PP +To load LNet configuration in standalone mode: +.RS +.EX +.B # lctl network configure +LNet configured +.EE +.RE +.PP +To clear the LNet configuration: +.RS +.EX +.B # lctl network unconfigure +LNet ready to unload +.EE +.RE .SH AVAILABILITY .B lctl network is a subcommand of .BR lctl (8) and is distributed as part of the .BR lustre (7) -filesystem package. +filesystem package since release 0.6.0 +.\" Added in commit 0.0.0-1251-ge772702b4c .SH SEE ALSO -.BR lctl (8) +.BR lctl (8), +.BR lnetctl (8) -- 1.8.3.1