Enterprise: First Mount

After installing the Enterprise server and optionally configuring additional resources, you are ready to mount flexFS on client hosts. The admin server provides a self-contained installer script that downloads the mount client, initializes credentials, creates an fstab entry, and mounts the filesystem in a single command.

Prerequisites

On the client host:

• Linux (amd64 or arm64)
• Root access
• curl installed
• Network access to the admin server (default: port 443) and metadata server (default: port 8443)
• Network access to the object storage endpoint, and to the proxy server if one is configured (mounts reach object storage directly for some operations even when a proxy is configured)

The installer script installs FUSE3 automatically if neither fusermount3 nor fusermount is present.

One-Command Install

The Enterprise installer prints the mount command at the end of setup. It follows this pattern:

curl -fksSL https://<admin-addr>/deploy/install-mount.sh | sudo bash -s <mount-point> <volume-token>

For example, to mount at /mnt/flexfs using the volume token created during installation:

curl -fksSL https://10.0.1.50:443/deploy/install-mount.sh | sudo bash -s /mnt/flexfs <volume-token>

Note

The -k flag in curl allows connecting to the admin server’s self-signed TLS certificate. If you have installed a trusted certificate on the admin server, you can omit -k. If the admin server runs with --noSSL, use http:// instead of https://; the script then passes --noAdminSSL to init creds and adds noAdminSSL to the fstab mount options.

What the Script Does

The deploy script (/deploy/install-mount.sh) is served by the admin server and executes the following steps:

1. Validates arguments — requires both a mount point and a volume token

2. Checks for root — exits if not running as uid 0

3. Detects platform — determines linux/amd64 or linux/arm64 from uname -m

4. Installs FUSE if neither fusermount3 nor fusermount is found, using the system package manager (apt-get, dnf, or yum). If yum cannot find the fuse3 package, the script enables the EPEL repository, leaves it enabled, and retries.

5. Stops any existing mount at the specified mount point and removes the old fstab entry if present

6. Downloads mount.flexfs from the admin server’s deploy endpoint to /sbin/mount.flexfs and sets it executable. SELinux contexts are restored if applicable.

7. Verifies the binary by running mount.flexfs version

8. Initializes credentials by contacting the admin server:

   mount.flexfs init creds \
     --adminAddr <admin-addr> \
     --token <volume-token> \
     --force

   This checks the token with the admin server, which also supplies the volume’s name, and writes the admin server address and volume token to a local credential file at ~root/.flexfs/mount/creds/<volume-name>. For a volume with end-to-end encryption, it also prompts for the encryption secret and stores it in the same file. The volume’s configuration (metadata server address, block store details, proxy groups) is fetched from the admin server each time the volume mounts.

9. Creates an fstab entry and mounts the filesystem:

   mount.flexfs init fstab <volume-name> <mount-point> --now --force

   The --now flag tells init fstab to mount immediately after writing the fstab entry.

Manual Installation

If you prefer to run each step separately (for example, in an automated provisioning pipeline), run the individual commands below as root, as the script does (writing to /sbin and init fstab require it). To mount as another user instead, place the binary where that user can run it, then run init creds and mount.flexfs start as that user (see Mounting without root).

Download the mount client

curl -fksSL https://<admin-addr>/deploy/production/v1.9.x/linux/amd64/mount.flexfs \
  -o /sbin/mount.flexfs
chmod 755 /sbin/mount.flexfs

Initialize credentials

mount.flexfs init creds \
  --adminAddr <admin-addr> \
  --token <volume-token> \
  --force

Create fstab entry

mount.flexfs init fstab <volume-name> /mnt/flexfs --force

This writes a line to /etc/fstab so the volume mounts automatically on boot.

Mount

mount /mnt/flexfs

Or mount directly without fstab:

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

Verify the Mount

After mounting, verify with:

# Check the mount is active
mountpoint /mnt/flexfs

# List the filesystem
ls -la /mnt/flexfs

# Write a test file
echo "hello flexFS" > /mnt/flexfs/test.txt
cat /mnt/flexfs/test.txt

# Check disk usage
df -h /mnt/flexfs

Mounting on Multiple Hosts

A single volume token can be used to mount the same volume on as many hosts as needed. Simply run the deploy script on each host with the same token and mount point.

Tip

While sharing a single token across many hosts is common, consider creating separate tokens per host or group of hosts. If a shared token is revoked, all mounts using that token are disconnected. Separate tokens allow you to revoke access to individual hosts without affecting others.

Mounting Additional Volumes

To mount a different volume, run the deploy script on the client host with its volume token and a different mount point:

curl -fksSL https://10.0.1.50:443/deploy/install-mount.sh | sudo bash -s /mnt/vol02 <volume-token>

Multiple volumes can be mounted concurrently on the same host, each at a different mount point.

Auto-Updates

Once mounted, the mount client periodically checks the admin server for newer versions of mount.flexfs. When an update is available, it downloads the new binary and performs a live handoff of the FUSE session — no unmount or downtime required. See Auto-Update for details.

Troubleshooting

Symptom	Likely cause	Resolution
Error: this script must be run as root	Not running as root	Use sudo bash
Error: unsupported architecture	Not amd64 or arm64	FlexFS only supports 64-bit Linux
Error: unable to install FUSE or Error: unable to install fuse3	No supported package manager, or no repository provides fuse3	Install FUSE3 manually (see Prerequisites)
Error: mount.flexfs failed to execute	Binary incompatible with host	Verify platform matches (uname -m)
Error: invalid volume token: unauthorized	The admin server does not recognize the volume token	Verify the volume token
Error: failed to get volume settings: ... (after repeated retries)	Cannot reach the admin server	Check network access to the admin port
Error: the admin server refused the request, not the token (status N); check its access rules for this host	The admin server’s access rules block this host	Review the admin server’s access rules
Mount hangs or times out	Metadata server unreachable	Check network access to the metadata server port

Next Steps

• Mount Options — customize caching, performance, and security settings
• fstab Integration — details on the fstab line format and systemd mount directives
• Proxy Server Setup — add proxy groups for CDN-like caching