-.TH lfs 1 "2003 Oct 29" Lustre "configuration utilities"
+.TH lfs 1 "2008 Mar 15" Lustre "user utilities"
.SH NAME
-lfs \- Lustre utility to create a file with specific striping pattern, find the striping pattern of exiting files
+lfs \- Lustre utility to create a file with specific striping pattern, find the striping pattern of existing files
.SH SYNOPSIS
.br
.B lfs
.br
-.B lfs find [--atime|-A N] [--mtime|-M N] [--ctime|-C N] [--maxdepth|-D N]
- \fB[--print0|-P] [--print|-p] [--obd|-O <uuid>] <dir/file>\fR
+.B lfs check <mds|osts|servers>
.br
-.B lfs find [--quiet|-q] [--verbose|-v] [--recursive|-r] <dir|file>
+.B lfs df [-i] [-h] [--pool|-p <fsname>[.<pool>] [path]
+.br
+.B lfs find [[!] --atime|-A [-+]N] [[!] --mtime|-M [-+]N]
+ \fB[[!] --ctime|-C [-+]N] [--maxdepth|-D N] [--name|-n pattern]
+ \fB[--print|-p] \fB[--print0|-P] [[!] --obd|-O <uuid[s]>]
+ \fB[[!] --size|-S [-+]N[kMGTPE]] [--type |-t {bcdflpsD}]
+ \fB[[!] --gid|-g|--group|-G <gname>|<gid>]
+ \fB[[!] --uid|-u|--user|-U <uname>|<uid>]
+ \fB<dirname|filename>\fR
+.br
+.B lfs osts
.br
.B lfs getstripe [--obd|-O <uuid>] [--quiet|-q] [--verbose|-v]
- \fB[--recursive|-r] <dir/file>\fR
+ \fB[--count | -c ] [--size | -s ] [--index | -i ]
+ \fB[--offset | -o ] [--pool | -p ] [--directory | -d ]
+ \fB[--recursive|-r] <dirname|filename>\fR
.br
-.B lfs setstripe <filename> <stripe-size> <start-ost> <stripe-cnt>
+.B lfs setstripe [--size|-s stripe-size] [--count|-c stripe-cnt]
+ \fB[--offset|-o start-ost] [--pool|-p <pool>]
+ \fB<dir|filename>\fR
.br
-.B lfs quotachown [-i] <filesystem>
+.B lfs setstripe -d <dir>
+.br
+.B lfs poollist <filesystem>[.<pool>] | <pathname>
+.br
+.B lfs quota [-q] [-v] [-o obd_uuid] [<-u|-g> <uname>|<uid>|<gname><gid>] <filesystem>
+.br
+.B lfs quota -t <-u|-g> <filesystem>
.br
.B lfs quotacheck [-ug] <filesystem>
.br
+.B lfs quotachown [-i] <filesystem>
+.br
.B lfs quotaon [-ugf] <filesystem>
.br
.B lfs quotaoff [-ug] <filesystem>
.br
-.B lfs setquota [-u|-g] <name> <block-softlimit> <block-hardlimit>
- \fB<inode-softlimit> <inode-hardlimit> <filesystem>\fR
+.B lfs quotainv [-ug] [-f] <filesystem>
.br
-.B lfs quota [-o obd_uuid] [-u|-g] <name> <filesystem>
+.B lfs setquota <-u|--user|-g|--group> <uname|uid|gname|gid>
+ \fB[--block-softlimit <block-softlimit>]
+ \fB[--block-hardlimit <block-hardlimit>]
+ \fB[--inode-softlimit <inode-softlimit>]
+ \fB[--inode-hardlimit <inode-hardlimit>]
+ \fB<filesystem>\fR
.br
-.B lfs setstripe <filename> <stripe-size> <start-ost> <stripe-cnt>
+.B lfs setquota <-u|--user|-g|--group> <uname|uid|gname|gid>
+ \fB[-b <block-softlimit>] [-B <block-hardlimit>]
+ \fB[-i <inode-softlimit>] [-I <inode-hardlimit>]
+ \fB<filesystem>\fR
.br
-.B lfs check <mds| osts| servers>
+.B lfs setquota -t <-u|-g>
+ \fB[--block-grace <block-grace>]
+ \fB[--inode-grace <inode-grace>]
+ \fB<filesystem>\fR
.br
-.B lfs df [-i] [-h] [path]
+.B lfs setquota -t <-u|-g>
+ \fB[-b <block-grace>] [-i <inode-grace>]
+ \fB<filesystem>\fR
+.br
+.B lfs help
.SH DESCRIPTION
.B lfs
-can be used to create a new file with a specific striping pattern, determine the default striping pattern, gather the extended attributes (object numbers and
-location) for a specific file. It can be invoked interactively without any
-arguments or in a non-interactive mode with one of the arguements supported.
+can be used to create a new file with a specific striping pattern, determine the default striping pattern, gather the extended attributes (object numbers and location) for a specific file, find files with specific attributes, list OST information, or set quota limits. It can be invoked interactively without any arguments or in a non-interactive mode with one of the arguements supported.
.SH OPTIONS
The various options supported by lctl are listed and explained below:
.TP
-.B setstripe
-To create a new file with a specific striping pattern
+.B check
+Display the status of MDS or OSTs (as specified in the command) or all the servers (MDS and OSTs)
+.TP
+.B df [-i] [-h] [--pool|-p <fsname>[.<pool>] [path]
+Report filesystem disk space usage or inodes usage (with \fB-i\fR) of each
+MDT/OST, or a subset of OSTs if a pool is specified with \fB-p\fR. By default
+print the usage of all mounted Lustre filesystems, otherwise if \fBpath\fR is
+specified print only the usage of that filesystem. If \fB-h\fR is given, the
+output is printed in \fIh\fRuman readable format, using SI base-2 suffixes
+for \fBM\fRega-, \fBG\fRiga-, \fBT\fRera-, \fBP\fReta-, or \fBE\fRxabytes.
.TP
.B find
-To search the directory tree rooted at the given dir/file name for the files that match the given parameters: \fB--atime\fR (file was last accessed N*24 hours ago), \fB--ctime\fR (file's status was last changed N*24 hours ago), \fB--mtime\fR (file's data was last modified N*24 hours ago), \fB--obd\fR (file has an object on a specific OST). The option \fB--maxdepth\fR allows find to decend at most N levels of directory tree. The options \fB--print\fR and \fB--print0\fR print full file name, followed by a newline and null character correspondingly. Using one of these options works in the new (filename only) mode.
+To search the directory tree rooted at the given dir/file name for the files that match the given parameters: \fB--atime\fR (file was last accessed N*24 hours ago), \fB--ctime\fR (file's status was last changed N*24 hours ago), \fB--mtime\fR (file's data was last modified N*24 hours ago), \fB--obd\fR (file has an object on a specific OST or OSTs), \fB--size\fR (file has size in bytes, or \fBk\fRilo-, \fBM\fRega-, \fBG\fRiga-, \fBT\fRera-, \fBP\fReta-, or \fBE\fRxabytes if a suffix is given), \fB--type\fR (file has the type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory, \fBp\fRipe, \fBf\fRile, sym\fBl\fRink, \fBs\fRocket, or \fBD\fRoor (Solaris)), \fB--uid\fR (file has specific numeric user ID), \fB--user\fR (file owned by specific user, numeric user ID allowed), \fB--gid\fR (file has specific group ID), \fB--group\fR (file belongs to specific group, numeric group ID allowed). The option \fB--maxdepth\fR limits find to decend at most N levels of directory tree. The options \fB--print\fR and \fB--print0\fR print full file name, followed by a newline or NUL character correspondingly. Using \fB!\fR before an option negates its meaning (\fIfiles NOT matching the parameter\fR). Using \fB+\fR before a numeric value means \fIfiles with the parameter OR MORE\fR, while \fB-\fR before a numeric value means \fIfiles with the parameter OR LESS\fR.
+.TP
+.B osts
+List all the OSTs for the filesystem
.TP
-.B find
-To list the striping info for a given filename or files in a directory or recursively for all files in a directory tree use one of the following options: \fB[--quiet|-q] [--verbose|-v] [--recursive|-r]\fR. If one of these options is given find works in old (obsolete, please use getstripe instead) filename and striping mode.
+.B getstripe [--obd|-O <uuid>] [--quiet|-q] [--verbose|-v]
+ \fB[--count | -c ] [--size | -s ] [--index | -i ]
+ \fB[--offset | -o ] [--pool | -p ] [--directory | -d ]
+ \fB[--recursive|-r] <dirname|filename>\fR
+.br
+To list the striping information for a given filename or directory. By default the stripe count, size, and offset will be returned. If you only want specific striping information then the options of \fB--count\fR,\fB--size\fR,\fB--index\fR or \fB--offset\fR plus various combinations of these options can be used to retrieve only what you want. What pools a file belong to can also be obtained with \fB--pool\fR. In the case where you only want details about the files object id information then the \fB--quiet\fR option is used. Additional information available about striping can be displayed with \fB--verbose\fR. The default behavior of lfs getstripe used to retrieve data about a directory is to list all the contents of that directory. If you wish to inquire only about that directory then \fB--directory\fR,can be used to list directory entries instead of its contents in the same manner as ls -d. This can be expanded with \fB--recursive\fR which will recurse into all subdirectories. You can filter the search to return only files that has a object on a specific OST with \fB--obd\fR.
.TP
-.B getstripe
-To list the striping info for given filename or files in a directory or recursively for all files in a directory tree. It can also be used to list the files that have objects on a specific OST.
+.B setstripe [--size stripe-size] [--count stripe-cnt]
+ \fB[--offset start-ost] [--pool <pool>]\fR
+.br
+To create a new file, or set the directory default, with the specified striping parameters. The
+.I stripe-count
+is the number of OSTs to stripe a file over. A
+.I stripe-count
+of 0 means to use the filesystem-wide default stripe count (default 1), and a
+.I stripe-count
+of -1 means to stripe over all available OSTs. The
+.I stripe-size
+is the number of bytes to store on each OST before moving to the next OST. A
+.I stripe-size
+of 0 means to use the filesystem-wide default stripe size (default 1MB). The
+.I start-ost
+is the OST index (base 10, starting at 0) on which to start striping for this file. A
+.I start-ost
+of -1 allows the MDS to choose the starting index and it is strongly recommended, as this allows space and load balancing to be done by the MDS as needed. The
+.I pool
+is the name of a predefined pool of OSTs (see
+.I lctl
+) that will be used for striping. The
+.I stripe-count, stripe-size, start-ost
+will be used as well; the
+.I start-ost
+must be part of the pool or an error will be returned.
+.TP
+.B setstripe -d
+Delete the default striping on the specified directory.
+.TP
+.B poollist <filesystem>[.<pool>] | <pathname>
+List the pools in \fBfilesystem\fR or \fBpathname\fR, or the OSTs in \fBfilesystem.pool\fR
.TP
.B quotachown
To change files' owner and group on OSTs of the specified filesystem
.TP
-.B quotacheck
-To scan the specified filesystem for disk usage, and create or update quota files
+.B quotacheck [-ugf] <filesystem>
+To scan the specified filesystem for disk usage, and create or update quota files. Options specify quota for users (-u) groups (-g) and force (-f)
.TP
-.B quotaon
-To turn filesystem quotas on
+.B quotaon [-ugf] <filesystem>
+To turn filesystem quotas on. Options specify quota for users (-u) groups (-g) and force (-f)
.TP
-.B quotaoff
-To turn filesystem quotas off
+.B quotaoff [-ugf] <filesystem>
+To turn filesystem quotas off. Options specify quota for users (-u) groups (-g) and force (-f)
.TP
-.B setquota
-To set filesystem quotas
+.B quotainv [-ug] [-f] <filesystem>
+Clear quota files (administrative quota files if used without -f, operational quota files otherwise), all of their quota entries, for (-u) users or (-g) groups; after quotainv one must use quotacheck before using quotas. DO NOT USE THIS COMMAND UNLESS YOU REALLY KNOW WHAT IT DOES. IT IS MAINLY FOR INTERNAL PURPOSES.
.TP
-.B quota
-To display disk usage and limits
+.B setquota <-u|-g> <uname>|<uid>|<gname>|<gid> [--block-softlimit <block-softlimit>] [--block-hardlimit <block-hardlimit>] [--inode-softlimit <inode-softlimit>] [--inode-hardlimit <inode-hardlimit>] <filesystem>
+To set filesystem quotas for users or groups. Limits can be specified with -b, -k, -m, -g, -t, -p suffixes which specify units of 1, 2^10, 2^20, 2^30, 2^40 and 2^50 accordingly. Block limits unit is kilobyte (1024) by default and block limits are always kilobyte-grained (even if specified in bytes), see EXAMPLES
.TP
-.B check
-Display the status of MDS or OSTs (as specified in the command) or all the servers (MDS and OSTs)
+.B setquota -t <-u|-g> [--block-grace <block-grace>] [--inode-grace <inode-grace>] <filesystem>
+To set filesystem quota grace times for users or groups. Grace time is specified in "XXwXXdXXhXXmXXs" format or as an integer seconds value, see EXAMPLES
.TP
-.B osts
-List all the OSTs for the filesystem
+.B quota [-q] [-v] [-o obd_uuid] [ -u|-g <uname|uid|gname|gid> ] <filesystem>
+To display disk usage and limits, either for the full filesystem, or for objects on a specific obd. A user or group name or an ID can be specified. If both user and group are omitted quotas for current uid/gid are shown. -v provides more verbose (with per-obd statistics) output. -q disables printing of additional descriptions (including column titles).
.TP
-.B df
-Report filesystem disk space usage or inodes usage of each MDT/OST.
+.B quota -t <-u|-g> <filesystem>
+To display block and inode grace times for user (-u) or group (-g) quotas
.TP
.B help
Provides brief help on the various arguments
Quit the interactive lfs session
.SH EXAMPLES
.TP
-.B $ lfs setstripe /mnt/lustre/file1 131072 -1 2
-This creats a file striped on two OSTs with 128kB on each stripe.
+.B $ lfs setstripe -s 128k -c 2 /mnt/lustre/file1
+This creates a file striped on two OSTs with 128kB on each stripe.
+.TP
+.B $ lfs setstripe -d /mnt/lustre/dir
+This deletes a default stripe pattern on dir. New files will use the default striping pattern created therein.
.TP
-.B $ lfs find /mnt/lustre/file1
-Lists the object allocation of a given file
+.B $ lfs getstripe -v /mnt/lustre/file1
+Lists the detailed object allocation of a given file
.TP
-.B $ lfs find /mnt/lustre/
-Lists the object allocationss of all files in a given directory
+.B $ lfs find /mnt/lustre
+Efficiently lists all files in a given directory and its subdirectories
.TP
-.B $ lfs find -r /mnt/lustre/
-Recursively list the objects of all files in a given directory tree
+.B $ lfs find /mnt/lustre -mtime +30 -type f -print
+Recursively list all regular files in given directory more than 30 days old
.TP
-.B $ lfs find -r --obd OST2-UUID /mnt/lustre/
+.B $ lfs find --obd OST2-UUID /mnt/lustre/
Recursively list all files in a given directory that have objects on OST2-UUID.
+.tP
+.B $ lfs check servers
+Check the status of all servers (MDT, OST)
+.TP
+.B $ lfs osts
+List all the OSTs
+.TP
+.B $ lfs df -h
+Lists space usage per OST and MDT in human readable format.
+.TP
+.B $ lfs df -i
+Lists inode usage per OST and MDT
+.TP
+.B $ lfs df --pool <filesystem>[.<pool>] | <pathname>
+List space or inode usage for a specific OST pool
.TP
.B $ lfs quotachown -i /mnt/lustre
Change file owner and group
.TP
.B $ lfs quotacheck -ug /mnt/lustre
-Quotacheck for user and group
+Quotacheck for user and group - will turn on quotas after making the check.
.TP
.B $ lfs quotaon -ug /mnt/lustre
Turn quotas of user and group on
.B $ lfs quotaoff -ug /mnt/lustre
Turn quotas of user and group off
.TP
-.B $ lfs setquota -u bob 0 1000000 0 10000 /mnt/lustre
-Set quotas of user `bob': 1GB block quota and 10,000 file quota
+.B $ lfs setquota -u bob --block-softlimit 2000000 --block-hardlimit 1000000 /mnt/lustre
+Set quotas of user `bob': 1GB block quota hardlimit and 2 GB block quota softlimit
+.TP
+.B $ lfs setquota -t -u --block-grace 1000 --inode-grace 1w4d /mnt/lustre
+Set grace times for user quotas: 1000 seconds for block quotas, 1 week and 4 days for inode quotas
.TP
.B $ lfs quota -u bob /mnt/lustre
List quotas of user `bob'
.TP
-.B $ lfs check servers
-Check the status of all servers (MDT, OST)
-.TP
-.B $ lfs osts
-List all the OSTs
-.TP
-.B $ lfs df -i
-Lists inode consumpton per OST and MDT
+.B $ lfs quota -t -u /mnt/lustre
+Show grace times for user quotas on /mnt/lustre
.SH BUGS
-None are known.
+The \fBlfs find\fR command isn't as comprehensive as \fBfind\fR(1).
+Report bugs using http://bugzilla.lustre.org.
+.SH AUTHOR
+The lfs command is part of the Lustre filesystem. Contact http://www.lustre.org/
+.SH SEE ALSO
+.BR lctl (8),
+.BR lustre (7)