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. This is also the behavior when running under systemd (detected via the NOTIFY_SOCKET environment variable).
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 — Sending SIGTERM, SIGINT, or SIGQUIT gracefully unmounts the filesystem and exits.

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 = "$TOKEN"

For volumes with end-to-end encryption enabled, the file also includes the derived secret:

adminAddr = "admin.example.com:443"
secret = "$SECRET"
token = "$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 $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 no secret has been registered yet, you will be prompted to create one.

Flags for init creds:

Flag	Type	Default	Description
--adminAddr	string	(required)	Admin server address
--token	string	(prompts)	Volume authentication token
--secret	string	(prompts if needed)	Encryption passphrase
--credsFile	string	~/.flexfs/mount/creds/<name>	Output credentials file path
--force	bool	false	Overwrite an existing credentials file

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 my-volume /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 automatically runs fusermount -u to clean it up.
• 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.
• Non-root operation: flexFS works without root, but with reduced functionality — allow_other requires user_allow_other in /etc/fuse.conf, and SUID/SGID permissions cannot be enforced.