X-Git-Url: https://git.whamcloud.com/?p=fs%2Flustre-release.git;a=blobdiff_plain;f=lustre%2Fdoc%2Flfs.1;h=ffad3287f7fececa3e402039634db8e3e4e09feb;hp=bb9a30cdc248d59f3323e119870f14ad97a2577b;hb=0652c828c93f266b9999883b1b2967bfaac11c89;hpb=72de3797771b1133e0a521c3612c814ab0fb6cdf diff --git a/lustre/doc/lfs.1 b/lustre/doc/lfs.1 index bb9a30c..ffad328 100644 --- a/lustre/doc/lfs.1 +++ b/lustre/doc/lfs.1 @@ -1,131 +1,288 @@ -.TH lfs 1 "2008 Mar 15" Lustre "user utilities" +.TH lfs 1 "2018-01-24" Lustre "user utilities" .SH NAME -lfs \- Lustre utility to create a file with specific striping pattern, find the striping pattern of exiting files +lfs \- client utility for Lustre-specific file layout and other attributes .SH SYNOPSIS .br -.B lfs +.B lfs changelog [--follow] [startrec [endrec]] +.br +.B lfs changelog_clear +.br +.B lfs check +.br +.B lfs data_version [-nrw] \fB\fR +.br +.B lfs df [-ihlv] [--pool|-p [.]] [path] +.br +.B lfs fid2path [--link ] ... +.br +.B lfs find \fR<\fIdirectory\fR|\fIfilename \fR...> + [[\fB!\fR] \fB--atime\fR|\fB-A\fR [\fB-+\fR]\fIn\fR] +[[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn\fR] + [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR <[\fB^\fR]\fIflag\fB,\fR...>] + [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--mirror-count|\fB-N\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--mirror-state\fR <[^]\fIstate\fR>] + [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>] + [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR] +[\fB--maxdepth\fR|\fB-D\fI n\fR] + [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR <\fIuuid\fR|\fIindex\fR,...>] + [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR] +[[\fB!\fR] \fB--mdt-hash\fR|\fB-H \fI\fR] + [[\fB!\fR] \fB--name\fR|\fB-n \fI\fR] +[[\fB!\fR] \fB--ost\fR|\fB-O\fR <\fIuuid\fR|\fIindex\fR,...>] + [[\fB!\fR] \fB--pool\fR <\fIpool\fR>] +[\fB--print\fR|\fB-P\fR] [\fB--print0\fR|\fB-0\fR] + [[\fB!\fR] \fB--projid\fR |<\fIprojid\fR>] +[[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...] + [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]] +[[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}] + [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U +<\fIuname\fR>|<\fIuid>\fR] .br -.B lfs check +.B lfs getname [-h]|[path ...] .br -.B lfs df [-i] [-h] [path] +.B lfs getstripe +[\fB--component-count\fR|\fB--comp-count\fR] + [\fB--component-end\fR[=[\fB+-\fR]\fIN\fR[kMGTPE]]|\fB-E\fR[[+-]\fIN\fR[kMGTPE]]] + [\fB--component-flags\fR[=[\fB^\fR]\fIflag\fB,\fR...]] + [\fB--component-id\fR[=\fIcomp_id\fR]|\fB-I\fR[<\fIcomp_id\fR>]] + [\fB--component-start\fR[=[\fB+-\fR]\fIN\fR[kMGTPE]]] + [\fB--directory\fR|\fB-d\fR] +[\fB--fid\fR|\fB-F\fR] +[\fB--generation\fR|\fB-g\fR] + [\fB--layout\fR|\fB-L\fR] +[\fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR] +[\fB--ost\fR|\fB-O\fR <\fIuuid\fR>] + [\fB--pool\fR|\fB-p\fR] +[\fB--quiet\fR|\fB-q\fR] +[\fB--recursive\fR|\fB-r\fR] + [\fB--raw\fR|\fB-R\fR] +[\fB--stripe-count\fR|\fB-c\fR] +[\fB--stripe-index\fR|\fB-i\fR] + [\fB--stripe-size\fR|\fB-S\fR] +[\fB--verbose\fR|\fB-v\fR] +[\fB--yaml\fR|\fB-y\fR] + <\fIdirname\fR|\fIfilename\fR> ... .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 ] - \fB[[!] --size|-S [-+]N[kMGTPE]] [--type |-t {bcdflpsD}] - \fB\fR +.B lfs migrate { --mdt-index | -m } \fI\fR +.IR directory .br -.B lfs getstripe [--obd|-O ] [--quiet|-q] [--verbose|-v] - \fB[--recursive|-r] \fR +.B lfs migrate [\fB-c | --stripe-count \fR] + [\fB-i | --stripe-index \fR] + [\fB-S | --stripe-size \fR] + [\fB-p | --pool \fR] + [\fB-o | --ost-list \fR] + [\fB-b | --block\fR] + [\fB-n | --non-block\fR] +.IR file|directory .br -.B lfs setstripe [--size|-s stripe-size] [--count|-c stripe-cnt] - \fB[--index|-i start-ost] \fR +.B lfs migrate <\fB-E | --component-end comp_end1\fR> [\fBSTRIPE_OPTIONS\fR] + <\fB-E | --component-end comp_end2\fR> [\fBSTRIPE_OPTIONS\fR] + \fB...\fR +.IR filename .br -.B lfs setstripe -d +.B lfs mkdir [\fB-c | --count \fR] + [\fB-i | --index \fR] + [\fB-h | --hash-type \fR] + [\fB-m | --mode \fR] + [\fB-D | --default\fR] +.IR directory .br -.B lfs quotachown [-i] +.B lfs osts +.RB [ path ] +.br +.B lfs mdts +.RB [ path ] +.br +.B lfs path2fid [--parents] ... +.br +.B lfs pool_list [.] | +.br +.B lfs quota [-q] [-v] [-o obd_uuid|-I ost_idx|-i mdt_idx] [-u | -u |-g | -g ] [-p ] +.br +.B lfs quota -t <-u|-g|-p> .br .B lfs quotacheck [-ug] .br +.B lfs quota <-U|-G|-P> +.br .B lfs quotaon [-ugf] .br .B lfs quotaoff [-ug] .br -.B lfs setquota [-u|-g] - \fB - \fB\fR +.B lfs setstripe [--stripe-size|-S ] [--stripe-count|-c ] + \fB[--stripe-index|-i ] [--pool|-p ] + \fB[--ost-list|-o ] \fR .br -.B lfs setquota -t [-u|-g] +.B lfs setstripe -d .br -.B lfs quota [-o obd_uuid] [-u|-g] +.B lfs setstripe --component-end|-E [STRIPE_OPTIONS] + [\fB--component-end|-E [STRIPE_OPTIONS]] ... \fR .br -.B lfs quota -t [-u|-g] +.B lfs setstripe --component-add --component-end|-E [STRIPE_OPTIONS] + \fB<--component-end|-E > [STRIPE_OPTIONS]] ... \fR +.br +.B lfs setstripe --component-del {--component-id|-I id | + \fB--component-flags } +.br +.B lfs setstripe --yaml= +.br +.B lfs --version +.br +.B lfs --list-commands .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. It can be invoked interactively without any +arguments or in a non-interactive mode with one of the arguments supported. .SH OPTIONS -The various options supported by lctl are listed and explained below: -.TP -.B check -Display the status of MDS or OSTs (as specified in the command) or all the servers (MDS and OSTs) -.TP -.B df -Report filesystem disk space usage or inodes usage of each MDT/OST. -.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), \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)). 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 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 getstripe -To list the striping info for a given filename or files in a directory, optionally recursively, for all files in a directory tree: \fB--quiet\fR (don't print object IDs), \fB--verbose\fR (print striping parameters), \fB--recursive\fR (recurse into subdirectories). -.TP -.B osts -List all the OSTs for the filesystem -.TP -.B setstripe -To create a new file with a specific striping pattern -.TP -.B quotachown -To change files' owner and group on OSTs of the specified filesystem -.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) -.TP -.B quotaon [-ugf] -To turn filesystem quotas on. Options specify quota for users (-u) groups (-g) and force (-f) -.TP -.B quotaoff [-ugf] -To turn filesystem quotas off. Options specify quota for users (-u) groups (-g) and force (-f) -.TP -.B setquota [-u|-g] -To set filesystem quotas for users or groups. Limits are specific as blocks and inodes, see EXAMPLES -.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 -.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. -.TP -.B quota -t [-u|-g] -To display block and inode grace times for user (-u) or group (-g) quotas -.TP -.B help +The various options supported by lfs are listed and explained below: +.TP +.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 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 check +Display the status of the MGTs, MDTs or OSTs (as specified in the command) or +all the servers (MGTs, MDTs and OSTs). +.TP +.B data_version [-nrw] +Display the current version of file data. If -n is specified, the data version +is read without taking a lock. As a consequence, the data version could be +outdated if there are dirty caches on filesystem clients, but this option will +not force data flushes and has less of an impact on the filesystem. If -r is +specified, the data version is read after dirty pages on clients are flushed. If +-w is specified, the data version is read after all caching pages on clients are +flushed. + +Even with -r or -w, race conditions are possible and the data version should be +checked before and after an operation to be confident the data did not change +during it. + +The data version is the sum of the last committed transaction numbers of all +data objects of a file. It is used by HSM policy engines for verifying that file +data has not been changed during an archive operation or before a release +operation, and by OST migration, primarily for verifying that file data has not +been changed during a data copy, when done in non-blocking mode. +.TP +.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 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 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 [--parents] ... +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. +The \fB--parents\fR switch makes it output 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. +.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|-p ||||] +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 user group and project are omitted quotas for current uid/gid/projid 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|-p> +To display block and inode grace times for user (-u) or group (-g) or project (-p) quotas +.TP +.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 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 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 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 mkdir +lfs mkdir is documented in the man page: lfs-mkdir(1). NOTE: +.B lfs setdirstripe +is an alias of the command +.B lfs mkdir +.TP +.B mv +lfs mv is deprecated, use lfs +.B migrate +instead. +.TP +.B migrate +See lfs-migrate(1). +.TP +.B setstripe +See lfs-setstripe(1). +.TP +.B --version +Output the build version of the lfs utility. Use "lctl lustre_build_version" to get the version of the Lustre kernel modules +.TP +.B --list-commands +Output a list of the commands supported by the lfs utility +.TP +.B help Provides brief help on the various arguments .TP -.B exit/quit +.B exit/quit Quit the interactive lfs session .SH EXAMPLES .TP -.B $ lfs setstripe -s 128k -c 2 /mnt/lustre/file1 -This creats 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 getstripe -v /mnt/lustre/file1 -Lists the detailed object allocation of a given file -.TP -.B $ lfs find /mnt/lustre -Efficiently lists all files in a given directory and its subdirectories -.TP -.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 --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) +.B $ lfs check all +Check the status of all servers (MGT, 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. +.B $ lfs mdts +List all the MDTs .TP -.B $ lfs df -i -Lists inode usage per OST and MDT +.B $ lfs quota -u bob /mnt/lustre +List quotas of user `bob' +.TP +.B $ lfs quota -U /mnt/lustre +List user quotas of system default setting +.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 @@ -138,23 +295,25 @@ Turn quotas of user and group on .TP .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 -.TP -.B $ lfs setquota -t -u 1000 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 -.SH BUGS -The \fBlfs find\fR command isn't as comprehensive as \fBfind\fR(1). -Report bugs using http://bugzilla.lustre.org. +.SH NOTES +The usage of \fBlfs find\fR, \fBlfs getstripe\fR, \fBlfs hsm_*\fR, +\fBlfs setstripe\fR, \fBlfs migrate\fR, \fBlfs getdirstripe\fR, +\fBlfs setdirstripe\fR, \fBlfs mkdir\fR, and \fBlfs project\fR are explained +in separate man pages. .SH AUTHOR -The lfs command is part of the Lustre filesystem. Contact info@clusterfs.com. +The lfs command is part of the Lustre filesystem. .SH SEE ALSO .BR lctl (8), +.BR lfs-df (1), +.BR lfs-find (1), +.BR lfs-getstripe (1), +.BR lfs-getdirstripe (1), +.BR lfs-hsm (1), +.BR lfs-mkdir (1), +.BR lfs-migrate (1), +.BR lfs_migrate (1), +.BR lfs-project (1), +.BR lfs-setdirstripe (1), +.BR lfs-setquota (1), +.BR lfs-setstripe (1), .BR lustre (7)