From 9726f057424d7300cebdddeae5ad88259c2738cd Mon Sep 17 00:00:00 2001 From: Frederick Dilger Date: Thu, 29 Aug 2024 14:49:37 -0600 Subject: [PATCH] LU-4315 doc: updating l[c-h] 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.8 - ldev.8 - ldev.conf.5 - lfs.1 - l_getidentity.8 - l_getsepol.8 - lgss_sk.8 - lhbadm.8 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: I77f4c6dd0e28cf09c076052a022885e30c2bbe6f Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56202 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin --- lustre/doc/l_getidentity.8 | 145 ++++++++-------- lustre/doc/l_getsepol.8 | 56 +++--- lustre/doc/lctl.8 | 424 +++++++++++++++++++++------------------------ lustre/doc/ldev.8 | 142 ++++++++------- lustre/doc/ldev.conf.5 | 85 +++++---- lustre/doc/lfs.1 | 266 ++++++++++------------------ lustre/doc/lgss_sk.8 | 126 +++++++------- lustre/doc/lhbadm.8 | 45 +++-- 8 files changed, 607 insertions(+), 682 deletions(-) diff --git a/lustre/doc/l_getidentity.8 b/lustre/doc/l_getidentity.8 index d86f1c9..13babc4 100644 --- a/lustre/doc/l_getidentity.8 +++ b/lustre/doc/l_getidentity.8 @@ -1,47 +1,44 @@ -.TH l_getidentity 1 "Dec 7, 2016" Lustre "utilities" +.TH L_GETIDENTITY 8 2024-08-29 Lustre "Lustre Configuration Utilities" .SH NAME l_getidentity \- Handle Lustre user/group cache upcall .SH SYNOPSIS -.B "l_getidentity {-d | mdtname} uid" +.SY l_getidentity +.RB { -d | mdtname } +.I UID +.YS .SH DESCRIPTION The identity upcall command specifies the path to an executable that, when properly installed, is invoked to resolve the numeric -.I uid +.I UID to a group membership list. -.LP +.PP .B l_getidentity is the reference implementation of the user/group cache upcall. This command is normally run directly by the Lustre MDS service and specifies the -.I mdtname +.B mdtname argument for the MDT that should be updated. -.br .SS "The permissions file" -.PP -.I /etc/lustre/perm.conf -supports a flat file database of permissions in the format -.br - UIDNIDperm1,perm2,...,permN -.br - -.br +.B /etc/lustre/perm.conf +supports a flat file database of permissions in the format: +.EX +.IB UID NID PERM1 , PERM2 ,..., PERMN +.EE where -.B perm +.I PERM is one of: -.I [no]setuid -.I [no]setgid -.I [no]setgrp -.I [no]rmtacl -.I [no]rmtown -.br - -.br +.B [no]setuid +.B [no]setgid +.B [no]setgrp +.B [no]rmtacl +.B [no]rmtown +.PP .BR nss (5) modules can be enabled for auth handling by adding a .B lookup command with a list of nss modules to the first line of .BR perm.conf -.br +.PP At the time of writing, known .BR nss (5) modules include: @@ -49,15 +46,11 @@ modules include: additional modules may be documented in .BR nsswitch.conf (5) or installed separately. -.br - -.br +.PP .BR nss (5) modules are searched in order. Once an entry is found in the module no further modules are searched. -.br - -.br +.PP A special .B lustre module is used to enable lustre specific password and group @@ -65,9 +58,7 @@ auth by way of .B /etc/lustre/passwd and .B /etc/lustre/group -.br - -.br +.PP For historical reasons .B nss_files was needed to use the @@ -79,59 +70,59 @@ This alias is now deprecated and will be removed in a future release. .TP .B -d Run in debug mode and print supplementary groups information for -.I uid +.I UID to .B stdout instead of updating Lustre. +.SH FILES +.EX +.RI /{proc,sys}/fs/lustre/mdt/ mdt-service /identity_upcall +.RI /etc/lustre/perm.conf +.RI /etc/lustre/passwd +.RI /etc/lustre/group +.EE +.SH LIMITS +A maximum of 8 nss modules can be enabled. .SH EXAMPLES The identity upcall command can be specified via: -.br -.RI "lctl set_param mdt." mdtname .identity_upcall= path_to_upcall -.br - -.br -Enable lustre auth and ldap -.br - [/etc/lustre/perm.conf] -.br -.B lookup lustre ldap -.br - -.br - [/etc/lustre/passwd] -.br - root:x:0:0:root:/root:/bin/bash -.br - ... -.br - [/etc/lustre/group] -.br - root:x:0:root -.br - ... -.br -Lustre passwd and group files use the same format as the system +.RS +.EX +.BI "lctl set_param mdt." MDTNAME .identity_upcall= PATH_TO_UPCALL +.EE +.RE +.PP +Enable lustre auth and ldap: +.RS +.EX +[/etc/lustre/perm.conf] +.B # lookup lustre ldap +\& +[/etc/lustre/passwd] +root:x:0:0:root:/root:/bin/bash +\&... +[/etc/lustre/group] +root:x:0:root +\&... +.EE +.RE +Lustre passwd and group files use the same format as the system .BR passwd (5) and .BR group (5) files. -.br -In this configuration root is local to the cluster and all other perms are delegated to ldap. -.br -.SH LIMITS -A maximum of 8 nss modules can be enabled. -.b4 -.SH FILES -.RI /{proc,sys}/fs/lustre/mdt/ mdt-service /identity_upcall -.br -.RI /etc/lustre/perm.conf -.br -.RI /etc/lustre/passwd -.br -.RI /etc/lustre/group +.P +In this configuration root is local to the cluster +and all other perms are delegated to ldap. +.EE +.SH AVAILABILITY +.B l_getidentity +is part of the +.BR lustre (7) +filesystem package since release 1.7.0 +.\" Added in commit 1.6.0.1-152-gd2d56f38da .SH SEE ALSO +.BR group (5), .BR nss (5), -.BR passwd (5), -.BR group (5) -.br +.BR passwd (5) +.PP Lustre Programming Interfaces section of Lustre Operations Manual. diff --git a/lustre/doc/l_getsepol.8 b/lustre/doc/l_getsepol.8 index 40eb1f0..c131004 100644 --- a/lustre/doc/l_getsepol.8 +++ b/lustre/doc/l_getsepol.8 @@ -1,49 +1,45 @@ -.TH l_getsepol 8 "2019 Feb 5" Lustre "configuration utilities" +.TH L_GETSEPOL 8 2024-08-29 Lustre "Lustre Configuration Utilities" .SH NAME l_getsepol \- Lustre SELinux policy info - .SH SYNOPSIS -.br -.B l_getsepol -.br +.SY l_getsepol +.YS .SH DESCRIPTION .B l_getsepol generates the Lustre SELinux policy info to set as reference on a nodemap with -.BR lctl -.BR nodemap_set_sepol (8). - -.br +.BR lctl-nodemap_set_sepol (8). The info string describing the SELinux policy has the following syntax: - -::: - +.EX +.IB MODE : NAME : VERSION : HASH +.EE where: -.RS 4 -- is a digit telling if SELinux is in Permissive mode (0) or Enforcing -mode (1) - -- is the name of the SELinux policy - -- is the version of the SELinux policy - -- is the computed hash of the binary representation of the policy, as +.TP 8 +.B MODE +is a digit telling if SELinux is in Permissive mode (0) or Enforcing mode (1) +.TP +.B NAME +is the name of the SELinux policy +.TP +.B VERSION +is the version of the SELinux policy +.TP +.B HASH +is the computed hash of the binary representation of the policy, as exported in /etc/selinux//policy/policy. -.RE - +.PP .B l_getsepol should be run on a client node known to enforce the right SELinux policy. - .SH EXAMPLES -.nf -# l_getsepol +.EX +.B # l_getsepol SELinux status info: 1:mls:31:c79984bb42c0151cb0d8cc34a196a6ca95c2791190c403804efb3e9d81b6109c -.fi - +.EE .SH AVAILABILITY .B l_getsepol is part of the -.BR Lustre (7) -filesystem package. +.BR lustre (7) +filesystem package since release 2.13.0 +.\" Added in commit v2_12_50-90-gc61168239e .SH SEE ALSO .BR lustre (7), .BR lctl-nodemap-set-sepol (8) diff --git a/lustre/doc/lctl.8 b/lustre/doc/lctl.8 index a08f90b..bcb6d28 100644 --- a/lustre/doc/lctl.8 +++ b/lustre/doc/lctl.8 @@ -1,190 +1,196 @@ -.TH LCTL 8 "2019-06-16" Lustre "configuration utilities" +.TH LCTL 8 2024-08-29 Lustre "Lustre Configuration Utilities" .SH NAME lctl \- Lustre filesystem administrator configuration tool .SH SYNOPSIS -.br -.B lctl -.br -.B lctl --device -.br -.B lctl --version -.br -.B lctl --list-commands -.br +.SY lctl +.SY lctl +.B --device +.I DEVNO +.I COMMAND +.RI [ ARGS ] +.SY lctl +.B --version +.SY lctl +.B --list-commands +.YS .SH DESCRIPTION .B lctl is used to directly control Lustre via an ioctl interface, allowing various configuration, maintenance, and debugging features to be accessed. - +.PP .B lctl -can be invoked in interactive mode by issuing lctl command. After that, commands are issued as below. The most common commands in lctl are +can be invoked in interactive mode by issuing lctl command. +After that, commands are issued as below. The most common commands in lctl are .BR dl , .BR dk , .BR device , .B network -.IR , +.RB { up | down }, .BR list_nids , .B ping .IR nid , .BR help , .BR quit . - +.PP To get a complete listing of available commands, type .B --list-commands -at the lctl prompt. To get basic help on the meaning and syntax of a +at the lctl prompt. To get basic help on the meaning and syntax of a command, type .B help .I command -. Command completion is activated with the TAB key, and command history is available via the up- and down-arrow keys. - -For non-interactive use, one uses the second invocation, which runs command after connecting to the device. - -.SS System Configuration -The on-line tool set for backup or removal of Lustre system configuration. For detail, please see: +Command completion is activated with the TAB key, +and command history is available via the up- and down-arrow keys. .PP -\fBlctl-lcfg\fR(8) -.RS 4 - +For non-interactive use, one uses the second invocation, +which runs command after connecting to the device. +.SS System Configuration +The on-line tool set for backup or removal of Lustre system configuration. +For detail, please see: +.br +.BR lctl-lcfg (8) .SS Network Configuration .TP -.BR network " <" up / down >|< tcp / o2ib > +.BR network { up | down }|{ tcp | o2ib } Start or stop LNET, or select a network type for other -.I lctl +.B lctl LNET commands .TP .BI list_nids Print all Network Identifiers on the local node. LNET must be running. .TP -.BI which_nid " " +.BI which_nid " NIDLIST" From a list of nids for a remote node, show which interface communication will take place on. .TP -.BI replace_nids " [,nid2,nid3:nid4,nid5:nid6 ...]" +.BI replace_nids " DEVICENAME NID1"\fR[, NID2 \fR, NID3 : NID4 \fR, NID5 : NID6 \fR...] Replace the LNET Network Identifiers for a given device, as when the server's IP address has changed. This command must be run on the MGS node. -Only MGS server should be started (command execution returns error -in another cases). To start the MGS service only: +Only MGS server should be started +(command execution returns error in another cases). +To start the MGS service only: mount -t lustre -o nosvc -Note the replace_nids command skips any invalidated records in the configuration log. +Note the replace_nids command skips +any invalidated records in the configuration log. The previous log is backed up with the suffix '.bak'. -Failover NID must be passed after ':' symbol. More than -one failover NID can be specified (every failover NID after ':' symbol). +Failover nids must be passed after ':' symbol. +More than one failover can be set (every failover NID after ':' symbol). .TP -.BI ping " timeout" +.BI ping " NID TIMEOUT" Check LNET connectivity via an LNET ping. This will use the fabric appropriate to the specified NID. By default lctl will attempt to reach the remote node up to 120 seconds and then timeout. To disable the timeout just specify an negative timeout value. .TP -.BI interface_list +.B interface_list Print the network interface information for a given .B network type. .TP -.BI peer_list +.B peer_list Print the known peers for a given .B network type. .TP -.BI conn_list +.B conn_list Print all the connected remote NIDs for a given .B network type. .TP -.BI route_list +.B route_list Print the complete routing table. -.PP .SS Device Selection .TP -.BI device " " -This will select the specified OBD device. All other commands depend on the device being set. +.BI device " DEVNAME" +This will select the specified OBD device. +All other commands depend on the device being set. .TP -.BI device_list " [--target|-t] [--yaml|-y] " +.BR device_list " [" --target | -t "] [ "--yaml | -y ] Show all the local Lustre OBDs. .B dl is the same command. The .B -t -option additonally will report the server's export NID linked to the local OBD. The +option additonally will report the server's export NID linked to the local OBD. +The .B -y option will display the OBD device information in YAML format. .SS Device Operations .TP -.BI conf_param " [-d] .=" -Set a permanent configuration parameter for any device via the MGS. This +.BI conf_param " \fR[" "-d\fR] " DEVICE \fR| FSNAME . PARAMETER = VALUE +Set a permanent configuration parameter for any device via the MGS. This command must be run on the MGS node. -.br -.B -d . -Delete a parameter setting (use the default value at the next restart). -A null value for also deletes the parameter setting. This is -useful if an incorrect or obsolete parameter is in the configuration. -.br +.IP +The +.B -d +option deletes a parameter setting (use the default value at the next restart). +A null value for +.I VALUE +also deletes the parameter setting. +This is useful if an incorrect or obsolete parameter is in the configuration. +.RS 2 +.TP .B Parameters: -.br All of the writable parameters under .B lctl list_param (e.g. -.I lctl list_param -F osc.*.* | grep = +.B lctl list_param -w osc.*.* +or +.B 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.) is ignored for system wide parameters. +, 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.) +.I DEVICE +is ignored for system wide parameters. +.TP .B Examples: -.br +.EX # 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 -.br # lctl conf_param -d testfs-OST0000.bad_param +.EE +.RE .TP -.BI activate -Reactivate an import after deactivating, below. This setting is only effective until the next restart (see -.B conf_param -). +.B activate +Reactivate an import after deactivating, below. +This setting is only effective until the next restart (see +.BR conf_param). .TP -.BI deactivate +.B deactivate Deactivate an import, in particular meaning do not assign new file stripes -to an OSC. This command should be used on the OSC in the MDT LOV +to an OSC. This command should be used on the OSC in the MDT LOV corresponding to a failed OST device, to prevent further attempts at communication with the failed OST. .TP -.BI abort_recovery +.B abort_recovery Abort the recovery process on a restarting MDT or OST device -.PP .SS Changelogs Changelog user can be registered and deregistered on particular device. Changelog starts logging when any user is registered. - -For more details see: - .PP -\fBlctl-changelog_register\fR(8) -.RS 4 +For more details see: +.TP +.BR lctl-changelog_register (8) Register a new changelog user on specified MDT device with specified parameters. -.RE -.PP -\fBlctl-changelog_deregister\fR(8) -.RS 4 +.TP +.BR lctl-changelog_deregister (8) Deregister an existing changelog user on the specified MDT. - -.PP -.SS Nodemap +.SS NODEMAP An identity mapping feature that facilitates mapping of client UIDs and GIDs to local file system UIDs and GIDs, while maintaining POSIX ownership, permissions, and quota. - +.P While the nodemap feature is enabled, all client file system access is subject to the nodemap identity mapping policy, which consists of the 'default' catchall nodemap, and any user-defined nodemaps. The 'default' nodemap maps all client @@ -192,7 +198,7 @@ identities to 99:99 (nobody:nobody). Administrators can define nodemaps for a range of client NIDs which map identities, and these nodemaps can be flagged as 'trusted' so identities are accepted without translation, as well as flagged as 'admin' meaning that root is not squashed for these nodes. - +.P Note: In the current phase of implementation, to use the nodemap functionality you only need to enable and define nodemaps on the MDS. The MDSes must also be in a nodemap with the admin and trusted flags set. To use quotas with nodemaps, @@ -200,69 +206,47 @@ you must also use set_param to enable and define nodemaps on the OSS (matching what is defined on the MDS). Nodemaps do not currently persist, unless you define them with set_param and use the -P flag. Note that there is a hard limit to the number of changes you can persist over the lifetime of the file system. - +.P See also: - -.PP -\fBlctl-nodemap-activate\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-activate (8) Activate/deactivate the nodemap feature. -.RE -.PP -\fBlctl-nodemap-add\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-add (8) Add a new nodemap, to which NID ranges, identities, and properties can be added. -.RE -.PP -\fBlctl-nodemap-del\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-del (8) Delete an existing nodemap. -.RE -.PP -\fBlctl-nodemap-add-range\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-add-range (8) Define a range of NIDs for a nodemap. -.RE -.PP -\fBlctl-nodemap-del-range\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-del-range (8) Delete an existing NID range from a nodemap. -.RE -.PP -\fBlctl-nodemap-add-idmap\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-add-idmap (8) Add a UID or GID mapping to a nodemap. -.RE -.PP -\fBlctl-nodemap-del-idmap\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-del-idmap (8) Delete an existing UID or GID mapping from a nodemap. -.RE -.PP -\fBlctl-nodemap-modify\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-modify (8) Modify a nodemap property. -.RE -.PP -\fBlctl-nodemap-set-fileset\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-set-fileset(8) Add a fileset to a nodemap. -.RE -.PP -\fBlctl-nodemap-set-sepol\fR(8) -.RS 4 +.TP +.BR lctl-nodemap-set-sepol (8) Set SELinux policy info on a nodemap. -.RE .SS Configuration logs .TP -.BI clear_conf " " -This command runs on MGS node having MGS device mounted with -o -nosvc. It cleans up configuration files stored in the CONFIGS/ directory +.BI clear_conf " DEVICE" \fR| FSNAME +This command runs on MGS node having MGS device mounted with -o nosvc. +It cleans up configuration files stored in the CONFIGS/ directory of any records marked SKIP. If the device name is given, then the specific logs for that filesystem (e.g. testfs-MDT0000) is processed. Otherwise, if a filesystem name is given then all configuration files for the specified filesystem are cleared. -.PP .SS LFSCK An on-line Lustre consistency check and repair tool. It is used for totally replacing the old lfsck tool for kinds of Lustre inconsistency verification, @@ -272,31 +256,21 @@ unmatched MDT-object and name entry pairs, orphan MDT-object, incorrect MDT-object links count, corrupted namespace, corrupted or lost LOV EA, lost OST-object, multiple referenced OST-object, unmatched MDT-object and OST-object pairs, orphan OST-object, and so on. - +.P See also: - -.PP -\fBlctl-lfsck-start\fR(8) -.RS 4 +.TP +.BR lctl-lfsck-start (8) Start LFSCK on the specified MDT or OST device with specified parameters. -.RE -.PP -\fBlctl-lfsck-stop\fR(8) -.RS 4 +.TP +.BR lctl-lfsck-stop (8) Stop LFSCK on the specified MDT or OST device. -.RE -.PP -\fBlctl-lfsck-query\fR(8) -.RS 4 +.TP +.BR lctl-lfsck-query (8) Get the LFSCK global status via the specified MDT device. -.RE - .SS BARRIER The tools set for write (modify) barrier on all MDTs. For detail, please see: -.PP -\fBlctl-barrier\fR(8) -.RS 4 - +.TP +.BR lctl-barrier (8) .SS SNAPSHOT ZFS backend based snapshot tools set. The tool loads system configuration from the file @@ -306,94 +280,94 @@ maintain Lustre snapshot pieces on all targets (MGS/MDT/OST). The configuration file .B /etc/ldev.conf is not only for snapshot, but also -for other purpose. The format is: - foreign/-