From 0caae7865f9a2d10518291e44a550875b1e257d3 Mon Sep 17 00:00:00 2001 From: Frederick Dilger Date: Wed, 28 Aug 2024 14:45:11 -0600 Subject: [PATCH] LU-4315 doc: updating ll[d-v] 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: - ll_decode_filter_fid.8 - ll_decode_linkea.8 - lljobstat.8 - llobdstat.8 - llog_reader.8 - llsom_sync.8 - llstat.8 - llverdev.8 - llverfs.8 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: Id0b09d1e1826f95d6e5fe820f61ed5e32232ce90 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56190 Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin Tested-by: jenkins Tested-by: Maloo --- lustre/doc/ll_decode_filter_fid.8 | 33 ++++++------ lustre/doc/ll_decode_linkea.8 | 43 +++++++-------- lustre/doc/lljobstat.8 | 50 ++++++++++-------- lustre/doc/llobdstat.8 | 32 ++++++++---- lustre/doc/llog_reader.8 | 82 ++++++++++++++++------------- lustre/doc/llsom_sync.8 | 107 +++++++++++++++++++------------------- lustre/doc/llstat.8 | 53 +++++++++++++------ lustre/doc/llverdev.8 | 73 ++++++++++++++------------ lustre/doc/llverfs.8 | 51 +++++++++++------- 9 files changed, 298 insertions(+), 226 deletions(-) diff --git a/lustre/doc/ll_decode_filter_fid.8 b/lustre/doc/ll_decode_filter_fid.8 index 488e709..64f0fac 100644 --- a/lustre/doc/ll_decode_filter_fid.8 +++ b/lustre/doc/ll_decode_filter_fid.8 @@ -1,11 +1,11 @@ -.TH ll_decode_filter_fid 1 "Dec 15, 2010" Lustre "utilities" +.TH LL_DECODE_FILTER_FID 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME ll_decode_filter_fid \- display Lustre Object ID and MDT parent FID .SH SYNOPSIS -.B ll_decode_filter_fid +.SY ll_decode_filter_fid .I object_file .RI [ "object_file ..." ] -.br +.YS .SH DESCRIPTION .B ll_decode_filter_fid decodes and prints the Lustre OST object ID and MDT FID and stripe index @@ -20,17 +20,14 @@ modified by Lustre after that time. .PP The OST object ID (objid) is useful in case of OST directory corruption, though normally the -.SH EXAMPLE -.fi -root@oss1# cd /mnt/ost/lost+found -.fi -root@oss1# ll_decode_filter_fid #12345[4,5,8] -.fi -#123454: objid=690670 seq=0 parent=[0x751c5:0xfce6e605:0x0] -.fi -#123455: objid=614725 seq=0 parent=[0x18d11:0xebba84eb:0x1] -.fi -#123458: objid=533088 seq=0 parent=[0x21417:0x19734d61:0x0] +.SH EXAMPLES +.EX +.B root@oss1# cd /mnt/ost/lost+found +.B root@oss1# ll_decode_filter_fid #12345[4,5,8] +\𞈾: objid=690670 seq=0 parent=[0x751c5:0xfce6e605:0x0] +\𞈿: objid=614725 seq=0 parent=[0x18d11:0xebba84eb:0x1] +\𞉂: objid=533088 seq=0 parent=[0x21417:0x19734d61:0x0] +.EE .PP This shows that the 3 files in lost+found have decimal object IDs 690670, 614725, and 533088, respectively. The object sequence number (formerly @@ -48,5 +45,11 @@ the internal inode number. .PP The idx field shows the stripe number of this OST object in the Lustre RAID-0 striped file. +.SH AVAILABILITY +.B ll_decode_filter_fid +is part of the +.BR lustre (7) +filesystem package since release 2.0.0 +.\" Added in commit v1_10_0_43-39-g48ee13b5ee .SH SEE ALSO -.BR lustre (7), +.BR lustre (7) diff --git a/lustre/doc/ll_decode_linkea.8 b/lustre/doc/ll_decode_linkea.8 index 98cf8f3..c4c789b 100644 --- a/lustre/doc/ll_decode_linkea.8 +++ b/lustre/doc/ll_decode_linkea.8 @@ -1,11 +1,11 @@ -.TH ll_decode_linkea 1 "May 25, 2016" Lustre "utilities" +.TH LL_DECODE_LINKEA 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME ll_decode_linkea \- display parent FIDs and name of a Lustre file .SH SYNOPSIS -.B ll_decode_linkea -.I file -.RI [ "file ..." ] -.br +.SY ll_decode_linkea +.I FILE +.RI [ FILE ...] +.YS .SH DESCRIPTION .B ll_decode_linkea decodes and prints the Lustre parent FIDs and name of a Lustre file, which @@ -21,32 +21,33 @@ The parent FID is useful in case of MDT corruption. The fsck of ldiskfs can recover most of the ldiskfs hierarchy, but it might leave some files or directories under lost+found. The parent FIDs can be used to determine the right Lustre paths to move them to. -.SH EXAMPLE -.fi -root@mdt1# cd /mnt/mdt/lost+found -.fi -root@mdt1# ll_decode_linkea \#123451 \#123452 -.fi -#123451: count 2 -.fi +.SH EXAMPLES +.EX +.B root@mdt1# cd /mnt/mdt/lost+found +.B root@mdt1# ll_decode_linkea \#123451 \#123452 +\𞈻: count 2 0: [0x200034021:0x2:0x0], name "file1" -.fi 1: [0x200034021:0x1:0x0], name "file1_link" -.fi -#123452: count 1 -.fi +\𞈼: count 1 0: [0x200000007:0x1:0x0], name "file2" +.EE .PP -This shows that the 2 files in lost+found. ll_decode_linkea prints all of the -parent FIDs of these files. file1 has two hard links, that is why it has two -parent directories. Command +This shows that there are 2 files in lost+found. +.B ll_decode_linkea +prints all of the parent FIDs of these files. +file1 has two hard links, that is why it has two parent directories. .B lfs fid2path could be used to extract the paths of the parents. .PP Since "trusted.link" xattr is accessible on Lustre client too, .B ll_decode_linkea could also be used on Lustre client. -.PP +.SH AVAILABILITY +.B ll_decode_linkea +is part of the +.BR lustre (7) +filesystem package since release 2.9.0 +.\" Added in commit v2_8_59_0-28-g11a138cb9d .SH SEE ALSO .BR lfs (1), .BR lustre (7) diff --git a/lustre/doc/lljobstat.8 b/lustre/doc/lljobstat.8 index 63aa762..cce7b8c 100644 --- a/lustre/doc/lljobstat.8 +++ b/lustre/doc/lljobstat.8 @@ -1,10 +1,8 @@ -.TH lljobstat 8 "Oct 14, 2022" Lustre "utilities" - +.TH LLJOBSTAT 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME lljobstat \- display top jobs and statistics - .SH SYNOPSIS -.B "llobdstat" +.SY "llobdstat" .RB [ -c|--count .IR COUNT ] .RB [ -i|--interval @@ -17,7 +15,7 @@ lljobstat \- display top jobs and statistics .IR PARAM ] .RB [ --fullname ] .RB [ --no-fullname ] - +.YS .SH DESCRIPTION .B lljobstat reads and parses the job_stats files on local node, @@ -25,9 +23,9 @@ sums up the operations of each job, and displays the top jobs. Repeat for some times or forever with given interval. .P Type Ctrl-C to stop printing. - .SS Abbreviations -\fBlljobstat\fR displays abbreviations of operation names as listed below: +.B lljobstat +displays abbreviations of operation names as listed below: .P .nf ops: total number of operations @@ -37,39 +35,37 @@ mn: mknod, mv: rename, op: open, pa: prealloc, pu: punch qc: quotactl, rd: read, rm: rmdir, sa: setattr, si: set_info st: statfs, sx: setxattr, sy: sync, ul: unlink, wr: write .fi - -.SH "OPTIONS" +.SH OPTIONS .TP -\fB-c|--count\fR \fICOUNT\fR +.BR -c ", " --count \ \fICOUNT how many top jobs are listed. Default 5. .TP -\fB-i|--interval\fR \fIINTERVAL\fR +.BR -i ", " --interval \ \fIINTERVAL interval in seconds before list top jobs again. Default 10. .TP -\fB-n|--repeats\fR \fIREPEATS\fR +.BR -n ", " --repeats \ \fIREPEATS how many times to repeat. Default unlimited. .TP -\fB-m|--mdt\fR +.BR -m ", " --mdt get data from only job_stats of MDTs. .TP -\fB-o|--ost\fR +.BR -o ", " --ost get data from only job_stats of OSTs. .TP -\fB--param\fR \fIPARAM\fR +.BI --param " PARAM" get data from only PARAM path. For example, "*.lustre-*.job_stat". .TP -\fB--fullname\fR +.B --fullname show full name of operations. Default no. .TP -\fB--no-fullname\fR +.B --no-fullname show abbreviated name of operations. .TP -\fB-h|--help\fR +.BR -h ", " --help print help message. - -.SH EXAMPLE -.nf -# lljobstat -n 1 -c 3 +.SH EXAMPLES +.EX +.B # lljobstat -n 1 -c 3 --- timestamp: 1665623345 top_jobs: @@ -77,4 +73,12 @@ top_jobs: - touch.500: {ops: 48, op: 8, cl: 8, mn: 8, ga: 8, sa: 16} - dd.0: {ops: 38, op: 4, cl: 4, mn: 1, ga: 1, sa: 3, gx: 3, wr: 19, pu: 3} \[char46].. -.fi +.EE +.SH AVAILABILITY +.B lljobstat +is part of the +.BR lustre (7) +filesystem package since release 2.16.0 +.\" Added in commit v2_15_53-96-ge2812e8773 +.SH SEE ALSO +.BR llobdstat (8) diff --git a/lustre/doc/llobdstat.8 b/lustre/doc/llobdstat.8 index 7b71045..e53202e 100644 --- a/lustre/doc/llobdstat.8 +++ b/lustre/doc/llobdstat.8 @@ -1,25 +1,27 @@ -.TH llobdstat 1 "Jul 7, 2008" Lustre "utilities" +.TH LLOBDSTAT 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME llobdstat \- display OST statistics .SH SYNOPSIS -.B "llobdstat ost_name [interval]" -.br +.SY llobdstat +.I ost_name +.RI [ interval ] +.YS .SH DESCRIPTION .B llobdstat displays a line of OST statistics for the given -.I ost_name +.I OST_NAME every -.I interval +.I INTERVAL seconds. It should be run directly on an OSS node. Type control-C to stop statistics printing. -.SH EXAMPLE -.nf -# llobdstat liane-OST0002 1 +.SH EXAMPLES +.EX +.B # llobdstat liane-OST0002 1 /usr/bin/llobdstat on liane-OST0002 Processor counters run at 2800.189 MHz Read: 1.21431e+07, Write: 9.93363e+08, create/destroy: 24/1499, stat: 34, punch: 18 [NOTE: cx: create, dx: destroy, st: statfs, pu: punch ] - +\& Timestamp Read-delta ReadRate Write-delta WriteRate -------------------------------------------------------- 1217026053 0.00MB 0.00MB/s 0.00MB 0.00MB/s @@ -29,5 +31,13 @@ Timestamp Read-delta ReadRate Write-delta WriteRate 1217026057 0.00MB 0.00MB/s 0.00MB 0.00MB/s 1217026058 0.00MB 0.00MB/s 0.00MB 0.00MB/s 1217026059 0.00MB 0.00MB/s 0.00MB 0.00MB/s st:1 -... -.fi +\&... +.EE +.SH AVAILABILITY +.B llobdstat +is part of the +.BR lustre (7) +filesystem package since release 0.8.0 +.\" Added in commit 0.7.1-38-g576c9a8212 +.SH SEE ALSO +.BR lljobstat (8) diff --git a/lustre/doc/llog_reader.8 b/lustre/doc/llog_reader.8 index d1fc26c..4489c19 100644 --- a/lustre/doc/llog_reader.8 +++ b/lustre/doc/llog_reader.8 @@ -1,57 +1,62 @@ -.TH llog_reader 8 "2009 Apr 02" Lustre "System management commands" +.TH LLOG_READER 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME llog_reader \- lustre on-disk log parsing utility .SH SYNOPSIS -.B "llog_reader filename" -.br +.SY llog_reader +.I FILENAME +.YS .SH DESCRIPTION .B llog_reader parses the binary format of Lustre's on-disk configuration logs. -It can only read the logs. Use +It can only read the logs. Use .B tunefs.lustre to write to them. -.LP +.SH CAVEATS +Although they are stored in the CONFIGS directory, +.I mountdata +files do not use the config log format and will confuse +.BR llog_reader . +.SH EXAMPLES To examine a log file on a stopped Lustre server, first mount its backing file system as ldiskfs, then use .B llog_reader -to dump the log file's contents, e.g. -.IP -.nf -mount -t ldiskfs /dev/sda /mnt/mgs +to dump the log file's contents: +.RS +.EX +.B # mount -t ldiskfs /dev/sda /mnt/mgs llog_reader /mnt/mgs/CONFIGS/tfs-client -.fi -.LP +.EE +.RE +.PP To examine the same log file on a running Lustre server, use the ldiskfs-enabled debugfs utility (called .B debug.ldiskfs -on some distros) to extract the file, e.g. -.IP -.nf -debugfs -c -R 'dump CONFIGS/tfs-client /tmp/tfs-client' /dev/sda +on some distros) to extract the file: +.RS +.EX +.B # debugfs -c -R 'dump CONFIGS/tfs-client /tmp/tfs-client' /dev/sda llog_reader /tmp/tfs-client -.fi -.LP +.EE +.RE +.PP To examine Changelog records on a stopped Lustre server, first mount its backing file system as ldiskfs, then use .B llog_reader -to dump the log changelog's contents, e.g. -.IP -.nf -# mount -t ldiskfs /dev/sda /mnt/mgs -# llog_reader /mnt/mgs/changelog_catalog +to dump the log changelog's contents: +.RS +.EX +.B # mount -t ldiskfs /dev/sda /mnt/mgs +.B # llog_reader /mnt/mgs/changelog_catalog rec #1 type=1064553b len=64 offset 8192 Header size : 8192 Time : Mon Jan 22 23:28:24 2018 Number of records: 1 Target uuid : ----------------------- -.fi -#01 (064)id=[0x5:0x1:0x0]:0 path= -.B "O/1/d5/5" - -# llog_reader /mnt/mgs/ -.B O/1/d5/5 -.nf +\ (064)id=[0x5:0x1:0x0]:0 path= +.I "O/1/d5/5" +.B # llog_reader /mnt/mgs/ +.I O/1/d5/5 rec #1 type=10660000 len=136 offset 8192 rec #2 type=10660000 len=136 offset 8328 rec #3 type=10660000 len=128 offset 8464 @@ -60,16 +65,21 @@ Time : Mon Jan 22 23:30:01 2018 Number of records: 3 Target uuid : ----------------------- -#01 (136)changelog record id:0x0 cr_flags:0x9000 cr_type:CREAT(0x1) +\ (136)changelog record id:0x0 cr_flags:0x9000 cr_type:CREAT(0x1) date:'14:30:01.370700741 2018.01.22' target:[0x200000402:0x1:0x0] cr_extra_flags:0x3 user:0:0 nid:10.128.11.159@tcp parent:[0x200000007:0x1:0x0] name:fileA -.fi -.SH CAVEATS -Although they are stored in the CONFIGS directory, \fImountdata\fR -files do not use the config log format and will confuse \fBllog_reader\fR. +.EE +.RE +.SH AVAILABILITY +.B llog_reader +is part of the +.BR lustre (7) +filesystem package since release 1.4.0 +.\" Added in commit 1.3.4-1130-g113303973e .SH SEE ALSO -Lustre Operations Manual, Section 21.1, \fITroubleshooting Lustre\fR. -.br .BR lustre (7), .BR tunefs.lustre (8) +.P +Lustre Operations Manual, +.IR "Troubleshooting Lustre" . diff --git a/lustre/doc/llsom_sync.8 b/lustre/doc/llsom_sync.8 index ba7348e..7a6a333 100644 --- a/lustre/doc/llsom_sync.8 +++ b/lustre/doc/llsom_sync.8 @@ -1,92 +1,93 @@ -.TH llsom_sync 8 "2018 Jan 10" Lustre "Lustre Filesystem utility" +.TH LLSOM_SYNC 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME llsom_sync \- Utility to sync file LSOM xattr. .SH SYNOPSIS -.br -.B llsom_sync --mdt|-m --user|-u -.br -.B\t\t\t [--daemonize|-d] [--verbose|-v] [--interval|-i] -.br -.B\t\t\t [--min-age|-a] [--max-cache|-c] [--sync|-s] -.br - +.SY llsom_sync +.RB { --mdt | -m }\c +.BI = MDT +.RB { --user | -u }\c +.BI = USER_ID +.RB [ --daemonize | -d ] +.RB [ --verbose | -v ] +.RB [ --interval | -i ] +.RB [ --min-age | -a ] +.RB [ --max-cache | -c ] +.RB [ --sync | -s ] +.I LUSTRE_MOUNT_POINT +.YS .SH DESCRIPTION .B llsom_sync is designed to sync file LSOM xattr in the Lustre Filesystem by using Lustre MDT changelogs. A changelog user must be registered (see lctl (8) changelog_register) before using this tool. - .SH OPTIONS - -.B --mdt= -.br +.TP +.BR -m ", " --mdt= \fIMDT The metadata device which need to be synced the LSOM xattr of files. A changelog user must be registered for this device. - -.B --user= -.br +.TP +.BR -u ", " --user= \fIUSER_ID The changelog user id for the above MDT device. See lctl(8) changelog_register. - +.TP .B --daemonize -.br -Daemonize the program. In daemon mode, the utility will scan, process the -changelog records and sync the LSOM xattr for files periodically. - +Daemonize the program. In daemon mode, the utility will scan, +process the changelog records and sync the LSOM xattr for files periodically. +.TP .B --verbose -.br Produce a verbose output. - +.TP .B --interval -.br The time interval to scan the Lustre changelog and process the log record in daemon mode. - +.TP .B --min-age -.br The time that llsom_sync tool will not try to sync the SOM data for any files -closed less than this many seconds old. The default min-age value is 600s -(10 minutes). - +closed less than this many seconds old. +The default min-age value is 600s (10 minutes). +.TP .B --max-cache -.br The total memory used for the FID cache which can be with a suffix [KkGgMm]. The default max-cache value is 256MB. For the parameter value < 100, it is taken as the percentage of total memory size used for the FID cache instead of the cache size. - +.TP .B --sync -.br Sync file data to make the dirty data out of cache to ensure the blocks count is correct when update the file LSOM xattr. This option could hurt server performance significantly if thousands of fsync requests are sent. - .SH EXAMPLES - -.TP -Register a changelog consumer for MDT lustre-MDT0000 -$ cl_user=$(ssh root@mds01 lctl --device lustre-MDT0000 changelog_register -n) -.br -$ echo $cl_user -.br +Register a changelog consumer for MDT lustre-MDT0000: +.RS +.EX +.B # cl_user=$(ssh root@mds01 lctl --device lustre-MDT0000 changelog_register -n) +.B # echo $cl_user cl1 - -.TP +.EE +.RE +.PP After perform some file operations on the Lustre Filesystem with mount point '/mnt/lustre' and the filesystem undergoes some changes, sync file LSOM xattr: -$ llsom_sync --mdt=lustre-MDT0000 --user=$cl_user \\ -.br - --verbose /mnt/lustre - -.TP +.RS +.EX +.B # llsom_sync --mdt=lustre-MDT0000 --user=$cl_user --verbose /mnt/lustre +.EE +.RE +.PP To deregister the changelog user (e.g. after this example, or if SOM updates are no longer needed): -.br -$ ssh root@mds01 lctl --device lustre-MDT0000 changelog_deregister $cl_user - -.SH AUTHOR -The llsom_sync command is part of the Lustre filesystem. - +.RS +.EX +.B # ssh root@mds01 lctl --device lustre-MDT0000 changelog_deregister $cl_user +.EE +.RE +.SH AVAILABILITY +The +.B llsom_sync +command is part of the +.BR lustre (7) +filesystem package since release 2.12.0 +.\" Added in commit v2_11_53_0-60-gcaba6b9af0 .SH SEE ALSO .BR lustre (7), .BR lctl (8) diff --git a/lustre/doc/llstat.8 b/lustre/doc/llstat.8 index db2bf89..e723a44 100644 --- a/lustre/doc/llstat.8 +++ b/lustre/doc/llstat.8 @@ -1,36 +1,42 @@ -.TH llstat 1 "Jul 7, 2008" Lustre "utilities" +.TH LLSTAT 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME llstat \- print Lustre statistics .SH SYNOPSIS -.B "llstat [-c] [-g] [-i interval] stats_file" -.br +.SY llstat +.RB [ -c ] +.RB [ -g ] +.RB [ -i +.IR INTERVAL ] +.I STATS_FILE +.YS .SH DESCRIPTION .B llstat can display statistics from any of several lustre stats files that -share a common format, updated every \fIinterval\fR seconds. +share a common format, updated every +.I INTERVAL +seconds. Use control-C to stop statistics printing. +.SH OPTIONS .TP -.I "\-c" +.B -c Clear the stats file first. .TP -.I "\-i interval" +.BI -i " INTERVAL" Polling period in seconds. .TP -.I "\-g" +.B -g Graphable output format. .TP -.I "\-h" +.B -h Display help information. .TP -.I "stats_file" +.I STATS_FILE Either the full path to a stats file, or the shorthand: -\fImds\fR or \fIost\fR. -.SH EXAMPLE -To monitor the OST RPC stats every second: -.IP -llstat -i 1 ost +.I mds +or +.IR ost . .SH FILES -.nf +.EX llite.*.stats lwp.*.stats mdc.*.stats @@ -41,4 +47,19 @@ osp.*.stats ldlm.services.*.stats mds.MDS.*.stats ost.OSS.*.stats -.fi +.EE +.SH EXAMPLES +To monitor the OST RPC stats every second: +.RS +.EX +.B # llstat -i 1 ost +.EE +.RE +.SH AVAILABILITY +.B llstat +is part of the +.BR lustre (7) +filesystem package since release 0.8.0 +.\" Added in commit 0.7.1-38-g576c9a8212 +.SH SEE ALSO +.BR lljobstat (8) diff --git a/lustre/doc/llverdev.8 b/lustre/doc/llverdev.8 index 790b111..aa88995 100644 --- a/lustre/doc/llverdev.8 +++ b/lustre/doc/llverdev.8 @@ -2,23 +2,24 @@ .\" Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. .\" This file may be copied under the terms of the GNU Public License, v2. .\" -.TH llverdev 8 "2008 Mar 15" Lustre "configuration utilities" +.TH LLVERDEV 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME llverdev - verify a block device is functioning properly over its full size .SH SYNOPSIS -.BI llverdev +.SY llverdev .RB [ -c -.IR chunksize ] +.IR CHUNKSIZE ] .RB [ -f "] [" -h ] .RB [ -o -.IR offset_kb ] +.IR OFFSET_KB ] .RB [ -l "] [" -p "] [" -r ] .RB [ -s -.IR size_mb ] +.IR SIZE_MB ] .RB [ -t -.IR timestamp ] +.IR TIMESTAMP ] .RB [ -v "] [" -w ] -.I device +.I DEVICE +.YS .SH DESCRIPTION Sometimes kernel drivers or hardware devices have bugs that prevent them from accessing the full device size correctly, or possibly have bad sectors on disk @@ -42,68 +43,76 @@ so it is advisable to start with a partial verification to ensure the device is minimally sane before investing the time in a full verification. .SH OPTIONS .TP -.BR -c | --chunksize " \fIchunk_mb" +.BR -c ", " --chunksize \ \fICHUNK_MB IO chunk size in megabytes (default=1), with optional KMG suffix. .TP -.BR -f | --force +.BR -f ", " --force force test to run without confirmation that the device will be overwritten and all data therein will be permanently destroyed. .TP -.BR -h | --help +.BR -h ", " --help display a brief help message. .TP -.BR -l | --long +.BR -l ", " --long Run a full check, writing and then reading and verifying every block on the disk. .TP -.BR -o | --offset " \fIoffset_kb" +.BR -o ", " --offset \ \fIOFFSET_KB offset of IO start in kilobytes (default=0), with optional KMGTP suffix. .TP -.BR -p | --partial +.BR -p ", " --partial Run a partial check, only doing periodic checks across the device (1GB steps). .TP -.BR -r | --read +.BR -r ", " --read Run test in read (verify) mode only, after having run the test in .B -w mode previously. .TP -.BR -s | --size " \fIsize_mb" +.BR -s ", " --size \ \fISIZE_MB device or file size in megabytes to use for the test, with optional KMGTP suffix. If unspecified, use the actual device or file size (or write until an error is hit if 0). .TP -.BR -t | --timestamp " \fItimestamp" +.BR -t ", " --timestamp \ \fITIMESTAMP Set test start time as printed at the start of a previously interrupted test to ensure that the validation data is the same across the whole filesystem (default=current time()) .TP -.BR -v | --verbose +.BR -v ", " --verbose Run test in verbose mode, listing each read and write operation. .TP -.BR -w | --write +.BR -w ", " --write Run test in write (test-pattern) mode (default run both read and write) .SH EXAMPLES -.TP -Run a partial device verification on \fB/dev/sda\fR: -.B llverdev -v -p /dev/sda -.br +Run a partial device verification on +.BR /dev/sda : +.RS +.EX +.B # llverdev -v -p /dev/sda llverdev: permanently overwrite all data on /dev/sda (yes/no)? y -.br llverdev: /dev/sda is 4398046511104 bytes (4096.0 GB) in size -.br Timestamp: 1009839028 -.br Current write offset: 4096 kB -.TP -Continue an interrupted verification at offset \fB4096\fRkB from the start of the device, using the same timestamp as the previous run: -.B llverdev -f -v -p --offset=4096 --timestamp=1009839028 /dev/sda -.br +.EE +.RE +.PP +Continue an interrupted verification at offset +.BR 4096 kB +from the start of the device, using the same timestamp as the previous run: +.RS +.EX +.B # llverdev -f -v -p --offset=4096 --timestamp=1009839028 /dev/sda llverdev: /dev/sda is 4398046511104 bytes (4096.0 GB) in size -.br Timestamp: 1009839028 -.br write complete -.br read complete +.EE +.RE +.SH AVAILABILITY +.B llverdev +is part of the +.BR lustre (7) +filesystem package since release 1.4.0 +.\" Added in commit 1.3.4-1130-g113303973e .SH SEE ALSO .BR llverfs (8) diff --git a/lustre/doc/llverfs.8 b/lustre/doc/llverfs.8 index 288bde5..4862030 100644 --- a/lustre/doc/llverfs.8 +++ b/lustre/doc/llverfs.8 @@ -1,26 +1,30 @@ -.TH llverfs 8 "2023 Apr 23" Lustre "configuration utilities" +.TH LLVERFS 8 2024-08-28 Lustre "Lustre Configuration Utilities" .SH NAME llverfs - filesystem verification tool for ldiskfs based on ext3vt .SH SYNOPSIS -.BI llverfs +.SY llverfs .RB [ -c .I CHUNKSIZE_MB .RB ] .RB [ -h ] .RB [ -o .IR OFFSET_KB ] -.RB [ -l "] [" -p "] [" -r ] +.RB [ -l ] +.RB [ -p ] +.RB [ -r ] .RB [ -s .IR SIZE_MB ] .RB [ -t .IR TIMESTAMP ] -.RB [ -v "] [" -w ] +.RB [ -v ] +.RB [ -w ] .I DEVICE +.YS .SH DESCRIPTION This program tests the correct operation of large filesystems and the underlying block storage device(s). This tool has two working modes: - +.P In full mode, the program creates a subdirectory in the test filesystem, writes n (files_in_dir, default=32) large (4GB) files to the directory with the test pattern at the start of each 4KB block. @@ -29,7 +33,7 @@ run), relative file offset and per-file unique identifier (inode number, to detect data written to the wrong location on disk). This continues until the whole filesystem is full and then the tool verifies that the data in all of the test files is correct. - +.P In partial mode, the tool creates test directories with the EXT2_TOPDIR_FL flag set (if supported) to spread the directory data around the block device instead of localizing it in a single place. @@ -39,25 +43,28 @@ then writes a single 1MB file in each directory. The tool then verifies that the data in each file is correct. .SH OPTIONS .TP -.BR -c | --chunksize " \fICHUNKSIZE_MB" +.BR -c ", " --chunksize " \fICHUNKSIZE_MB" IO chunk size in megabytes (default=1), with optional KMG suffix. .TP -.BR -h | --help +.BR -h ", " --help Display a brief help message. .TP -.BR -l | --long | --full +.BR -l ", " --long | --full Run a full check, 4GB files with 4k blocks .TP -.BR -n | --num_dirs " \fICOUNT" -\fICOUNT\fR number of sub-directories to create. (\fICOUNT\fR must be >0 and <= INT_MAX) +.BR -n ", " --num_dirs " \fICOUNT" +.I COUNT +number of sub-directories to create. +.RI ( COUNT +must be >0 and <= INT_MAX) .TP -.BR -o | --offset " \fIOFFSET_KB" +.BR -o ", " --offset " \fIOFFSET_KB" offset of IO start in kilobytes (default=0), with optional KMGTP suffix. .TP -.BR -p | --partial +.BR -p ", " --partial Run a partial check, with 1MB files .TP -.BR -r | --read +.BR -r ", " --read Run test in read (verify) mode only, after having run the test in .B -w mode previously. The flag @@ -66,20 +73,26 @@ is also needed in this case, using the timestamp printed out during the .B --write run. .TP -.BR -s | --filesize " \fISIZE_MB" +.BR -s ", " --filesize " \fISIZE_MB" File size in megabytes to use for the test, with optional KMGTP -suffix. The default is 4096MB. +suffix. The default is 4096MB. .TP -.BR -t | --timestamp " \fITIMESTAMP" +.BR -t ", " --timestamp " \fITIMESTAMP" Set test start time as printed at the start of a previously interrupted test. This is to ensure that read phases (or multiple read phases) after a separate write phase will be able to check the validation data. (default=current time()) .TP -.BR -v | --verbose +.BR -v ", " --verbose Run test in verbose mode, listing each read and write operation. .TP -.BR -w | --write +.BR -w ", " --write Run test in write (test-pattern) mode (default run both read and write) +.SH AVAILABILITY +.B llverfs +is part of the +.BR lustre (7) +filesystem package since release 1.4.0 +.\" Added in commit 1.3.4-1130-g113303973e .SH SEE ALSO .BR llverdev (8) -- 1.8.3.1