mount.flexfs
mount.flexfs is the FUSE-based mount client that presents a flexFS volume as a local POSIX filesystem. It connects to a metadata server for inode/dentry operations and to object storage (directly or through a proxy group) for block data.
Subcommands
Section titled “Subcommands”| Subcommand | Description |
|---|---|
| deinit creds | Remove the credentials file |
| deinit fstab | Remove the fstab entry |
| init creds | Initialize the credentials file |
| init fstab | Create an fstab entry and mount point |
| license | Print license information |
| start | Start the mount client |
| version | Print the build version |
mount.flexfs start [flags] <name> <mount-point>The start subcommand connects to the admin server, retrieves volume settings, and mounts the filesystem at the specified mount point. In the default daemon mode, the process forks into the background and writes logs to a file. Use --foreground to run in the foreground.
Start Flags
Section titled “Start Flags”Filesystem Options
Section titled “Filesystem Options”| Flag | Type | Default | Description |
|---|---|---|---|
| --acl | bool | false | Enable extended ACL support (implies --xAttr) |
| --atTime | string | | Mount filesystem at a specific point in time (RFC3339 format, implies --ro) |
| --noATime | bool | false | Mount with noatime option |
| --noExec | bool | false | Mount with noexec option |
| --noGroupCache | bool | false | Disable extended ACL group caching |
| --nonEmpty | bool | false | Allow mounting over a non-empty directory |
| --noSUID | bool | false | Mount with nosuid option |
| --ro | bool | false | Mount read-only (implies --noATime) |
| --rootSquash | bool | false | Map uid=0/gid=0 to the squash uid/gid (implies --acl) |
| --rootSquashGID | uint32 | 65534 | GID to map root to when --rootSquash is set |
| --rootSquashUID | uint32 | 65534 | UID to map root to when --rootSquash is set |
| --umask | string | | Explicit umask override in octal notation (e.g. 0002) |
| --xAttr | bool | false | Enable extended attribute support |
Cache and Performance
Section titled “Cache and Performance”| Flag | Type | Default | Description |
|---|---|---|---|
| --diskFolder | string | ~/.flexfs/mount/cache/<pid> | On-disk block cache folder path |
| --diskMaxBlockSize | uint64 | 262144 | Max processed block size to cache on disk (bytes, 0 = no limit) |
| --diskQuota | string | | Max disk usage for cache (e.g. 5%, 64M) |
| --diskWriteback | bool | false | Enable disk cache writeback mode |
Logging and Diagnostics
Section titled “Logging and Diagnostics”| Flag | Type | Default | Description |
|---|---|---|---|
| --foreground, -f | bool | false | Run in foreground mode (implies --noRemount) |
| --logFile | string | ~/.flexfs/mount/logs/<name>-<pid>.log | Log file path (daemon mode only) |
| --verbose, -v | bool | false | Enable verbose logging |
Update Control
Section titled “Update Control”| Flag | Type | Default | Description |
|---|---|---|---|
| --noRemount | bool | false | Disable remount after auto-update |
| --noUpdate | bool | false | Disable auto-update mechanism (implies --noRemount) |
| --staging | bool | false | Auto-update from staged builds |
Credentials
Section titled “Credentials”| Flag | Type | Default | Description |
|---|---|---|---|
| --credsFile | string | ~/.flexfs/mount/creds/<name> | Credentials file path |
Internal Flags
Section titled “Internal Flags”| Flag | Type | Default | Description |
|---|---|---|---|
| --adminAddr | string | | Admin server address (overrides creds file) |
| --asyncRead | bool | false | Run FUSE with async read support |
| --attrValid | uint64 | 28800 | Seconds to cache file attributes |
| --attrValidNsec | uint32 | 0 | Nanosecond offset for --attrValid |
| --blockRTT | bool | false | Log block storage round-trip times |
| --dirPageSize | uint32 | 5000 | Directory stream page size |
| --dirTTL | uint32 | 10 | Seconds to cache directory stream pages |
| --dirtyActive | uint32 | 0 | Maximum number of active dirty block syncs |
| --dirtyCapacity | uint32 | 0 | In-memory dirty block cache capacity (blocks) |
| --entryValid | uint64 | 1 | Seconds to cache directory entries |
| --entryValidNsec | uint32 | 0 | Nanosecond offset for --entryValid |
| --fuseRTT | bool | false | Log FUSE round-trip times |
| --longNames | bool | false | Allow names up to 1023 characters |
| --maxBops | uint32 | 0 | Maximum number of parallel block operations |
| --memCapacity | string | (empty) | In-memory block cache capacity (e.g. 2%, 4G, 2000) |
| --memStats | bool | false | Log buffer pool and LRU cache stats |
| --metaRTT | bool | false | Log metadata store round-trip times |
| --noMaxPages | bool | false | Limit FUSE max_pages to 32 |
| --noMetaSSL | bool | false | Disable SSL for metadata server connections |
| --noPrefetch | bool | false | Disable block prefetching |
| --noProxy | bool | false | Disable block proxying |
| --noProxyReads | bool | false | Disable proxy reads |
| --noProxySSL | bool | false | Disable SSL for proxy server connections |
| --noProxyWrites | bool | false | Disable proxy writes |
| --numReaders | uint32 | 0 | Number of FUSE reader goroutines |
| --poolCapacity | uint32 | 0 | Block buffer pool capacity (blocks) |
| --pprof | bool | false | Enable pprof profiler |
| --pprofPort | int | 6063 | Pprof server port |
| --prefetchActive | uint32 | 0 | Maximum number of active prefetches |
| --prefetchDepth | uint32 | 0 | Maximum number of queued prefetches |
| --secret | string | | Volume encryption secret (overrides creds file) |
| --sse | bool | false | Enable S3 server-side encryption (AES256) |
| --storeRTT | bool | false | Log store subsystem round-trip times |
| --subType | string | flexfs | FUSE filesystem sub type |
| --testVersion | string | | Override build version for testing auto-update handoff |
| --token | string | | Volume auth token (overrides creds file) |
| --updateInterval | uint32 | 360 | Auto-update check interval in seconds |
Init Creds
Section titled “Init Creds”mount.flexfs init creds --adminAddr <addr> [--token <uuid>]Initializes a credentials file for a volume. If --token is omitted, the command prompts for a volume token interactively.
| Flag | Type | Default | Description |
|---|---|---|---|
| --adminAddr | string | | Admin server address (required) |
| --credsFile | string | ~/.flexfs/mount/creds/<name> | Credentials file path |
| --force | bool | false | Overwrite existing credentials file |
| --printName | bool | false | Print the volume name to stdout after initialization |
| --secret | string | | Volume encryption secret (will prompt if omitted and needed) |
| --token | string | | Volume auth token (will prompt if omitted) |
Init Fstab
Section titled “Init Fstab”mount.flexfs init fstab <name> <mount-point> [flags]Creates an /etc/fstab entry and the mount point directory for the volume.
| Flag | Type | Default | Description |
|------|------|---------|-------------|
| --credsFile | string | ~/.flexfs/mount/creds/<name> | Credentials file path |
| --force | bool | false | Overwrite an existing fstab entry for this volume |
| --mountOptions | string | "" | Additional mount options to include in the fstab entry |
| --now | bool | false | Mount the volume immediately after creating the fstab entry |
Deinit Creds
Section titled “Deinit Creds”mount.flexfs deinit creds <name>Removes the credentials file for a volume. If the credentials file is referenced by an fstab entry or systemd unit, the command refuses unless --force is passed, in which case it removes the references too.
| Flag | Type | Default | Description |
|---|---|---|---|
| --credsFile | string | ~/.flexfs/mount/creds/<name> | Credentials file path |
| --force | bool | false | Remove creds even if referenced by fstab/systemd (removes references too) |
Deinit Fstab
Section titled “Deinit Fstab”sudo mount.flexfs deinit fstab <mount-point>Removes flexFS fstab entries for the given mount point from /etc/fstab. Requires root.
Credentials File
Section titled “Credentials File”The credentials file is a TOML file stored at the path specified by --credsFile. It contains the admin server address, volume token, and optionally an encryption secret:
adminAddr = "admin.example.com:443"token = "$TOKEN"secret = "$SECRET"