free.flexfs

free.flexfs is the server for flexFS Community edition. It manages a single volume and provides the same deploy endpoint as the Enterprise admin server for mount client installation and auto-updates. All flags are public.

The Community server differs from the Enterprise admin server in the following ways:

• Manages a single volume (no multi-volume support), named free, with a fixed 2 MiB block size and lz4 compression
• No configure.flexfs support
• No proxy group management
• No end-to-end encryption
• No dynamic CSI provisioning
• Fixed volume limits (5 TiB and 5 million files) instead of configurable quotas, and no volume tokens with mount-path scoping

All CLI utilities (analyze.flexfs, dedup.flexfs, find.flexfs, manage.flexfs) work with the Community edition, though the Community server sets no storage rates, so cost fields always report $0. Local on-disk writeback caching (--diskWriteback with --diskQuota) is available on the mount client to help mitigate object storage latency.

Persistent Flags

These flags apply to every subcommand.

Flag	Type	Default	Description	Visibility
--reportErrors	bool	false	Report errors and panics to Paradigm4. Governs what this server reports about itself only — to require reporting on mount clients, see --reportMountErrors below	Public

Subcommands

Subcommand	Description	Visibility
deinit creds	Remove the credentials file	Public
deinit systemd	Remove the systemd service unit	Public
init creds	Initialize the credentials file	Public
init systemd	Create and enable a systemd service unit	Public
license	Print license information	Public
start	Start the server	Public
version	Print the build version	Public

deinit creds

free.flexfs deinit creds [flags]

Removes the credentials file for the server. If the credentials file is referenced by a 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/free/creds	Credentials file path	Public
--force	bool	false	Remove creds even if referenced by systemd (removes references too)	Public

deinit systemd

sudo free.flexfs deinit systemd

Removes the systemd service unit (flexfs-free.service) for the server. Requires root.

init creds

free.flexfs init creds [flags]

Initializes a credentials file for the server with block storage and metadata configuration. init on its own does the same thing as init creds. The bucket name, prefix, --blockAddr endpoint ([scheme://]host[:port], with a path allowed only for the azure API) and OCI namespace are checked; an invalid value is refused and no file is written.

Flag	Type	Default	Description	Visibility
--api	string	""	Block storage API (s3, gcs, azure, oci; required)	Public
--blockAddr	string	""	Custom block storage endpoint	Public
--blockPass	string	""	Block storage password	Public
--blockUser	string	""	Block storage username	Public
--bucket	string	""	Block storage bucket (required)	Public
--credsFile	string	~/.flexfs/free/creds	Credentials file path	Public
--force	bool	false	Overwrite existing credentials file	Public
--metaAddr	string	""	Metadata server address (host:port) (required)	Public
--namespace	string	""	Object storage namespace; required for --api oci, rejected otherwise. Stored as its own namespace key	Public
--prefix	string	flexfs	Block storage key prefix	Public
--provider	string	""	Storage provider, such as aws, gcp, azure or oci, or a name of your choice for other S3-compatible storage (required)	Public
--region	string	""	Region (e.g. us-east-1; required). Lowercased for aws, gcp, azure and oci; kept as given for other providers	Public
--retention	string	7d	Retention duration (e.g. 7d, 168h, 30m) or seconds; -1 = forever	Public
--volumeFlags	string	admin	Flags carried by the volume token. The default lets it run reporting queries against the metadata server; set it to an empty string to withhold that	Public

The server reads these values from the credentials file each time it starts. It refuses to start if the file’s retention or volumeFlags value is invalid; a file with no retention uses 7 days, and one with no volumeFlags uses admin.

init systemd

sudo free.flexfs init systemd [flags]

Creates and enables a systemd service unit (flexfs-free.service) for the server. Requires root. Optional: the server can also be run directly with start by any user. The service runs as root, so it uses root’s /root/.flexfs defaults, credentials included, unless --startFlags names other paths.

Flag	Type	Default	Description	Visibility
--force	bool	false	Overwrite existing systemd unit file	Public
--now	bool	false	Start the service immediately after enabling	Public
--startFlags	string	""	Additional flags to pass to the start command	Public

start

free.flexfs start [flags]

Starts the Community server, binding the endpoint for the volume it serves. Any user can run it, and ~ in the defaults is that user’s home folder. A non-root user needs a --bindAddr port above 1023.

Flag	Type	Default	Description	Visibility
--accessFile	string	~/.flexfs/free/access	API access file path — whitelists the source addresses allowed to reach each endpoint. Absent = all endpoints unrestricted	Public
--bindAddr	string	0.0.0.0:443	Address and port to bind	Public
--credsFile	string	~/.flexfs/free/creds	Credentials file path	Public
--noInstaller	bool	false	Disable the /deploy/install-mount.sh installer endpoint	Public
--noSSL	bool	false	Serve over plain HTTP instead of HTTPS. Every client must then use its Internal --noAdminSSL flag: mount.flexfs (start and init creds), meta.flexfs (start and missing-objects), and analyze.flexfs, dedup.flexfs, and find.flexfs (queries and init creds). The CSI driver has no such flag and needs HTTPS.	Public
--reportMountErrors	bool	false	Require error reporting on the mount clients of the volume this server serves. The reporterrors flag is added to the volume settings the server hands out (see Accepted Volume and Token Flags). Independent of --reportErrors, which covers only this server’s own panics	Public
--sslCert	string	~/.flexfs/ssl/cert	SSL certificate file path. A self-signed certificate and key are created if neither exists.	Public
--sslKey	string	~/.flexfs/ssl/key	SSL private key file path	Public

API access control

--accessFile names a TOML file listing the IP addresses and CIDR blocks allowed to reach each endpoint. There is no file by default and nothing creates one, so every endpoint is unrestricted until you write it. It is re-read every two seconds, so a change takes effect within seconds without a restart; deleting it lifts all restrictions.

Most callers of this API are machines rather than people — mount clients fetch volume settings and rotate secret ids, and the metadata server posts stats and reads rate bins — so a rule written to fence off volume administration gates those endpoints too unless they are opened back up. Read the global rule gates: line the server logs whenever it loads a file with a global list. The /deploy/ tree is the exception: its URLs are baked into published install commands, so it is reached only by a rule naming it explicitly — and one [endpoint."/deploy/"] rule covers the whole tree, the installer script included.

A file that cannot be parsed, or that names an endpoint this server does not serve, is refused: the server will not start on one, and a running server keeps the rules already in force. Blocked requests are answered 403 with the usual {"code":403,"text":"forbidden"} body.

See API Access Control for the file format and the rule precedence.