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.

Persistent Flags

These flags apply to every subcommand.

Flag	Type	Default	Description	Visibility
--reportErrors	bool	false	Report errors and panics to Paradigm4. Off by default; a volume or token flag can mandate it for every mount of a volume — see Accepted Volume and Token Flags.	Public

What is sent: panic traces, auto-update failures, and abnormal exits. When a mount fails to come up at all — the daemon dies during startup, or does not mount within ten minutes — the child’s entire log file is sent as well, since the trace alone rarely explains a startup failure. Mount logs carry volume names, mount points and paths, so treat enabling this as a decision about what leaves the host.

Subcommands

Subcommand	Description	Visibility
deinit creds	Remove the credentials file	Public
deinit fstab	Remove the fstab entry	Public
init creds	Initialize the credentials file	Public
init fstab	Create an fstab entry and mount point	Public
license	Print license information	Public
start	Start the mount client	Public
version	Print the build version	Public

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	Visibility
--credsFile	string	~/.flexfs/mount/creds/<name>	Path to the credentials file. The <name> placeholder is replaced with the volume name.	Public
--force	bool	false	Remove creds even if referenced by fstab/systemd (removes references too)	Public

deinit fstab

sudo mount.flexfs deinit fstab <mount-point>

Removes flexFS fstab entries for the given mount point from /etc/fstab. Requires root.

init creds

mount.flexfs init creds --adminAddr <admin-addr> [--token <uuid>]

Initializes a credentials file for a volume. If --token is omitted, the command prompts for a volume token interactively. init on its own does the same thing as init creds.

The reporting utilities (analyze.flexfs, dedup.flexfs, find.flexfs) fall back to this file when the user running them has no credentials of their own, so a user who has run this command needs no further setup to query the volume.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address (required)	Public
--credsFile	string	~/.flexfs/mount/creds/<name>	Path to the credentials file. The <name> placeholder is replaced with the volume name.	Public
--force	bool	false	Overwrite existing credentials file	Public
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--printName	bool	false	Print the volume name to stdout after initialization	Public
--secret	string	""	Volume encryption secret (will prompt if omitted and needed)	Public
--token	string	""	Volume auth token (will prompt if omitted)	Public

init fstab

sudo mount.flexfs init fstab <name> <mount-point> [flags]

Creates an /etc/fstab entry and the mount point directory for the volume. Requires root.

Flag	Type	Default	Description	Visibility
--credsFile	string	~/.flexfs/mount/creds/<name>	Path to the credentials file. The <name> placeholder is replaced with the volume name.	Public
--force	bool	false	Replace an existing flexFS fstab entry for this mount point	Public
--mountOptions	string	""	Additional mount options to include in the fstab entry	Public
--now	bool	false	Mount the volume immediately after creating the fstab entry	Public

start

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. Under systemd (detected via the NOTIFY_SOCKET environment variable), it stays in the foreground without forking and logs to standard output. Use --foreground to run in the foreground.

Any user can run start. See Mounting without root for how a mount started by a user other than root differs.

