find.flexfs

find.flexfs provides fast filesystem search by querying the metadata server directly, bypassing the FUSE layer. It supports filters on inode attributes, timestamps, size, cost, permissions, and file type.

Usage

find.flexfs [flags] [path...]

If no path is specified, the current directory is used. Can operate from within a flexFS mount or connect directly via --metaAddr and --volume.

Flags

Output Control

Flag	Type	Default	Description
--fields	string slice	path	Output fields (comma-separated). Use all for all fields.
--header	bool	false	Include header row in output
--limit	uint64	0	Maximum number of results (0 = unlimited)
--noDecode	bool	false	Print base32-encoded paths
--outputFile, -o	string		Output file path. With multiple search paths, all results go to this one file, with a single header row.

Results are written to standard output (or the --outputFile file); error messages are written to standard error. This means you can safely pipe results into other commands without error text mixing into the data.

Available fields: path, ino, mode, type, perm, blocks, size, size_bin, cost, nlink, uid, gid, ctime, mtime, atime, btime, xattrs.

The cost field is an estimated monthly storage cost in US dollars ($/month). See the analyze.flexfs cost field documentation for how it is calculated.

The xattrs field emits an inode’s extended attributes as a JSON object. See Xattrs field below.

Connection

Flag	Type	Default	Description
--metaAddr	string		Metadata server address (must pair with --volume)
--mountPath	string		Client mount path. Only needed in direct mode when the search path passes through symbolic links whose targets are absolute paths (e.g. /mnt/flexfs/data); when run from inside a mount, this is detected automatically.
--volume	string		Volume UUID or name (must pair with --metaAddr)

Symbolic links

Search paths may pass through symbolic links. Links that stay within the volume are followed automatically, including a link as the final path component — find.flexfs /mnt/flexfs/current/logs works even when current is a link to a release directory. A link whose target points outside the volume cannot be searched and returns an error that names the link.

Inode Filters

Flag	Type	Default	Description
--empty	bool	false	Filter for empty files or directories
--gid	uint32	0	Filter by group ID
--ino	uint64	0	Filter by inode number
--name	string		Filter by dentry name (supports glob patterns)
--perm	string	0	Required permission bits (octal, with or without a leading 0 — 755 and 0755 mean the same thing; max 07777). Matches when (mode & permMask) == perm.
--permMask	string	0777	Bits of the file mode to test (octal, with or without a leading 0; max 07777). The default tests owner/group/other. Set to 7777 to also test setuid/setgid/sticky.
--sparse	bool	false	Filter for sparse files
--type	string		Filter by inode type: b, c, d, f, l, p, s
--uid	uint32	0	Filter by user ID

Size and Block Filters

Flag	Type	Default	Description
--maxBlocks	uint64	0	Maximum blocks filter
--maxCost	float64	0	Maximum estimated monthly cost filter ($/month)
--maxNlink	uint32	0	Maximum hard link count filter
--maxSize	uint64	0	Maximum byte size filter
--maxSizeBin	uint32	0	Maximum size bin filter (0-74)
--minBlocks	uint64	0	Minimum blocks filter
--minCost	float64	0	Minimum estimated monthly cost filter ($/month)
--minNlink	uint32	0	Minimum hard link count filter
--minSize	uint64	0	Minimum byte size filter
--minSizeBin	uint32	0	Minimum size bin filter (0-74)

Timestamp Filters

Timestamp values are in seconds since epoch (Unix time).

Flag	Type	Default	Description
--maxAtime	uint64	0	Maximum access time
--maxBtime	uint64	0	Maximum birth time
--maxCtime	uint64	0	Maximum change time
--maxMtime	uint64	0	Maximum modification time
--minAtime	uint64	0	Minimum access time
--minBtime	uint64	0	Minimum birth time
--minCtime	uint64	0	Minimum change time
--minMtime	uint64	0	Minimum modification time

Depth Control

Flag	Type	Default	Description
--maxDepth	uint32	0	Maximum query depth (0 = unlimited)
--minDepth	uint32	0	Minimum query depth

Internal Flags

Flag	Type	Default	Description
--noMetaSSL	bool	false	Disable SSL for metadata server connections

Examples

File discovery

Find all files larger than 1 GiB:

find.flexfs --minSize 1073741824 --type f /mnt/flexfs

Find files by name pattern with full metadata:

find.flexfs --name "*.bam" --fields all --header /mnt/flexfs/data

Find empty directories (candidates for cleanup):

find.flexfs --type d --empty /mnt/flexfs

Find all symlinks under a path:

find.flexfs --type l --fields path,size /mnt/flexfs/data

Cost and storage analysis

Find the most expensive files (costing more than $1/month):

find.flexfs --minCost 1 --type f --fields path,size,cost --header /mnt/flexfs

Find cold files (not accessed in over 6 months, size bin 6+) that are still large:

find.flexfs --minSizeBin 6 --minSize 1073741824 --type f \
  --fields path,size,size_bin,cost --header /mnt/flexfs

Timestamp queries

Find files not accessed since January 1 2025 (stale data candidates):

