Mount Options

This page documents every flag accepted by mount.flexfs start. Flags marked [internal] are hidden from --help output and intended for advanced tuning or debugging. Flags marked [testing only] are also hidden, and exist solely for the test suite — do not set them on a production mount.

POSIX and access control

Flag	Type	Default	Description
--acl	bool	false	Enable extended ACL support (implies --xAttr)
--forceClientDAC	bool	false	[testing only] Force extended-ACL enforcement into the mount client
--noATime	bool	false	Do not update access times on file opens
--noExec	bool	false	Disallow execution of binaries
--nonEmpty	bool	false	Allow mounting over a non-empty directory
--noSUID	bool	false	Disable SUID / SGID special permissions
--ro	bool	false	Mount read-only (implies --noATime)
--rootSquash	bool	false	Map UID 0 / GID 0 to --rootSquashUID / --rootSquashGID (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	(none)	Explicit umask override in octal notation (e.g. 0002)

Note

--acl needs kernel POSIX ACL support (Linux 4.9+) to perform well. On current kernels it caches exactly like a mount without it. On older kernels, and whenever --rootSquash is set, the mount client checks every operation itself — correct, but with more metadata round trips. See Access Control.

| --xAttr | bool | false | Enable extended attribute support |

Note

Many access control flags (acl, noATime, noExec, noSUID, rootSquash, nonEmpty, xAttr) can also be set at the volume level via configure.flexfs. Volume-level settings are combined with mount-level flags — if either side enables a flag, it takes effect.

Caching

Flag	Type	Default	Description
--dirtyCapacity	uint32	auto	[internal] In-memory dirty block cache capacity in blocks. Default is memCapacity/4 (minimum 8).
--diskFolder	string	~/.flexfs/mount/cache/<pid>	On-disk block cache folder path
--diskMaxBlockSize	uint64	262144	Maximum processed block size in bytes that will be cached to disk. Blocks larger than this after processing bypass the disk cache. 0 means no limit.
--diskQuota	string	(empty)	Maximum disk usage for the block cache (e.g. 5%, 64M, 10G). Empty or 0 disables the disk cache.
--diskWriteback	bool	false	Enable disk cache writeback mode for latency mitigation
--memCapacity	string	auto	[internal] In-memory block cache capacity. Accepts a percentage of system RAM (e.g. 2%), a human-readable size (e.g. 4G, 512M), or a plain number of blocks (e.g. 2000). Default is 2% of system RAM divided by block size (minimum 32 blocks).
--poolCapacity	uint32	auto	[internal] Block buffer pool capacity in blocks. Default is prefetchActive + dirtyActive (minimum 8).

Tip

The default --diskFolder path is within the user’s home directory (~/.flexfs/mount/cache/<pid>). For better performance, consider pointing this to a path on a local SSD. The <pid> placeholder is replaced with the mount process ID.

Caution

A custom --diskFolder should include the <pid> placeholder (or otherwise be unique per mount instance). The cache folder is wiped and recreated on startup; if two mount processes (or a mount and its auto-update successor) are given the exact same fixed folder, they can race to wipe each other’s directory, silently disabling the on-disk cache (I/O transparently falls back to object storage). Keeping <pid> in the path guarantees a unique folder per instance.

Performance

Flag	Type	Default	Description
--asyncRead	bool	false	[internal] Enable FUSE async read support
--dirtyActive	uint32	auto	[internal] Maximum number of dirty blocks actively syncing. Default is half of dirtyCapacity (minimum 4).
--maxBops	uint32	auto	[internal] Maximum number of parallel block operations. Default is dirtyActive + prefetchActive.
--noMaxPages	bool	false	[internal] Limit FUSE max_pages to 32 instead of the kernel maximum
--noPrefetch	bool	false	[internal] Disable block prefetching entirely
--numReaders	uint32	auto	[internal] Number of FUSE reader goroutines. Default is 8 × CPU count.
--prefetchActive	uint32	auto	[internal] Maximum number of active block prefetches. Default is memCapacity/8.
--prefetchDepth	uint32	auto	[internal] Maximum number of queued block prefetches.

FUSE tuning

Flag	Type	Default	Description
--attrValid	uint64	28800	[internal] Seconds to cache file/directory attributes
--attrValidNsec	uint32	0	[internal] Nanosecond offset for --attrValid
--dirPageSize	uint32	5000	[internal] Directory stream page size
--dirTTL	uint32	10	[internal] Seconds to cache directory stream pages
--entryValid	uint64	1	[internal] Seconds the kernel caches directory entries
--entryValidNsec	uint32	0	[internal] Nanosecond offset for --entryValid
--longNames	bool	false	[internal] Allow names up to 1023 characters (default limit is 255)
--noOpenCoherence	bool	false	[testing only] Skip the open() cross-mount freshness check
--subType	string	flexfs	[internal] FUSE filesystem subtype (shown in mount listings)

Networking and proxy

Flag	Type	Default	Description
--noMetaSSL	bool	false	[internal] Disable TLS for metadata server connections
--noProxy	bool	false	[internal] Bypass proxy servers and connect directly to object storage
--noProxyReads	bool	false	[internal] Bypass proxy servers for block reads
--noProxySSL	bool	false	[internal] Disable TLS for proxy server connections
--noProxyWrites	bool	false	[internal] Bypass proxy servers for block writes
--proxyProbeTO	uint32	125	[internal] Per-proxy-group health check timeout (ms)
--sse	bool	false	[internal] Enable S3 server-side encryption (AES256)

Credentials and auth

Flag	Type	Default	Description
--adminAddr	string	(from creds)	[internal] Admin server address (overrides the credentials file)
--credsFile	string	~/.flexfs/mount/creds/<name>	Path to the credentials file. The <name> placeholder is replaced with the volume name.
--secret	string	(from creds)	[internal] Volume encryption secret (overrides the credentials file)
--token	string	(from creds)	[internal] Volume auth token (overrides the credentials file)

Update control

Flag	Type	Default	Description
--noRemount	bool	false	Disable automatic remount after an update (the mount will stop instead)
--noUpdate	bool	false	Disable the automatic update mechanism (implies --noRemount)
--staging	bool	false	Check the staging channel for updates instead of production
--testVersion	string	(none)	[testing only] Override build version for testing update handoff
--updateInterval	uint32	360	[testing only] Seconds between auto-update checks

Logging and diagnostics

Flag	Type	Default	Description
--blockRTT	bool	false	[internal] Log all block storage round-trip times
--foreground / -f	bool	false	Run in foreground mode instead of daemonizing (implies --noRemount)
--fuseRTT	bool	false	[internal] Log all FUSE round-trip times
--logFile	string	~/.flexfs/mount/logs/<name>-<pid>.log	Log file path in daemon mode. The <name> and <pid> placeholders are replaced at startup.
--memStats	bool	false	[internal] Log buffer pool and LRU cache statistics
--metaRTT	bool	false	[internal] Log all metadata server round-trip times
--metrics	bool	false	Enable the Prometheus metrics endpoint (see Metrics Reference)
--metricsPort	int	6073	Port for the metrics endpoint
--pprof	bool	false	[internal] Enable the Go pprof profiler
--pprofPort	int	6063	[internal] Pprof server port
--storeRTT	bool	false	[internal] Log all store subsystem round-trip times
--verbose / -v	bool	false	Enable verbose logging (implies all RTT and memStats logging)

Time-travel

Flag	Type	Default	Description
--atTime	string	(none)	Mount the filesystem at a specific point in time in RFC 3339 format (e.g. 2025-06-15T14:30:00Z). Implies --ro. See Time-Travel Mounting.

Passing options via fstab

All flags can be passed as fstab mount options by removing the -- prefix. Boolean flags are set by name alone. For example:

my-volume  /mnt/data  flexfs  _netdev,nofail,ro,acl,verbose  0 0

See fstab Integration for details.