From: Frederick Dilger Date: Fri, 24 Jan 2025 23:42:46 +0000 (-0700) Subject: LU-4315 docs: updating lfs-[m-q] mage page style X-Git-Tag: 2.16.52~3 X-Git-Url: https://git.whamcloud.com/gitweb?a=commitdiff_plain;h=117aaece71b464bfdcad54a058e4c2f9237d30c1;p=fs%2Flustre-release.git LU-4315 docs: updating lfs-[m-q] mage 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. Only using features that appear in groff 1.22.3 as this is the available version is CentOS 8. Checked files: - lfs-mkdir.1 - lfs-path2fid.1 - lfs-pcc.1 - lfs-pcc-attach.1 - lfs-pcc-detach.1 - lfs-pcc-delete.1 - lfs-pcc-state.1 - lfs-project.1 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: Iefaad081f9a4f6627f0c7ac4e9e59c4bc099fa93 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/57890 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin --- diff --git a/lustre/doc/lfs-path2fid.1 b/lustre/doc/lfs-path2fid.1 index 5aa1d17..b561f86 100644 --- a/lustre/doc/lfs-path2fid.1 +++ b/lustre/doc/lfs-path2fid.1 @@ -1,32 +1,40 @@ -.TH lfs-path2fid 1 "2018-11-24" Lustre "user utilities" +.TH LFS-PATH2FID 1 2025-01-24 Lustre "Lustre User Utilities" .SH NAME lfs-path2fid \- print the file identifier for a given pathname .SH SYNOPSIS -.BR "lfs path2fid " [ --parents ] -.RI < directory | file > ... +.SY "lfs path2fid" +.RB[ --parents ] +.IR DIRECTORY | FILE ... +.YS .SH DESCRIPTION .B lfs path2fid prints the File Identifier for the specified -.I file +.I FILE or -.IR directory . +.IR DIRECTORY . The FID is unique for each file in the filesystem, and is never reused for other files if the file is deleted. -.br +.P The FID is also available for regular files via -.BR "lfs getstripe -F". +.BR "lfs getstripe -F" . .SH OPTIONS .TP .B --parents Print out the parent FID and name(s) of the given entries. If an entry has multiple links, these are displayed on a single line, tab-separated. .SH EXAMPLES -.TP +.EX .B $ lfs path2fid /mnt/lustre/etc/hosts [0x200000403:0x11f:0x0] -.TP .B $ lfs path2fid --parents /mnt/lustre/etc/hosts [0x200000403:0x101:0x0]/hosts +.EE +.SH AVAILABILITY +.B lfs path2fid +is part of the +.BR lustre (7) +filesystem package since release 1.7.0 +.\" Added in commit 1.6.0-2045-g32d982a271 .SH SEE ALSO .BR lfs (1), .BR lfs-fid2path (1), diff --git a/lustre/doc/lfs-pcc-attach.1 b/lustre/doc/lfs-pcc-attach.1 index 33aa641..6261e9d 100644 --- a/lustre/doc/lfs-pcc-attach.1 +++ b/lustre/doc/lfs-pcc-attach.1 @@ -1,10 +1,18 @@ -.TH LFS-PCC-ATTACH 1 2021-10-07 "Lustre" "Lustre Utilities" +.TH LFS-PCC-ATTACH 1 2025-01-24 "Lustre" "Lustre User Utilities" .SH NAME -lfs pcc attach \- attach file to local cache filesystem +lfs-pcc-attach \- attach file to local cache filesystem .SH SYNOPSIS -.BR "lfs pcc attach " [ -rw "] [" --id | -i "\fIID\fR] " \fIFILE [...] -.br -.BR "lfs pcc attach_fid " [ -rw "] [" --id | -i "\fIID\fR] {" --mnt | -m "\fIMNTPATH\fR}" \fIFID [...] +.SY "lfs pcc attach" +.RB [ -rw "] [" --id | -i +.IR ID ] +.IR FILE \ [...] +.SY "lfs pcc attach_fid" +.RB [ -rw "] [" --id | -i +.IR ID ] +.RB { --mnt | -m +.IR MNTPATH } +.IR FID \ [...] +.YS .SH DESCRIPTION Attach and copy the specified files into the persistent client cache. Use .B lfs pcc detach @@ -12,7 +20,7 @@ to remove the cached files from PCC either manually, or through automatic mechanisms for the purpose of the cache space management. .SH OPTIONS .TP -.BR --id | -i +.BR --id ", " -i The ARCHIVE .I ID to choose which backend for the cached @@ -22,31 +30,37 @@ If is not specified, use the first archive attached to the mounted filesystem by default. .TP -.BR --mnt | -m +.BR --mnt ", " -m Specify the Lustre client mountpoint for the file .IR FID to be attached. .TP -.BR --readonly | -r +.BR --readonly ", " -r Attach the file in read-only mode. This is the default. .TP -.BR --write | -w +.BR --write ", " -w Attach the file in read-write mode. .SH EXAMPLES -.TP -.B $ lfs pcc attach -i 1 /mnt/lustre/file Attach an existing file into PCC with archive ID 1 and copy data from Lustre to cache device. Reads from the Lustre file will direct to the PCC-RO copy. -.TP -.B $ lfs pcc attach_fid -r -m /mnt/lustre 0x200000401:0x1:0x0 +.EX +.RS +.B $ lfs pcc attach -i 1 /mnt/lustre/file +.RE +.EE +.PP Read-only attach file referenced by FID "0x200000401:0x1:0x0" in filesystem .B /mnt/lustre using the first/only cache ID for that mountpoint. -.TP +.EX +.RS +.B $ lfs pcc attach_fid -r -m /mnt/lustre 0x200000401:0x1:0x0 +.RE +.EE .SH SEE ALSO .BR lfs (1), .BR lfs-pcc (1), .BR lfs-pcc-detach (1), .BR lfs-pcc-state (1), -.BR lctl-pcc (8), -.BR llapi_pcc_attach (3) +.BR llapi_pcc_attach (3), +.BR lctl-pcc (8) diff --git a/lustre/doc/lfs-pcc-delete.1 b/lustre/doc/lfs-pcc-delete.1 index 7bdeaf5..c63a4cd 100644 --- a/lustre/doc/lfs-pcc-delete.1 +++ b/lustre/doc/lfs-pcc-delete.1 @@ -1,14 +1,22 @@ -.TH LFS-PCC-DELETE 1 2019-04-15 "Lustre" "Lustre Utilities" +.TH LFS-PCC-DELETE 1 2025-01-24 "Lustre" "Lustre User Utilities" .SH NAME -lfs pcc delete \- delete PCC component from file +lfs-pcc-delete \- delete PCC component from file .SH SYNOPSIS -.BR "lfs pcc delete" \fIFILE [...] +.SY "lfs pcc delete" +.IR FILE \ [...] +.YS .SH DESCRIPTION Delete PCC component from specified .IR FILE (s). This will remove the cached file from all connected clients, and allow the file to be accessed by older clients that do not have PCC support. +.SH AVAILABILITY +.B lfs pcc delete +is part of the +.BR lustre (7) +filesystem package since release 2.17.0 +.\" Added in commit v2_16_50-46-g01b82baffe .SH SEE ALSO .BR lfs (1), .BR lfs-pcc (1), diff --git a/lustre/doc/lfs-pcc-detach.1 b/lustre/doc/lfs-pcc-detach.1 index 8f0b15e..9a2d038 100644 --- a/lustre/doc/lfs-pcc-detach.1 +++ b/lustre/doc/lfs-pcc-detach.1 @@ -1,10 +1,16 @@ -.TH LFS-PCC-DETACH 1 2019-04-15 "Lustre" "Lustre Utilities" +.TH LFS-PCC-DETACH 1 2019-04-15 "Lustre" "Lustre User Utilities" .SH NAME lfs-pcc-detach, lfs-pcc-detach_fid \- Detach given files from PCC .SH SYNOPSIS -.BR "lfs pcc detach " [ --keep | -k ] \fIFILE [...] -.br -.BR "lfs pcc detach_fid " [ --keep | -k "] {" --mnt | -m "\fIMNTPATH\fR}" \fIFID [...] +.SY "lfs pcc detach" +.RB [ --keep | -k ] +.IR FILE \ [...] +.SY "lfs pcc detach_fid" +.RB [ --keep | -k ] +.RB { --mnt | -m +.IR MNTPATH } +.IR FID \ [...] +.YS .SH DESCRIPTION Detach specified .I FILE @@ -13,7 +19,7 @@ or from the persistent client cache. .SH OPTIONS .TP -.BR --keep | -k +.BR -k ", " --keep By default, the detach command will detach .I FILE from PCC permanently and remove the PCC copy after detach. This option @@ -21,31 +27,52 @@ will only detach the file in memory, but keep the PCC copy in cache. It allows the detached file to be attached automatically at next open if the cached copy of the file is still valid. .TP -.BR --mnt | -m +.BR -m ", " --mnt Specify the Lustre client mountpoint for the file .I FID to be detached. .SH EXAMPLES -.TP -.B $ lfs pcc detach /mnt/lustre/test Detach the file permanently from PCC. The cached file on PCC will be removed -after detach. IO to the file will come to Lustre OSTs after this command. -.TP -.B $ lfs pcc detach_fid -m /mnt/lustre 0x200005348:0x101:0x0 +after detach. IO to the file will come to Lustre OSTs after this command: +.EX +.RS +.B $ lfs pcc detach /mnt/lustre/test +.RE +.EE +.PP Detach the file referenced by FID "0x200005348:0x101:0x0" from PCC -permanently, and the cached file on PCC will be removed after detach. -.TP -.B $ lfs pcc detach -k /mnt/lustre/test +permanently, and the cached file on PCC will be removed after detach: +.EX +.RS +.B $ lfs pcc detach_fid -m /mnt/lustre 0x200005348:0x101:0x0 +.RE +.EE +.PP Detach the file "/mnt/lustre/test" from PCC. The client will try to attach -this file again at the next open if the cached copy is still valid. -.TP -.B $ lfs pcc detach_fid -k -m /mnt/lustre 0x200000401:0x1:0x0 +this file again at the next open if the cached copy is still valid: +.EX +.RS +.B $ lfs pcc detach -k /mnt/lustre/test +.RE +.EE +.PP Detach the file referenced by FID "0x200000401:0x1:0x0" from PCC. The client will try to attach this file again at the next open if the cached copy is still -valid. +valid: +.EX +.RS +.B $ lfs pcc detach_fid -k -m /mnt/lustre 0x200000401:0x1:0x0 +.RE +.EE +.SH AVAILABILITY +.B lfs pcc detach +is part of the +.BR lustre (7) +filesystem package since release 2.13.0 +.\" Added in commit v2_12_53-113-gf172b11688 .SH SEE ALSO .BR lfs (1), .BR lfs-pcc (1), .BR lfs-pcc-attach (1), -.BR lctl-pcc (8), -.BR llapi_pcc_detach (3) +.BR llapi_pcc_detach (3), +.BR lctl-pcc (8) diff --git a/lustre/doc/lfs-pcc-state.1 b/lustre/doc/lfs-pcc-state.1 index 3616286..6b9797b 100644 --- a/lustre/doc/lfs-pcc-state.1 +++ b/lustre/doc/lfs-pcc-state.1 @@ -1,8 +1,10 @@ -.TH LFS-PCC-STATE 1 2021-10-07 "Lustre" "Lustre Utilities" +.TH LFS-PCC-STATE 1 2025-01-24 "Lustre" "Lustre User Utilities" .SH NAME -lfs pcc state \- display current PCC state of file +lfs-pcc-state \- display current PCC state of file .SH SYNOPSIS -.BI "lfs pcc state " FILE \fR[...] +.SY "lfs pcc state" +.IR FILE \ [...] +.YS .SH DESCRIPTION Display the current PCC cache state of .I FILE @@ -25,15 +27,23 @@ shows additional file states, including .B attaching for files that are not fully copied into cache, .SH EXAMPLES -.TP -.B $ lfs pcc state /mnt/lustre/file Show the PCC cache state of -.BR file . -.TP +.BR file : +.EX +.RS +.B $ lfs pcc state /mnt/lustre/file +.RE +.EE +.SH AVAILABILITY +.B lfs pcc state +is part of the +.BR lustre (7) +filesystem package since release 2.13.0 +.\" Added in commit v2_12_53-113-gf172b11688 .SH SEE ALSO .BR lfs (1), .BR lfs-pcc (1), .BR lfs-pcc-detach (1), .BR lfs-pcc-state (1), -.BR lctl-pcc (8), -.BR llapi_pcc_attach (3) +.BR llapi_pcc_attach (3), +.BR lctl-pcc (8) diff --git a/lustre/doc/lfs-pcc.1 b/lustre/doc/lfs-pcc.1 index bf679ed..f904071 100644 --- a/lustre/doc/lfs-pcc.1 +++ b/lustre/doc/lfs-pcc.1 @@ -1,36 +1,49 @@ -.TH LFS-PCC 1 2019-04-15 "Lustre" "Lustre Utilities" +.TH LFS-PCC 1 2025-01-24 "Lustre" "Lustre User Utilities" .SH NAME lfs-pcc \- commands used to interact with the Persistent Client Cache (PCC). .SH SYNOPSIS -.B lfs pcc attach <\fB--id\fR|\fB-i\fR \fINUM\fR> <\fIfile \fR...> -.br -.B lfs pcc attach <\fB--id\fR|\fB-i\fR \fINUM\fR> <\fB--mnt\fR|\fB-m\fR \fImntpath\fR> <\fIfid \fR...> -.br -.B lfs pcc state <\fIfile \fR...> +.SY "lfs pcc attach" +.BR --id | -i +.IR "NUM FILE" ... +.SY "lfs pcc attach" +.BR --id | -i +.I NUM +.BR --mnt | -m +.IR "MNTPATH FID" ... +.SY "lfs pcc state" +.IR FILE ... +.YS .SH DESCRIPTION -.TP -.B lfs pcc attach <\fB--id\fR|\fB-i\fR \fINUM\fR> <\fIfile \fR...> +.B lfs pcc attach +.BR --id | -i +.IR "NUM FILE" ... +.IP Attach given files on the persistent client cache. Use +.PP .B lfs pcc detach to remove the cached files from PCC either manually, or through automatic mechanisms for the purpose of the cache space management. -.TP -.B lfs pcc attach <\fB--id\fR|\fB-i\fR \fINUM\fR> <\fB--mnt\fR|\fB-m\fR \fImntpath\fR> <\fIfid \fR...> +.PP +.B lfs pcc attach +.BR --id | -i +.I NUM +.BR --mnt | -m +.IR "MNTPATH FID" ... +.IP Attach given files into the persistent client cache by FID(s). -.TP -.B lfs pcc state <\fIfile \fR...> +.PP +.B lfs pcc state +.IR FILE ... +.IP Display the PCC state for given files. -.TP .SH OPTIONS .TP -.B --id | -i +.BR --id ", " -i For RW-PCC, it is HSM ARCHIVE ID to choose which backend for cache files. .TP -.B --mnt | -m +.BR --mnt ", " -m Specify the Lustre mount point. -.TP Before using RW-PCC, you need to configure HSM root and Archive ID mapping properly: -.TP .B lfs pcc add $MNTPATH $PCCPATH \ "$PARAM" Add one PCC backend to the Lustre client. For RW-PCC, when a file is being created, a rule-based policy is used to determine whether it will be cached. @@ -46,43 +59,70 @@ caching rule will be persistently cached automatically. .TP .B lfs pcc clear $MNTPATH Clear and remove all PCC backends for the client. -.TP .SH EXAMPLES -.TP +Enable HSM on the appropriate MDT: +.EX +.RS .B # lctl set_param mdt.$FSNAME-MDT0000.hsm_control=enabled -Enable HSM on the appropriate MDT. -.TP +.RE +.EE +.PP +Launch one copytool on client node to connect cache storage: +.EX +.RS .B # lhsmtool_posix --daemon --hsm-root /mnt/pcc/ --archive=1 /mnt/lustre -Launch one copytool on client node to connect cache storage. -.TP -.B # lfs pcc add /mnt/lustre /mnt/pcc \ "projid={500,1000}&fname={*.h5},uid=1001 rwid=1" +.RE +.EE +.PP Add HSM root and Archive ID (referenced by .IB rwid name-value pair) mapping for RW-PCC. Where "&" represents the logical conjunction operator while "," represents the logical disjunction operator. The example rule means that new files are only auto cached if the project ID is either 500 or 1000 and the suffix of the file name is “h5” or the user ID is -1001. -.TP -.B $ lfs pcc attach -i 1 /mnt/lustre/file +1001: +.EX +.RS +.B # lfs pcc add /mnt/lustre /mnt/pcc \ "projid={500,1000}&fname={*.h5},uid=1001 rwid=1" +.RE +.EE +.PP Attach an existing file into PCC and migrate data from lustre to Cache Device, -any I/O to the Lustre file will direct to the RW-PCC copy. -.TP +any I/O to the Lustre file will direct to the RW-PCC copy: +.EX +.RS +.B $ lfs pcc attach -i 1 /mnt/lustre/file +.RE +.EE +.PP +Attach an existing file referenced by FID "0x200000401:0x1:0x0" into PCC: +.EX +.RS .B $ lfs pcc attach_fid -i 1 -m /mnt/lustre 0x200000401:0x1:0x0 -Attach an existing file referenced by FID "0x200000401:0x1:0x0" into PCC. -.TP +.RE +.EE +.PP +Display the PCC state of the file "/mnt/lustre/file": +.EX +.RS .B $ lfs pcc state /mnt/lustre/file -.br file: /mnt/lustre/file, type: readwrite, PCC file: /mnt/pcc/0004/0000/0bd1/0000/0002/0000/0x200000bd1:0x4:0x0, user number: 1, flags: 6 -.br -Display the PCC state of the file "/mnt/lustre/file". -.TP +.RE +.EE +.PP +Display the PCC state of the file "/mnt/lustre/file": +.EX +.RS .B $ lfs pcc state /mnt/lustre/file -.br file: /mnt/lustre/file, type: readwrite, PCC file: /mnt/pcc/0004/0000/0bd1/0000/0002/0000/0x200000bd1:0x4:0x0, user number: 1, flags: 6 -.br -Display the PCC state of the file "/mnt/lustre/file". -.TP +.RE +.EE +.SH AVAILABILITY +.B lfs pcc attach +is part of the +.BR lustre (7) +filesystem package since release 2.13.0 +.\" Added in commit v2_12_53-113-gf172b11688 .SH SEE ALSO .BR lfs (1), .BR lfs-hsm (1), diff --git a/lustre/doc/lfs-project.1 b/lustre/doc/lfs-project.1 index c23b696..243f7a1 100644 --- a/lustre/doc/lfs-project.1 +++ b/lustre/doc/lfs-project.1 @@ -1,35 +1,57 @@ -.TH LFS-PROJECT 1 2017-10-26 "Lustre" "Lustre Utilities" +.TH LFS-PROJECT 1 2025-01-24 "Lustre" "Lustre User Utilities" .SH NAME lfs-project \- Change or list project attribute for specified file or directory. .SH SYNOPSIS -.BR "lfs project" " [" -d | -r ] " "< \fI file | directory...\fR> -.br -.BR "lfs project" " {" -p " "\fIID " |" -s } " "[ -r ] " "<\fI file | directory...\fR> -.br -.BR "lfs project" " -c" " [" -d | -r " [" -p " "\fIID ] " [" -0 ] ] " <" file | directory...> -.br -.BR "lfs project" " -C" " [" -d | -r "] [" -k ] " <" file | directory...> -.br +.SY "lfs project" +.RB [ -d | -r ] +.IR FILE | DIRECTORY ... +.SY "lfs project" +.RB { -p +.I ID +.RB | -s } +.RB [ -r ] +.IR FILE | DIRECTORY ... +.SY "lfs project" +.B -c +.RB [ -d | -r +.RB [ -p +.IR ID ] +.RB [ -0 ]] +.IR FILE | DIRECTORY ... +.SY "lfs project" +.B -C +.RB [ -d | -r ] +.RB [ -k ] +.IR FILE | DIRECTORY ... +.YS .SH DESCRIPTION -.TP -.BR "lfs project" " [" -d | -r ] -.RI < file | directory...> +.BR "lfs project" +.RB [ -d | -r ] +.IR FILE | DIRECTORY ... .TP List project ID and flags on file(s) or directories. .TP .B -d -Show the directory's own project ID and flags, override \fB-r\fR option. +Show the directory's own project ID and flags, override +.B -r +option. .TP .B -r Recursively list all descendants'(of the directory) project attribute. -.TP -.BR "lfs project" " {" -p " "\fIID " |" -s } " "[ -r ] -.RI < file | directory...> +.PP +.BR "lfs project" +.BR { -p +.I ID +.RB | -s } +.RB [ -r ] +.IR FILE | DIRECTORY ... .TP Set project ID and/or inherit flag for specified file(s) or directories. .TP -.B -p <\fIID\fR> -Set project \fIID\fR with given value for the specified file or directory +.BI -p \ ID +Set project +.I ID +with given value for the specified file or directory .TP .B -s Set the @@ -38,30 +60,42 @@ attribute on directories, so that new files and subdirectories created therein will inherit the project ID and attribute from the parent. .TP .B -r -Set project \fIID\fR with the directory's project ID for all -its descendants (with \fB-p\fR specified). For descendant directories, also set -inherit flag (if \fI-s\fR specified). -.TP -.BR "lfs project" " -c" " [" -d|-r " [" -p " "\fIID ] " [" -0 ] ] -.RI < file | directory...> -.TP +Set project +.I ID +with the directory's project ID for all its descendants (with +.B -p +specified). For descendant directories, also set +inherit flag (if +.B -s +specified). +.PP +.BR "lfs project" +.B -c +.RB [ -d | -r [ -p +.IR ID ] +.RB [ -0 ]] +.IR FILE | DIRECTORY ... +.PP Check project ID and flags on file(s) or directories, print outliers. .TP .B -c Check project ID and inherit flag on specified file(s) or directory. If .B -p -is not given, then use the project ID on the top-level directory -, otherwise use the ID specified with +is not given, then use the project ID on the top-level directory, +otherwise use the ID specified with .BR -p . if checking a directory and or recursively, print only files that do not match. .TP .B -0 Print pathnames returned by -c with a trailing NUL, suitable for use by .B 'xargs -0 lfs project -p'. -.TP -.BR "lfs project" " -C [" -d | -r "] [" -k ] -.RI < file | directory...> -.TP +.PP +.BR "lfs project" +.B -C +.RB [ -d | -r ] +.RB [ -k ] +.IR FILE | DIRECTORY ... +.PP Clear the project inherit flag and ID on the file(s) or directories .TP .B -C @@ -71,28 +105,41 @@ Clear inherit attribute and reset project ID to 0 for file or directory. Clear only the directory itself. .TP .B -r -Clear the directory and all its descendants recursively. -.TP -.B "" -If neither \fB-d\fR nor \fB-r\fR is specified, clear the directory and its +Clear the directory and all its descendants recursively. If neither +.B -d +nor +.B -r +is specified, clear the directory and its immediate children. .TP .B -k Keep the project ID unchanged. -.TP .SH EXAMPLES -.TP -.B $ lfs project -srp 1000 /mnt/lustre/dir1 set directory quota on .BR /mnt/lustre/dir1, -all descendants' project ID and inherit attribute are set. -.TP -.B $ lfs project -cr -p 1000 /mnt/lustre/dir1 -check directory +all descendants' project ID and inherit attribute are set: +.EX +.RS +.B $ lfs project -srp 1000 /mnt/lustre/dir1 +.RE +.EE +.PP +Check directory .BR /mnt/lustre/dir1, whether all files and directories ID are 1000, inherit attribute is properly set for all directories, print mismatch -if any are found. +if any are found: +.EX +.RS +.B $ lfs project -cr -p 1000 /mnt/lustre/dir1 +.RE +.EE +.SH AVAILABILITY +.B lfs project +is part of the +.BR lustre (7) +filesystem package since release 1.4.0 +.\" Added in commit 1.3.4-465-g761ab6a5cd .SH SEE ALSO -.BR lfs (1) +.BR lfs (1), .BR xargs (1)