X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=lustre%2Fdoc%2Flfs.1;h=6537be199e4c75ca83c0ec42d440aae9cd8d76a6;hb=a89a63d22879014d1ac09a86d43b4e27940ac555;hp=d8455bb8865012cb909c7f8adfc63f99aabcb3bc;hpb=f6857d08880a4351780e1b95c92927aa871ae134;p=fs%2Flustre-release.git diff --git a/lustre/doc/lfs.1 b/lustre/doc/lfs.1 index d8455bb..6537be1 100644 --- a/lustre/doc/lfs.1 +++ b/lustre/doc/lfs.1 @@ -1,25 +1,56 @@ -.TH lfs 1 "2003 Oct 29" Lustre "configuration utilities" +.TH lfs 1 "2009 Jan 29" 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, do certain quota operations, and manage distributed namespace options for directories .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 ] \fR +.B lfs changelog [--follow] [startrec [endrec]] .br -.B lfs find [--quiet|-q] [--verbose|-v] [--recursive|-r] +.B lfs changelog_clear +.br +.B lfs check +.br +.B lfs df [-i] [-h] [--lazy] [--pool|-p [.] [path] +.br +.B lfs fid2path [--link ] ... +.br +.B lfs find + \fB[[!] --atime|-A [-+]N] [[!] --mtime|-M [-+]N] [[!] --ctime|-C [+-]N] + \fB[--maxdepth|-D N] [[!] --mdt|-m ] [--name|-n pattern] + \fB[[!] --ost|-O ] [--print|-p] [--print0|-P] + \fB[[!] --size|-s [-+]N[kMGTPE]] + \fB[[!] --stripe-count|-c [+-]] + \fB[[!] --stripe-index|-i ] + \fB[[!] --stripe-size|-S [+-]N[kMG]] + \fB[[!] --layout|-L raid0,released] + \fB[--type |-t {bcdflpsD}] [[!] --gid|-g|--group|-G |] + \fB[[!] --uid|-u|--user|-U |] [[!] --pool ]\fR +.br +.B lfs getname [-h]|[path ...] .br .B lfs getstripe [--obd|-O ] [--quiet|-q] [--verbose|-v] - \fB[--recursive|-r] \fR + \fB[--stripe-count|-c ] [--stripe-index|-i] [--mdt-index|-M] + \fB[--stripe-size|-S] [--directory|-d] + \fB[--layout|-L] + \fB[--pool|-p] [--recursive|-r] [--raw|-R] ...\fR +.br +.B lfs setstripe [--stripe-size|-S stripe_size] [--stripe-count|-c stripe_count] + \fB[--stripe-index|-i start_ost_index ] [--pool|-p ] + \fB\fR +.br +.B lfs setstripe -d .br -.B lfs setstripe +.B lfs osts +.RB [ path ] .br -.B lfs setstripe [--size|-s stripe-size] [--index|-i start-ost] [--count|-c stripe-cnt] +.B path2fid ... .br -.B lfs setstripe -d +.B lfs pool_list [.] | .br -.B lfs quotachown [-i] +.B lfs quota [-q] [-v] [-o obd_uuid|-I ost_idx|-i mdt_idx] [-u | -u |-g | -g ] +.br +.B lfs quota -t <-u|-g> .br .B lfs quotacheck [-ug] .br @@ -27,70 +58,233 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the .br .B lfs quotaoff [-ug] .br -.B lfs setquota [-u|-g] - \fB \fR +.B lfs setquota <-u|--user|-g|--group> + \fB[--block-softlimit ] + \fB[--block-hardlimit ] + \fB[--inode-softlimit ] + \fB[--inode-hardlimit ] + \fB\fR +.br +.B lfs setquota <-u|--user|-g|--group> + \fB[-b ] [-B ] + \fB[-i ] [-I ] + \fB\fR +.br +.B lfs setquota -t <-u|-g> + \fB[--block-grace ] + \fB[--inode-grace ] + \fB\fR +.br +.B lfs setquota -t <-u|-g> + \fB[-b ] [-i ] + \fB\fR .br -.B lfs setquota -t [-u|-g] .br -.B lfs quota [-o obd_uuid] [-u|-g] +.B lfs swap_layouts .br -.B lfs quota -t [-u|-g] +.B lfs data_version [-n] \fB\fR .br -.B lfs check +.B lfs mkdir <--index|-i mdt_index> .br -.B lfs df [-i] [-h] [path] +.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. 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 -.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. -.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 changelog +Show the metadata changes on an MDT. Start and end points are optional. The --follow option will block on new changes; this option is only valid when run direclty on the MDT node. .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 changelog_clear +Indicate that changelog records previous to are no longer of +interest to a particular consumer , potentially allowing the MDT to +free up disk space. An of 0 indicates the current last record. +Changelog consumers must be registered on the MDT node using \fBlctl\fR. .TP -.B quotachown -To change files' owner and group on OSTs of the specified filesystem +.B check +Display the status of MDS or OSTs (as specified in the command) or all the servers (MDS and OSTs) .TP -.B quotacheck [-ugf] -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) +.B df [-i] [-h] [--lazy] [--pool|-p [.] [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. +The \fB--lazy\fR/\fB-l\fR option skips any OST that is currently disconnected +from the client. This avoids blocking the \fBdf\fR output if an OST is down, +and only returns the space on the OSTs that can currently be accessed. .TP -.B quotaon [-ugf] -To turn filesystem quotas on. Options specify quota for users (-u) groups (-g) and force (-f) +.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 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), \fB--layout\fR (file has a raid0 layout or is released). 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 quotaoff [-ugf] -To turn filesystem quotas off. Options specify quota for users (-u) groups (-g) and force (-f) +.B getname [-h]|[path ...] +Report all the Lustre mount points and the corresponding Lustre filesystem +instance. If one or more \fBpath\fR entries are provided, then only the +Lustre instance for these mount points is returned. If the path given is not on +a Lustre instance 'No such device' is reported. .TP -.B setquota [-u|-g] -To set filesystem quotas for users or groups. Limits are specific as blocks and inodes, see EXAMPLES +.B osts +.RB [ path ] +List all the OSTs for all mounted filesystems. If a \fBpath\fR is provided +that is located on a lustre mounted file system then only the OSTs belonging +to that filesystem are displayed. +.TP +.B getstripe [--obd|-O ] [--quiet|-q] [--verbose|-v] + \fB[--count | -c ] [--index | -i | --offset | -o ] + \fB[--pool | -p ] [--size | -s ] [--directory | -d ] + \fB[--layout | -L] + \fB[--recursive | -r ] [--raw | -R ] \fR +.br +List the striping information for a given filename or directory tree. +By default the stripe count, size, and offset will be returned. If you +only want specific striping information then the options of +.BR --count , +.BR --size , +.BR --index , +.BR --offset , +.BR --layout , +or +.B --pool +can be used to return only the specific fields. +.br +If the +.B --raw +option is specified, the stripe information is printed without substituting the +filesystem's default values for unspecified fields. If the striping EA is not +set, 0, 0, and -1 will be printed for the stripe count, size, and offset +respectively. +In the case where you only want details about the files' object id +information then the +.B --quiet +option is used. Additional information available about striping can be +displayed with +.BR --verbose . +The default behavior when a directory is specified is to list the striping +information for all files within the specified directory (like +.RB ' "ls -l" ') . +This can be expanded with +.B --recursive +which will recurse into all subdirectories. +If you wish to get striping information for only the specified directory, then +.B --directory +can be used to limit the information, like +.RB ' "ls -d" '). +You can limit the returned files to those with objects on a specific OST with +.BR --obd . +.TP +.B setstripe [--stripe-count|-c stripe_count] [--stripe-size|-S stripe_size] + \fB[--stripe-index|-i start_ost_index] [--pool ] + \fB\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_index +is the OST index (starting at 0) on which to start striping for this file. A +.I start_ost_index +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 poolname +is the name of a predefined pool of OSTs (see +.B lctl +) that will be used for striping. The +.IR stripe_count , +.IR stripe_size , +and +.I start_ost_index +will be used as well; the +.I start_ost_index +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 fid2path [--link ] ... +Print out the pathname(s) for the specified \fIfid\fR(s) from the filesystem +mounted at \fBrootpath\fR or named \fBfsname\fR. If a file has multiple +hard links, then all of the pathnames for that file are printed, unless +\fB--link\fR limits the printing to only the specified link number (starting +at 0, in no particular order). If multiple fids are specified, but only a +single pathname is needed for each file, use \fB--link 0\fR. +.TP +.B path2fid ... +Print out the FIDs for the specified \fBpath(s)\fR. If multiple pathnames +are given, then they will be printed one per line with the path as prefix. +.TP +.B pool_list +.RI { filesystem }[ .poolname "] | {" pathname } +List the pools in +.I filesystem +or +.IR pathname , +or the OSTs in +.IR filesystem.pool . +.TP +.B quota [-q] [-v] [-o obd_uuid|-i mdt_idx|-I ost_idx] [-u|-g |||] +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 quota -t <-u|-g> +To display block and inode grace times for user (-u) or group (-g) quotas .TP -.B setquota -t [-u|-g] -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 +.B quotacheck [-ugf] (deprecated as of 2.4.0) +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). Not useful anymore with servers >= 2.4.0 since space accounting is always turned on. .TP -.B quota [-o obd_uuid] [-u|-g] -To display disk usage and limits, either for the full filesystem, or for objects on a specific obd. A user or group name must be specified. +.B quotaon [-ugf] (deprecated as of 2.4.0) +To turn filesystem quotas on. Options specify quota for users (-u) groups (-g) and force (-f). Not used anymore in lustre 2.4.0 where quota enforcement must be enabled via conf_param (e.g. lctl conf_param ${FSNAME}.quota.=) .TP -.B quota -t [-u|-g] -To display block and inode grace times for user (-u) or group (-g) quotas +.B quotaoff [-ugf] (deprecated as of 2.4.0) +To turn filesystem quotas off. Options specify quota for users (-u) groups (-g) and force (-f). Not used anymore in lustre 2.4.0 where quota enforcement can be turned off (for inode or block) by running the following command on the MGS: lctl conf_param ${FSNAME}.quota.="" .TP -.B check -Display the status of MDS or OSTs (as specified in the command) or all the servers (MDS and OSTs) +.B setquota <-u|-g> ||| [--block-softlimit ] [--block-hardlimit ] [--inode-softlimit ] [--inode-hardlimit ] +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 osts -List all the OSTs for the filesystem +.B setquota -t [-u|-g] [--block-grace ] [--inode-grace ] +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 df -Report filesystem disk space usage or inodes usage of each MDT/OST. +.B swap_layouts +Swap the data (layout and OST objects) of two regular files. The +two files have to be in the same filesystem, owned by the same user, +reside on the same MDT and writable by the user. + +Swapping the layout of two directories is not permitted. +.TP +.B data_version [-n] +Display current version of file data. If -n is specified, data version is read +without taking lock. As a consequence, data version could be outdated if there +is dirty caches on filesystem clients, but this will not force data flushes and +has less impact on filesystem. + +Even without -n, race conditions are possible and data version should be +checked before and after an operation to be confident the data did not change +during it. +.TP +.B mkdir <--index|-i mdt_index> +Allocate a new directory on a specified MDT. + +The "lfs mkdir" command is only executable by root unless +"mdt.*.enable_remote_dir_gid" is set via "lctl set_param" to be either a +non-zero GID to limit it to a single group (e.g. "operator" or "admin"), +or "-1" to allow any group to create remote directories. + +The root of the file system is on MDT0000, and directories and files inherit the +MDT of their parent directory unless a different MDT is specified with this +command. + +By default, only directories on MDT0000 can contain directories that are not on +the same MDT. However, if "mdt.*.enable_remote_dir" is set non-zero on an MDT +then it will allow creating remote directories that have parents other than +MDT0000. This is restricted to avoid creating directory trees that have +intermediate path components on a series different MDTs and become unavailable +if any of the intermediate MDTs are offline. .TP .B help Provides brief help on the various arguments @@ -99,23 +293,44 @@ 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 [.] | +List space or inode usage for a specific OST pool +.TP +.B $ lfs quota -u bob /mnt/lustre +List quotas of user `bob' +.TP +.B $ lfs quota -t -u /mnt/lustre +Show grace times for user quotas on /mnt/lustre .TP .B $ lfs quotachown -i /mnt/lustre Change file owner and group @@ -129,25 +344,19 @@ 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 1000 1w4d /mnt/lustre +.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 quota -t -u /mnt/lustre -Show grace times for user quotas on /mnt/lustre -.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 mkdir -i 1 new_directory +Create directory 'new_directory' on the mdt with index 1. .SH BUGS -None are known. +The \fBlfs find\fR command isn't as comprehensive as \fBfind\fR(1). +.SH AUTHOR +The lfs command is part of the Lustre filesystem. +.SH SEE ALSO +.BR lfs-hsm (1), +.BR lctl (8), +.BR lustre (7)