Mount Client Overview

mount.flexfs is the FUSE-based mount client that presents a flexFS volume as a local POSIX filesystem. It communicates with the metadata server via RPC for filesystem operations and loads/stores data blocks directly to object storage (or through proxy servers when configured).

Lifecycle

A typical mount follows this sequence:

1. Initialize credentials — mount.flexfs init creds contacts the admin server to validate the volume token and writes a local credentials file.
2. Start the mount — mount.flexfs start <name> <mount-point> reads the credentials file, connects to the admin server to fetch volume settings, establishes an RPC session with the metadata server, and mounts the FUSE filesystem.
3. Daemon mode (default) — The start command forks a background daemon process, waits for the mount to appear in the mount table, and exits. The daemon holds a file lock to prevent duplicate mounts on the same mount point.
4. Foreground mode — With --foreground (or -f), the process stays in the foreground and does not perform auto-update handoffs (--noRemount is implied). Under systemd (detected via the NOTIFY_SOCKET environment variable), the start command also stays in the foreground instead of forking a daemon and reports its readiness and main process ID to systemd, but auto-update handoffs remain enabled.
5. Auto-update — The daemon periodically checks the admin server for new versions. When an update is available, it downloads the new binary, yields the FUSE session to the new process, and exits. See Automatic Updates for details.
6. Shutdown — On SIGHUP, SIGTERM, SIGINT, or SIGQUIT, the mount client writes out pending data, unmounts the filesystem, finishes pending uploads, and exits. If the filesystem is in use (for example, a process has a file open or its working directory under the mount point), the unmount fails, the error is logged, and the mount keeps serving; send the signal again once the mount is no longer in use. A signal received during an auto-update handoff takes effect once the handoff ends. A second signal while the final uploads run, or 30 seconds in which they make no progress, cancels the remaining uploads and exits; blocks held in a write-back disk cache stay on local disk and are uploaded later (see Performance tuning), while other pending writes are lost.

Credential file format

Credentials are stored in TOML format. The default location is:

~/.flexfs/mount/creds/<volume-name>

A typical credentials file contains:

adminAddr = "admin.example.com:443"
token = "<volume-token>"

For volumes with end-to-end encryption enabled, the file also includes the volume secret (passphrase):

adminAddr = "admin.example.com:443"
secret = "<secret>"
token = "<volume-token>"

Field	Description
adminAddr	Address of the admin server (host:port)
token	Volume authentication token (UUID)
secret	Encryption passphrase for end-to-end encryption (Enterprise only)

The credentials file is created by mount.flexfs init creds with permissions 0600.

Initializing credentials

mount.flexfs init creds \
  --adminAddr admin.example.com:443 \
  --token <volume-token>

If --token is omitted, the command prompts interactively. The admin server is contacted to validate the token and retrieve the volume name. If the volume uses end-to-end encryption and --secret is omitted, you are prompted for the secret: to create one if none has been registered yet, or otherwise to enter the registered secret, which must match.

Flags for init creds:

See the mount.flexfs CLI reference for the full list of init creds flags, including types and defaults.

Volume token authentication

Every mount must present a valid volume token. The token is a UUID created via configure.flexfs (Enterprise) or pre-configured in the Community edition. The authentication flow is:

1. The mount client sends the volume token to the admin server.
2. The admin server validates the token, resolves the associated volume, and returns the volume settings (block size, compression, encryption, mount flags, proxy groups, metadata server address, and block store credentials).
3. The mount client uses the metadata server address and token to establish an RPC session.
4. All subsequent filesystem operations flow through the RPC session.

Volume tokens can be scoped to a specific mount path, restricting the mount to a subdirectory of the volume. See Volume Tokens for details.

Starting a mount

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

The first argument is the volume name (or alias). The second argument is the mount point directory, which must exist and (by default) be empty.

Key behaviors during startup:

• Stale mount detection: If the mount point appears in /proc/mounts but no daemon is running (stale mount after a crash), the client cleans it up and mounts again. This happens however the mount is started — directly, through mount, from /etc/fstab, or by systemd. If a process is still sitting in the dead mount, the client detaches it rather than give up, so no manual unmount is needed.
• Mount lock: A per-mount-point file lock prevents concurrent mount attempts.
• OOM protection: When running as root, the daemon adjusts its OOM killer score to avoid being killed under memory pressure.

Mounting without root

Any user can run mount.flexfs init creds and mount.flexfs start. The credentials file, log file, and disk cache default to that user’s ~/.flexfs/mount/ folder (/root/.flexfs/mount/ for root, as on hosts set up by the mount client installer script). A mount started by a user other than root differs from a root mount in these ways:

• FUSE helper: Unless the user has CAP_SYS_ADMIN, the mount is made through fusermount3 (or fusermount), which must be installed (see Prerequisites), and the user needs write access to the mount point.
• FUSE module: The mount client does not run modprobe fuse, so the FUSE kernel module must already be available.
• Access by other users: allow_other is enabled only if /etc/fuse.conf contains a user_allow_other line. Without it, only the mounting user can access the mount.
• SUID/SGID: A mount made through the FUSE helper always uses nosuid, so set-user-ID and set-group-ID bits have no effect.
• OOM protection: The OOM killer score is not adjusted.
• Squash flags: --rootSquash, --allSquash, --anonUID, and --anonGID are refused; squashing set on the volume or token still applies (see Mount Options).
• Auto-update: Updates are installed only if the user can write both the mount.flexfs binary and its folder (see Automatic Updates).
• fstab: mount.flexfs init fstab and deinit fstab require root, so a non-root mount is started with mount.flexfs start.