LFS-FIND(1)

📦 version 2.17.58, in ubuntu stonking

✨ LFS-FIND(1) ✨

okay bestie, buckle up 💖 this is lfs-find, from the Lustre User Utilities collection, and she is that girl. She's a client utility that lists files with specific attributes, and honestly? iconic behaviour.

🎀 NAME 🎀

lfs-find — a Lustre client utility to list files with specific attributes. no cap. 🦋

🌸 SYNOPSIS 🌸

lfs find DIRECTORY|FILENAME ...
         [[!]  --atime|-A [-+]N[smhdwy]]
         [[!]  --attrs=[^]ATTR[,...]]
         [[!]  --blocks|-b [+-]N]
         [[!]  --btime|-B|--crtime [+-]N[smhdwy]]
         [[!]  --ctime|-C [+-]N[smhdwy]]
         [[!]  --component-count|--comp-count [+-]N]
         [[!]  --component-end|--comp-end|-E [+-]N[KMGTPE]]
         [[!]  --component-flags|--comp-flags [^]FLAG, ...]
         [[!]  --component-start|--comp-start [+-]N[KMGTPE]]
         [[!]  --extension-size|-z [+-]N[KMG]]
         [[!]  --foreign [TYPE]]
         [[!]  --gid|-g|--group|-G GNAME|GID] [--help|-h]
         [[!]  --layout|-L mdt|raid0|released] [--lazy|-l] [--ls]
         [[!]  --links [+-]N] [--maxdepth|-D N] [--mindepth|-d N]
         [[!]  --mdt|--mdt-index|-m UUID|INDEX|INDEX_RANGE, ...]
         [[!]  --mdt-count|-T [+-]N]
         [[!]  --mdt-hash|-H [^]HASHFLAG,[^]HASHTYPE, ...]
         [[!]  --mirror-count|-N [+-]N] [[!]  --mirror-state [^]STATE]
         [[!]  --mtime|-M [-+] N[smhdwy]] [[!]  --name|-n PATTERN]
         [[!]  --newer[XY] REFERENCE] [[!]  --ost|-O INDEX|INDEX_RANGE,
         ...]
         [[!]  --perm [/-] MODE] [[!]  --pool POOL] [--print|-P]
         [--print0|-0] [--printf FORMAT] [[!]  --projid PROJID|PROJNAME]
         [[!]  --size|-s [-+]N[KMGTPE]] [--skip|-k] PERCENT]
         [[!]  --stripe-count|-c [+-]N]
         [[!]  --stripe-index|-i n, ...]  [[!]  --stripe-size|-S
         [+-]N[KMG]]
         [[!]  --type|-t {bcdflps}] [--threads N] [[!]
         --uid|-u|--user|-U UNAME|UID]
         [[!]  --xattr NAME[=VALUE]]

she's a lot, but she's worth it. 💅

💜 DESCRIPTION 💜

so lfs find is basically find(1)'s cooler cousin 💫 — they're similar, and she's here to list out files and directories that have specific attributes.

and the range, bestie?? she handles the regular POSIX stuff — ownership, timestamps, size — using the same options as find(1). 🫶 but then she ALSO does the Lustre-specific stuff, and that's where it gets juicy: stripe count and size, OST and MDT location, and composite layout attributes. main character energy fr fr. 👑

