Access Control

FlexFS provides multiple layers of access control that work together to protect data and enforce security policies.

This page covers access control inside the filesystem — who may read and write which files. For restricting which hosts may reach the metadata, admin and free-tier REST APIs, see API Access Control.

POSIX permissions

FlexFS is a fully POSIX-compliant filesystem and enforces standard Unix file permissions (owner, group, other with read/write/execute bits). Checks are made against the calling process’s UID and GID. See Extended ACLs.

Root squashing

Root squashing maps uid=0 and gid=0 to a specified non-root user, preventing root users on mount clients from having root-level access to the filesystem.

Enabling root squashing

On the mount client:

mount.flexfs start <volume-name> /mnt/data --rootSquash

By default, root is mapped to uid=65534 / gid=65534 — the conventional anonymous identity, and the same default NFS uses. You can customize the mapping:

mount.flexfs start <volume-name> /mnt/data \
  --rootSquash \
  --anonUID 1000 \
  --anonGID 1000

Root squashing can also be set as a volume-level flag via configure.flexfs, in which case it applies to all mounts of that volume.

Note

When root squashing is enabled, extended ACLs and xattr support are automatically enabled as well, since they are required for the squashing implementation.

Caution

--rootSquash, --allSquash, --anonUID and --anonGID may only be passed by root. A mount that sets any of them as an unprivileged user is refused, since a caller free to name the identity could aim a squash at uid 0 and grant itself everything the squash was meant to remove. To squash mounts whose users you do not control, set the flags on the volume instead.

A volume or token setting overrides the matching local flag: the startup banner shows the applied value marked (mandated) and the mount continues silently. A token’s value replaces the volume’s, and a mandated squash discards all four local flags together, so you set the anonymous identity and mode on the volume or token too.

Caution

Choose the anonymous identity carefully. It defaults to 65534; nothing validates a chosen value beyond refusing to let an unprivileged mount set it, so anonuid naming a real user gives squashed callers that user’s access. Avoid 0 (root’s access) and 65535 (the (uid_t)-1 “unset” id).

All squashing

All squashing maps every UID and GID to the anonymous UID / GID, not just uid=0 / gid=0. Every caller on the mount reaches the filesystem as the same anonymous identity, so no file’s ownership can distinguish one local user from another and no local user can hold permissions any other does not.

Enabling all squashing

mount.flexfs start <volume-name> /mnt/data --allSquash

The anonymous identity is the same one root squashing uses — uid=65534 / gid=65534 by default, and configurable with the same two flags:

mount.flexfs start <volume-name> /mnt/data \
  --allSquash \
  --anonUID 1000 \
  --anonGID 1000

Like root squashing, it can also be set as a volume-level flag via configure.flexfs, in which case it applies to all mounts of that volume.

--allSquash implies --rootSquash — squashing every caller necessarily squashes root — and with it extended ACLs and xattr support. Setting both flags is the same as setting --allSquash alone. Like the other squash flags, it may only be passed by root; see the caution under Root squashing.

Note

Squashing also discards the caller’s supplementary groups. Under --rootSquash only gid=0 is dropped from that set; under --allSquash the whole set is, so access is evaluated against the anonymous GID and nothing else. Without this a caller could keep group-derived access as the identity the squash just replaced.

Caution

Setting the anonymous identity to 0 defeats the flag: every caller would be mapped to uid 0, so all callers would have root access to the volume. The mount warns about it and continues. Only an operator can reach this state — on the volume, or as root on the command line — since no unprivileged mount can set the anonymous identity.

Because every caller shares one identity, files created on an --allSquash mount are all owned by the anonymous UID / GID, and per-user permissions and ACL entries have no effect for local callers. Use it where a volume should be reachable as a single shared identity — not as a way to isolate users from each other on the same mount.

Extended ACLs

FlexFS supports POSIX.1e extended access control lists (ACLs), which allow fine-grained per-user and per-group permissions beyond the standard owner/group/other model.

Enabling ACLs

On the mount client:

mount.flexfs start <volume-name> /mnt/data --acl

ACLs need kernel support that arrived in Linux 4.9. On any current distribution this is present and an --acl mount performs the same as a mount without it. On older systems — in practice RHEL/CentOS 7 — the mount client enforces ACLs itself instead: still correct, but slower, because the kernel cannot cache file metadata when the client is doing the checking. The same applies whenever --rootSquash or --allSquash is used, on any kernel.

The mount log records which is in effect:

ACL enforcement: kernel (default_permissions + FUSE_POSIX_ACL)
ACL enforcement: client (userspace POSIX.1e evaluation)

On the rare kernel that is new enough but was built without POSIX ACL support, an --acl mount refuses to start rather than run with ACLs partly ignored. See Troubleshooting.

Or as a volume-level flag via configure.flexfs.

The same principle applies to a mount where ACLs are simply not enabled: it does not run with ACLs partly ignored, it has no POSIX ACL support at all, like a filesystem whose kernel lacks it. setfacl and getfacl fail with Operation not supported, ACLs already stored on the volume by ACL-enabled mounts are neither reported nor applied, and access is governed by the owner/group/other mode bits alone. Because a shared volume’s access control is only as strong as its weakest mount, set the volume-level acl flag whenever access decisions depend on ACLs — it makes every mount of the volume enforce them, regardless of each mount client’s local flags.