# 2025-01-01T00:00:00Z = 1735689600
find.flexfs --maxAtime 1735689600 --type f /mnt/flexfs

Find files modified in a specific window (e.g. during an incident):

# 2025-03-15 00:00:00Z = 1741996800, 2025-03-16 00:00:00Z = 1742083200
find.flexfs --minMtime 1741996800 --maxMtime 1742083200 --type f \
  --fields path,size,mtime --header /mnt/flexfs

Find files created in the last 7 days:

# Use $(date -d '7 days ago' +%s) on Linux or $(date -v-7d +%s) on macOS
find.flexfs --minBtime $(date -v-7d +%s) --type f /mnt/flexfs

Permissions audit

Find files with exact permissions rwxrwxrwx:

find.flexfs --perm 777 --type f --fields path,perm /mnt/flexfs

Find world-writable files (other-write bit set):

find.flexfs --perm 2 --permMask 2 --type f --fields path,perm /mnt/flexfs

Find files with the setuid bit set:

find.flexfs --perm 4000 --permMask 4000 --type f --fields path,perm /mnt/flexfs

Ownership

Find all files owned by a specific user:

find.flexfs --uid 1001 --type f --fields path,size,uid /mnt/flexfs

Sparse files

Find sparse files (logical size exceeds allocated blocks):

find.flexfs --sparse --type f --fields path,size,blocks /mnt/flexfs

Exporting and direct connection

Export a full file inventory to TSV:

find.flexfs --fields all --header --type f \
  --outputFile /tmp/inventory.tsv /mnt/flexfs

Query a volume directly without a local mount:

find.flexfs --metaAddr meta.example.com:443 --volume my-vol --type d /

Output Format

Output is tab-separated. The columns correspond to the --fields list. When --header is set, the first line contains field names.

Xattrs Field

The xattrs field emits all of an inode’s extended attributes as a single JSON object, occupying one tab-separated column:

{"user.department":"cmVzZWFyY2g=","user.project":"Z2Vub21pY3M="}

• Keys are attribute names, including the namespace prefix, exactly as stored. Names settable with setfattr live in the user., trusted., and security. namespaces; system. and flexfs. also appear, holding attributes flexFS maintains on your behalf (see below).
• Values are base64-encoded (standard alphabet, with padding). Extended attribute values are arbitrary binary data, so they are never emitted raw. Decode with base64 -d; in the example above the values are the strings research and genomics.
• Keys are sorted lexicographically, so the object is byte-for-byte stable across runs for a given inode.
• An inode with no extended attributes emits {}, not an empty column.
• The object is always one line and always tab-free: base64 values cannot contain a tab or newline, and JSON escapes both characters if an attribute name contains them. An xattrs column therefore never breaks the tab-separated row structure.
• There are no filter flags for extended attributes. xattrs is an output field only — filter the results downstream (see the examples below).

Which attributes appear

Everything stored on the inode appears, including attributes flexFS maintains itself. Beyond whatever your applications set under user., expect to see:

Attribute	Written by	Contents
system.posix_acl_access	ACLs (--acl)	Packed POSIX ACL structure for the inode’s access ACL
system.posix_acl_default	ACLs (--acl)	Packed POSIX ACL structure inherited by new children of a directory
security.capability	setcap	File capability set. Stripped automatically on write, so it may disappear between runs.
flexfs.iflags	chattr	4-byte little-endian inode flag word backing the immutable and append-only inode flags. Present even on volumes mounted without --xAttr, and removed entirely once every flag is cleared.

Setting and reading extended attributes through a mount requires --xAttr, but that option gates the FUSE layer only. find.flexfs queries the metadata server, so it reports stored attributes regardless of how any mount is currently configured — including attributes written earlier on a volume now mounted without --xAttr.

Encrypted volumes

find.flexfs queries the metadata server directly and reads the stored form of each attribute. On a volume using metadata encryption, encryption and decryption happen only in the mount client, so attribute names and values reach find.flexfs as ciphertext:

{"5LJ0aBv...=":"n4Kc2Rv1Zt8..."}

The name is base64 of the AES-256-GCM ciphertext of the name; the value is base64 of the AES-256-GCM ciphertext of the value. Neither is recoverable from find.flexfs output. Reading extended attributes in plaintext on an encrypted volume requires going through a mount — getfattr on the mounted path. Note that --noDecode is unrelated: it governs base32 path encoding only and has no effect on the xattrs column.

Querying extended attributes

List every file that carries any extended attribute:

find.flexfs --type f --fields path,xattrs /mnt/flexfs | awk -F'\t' '$2 != "{}"'

Report a specific attribute in plaintext, one file per line:

find.flexfs --type f --fields path,xattrs /mnt/flexfs \
  | jq -Rr 'split("\t") | (.[1] | fromjson)["user.project"] as $v
            | select($v != null) | .[0] + "\t" + ($v | @base64d)'

Find files carrying a POSIX ACL:

find.flexfs --type f --fields path,perm,xattrs /mnt/flexfs \
  | grep 'system.posix_acl_access'