✨ OPTIONS ✨

  • -A, --atime — the file was last accessed N*24 hours ago, but only if you didn't give any units. if you DO give units, it's N seconds, minutes, hours, days, weeks, or years ago. and lowkey, when there's no unit specified, there's a margin of error of 24h. 🙈 you can stack multiple units too — for example 8h20m is equivalent to 500m. when you stack units, the margin of error is based on the smallest unit you used, so -atime 3d has a margin of error of one day, while -atime 72h has a margin of error of one hour. and if you use both -atime +OLDER and -atime -NEWER, then files with atime within the range OLDER-NEWER get matched. 💖
  • --attrs — the file has ATTRS attribute flags. the supported attributes are (and this is a non exhaustive list, so don't come for her): Compressed (c), Immutable (i), Append_Only (a), No_Dump (d), Encrypted (E), Automount (M)
  • -b, --blocks — blocks allocated by the file is N 512-byte blocks (when no units are given), or chars (bytes), Kibi-, Mebi-, Gibi-, Tebi-, Pebi-, or Ebi-bytes if you throw that suffix on there. 🍓
  • -B, --btime, --Btime, --crtime — the file was created N*24 hours ago. see --atime for the full details and options, bestie, it's all there. ✨
  • -C, --ctime — the file's status was last changed N*24 hours ago. again, --atime has the full details and options. 🌸
  • --component-count, --comp-count — the file has N components in its layout. 🧚
  • --component-end, --comp-end — the file has component end offset N (in bytes) for any component.
  • --component-flags, --comp-flags — the file has components with the specified flag set. if you use ^flag, she prints only components not matching that flag. you can specify multiple flags, separated by commas. the valid flag names are:
    • init — component has been initialized (has allocated OST objects).
    • stale — replicated (mirrored) components that do not have up-to-date data. stale components will not be used for read or write operations, and need to be resynched using lfs mirror resync before they can be accessed again. 💀
    • prefer — replicated (mirrored) components that are preferred for read or write. for example, because they are located on SSD-based OSTs, or are more local on the network to clients.
    • prefrd — replicated (mirrored) components that are preferred for read.
    • prefwr — replicated (mirrored) components that are preferred for write.
  • --component-start, --comp-start — the file has component start offset N (in bytes) for any component.
  • --foreign — the file has a foreign (non-Lustre/free format) layout and is of the given TYPE, if you specified one. presently only none or symlink are defined types, though 32-bit numeric types can also be used. 🌈
  • -g, --gid — the file has the specified numeric group ID GID.
  • -G, --group — the file belongs to the specified GROUPNAME, or numeric group GID.
  • -h, --help — prints the usage message. love a helper. 🫶
  • -L, --layout — the file has a layout of the given type, one of:
    • raid0 — traditional Lustre RAID-0 striping format.
    • released — HSM-archived files that are not resident in the filesystem.
    • mdt — files that have the first data component on an MDT.
  • -l, --lazy — uses file size and blocks from the MDT, if available, to avoid extra RPCs. efficiency queen. 💅
  • --ls — prints files in a format similar to ls -l, showing the inode number, allocated blocks, permissions, link count, owner, group, size, file type, and path. this is equivalent to specifying the ´--printf '%i\t%k\t%M\t%n\t%u\t%g\t%s\t%t\t%p\n' option.
  • --links — the file has N links.
  • --maxdepth — limits find to descend at most N levels of the directory tree.
  • --mindepth — starts find at N levels of the directory tree.
  • -m, --mdt, --mdt-index — the file or directory inode is located on the specified MDT(s).
  • -H, --mdt-hash — a DNE striped directory uses the given filename hashing function, one of:
    • crush — the CRUSH consistent hash function, added in Lustre 2.14, minimizes entry migration if the directory stripe count changes during migration.
    • fnv_1a_64 — the Fowler-Noll-Vo hash function, which is a simple and efficient hash.
    • all_char — a simple hash function that sums all of the characters in the filename. this is mostly for testing, or if it is known that filenames will use sequential filenames.
heads up bestie: this implicitly selects only directories to be matched, like -type d and not other file types. 👀
  • -T, --mdt-count — the DNE striped directory has the given number of MDT shards.
same vibe check as above: this implicitly selects only directories to be matched, like -type d and not other file types.
  • -N, --mirror-count — the file has N mirrors in its layout.
  • --mirror-state — the file has a state of state. if you use ^state, she prints only files not matching that state. only one state can be specified, so pick a fave. 🎀 the valid state name is:
    • ro — the mirrored file is in read-only state. all of the mirrors contain the up-to-date data.
    • wp — the mirrored file is in a state of being written.
    • sp — the mirrored file is in a state of being resynchronized.
  • -M, --mtime — the file's data was last modified N*24 hours ago. see --atime for full details and options. ⭐
  • -n, --name — the filename matches the given filename, or a regular expression using standard glob(7) file name regular expressions and wildcards. 🦋
  • --newer[XY] reference — succeeds if timestamp X of the file being considered is newer than timestamp Y of the file reference. the letters X and Y can be any of the following:
  • a — the access time of the file reference
  • b|B — the birth time of the file reference
  • c — the inode status change time of reference
  • m — the modification time of the file reference
  • t — reference is interpreted directly as a time
some combinations are invalid; for example, it is invalid for X to be t. specifying -newer is equivalent to -newermm.

when reference is interpreted directly as a time, currently it must be in one of these formats: "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d", "%H:%M:%S", "%H:%M" — those represent year, month, day, hour, minute, seconds, with unspecified times at the start of that minute or day, unspecified dates being "today", and "@%s" or "%s" the seconds since the Unix epoch (peep strftime(3) for the details of the time formats). otherwise, she will report an error. 😭 and if you try to use the birth time of a reference file and the birth time cannot be determined, a fatal error message results. also, if you specify a test which refers to the birth time of files being examined, this test will fail for any files where the birth time is unknown.

  • -O, --ost — the file has an object on the specified OST(s). the OST names can be specified using the whole OST target name, or just the OST index number, or an OST index range like 0-3. if multiple OSTs are given in a comma-separated list, the file may have an object on any of the given OSTs. specifying multiple OSTs allows scanning the filesystem only once when migrating objects off multiple OSTs for evacuation and replacement using lfs-migrate(1). 🔥
  • --perm MODE — the file's permissions are exactly MODE (octal or symbolic).
  • --perm/MODE — all of the permission bits MODE are set for the file.
  • --perm-MODE — any of the permission bits MODE are set for the file. if no permission bits in MODE are set, this test matches any file.
  • --pool — the layout was created with the specified POOL name. for composite files, this may match the pool of any component. 🌊
  • -P, --print — prints the file or directory name to standard output if it matches all specified parameters, one file per line with a trailing linefeed. this is the default behaviour for any matching files. 👑

more coming, bestie, don't go anywhere 💖

  • -0, --print0 — prints the full file name to standard output whenever it matches your filters, then drops a NUL character right after it instead of a newline. It's made to be piped into xargs(1) with its -0 option, so filenames with spaces or other chaotic characters don't break everything. 💅
  • --printf FORMAT — prints FORMAT to standard output for every matching file, and it interprets escape sequences and % directives while doing it. Unlike --print, --printf does not automatically add a newline at the end of the string. The escapes and directives are:
    • \n — newline.
    • \t — horizontal tab.
    • \\ — a literal backslash.
    • %% — a literal percent sign.
    • %a — the file's last access time, in the format the C ctime function returns.
    • %A@ — the file's last access time in seconds since Jan. 1, 1970, 00:00 GMT.
    • %b — the amount of disk space used for the file (in 512-byte blocks).
    • %c — the file's last status change time, in the format the C ctime function returns.
    • %C@ — the file's last status change time in seconds since Jan. 1, 1970, 00:00 GMT.
    • %g — the file's groupname.
    • %G — the file's numeric group ID.
    • %i — the file's inode number in decimal.
    • %k — the amount of storage space allocated for this file in 1K blocks.
    • %m — file permission bits (in octal).
    • %M — file permissions (rwx format).
    • %n — number of hard links to the file.
    • %p — the file's pathname.
    • %s — file size in bytes.
    • %t — the file's last modification time, in the format the C ctime function returns.
    • %T@ — the file's last modification time in seconds since Jan. 1, 1970, 00:00 GMT.
    • %u — the file's username.
    • %U — the file's numeric user ID.
    • %w — the file's birth time, in the format the C ctime function returns.
    • %W@ — the file's birth time in seconds since Jan. 1, 1970, 00:00 GMT.
    • %y — the file's type (f=file, d=directory, p=pipe, b=block device, c=character device, s=socket, l=symbolic link).

And for the Lustre girlies, you can print Lustre-specific info about a file with these directives:

  • %La — comma-separated list of the file's named attribute flags in short form (letter), or the hex value of any unknown attributes.
  • %LA — comma-separated list of the file's named attribute flags, or the hex value of any unknown attributes.
  • %Lc — file or directory stripe count. For a composite file, this is the stripe count of the last instantiated component.
  • %LF — the File Identifier (FID) associated with the file.
  • %Lh — the directory's hash type (or none for an unstriped directory).
  • %Li — the file's starting OST index (or starting MDT index for a directory). For a composite file, this is the starting OST index of the last instantiated component.
  • %Lo — list of all OST/MDT indices associated with a file or directory.
  • %Lp — the file's OST pool name. For a composite file, this is the pool associated with the last instantiated component. (NOTE: this can also be used for directories, but since MDT pools are not currently implemented, nothing will be printed.)
  • %LP — numeric project ID assigned to the file or directory.
  • %LS — the file's stripe size. For a composite file, this is the stripe size of the last instantiated component.
  • --projid — the file belongs to the project specified by PROJID or PROJNAME. You can slot in a username or group name instead of a project name by saying u:USERNAME or user:USERNAME or g:GROUPNAME or group:GROUPNAME respectively — though heads up, that name will not be shown in place of the numeric ID. 🙈
  • -s, --size — file size is N 512-byte blocks (if you give no unit at all), or N chars (bytes), Kibi-, Mebi-, Gibi-, Tebi-, Pebi-, or Ebi-bytes if a suffix is given.
  • -k, --skip — skip PERCENT of the total files that match the other filters. This is the moment when it pairs up with lfs-migrate(1) so you only process a fraction of the files to rebalance things when new OSTs get added to the filesystem.
  • -c, --stripe-count — file has N stripes allocated. For composite files, this matches the stripe count of the last initialized component.
  • -i, --stripe-index — file has a stripe on OST index N. You can list multiple OST indices in a comma-separated list, which means the file has a stripe on any of the specified OSTs. That's how a single namespace scan can cover files on multiple different OSTs, if there are multiple OSTs being replaced. ✨
  • -S, --stripe-size — stripe size is N bytes, or Kibi-, Mebi-, Gibi-, Tebi-, Pebi-, or Ebi-abytes if a suffix is given. For composite files, this matches the stripe size of the last initialized non-extension component.
  • -z, --extension-size, --ext-size — extension size is N bytes, or Kibi-, Mebi-, Gibi-, Tebi-, Pebi-, or Ebi-bytes if a suffix is given. For composite files, this matches the extension size of any extension component.
  • -t, --type — file has type: block, character, directory, file, pipe, symlink, or socket.
  • --threads N — use N threads for parallel directory traversal. If you don't specify it, the default thread count is calculated as min(MDT_COUNT * 4, CPU_COUNT / 2), where CPU_COUNT is the total number of CPUs configured for Lustre. This lets big directory trees get scanned faster by processing multiple directories at once while still respecting the CPU resources you actually have. 🚀
  • -u, --uid — file has the specified numeric user ID UID.
  • -U, --user — file owned by the specified USERNAME, or numeric user UID.
  • --xattrNAME[=VALUE] — file has an extended attribute whose name matches the regular expression (regex(7)) NAME, and optionally a value matching the regular expression VALUE. Those regular expressions have to match the complete attribute names and values, not just some substring, okay? And you can pass this option multiple times — the file has to match all of the arguments you gave it. 🔥

📝 NOTES 📝

Putting a ! before an option negates it, meaning you get the files that do NOT match that parameter. Using + before a numeric value means "more than N", and - before a numeric value means "less than N". If you use neither, it means "equal to N", within the bounds of whatever unit you specified (if any).

Numeric suffixes are in binary SI (power-of-two) units. 🧮

For compatibility with find(1), you can specify long options with either a single or a double leading dash. No stress either way.

The order of your parameters does not affect how files get matched. lfs find first scans the directory for any specified filename, and then fetches MDT inode attributes for each matching filename. If it can make a positive or negative decision about a file using only the MDT attributes (newer than a specified time, user/group/project ID, that kind of thing) it will not go fetch the OST object attributes for that file. Efficiency slay. 💅

🎀 BASH COMPLETION 🎀

The lfs find command supports bash-completion(1) for tab-completing option names and, in some cases, their arguments — assuming you've got proper package installation and you're using a supporting shell. It makes specifying complex search commands way less painful.

To list mountpoints, type lfs find TAB. To list long options (more descriptive, easier to understand, iconic behavior), type --TAB, and to list short options type -TAB. Some arguments also allow context-specific completion for the command-line option — for example, generating a list of OST devices for the -ost option, or a list of OST pools for the -pool option. 🦋

💀 BUGS 💀

Real talk: the lfs find command isn't as comprehensive as find(1). Specifically, it does not support complex boolean expressions with -o (logical OR) — it only does logical AND of most expressions. The parameter ordering does not affect how files are matched. And specifying multiple identical options generally clobbers the earlier option (so like, you can't specify a range of stripe counts, or multiple pools). Not me betraying you with clobbering. 😭

