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 proxy server (if configured) or directly to the object storage endpoint

The installer script will automatically install FUSE3 if it is not already 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> $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 $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.

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)

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 /usr/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 <server-addr> \
     --token $TOKEN \
     --printName --force

   This fetches the volume configuration (metadata server address, block store details, proxy groups) from the admin server and writes a local credential file at ~root/.flexfs/mount/<volume-name>/creds.

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), the individual commands are:

Download the mount client

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

Initialize credentials

mount.flexfs init creds \
  --adminAddr <admin-addr> \
  --token $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 $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 seamless 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	No supported package manager	Install FUSE3 manually
Error: mount.flexfs failed to execute	Binary incompatible with host	Verify platform matches (uname -m)
Error: failed to initialize credentials	Cannot reach admin server or invalid token	Check network access to admin port and verify the volume token
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