Volume Analysis and Search

analyze.flexfs and find.flexfs query the metadata server directly, providing fast volume-wide analysis without traversing the FUSE layer. Both tools work with Enterprise and Community editions.

Credentials

Both tools query the metadata server, which requires a volume token carrying the admin flag. Store one per volume, once per user:

analyze.flexfs init creds --adminAddr admin.example.com:443
find.flexfs init creds --adminAddr admin.example.com:443

Each command prompts for the token and confirms with the admin server that it allows reporting queries. See Volume Tokens for how to obtain one.

If credentials have not been stored for a tool, it falls back to the ones mount.flexfs uses for the same volume and the same user. Credentials files must be readable only by their owner (chmod 600).

analyze.flexfs

Top Files by Cost

Identify the most expensive files in a volume:

analyze.flexfs files --orderBy cost --limit 5 /mnt/flexfs

Default output is tab-separated, suitable for scripting:

path  size  size_bin  cost
/data/genome/sample1.bam  52428800000  62  15.23
/data/genome/sample2.bam  48318382080  61  14.02

Use --friendly for human-readable output with aligned columns, readable sizes, dollar costs, and how recently each file was used:

analyze.flexfs files --friendly --orderBy cost --limit 5 /mnt/flexfs

path                                        size    cost                     last_active
/mnt/flexfs/data/genome/sample1.bam    48.83 GiB  $15.23  [1860, 1890) days ago (bin 62)
/mnt/flexfs/data/genome/sample2.bam    45.00 GiB  $14.02  [1830, 1860) days ago (bin 61)
/mnt/flexfs/data/genome/reference.fa    3.00 GiB   $1.50    [120, 150) days ago (bin  4)
/mnt/flexfs/data/logs/pipeline.log    100.00 MiB   $0.05          < 30 days ago (bin  0)
/mnt/flexfs/data/tmp/scratch.dat       10.00 GiB   $1.12  [1350, 1380) days ago (bin 45)

Directory Size Breakdown

See which directories consume the most storage:

analyze.flexfs folders --maxDepth 2 /mnt/flexfs

With --friendly, folders are rendered as an ASCII directory tree:

analyze.flexfs folders --friendly --maxDepth 2 /mnt/flexfs

path                  size    cost
/mnt/flexfs      62.83 GiB  $17.69
├── data         52.83 GiB  $16.52
│   ├── genome   51.83 GiB  $16.02
│   └── logs    100.00 MiB   $0.05
└── scratch      10.00 GiB   $1.17

Per-User Storage Usage

Identify which users are consuming the most space:

analyze.flexfs users --orderBy size /mnt/flexfs

Output includes UID, resolved username, size, and cost. With --friendly:

analyze.flexfs users --friendly --orderBy size /mnt/flexfs

uid    user        size    cost
1001  alice   48.83 GiB  $15.23
1002    bob   10.00 GiB   $1.12
0      root  100.00 MiB   $0.05

Reporting on an Unmounted Volume

All analyze.flexfs subcommands can report on a volume that is not mounted locally:

analyze.flexfs files --volume <volume-name> --orderBy size --limit 50 /data

--volume takes the volume’s name and selects the credentials to use. The admin server address is read from those credentials, and is used to find the metadata server holding the volume — so once init creds has run, the volume name is all that is needed.

If the admin server moves, re-run init creds --adminAddr <admin-host:port> --force to record the new address.

Saving Output

Write results to a file:

analyze.flexfs files --outputFile /tmp/top-files.tsv /mnt/flexfs

find.flexfs

Find Files by Name Pattern

find.flexfs --name '*.bam' --type f /mnt/flexfs

Find Large Files

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

Find Files by Owner

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

Find Old Files (by Access Time)

Find files not accessed since a specific timestamp (seconds since epoch):

# Files not accessed since 2025-01-01 (1735689600 = 2025-01-01T00:00:00Z)
find.flexfs --maxAtime 1735689600 --type f /mnt/flexfs

Find Empty Directories

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

Find Files with Specific Permissions

The --perm and --permMask flags filter by permission bits using the logic (mode & permMask) == perm. Values are always interpreted as octal, with or without a leading 0 (755 and 0755 are equivalent); the maximum is 07777. Without --permMask, the default mask is 0777 (owner/group/other), so --perm performs an exact match on all rwxrwxrwx bits.

Find files with exact permissions rwxrwxrwx:

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

Use --permMask to test only specific bits. The mask selects which bits to compare, and --perm specifies the expected value of those bits:

# Files that are world-writable (other-write bit set)
find.flexfs --perm 02 --permMask 02 --type f /mnt/flexfs

# Files that are group-executable (group-execute bit set)
find.flexfs --perm 010 --permMask 010 --type f /mnt/flexfs

# Files with setuid bit set (requires testing beyond the default 0777 mask)
find.flexfs --perm 04000 --permMask 04000 --type f /mnt/flexfs

# Files that are not readable by others (other-read bit unset)
find.flexfs --perm 0 --permMask 04 --type f /mnt/flexfs

Full Metadata Export

Export all files with all metadata fields:

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

Searching an Unmounted Volume

Like analyze.flexfs, find.flexfs can search a volume that is not mounted locally:

find.flexfs --volume <volume-name> --name '*.log' --type f /

Available Output Fields

The find.flexfs tool supports this field set for --fields:

Field	Description
path	File path (default)
ino	Inode number
mode	Raw mode bits
type	Inode type (f, d, l, p, s, b, c)
perm	Permission bits (octal)
blocks	Block count
size	Size in bytes
size_bin	Activity-based bin (0 = read or written within the last 30 days, 1 = 30-60 days ago, up to 127). Driven by data I/O, so listing or touching a file does not affect it. It is a billing tier rather than a precise last-I/O timestamp. See Size Bin.
cost	Estimated monthly storage cost in US dollars ($/month). Computed as (effective_size / 1 GiB) * rate, where effective_size is capped at the allocated block size for sparse files, and rate is an activity-based tiered $/GiB/month rate determined by the file’s size_bin. See cost field details.
nlink	Hard link count
uid	Owner user ID
gid	Owner group ID
ctime	Change time (seconds since epoch)
mtime	Modification time (seconds since epoch)
atime	Access time (seconds since epoch)
btime	Birth (creation) time (seconds since epoch)
xattrs	Extended attributes

Use Cases

• Cost optimization: Use analyze.flexfs files --orderBy cost to find the most expensive files and schedule archival or deletion. Cost reflects activity-based tiered pricing, so cold data may already carry a lower rate — focus on large hot files for the biggest savings.
• Compliance auditing: Use find.flexfs --fields all --header to generate a complete filesystem inventory.
• Stale data identification: Use find.flexfs --maxAtime <cutoff> to find files not accessed within a retention window.
• Permissions audit: Use find.flexfs --perm --permMask to find files with overly permissive access.
• Capacity planning: Use analyze.flexfs folders --maxDepth 3 to understand storage distribution across the directory tree.