Volume Tokens

A volume token is a UUID that grants a mount client permission to mount a specific volume. Tokens can optionally restrict the mount to a subdirectory within the volume and enforce additional mount flags.

Creating a Volume Token

configure.flexfs create volume-token --volumeID <volume-name>

This creates a token with full access to the entire volume. The token UUID is auto-generated.

With Mount-Path Scoping

configure.flexfs create volume-token \
  --volumeID <volume-name> \
  --mountPath /data/project-a

When a mount client uses this token, it sees /data/project-a as the root of the filesystem. Files outside this path are inaccessible.

With Per-Token Flags

configure.flexfs create volume-token \
  --volumeID <volume-name> \
  --mountPath /data/project-a \
  --flags "ro,noExec" \
  --notes "Read-only access for CI pipeline"

Volume Token Fields

For the full list of volume token fields, their flags, types, and defaults, see Volume Token Fields in the configure.flexfs CLI reference.

Mount-Path Scoping

Mount-path scoping provides subdirectory isolation — each token holder sees only a subtree of the volume as their filesystem root.

For example, given a volume with this structure:

/
├── data/
│   ├── project-a/
│   └── project-b/
└── shared/

You can create separate tokens for each project:

# Token for project A -- sees /data/project-a as /
configure.flexfs create volume-token \
  --volumeID <volume-name> --mountPath /data/project-a

# Token for project B -- sees /data/project-b as /
configure.flexfs create volume-token \
  --volumeID <volume-name> --mountPath /data/project-b

Each token holder can only read and write within their scoped path. This is useful for:

Multi-tenant isolation — give each team or customer their own view of the volume
Security boundaries — limit access to sensitive directories
Kubernetes PVs — bind each PersistentVolume to a different subdirectory of the same underlying volume

Per-Token Flags

Token flags are merged over the volume’s flags, with the token’s value winning. A token can only add boolean flags — there is no syntax for turning one off, so a token can widen a volume’s squashing from rootsquash to allsquash but never remove it — but a key=value flag set on the token replaces the volume’s value, including with a more permissive one. Do not rely on a volume-level umask or anonUID/anonGID as a ceiling.

For example, if a volume has flags = "acl", a token with flags = "ro" results in the mount having both acl and ro active.

For the accepted per-token flag vocabulary, see Accepted Volume and Token Flags in the configure.flexfs CLI reference.

Reporting Access

A volume token can also carry the admin flag, which allows it to run reporting queries against the metadata server — find.flexfs, analyze.flexfs, dedup.flexfs, and the /find, /analyze/* and /duplicates endpoints they use. Those queries list every file and directory name in the volume, along with owners and permissions, so the flag is a meaningful grant.

configure.flexfs create volume-token \
  --volumeID <volume-name> \
  --flags admin \
  --notes "reporting for the storage team"

Three things to know about it:

It is set on tokens, not on volumes. A volume’s flags are merged into every token issued for that volume, so admin is rejected at the volume level. This keeps the grant on the tokens you choose.
It has no effect on mounting. admin is not a mount option, so a token carrying it mounts exactly as it would without it. Even so, prefer a separate token for reporting, so the grant can be withdrawn without disturbing any mount.
The three utilities share one copy. find.flexfs init creds, analyze.flexfs init creds and dedup.flexfs init creds all file the token under ~/.flexfs/util/creds/<volume-name>, per user, so storing it once is enough for all three. With none there they fall back to the credentials mount.flexfs uses for the same volume and user.
Mount path scoping applies to it. A token scoped to /data/project reports on that subdirectory and nothing above it, exactly as its mounts see only that subdirectory:

configure.flexfs create volume-token \
  --volumeID <volume-name> \
  --mountPath /data/project \
  --flags admin \
  --notes "reporting for the project team"

Paths in a reporting token’s output and queries are relative to that token’s own mount-path scope — not to whatever token a mount was made with. A path outside the reporting token’s subtree is rejected rather than resolved elsewhere in the volume.

Listing Volume Tokens

List all tokens:

configure.flexfs list volume-tokens

Filter by volume name:

configure.flexfs list volume-tokens --volumeName <volume-name>

The list view shows the volume name, token UUID, mount path, flags, notes, and last active timestamp.

Showing Token Details

configure.flexfs show volume-token <volume-token>

The full detail view includes volume_id, token, mount_path, flags, notes, created_at, and active_at (the last time a mount client used this token).

Updating a Token

Update the mount path, flags, or notes on an existing token:

configure.flexfs update volume-token <volume-token> \
  --mountPath /data/project-a/v2 \
  --flags "ro,noExec" \
  --notes "Updated for v2 migration"

Active mounts using this token are not affected until they reconnect.

Deleting a Token

configure.flexfs delete volume-token <volume-token>

Existing mounts using the deleted token will lose access when they next attempt to authenticate with the admin server. This does not forcibly unmount active sessions.

Token Lifecycle

Create a volume token with configure.flexfs create volume-token
Distribute the token UUID to the mount client operator (via the credential file or Kubernetes secret)
Mount — the mount client presents the token to the admin server, which returns volume settings and storage credentials
Active tracking — the active_at timestamp updates each time the token is used
Revoke by deleting the token when access is no longer needed