Once enabled, use standard Linux ACL tools:

# Set an ACL
setfacl -m u:alice:rwx /mnt/data/project

# View ACLs
getfacl /mnt/data/project

# Remove an ACL
setfacl -x u:alice /mnt/data/project

Extended attributes (xattrs)

Extended attributes are enabled with the --xattr flag:

mount.flexfs start <volume-name> /mnt/data --xattr

Xattrs are automatically enabled when ACLs or root squashing are active.

Umask

The umask controls the default permissions for newly created files and directories. FlexFS supports overriding the process umask at the mount level:

mount.flexfs start <volume-name> /mnt/data --umask 0027

This sets newly created files to 0640 and directories to 0750 regardless of the creating process’s umask. Umask can also be configured as a volume-level setting.

Volume-level flags

Several access control settings can be enforced at the volume level via configure.flexfs. Setting one on the volume turns it on for every mount of that volume, whatever the mount client asks for:

Volume flag	Effect
acl	Enable extended ACLs (implies xattr)
allsquash	Squash every uid / gid to the anonymous uid / gid (implies rootsquash)
anongid=N	GID squashed callers are mapped to
anonuid=N	UID squashed callers are mapped to
noexec	Prevent execution of files
nosuid	Disable SUID/SGID special permissions
ro	Read-only — no writes permitted
rootsquash	Enable root squashing (implies acl)
umask=NNNN	File creation mask in octal, with or without a leading 0 — 27 and 0027 mean the same thing; max 0777
xattr	Enable extended attributes

These flags are set during volume creation or update in configure.flexfs. They combine with the mount client’s own options rather than replacing them: for a boolean flag, either side can turn the behavior on and neither side can turn off what the other enables, so a volume flag raises the floor for every mount but never lowers it. For a key-value flag such as umask or attrvalid, the volume’s value wins where both sides set one.

The squash flags are the exception. A volume (or token) that sets rootsquash or allsquash replaces the mount’s entire local squash configuration — --rootSquash, --allSquash, --anonUID and --anonGID are all discarded, and an anonymous identity the volume does not state falls back to 65534 rather than to what the mount asked for. See Accepted Volume and Token Flags.

Additional non-access-control flags (e.g., caching, prefetching, proxy behavior) are also supported — see the full flag reference.

Volume token mount paths

Volume tokens can be scoped to a specific subdirectory within a volume. When a mount path is set on a token, the mount client only has access to that subdirectory and its contents — the rest of the volume is not visible.

This provides subdirectory isolation without creating separate volumes:

Volume: shared-data
  Token A (mount path: /team-alpha)   -> sees only /team-alpha/*
  Token B (mount path: /team-beta)    -> sees only /team-beta/*
  Token C (mount path: /)             -> sees entire volume

Mount path scoping is configured when creating or updating a volume token in configure.flexfs. The mount client automatically mounts at the scoped path.

Per-token flags

In addition to mount path scoping, each volume token can carry its own set of mount flags (e.g., ro, noExec). These flags are merged with the volume-level flags, providing token-level access control.

A volume token can also be granted the admin flag. It is not a mount option and changes nothing about how the volume is mounted; it allows the token to run reporting queries against the metadata server, which list file and directory names along with their owners and permissions. Where the token also sets a mount path, those queries are confined to that subdirectory. The flag is set on individual tokens and is rejected at the volume level, so it reaches only the tokens you grant it to. See Accepted Volume and Token Flags.

Immutable and append-only files

FlexFS supports the chattr(1) immutable (+i) and append-only (+a) inode flags on both files and directories. They differ from every other layer on this page in that they are not discretionary: an immutable file cannot be modified, deleted, renamed, or have its permissions changed even by root, until the flag is cleared. That makes them useful for pinning configuration or audit data against accidental change.

sudo chattr +i /mnt/flexfs/data/important.dat   # freeze
lsattr /mnt/flexfs/data/important.dat
sudo chattr -i /mnt/flexfs/data/important.dat   # release

Two limits matter for security planning. Setting a flag requires root as the mount sees it, so it is not possible on a --rootSquash or --allSquash mount. And enforcement is performed by the mount client, not the metadata server — the flags bind every caller reaching the data through a flexFS mount, but they are not a server-side retention or compliance control. See Inode flags for the full behavior.

Summary of access control layers

Layer	Scope	Configured via
POSIX permissions	Per-file/directory	Standard Unix tools (chmod, chown)
Extended ACLs	Per-file/directory	setfacl / getfacl
Immutable / append-only flags	Per-file/directory	chattr / lsattr
Root squashing	Per-mount or per-volume	--rootSquash flag or volume flag
All squashing	Per-mount or per-volume	--allSquash flag or volume flag
Umask	Per-mount or per-volume	--umask flag or volume setting
Volume flags	Per-volume	configure.flexfs
Token mount paths	Per-token	configure.flexfs
Token flags	Per-token	configure.flexfs

Next steps

• Authentication — token model
• TLS Certificates — in-transit encryption
• End-to-end Encryption — data-at-rest encryption