Flag	Type	Default	Description	Visibility
--acl	bool	false	Enable extended ACL support (implies --xattr)	Public
--adminAddr	string	""	Admin server address (overrides credentials file)	Internal
--allSquash	bool	false	Map all uids/gids to the anonymous uid/gid (implies --rootSquash). Root only.	Public
--anonGID	uint32	65534	GID squashed callers are mapped to. Root only.	Public
--anonUID	uint32	65534	UID squashed callers are mapped to. Root only.	Public
--appendGrantHoldFactor	float64	4	How long a mount keeps an append turn it has just received from another mount, as a multiple of its recent hand-over time (capped by --appendGrantMaxHold). Higher values raise append throughput under contention at the cost of longer waits for the other mount. Values below 1, including 0, act as 1: shorter holds make mounts spend more time handing the turn over than appending, which can slow concurrent appends to a small fraction of their normal rate.	Internal
--appendGrantMaxHold	string	500ms	Upper bound on the hold derived from --appendGrantHoldFactor, given as a duration (500ms) or whole milliseconds (500). At most 3s. Cannot be 0 when --appendGrantMinHold is 0.	Internal
--appendGrantMinHold	string	100ms	Minimum time a mount keeps an append turn it has just received from another mount, given as a duration (100ms) or whole milliseconds (100). At most 1s. 0 removes the minimum; the hold from --appendGrantHoldFactor still applies, and the mount still keeps a new turn until its first append lands, for up to one second. Each hand-over uploads the file’s last block and commits it, so shorter holds increase object-store PUT requests for files that several mounts append to concurrently. Lock requests and truncations from other mounts are not held back by this minimum. Applies only when the metadata server supports prompt hand-over.	Internal
--atTime	string	""	Mount at a point in time (RFC3339, implies --ro)	Public
--attrValid	string	1h	How long to cache file attributes, given as a duration (30s, 1h) or whole seconds (3600). Must resolve to a whole number of seconds; use --attrValidNsec for sub-second precision.	Internal
--attrValidNsec	uint32	0	Nanosecond offset added to --attrValid (0 to 999999999)	Internal
--blockRTT	bool	false	Log block storage round-trip times	Internal
--credsFile	string	~/.flexfs/mount/creds/<name>	Path to the credentials file. The <name> placeholder is replaced with the volume name.	Public
--diagHoles	bool	false	Log a diagnostic line whenever a read returns a zero-filled block because the file has no data stored for it. Costs an extra metadata round trip per zero-filled block and is not rate limited; leave it off outside an investigation.	Internal
--dirPageSize	uint32	5000	Directory stream page size	Internal
--dirtyActive	uint32	0 = auto	Maximum number of active dirty block syncs	Internal
--dirtyCapacity	uint32	0 = auto	In-memory dirty block cache capacity (blocks)	Internal
--dirValid	string	5s	How long a fetched directory page may be reused by a rewind or repeat listing while the directory is unchanged, given as a duration (5s, 1m) or whole seconds (5). Must resolve to a whole number of seconds; 0 refetches on every rewind. A listing in progress always consumes the page it has already fetched.	Internal
--diskFolder	string	~/.flexfs/mount/cache/<name>/<pid>	On-disk block cache folder path. The <name> and <pid> placeholders are replaced at startup.	Public
--diskMaxBlockSize	string	256K	Maximum processed block size that will be cached to disk. Blocks larger than this after processing bypass the disk cache. Given as a size (256K, 1M) or bytes (262144). 0 means no limit.	Public
--diskQuota	string	"" = disabled	Maximum disk usage for the block cache (e.g. 5%, 64M, 10G; empty or 0 = disabled). An unrecognized value is refused. A quota below 32 MiB disables the cache. The mount logs a warning when --diskFolder, --diskMaxBlockSize, --diskSync or --diskWriteback is given without a quota.	Public
--diskSync	bool	false	Fsync each block the writeback cache takes to local disk before the write is acknowledged, so that fsync() and close() guarantee the block survives a power loss. Adds latency to every such block write. The mount does not start if the file system holding the cache folder cannot flush it. Has no effect unless --diskWriteback is set; the mount then logs a warning.	Public
--diskWriteback	bool	false	Enable disk cache writeback mode. Has no effect unless --diskQuota enables the disk cache.	Public
--entryValid	string	1s	How long the kernel caches directory entries, given as a duration (1s, 30s) or whole seconds (1). Must resolve to a whole number of seconds; use --entryValidNsec for sub-second precision. 0 disables name caching. Negative lookups are governed separately by --negEntryValid.	Internal
--entryValidNsec	uint32	0	Nanosecond offset added to --entryValid (0 to 999999999)	Internal
--forceClientDAC	bool	false	Force extended-ACL enforcement into the mount client (implies --acl)	Internal
--foreground, -f	bool	false	Run in foreground mode (implies --noRemount)	Public
--fuseRTT	bool	false	Log FUSE round-trip times	Internal
--invalQueueSlots	uint32	0 = auto	Total kernel invalidation queue slots across all lanes	Internal
--logFile	string	~/.flexfs/mount/logs/<name>-<pid>.log	Log file path in daemon mode. The <name> and <pid> placeholders are replaced at startup.	Public
--maxBops	uint32	0 = auto	Maximum number of parallel block operations	Internal
--memCapacity	string	"" = auto	In-memory block cache capacity in blocks or bytes (e.g. 2000, 64M, 2%)	Internal
--memLimit	string	"" = auto	Soft memory limit for the mount process (e.g. 40%, 512M; 0 = disabled). A GOMEMLIMIT environment variable is honored when set. The automatic limit is half of RAM for each mount, regardless of other mounts on the host	Internal
--memStats	bool	false	Log buffer pool and LRU cache stats	Internal
--metaRTT	bool	false	Log metadata store round-trip times	Internal
--metrics	bool	false	Enable the Prometheus metrics endpoint (see Metrics Reference)	Public
--metricsPort	int	6075	Metrics server port	Public
--negEntryValid	string	1s	How long the kernel caches negative lookups (names found not to exist), given as a duration (1s, 30s) or whole seconds (1). Must resolve to a whole number of seconds; use --negEntryValidNsec for sub-second precision. 0 disables negative caching.	Internal
--negEntryValidNsec	uint32	0	Nanosecond offset added to --negEntryValid (0 to 999999999)	Internal
--noAdminSSL	bool	false	Disable SSL for admin server connections, auto-update downloads included	Internal
--noAppendBarrier	bool	false	Skip the cache synchronization each append performs for same-mount readers (readers may transiently see NUL bytes inside the file)	Internal
--noAppendDirectReads	bool	false	Let reads of actively-appended files use normal OS caching instead of always-fresh reads (racing readers may transiently see NUL bytes)	Internal
--noAppendGrant	bool	false	Disable serialized append grants (peer reads may observe zeros for in-flight appends)	Internal
--noAtime	bool	false	Mount with noatime option	Public
--noCreateConflictDAC	bool	false	Skip permission checks when a create finds an existing file	Internal
--noExec	bool	false	Mount with noexec option	Public
--noLockCoherence	bool	false	Skip the cache barriers a cross-mount lock carries (peers may lose updates made under a lock)	Internal
--noMaxPages	bool	false	Limit FUSE max_pages to 32	Internal
--noMetaSSL	bool	false	Disable SSL for metadata server connections	Internal
--nonEmpty	bool	false	Allow mounting over a non-empty directory	Public
--noOpenCoherence	bool	false	Skip the open() cross-mount freshness check	Internal
--noPrefetch	bool	false	Disable block prefetching	Internal
--noProxy	bool	false	Disable block proxying	Internal
--noProxyReads	bool	false	Disable proxy reads	Internal
--noProxySSL	bool	false	Disable SSL for proxy server connections	Internal
--noProxyWrites	bool	false	Disable proxy writes	Internal
--noRemount	bool	false	Disable remount after auto-update	Public
--noSUID	bool	false	Mount with nosuid option	Public
--noUpdate	bool	false	Disable auto-update mechanism (implies --noRemount)	Public
--numReaders	uint32	0 = auto	Number of FUSE readers	Internal
--poolCapacity	uint32	0 = auto	Block buffer pool capacity (blocks)	Internal
--pprof	bool	false	Enable pprof profiler	Internal
--pprofPort	int	6065	Pprof server port	Internal
--prefetchActive	uint32	0 = auto	Maximum number of active prefetches	Internal
--prefetchDepth	uint32	0 = auto	Maximum number of queued prefetches	Internal
--proxyProbeTO	string	125ms	Health check timeout for each proxy server, given as a duration (125ms, 1s) or whole milliseconds (125).	Internal
--readAhead	string	"" = auto	Kernel readahead window (e.g. 4M)	Internal
--ro	bool	false	Mount read-only (implies --noAtime)	Public
--rootSquash	bool	false	Map uid/gid 0 to the anonymous uid/gid (implies --acl). Root only.	Public
--secret	string	""	Volume encryption secret (overrides credentials file)	Internal
--sse	bool	false	Request S3 server-side encryption (AES256)	Public
--staging	bool	false	Auto-update from staged builds	Public
--statFsValid	string	3s	How long to serve statfs answers from cache, given as a duration (3s, 1m) or whole seconds (3). Must resolve to a whole number of seconds. 0 = disabled.	Internal
--storeRTT	bool	false	Log store subsystem round-trip times	Internal
--subType	string	flexfs	Ignored; accepted for compatibility. Mounts always use the fuse.flexfs type.	Internal
--testVersion	string	""	Override build version to exercise auto-update handoff	Internal
--token	string	""	Volume auth token (overrides credentials file)	Internal
--umask	string	""	Umask override (octal, with or without a leading 0 — 22 and 0022 mean the same thing; max 0777)	Public
--updateInterval	string	6m	Auto-update check interval, given as a duration (6m, 1h) or whole seconds (360). Must resolve to a whole number of seconds, at least 1s. Use --noUpdate to disable auto-update.	Internal
--verbose, -v	bool	false	Enable verbose logging	Public
--xattr	bool	false	Enable extended attribute support	Public

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"
secret = "<secret>"
token = "<volume-token>"