🌈 EXAMPLES 🌈

Efficiently list every file in a given directory and its subdirectories, without fetching any file attributes:

# lfs find /mnt/lustre

Print a formatted find string, listing the username, access mode and inode number:

# lfs find /mnt/lustre -printf %u %M %i 0

Recursively list all regular files in a given directory that are more than 30 days old:

# lfs find /mnt/lustre -mtime +30 -type f -print

Recursively find all files in test that have objects on OST0002 or OST0003 and migrate them to other OSTs. See lfs-migrate(1) for more details:

# lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs migrate -0

Recursively list all files ending with .mpg that have more than 3 components:

# lfs find -name *.mpg --component-count +3 /mnt/lustre

Recursively list all files that have at least one component with both init and prefer flags set, and that doesn't have the flag stale set:

# lfs find --component-flags=init,prefer,^stale /mnt/lustre

Recursively list all mirrored files that have more than 2 mirrors:

# lfs find --mirror-count +2 /mnt/lustre

Recursively list all out-of-sync mirrored files:

# lfs find ! --mirror-state=ro /mnt/lustre

Recursively list all but foreign files/dirs of symlink type:

# lfs find ! --foreign=symlink /mnt/lustre

Recursively list all files with the specified "user.job" extended attribute:

# lfs find -xattr user.job=202310.* /mnt/lustre

Recursively list all files in /var/www that have any SELinux extended attribute, but that do NOT have an SELinux extended attribute with a value containing "httpd":

# lfs find -xattr security.selinux ! -xattr security.selinux=.*httpd.* /var/www

Recursively list all files in a directory with detailed information in a format similar to ls -l:

# lfs find /mnt/lustre --ls

👑 AVAILABILITY 👑

lfs find has been part of the lustre(7) filesystem package since release 0.10.0. Vintage but still eating. ✨

🫶 SEE ALSO 🫶

lfs(1), lfs-getdirstripe(1), lfs-getstripe(1), lfs-migrate(1), xargs(1), projid(5), lustre(7), regex(7)

okay bestie that's the whole page, you're officially a lfs find girlie now 💖 this one came from the Lustre crew, dated 2026-03-06, and lives in section LFS-FIND(1) of the manual. go forth and find files, no cap. 🌸

📦 where this page comes from