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.

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	Overwrite an existing fstab entry for this volume	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. Use --foreground to run in the foreground.

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)	Public
--anonGID	uint32	65534	GID squashed callers are mapped to	Public
--anonUID	uint32	65534	UID squashed callers are mapped to	Public
--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 for --attrValid	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 to cache directory stream pages, given as a duration (5s, 1m) or whole seconds (5). Must resolve to a whole number of seconds.	Internal
--diskFolder	string	~/.flexfs/mount/cache/<pid>	On-disk block cache folder path	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)	Public
--diskWriteback	bool	false	Enable disk cache writeback mode	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.	Internal
--entryValidNsec	uint32	0	Nanosecond offset for --entryValid	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	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	6074	Metrics server port	Public
--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	6064	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	Per-proxy-group health check timeout, 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)	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	FUSE filesystem sub 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.	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"
token = "<volume-token>"
secret = "<secret>"