meta.flexfs

meta.flexfs is the metadata server that stores inodes, directory entries, attributes, extended attributes, and ACLs for one or more flexFS volumes. Mount clients communicate with it over an RPC protocol, and utilities like analyze.flexfs and find.flexfs use its REST API.

Persistent Flags

These flags apply to every subcommand.

Flag	Type	Default	Description	Visibility
--dbFolder	string	~/.flexfs/meta/data	Database folder path	Public
--reportErrors	bool	false	Report errors and panics to Paradigm4	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
migrate	Migrate volume data from the legacy snapshot format to the current format	Internal
missing-objects	Report meta-tracked block keys absent from the block store	Internal
start	Start the metadata server	Public
verify	Verify database integrity	Internal
version	Print the build version	Public

deinit creds

meta.flexfs deinit creds [flags]

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

deinit systemd

sudo meta.flexfs deinit systemd

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

init creds

meta.flexfs init creds --adminAddr <admin-addr> [flags]

Initializes a credentials file for the metadata server. If --token is omitted, the command prompts for a metadata server token interactively.

Flag	Type	Default	Description	Visibility
--adminAddr	string	""	Admin server address (required)	Public
--blockPass	string	""	Block storage password	Public
--blockUser	string	""	Block storage username	Public
--credsFile	string	~/.flexfs/meta/creds	Credentials file path	Public
--force	bool	false	Overwrite existing credentials file	Public
--token	string	""	Metadata server auth token (will prompt if omitted)	Public

Credentials File

The credentials file is a TOML file with connection details populated during init creds:

adminAddr = "admin.example.com:443"
token = "<meta-token>"
blockUser = "<username>"
blockPass = "<password>"

init systemd

sudo meta.flexfs init systemd [flags]

Creates and enables a systemd service unit (flexfs-meta.service) for the metadata server. Requires root.

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

migrate

Caution

This subcommand is internal and should only be used under guidance from Paradigm4 support.

meta.flexfs migrate [flags]

Migrates volume data from the legacy snapshot format to the current database format.

Flag	Type	Default	Description	Visibility
--srcFolder	string	~/.flexfs/meta/data	Source data folder	Public

missing-objects

Caution

This subcommand is internal and should only be used under guidance from Paradigm4 support.

meta.flexfs missing-objects [volume-id] [flags]

For each block key tracked by meta (live and/or retired), HEADs the corresponding object in the block store and reports any that are missing. Runs offline against the metadata database, so the meta service must be stopped (the database lock); contacts the admin server to fetch per-volume block settings, so the admin server must be reachable. If a volume ID is provided, only that volume is scanned; otherwise all volumes are scanned.

Flag	Type	Default	Description	Visibility
--concurrency	int	16	Number of parallel HEAD requests. Matches the metadata server’s block-store concurrency ceiling; higher values queue on that limit.	Public
--credsFile	string	~/.flexfs/meta/creds	Credentials file path	Public
--live-only	bool	false	Only check live block keys	Public
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--retired-only	bool	false	Only check retired block keys	Public

start

meta.flexfs start [flags]

Starts the metadata server, binding the RPC and REST endpoints.

Flag	Type	Default	Description	Visibility
--accessFile	string	~/.flexfs/meta/access	API access file path — whitelists the source addresses allowed to reach each endpoint. Absent = all endpoints unrestricted	Public
--adminAddr	string	""	Admin server address (overrides credentials file)	Internal
--bindAddr	string	0.0.0.0:443	Address and port to bind	Public
--blockPass	string	""	Block storage password (overrides credentials file)	Internal
--blockUser	string	""	Block storage username (overrides credentials file)	Internal
--credsFile	string	~/.flexfs/meta/creds	Credentials file path	Public
--dbMemCapacity	string	50%	Database memory cache capacity (e.g. 5%, 64M)	Internal
--fallback	string	""	Fallback RPC version for old clients (e.g. v1.4)	Internal
--minDiskAvail	string	1G	Minimum free space on the database folder filesystem (e.g. 2%, 512M; 0 = disabled)	Public
--minRESTVersion	int	2	Lowest REST API version to serve. 1 also serves the deprecated version 1 endpoints, which require no credential, and the unversioned paths that belong to them. A version below this one is not registered, so its URLs answer 404.	Internal
--noAdminSSL	bool	false	Disable SSL for admin server connections	Internal
--noSSL	bool	false	Disable SSL for the REST API	Public
--pprof	bool	false	Enable pprof profiler	Internal
--pprofPort	int	6063	Pprof server port	Internal
--sslCert	string	~/.flexfs/ssl/cert	SSL certificate file path	Public
--sslKey	string	~/.flexfs/ssl/key	SSL private key file path	Public
--sync	bool	false	Fsync every metadata write	Public
--token	string	""	Metadata server auth token (overrides credentials file)	Internal
--verbose, -v	bool	false	Enable verbose logging	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.

• The file is re-read every two seconds, so a change takes effect within seconds without a restart. Deleting it lifts all restrictions.
• 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. Access control does not fail open on a bad edit.
• The WebSocket root (/) is reached only by a rule naming it explicitly, never by the file’s global list — a rule aimed at the maintenance endpoints must not disconnect every mounted client. Nothing else is exempt, /metrics included, so remember to whitelist the Prometheus host.
• Blocked requests are answered 403, logged with their source address whether or not --verbose is set, and counted in flexfs_meta_rest_ops_total{status="403"}.

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

Low disk space protection

The metadata database cannot be written safely on a filesystem that has run out of space, and shutting it down is itself a write: closing each volume persists its lock state and flushes buffered writes into the database folder. The server therefore guards the --dbFolder filesystem:

• On startup, it refuses to start if the available space is already below --minDiskAvail.
• While running, it re-checks every minute and shuts down gracefully — draining in-flight requests and closing the database cleanly — as soon as available space drops below --minDiskAvail. Both events are logged, naming the folder and the space available.

Watch flexfs_meta_db_folder_disk_available_bytes to catch this well before it happens; see Alerting. The default floor leaves room for compaction and for the flush on close; raise it if a deployment needs more headroom than that. Setting it to 0 disables both checks.

REST Endpoints

The metadata server exposes REST endpoints for utilities, monitoring, and maintenance. See the Metadata REST API reference for the full list of endpoints and their parameters.

verify

Caution

This subcommand is internal and should only be used under guidance from Paradigm4 support.

meta.flexfs verify [volume-id] [flags]

Verifies the integrity of the metadata database by comparing stored counters, dentries, and size bins against actual data. If a volume ID is provided, only that volume is verified; otherwise all volumes are checked.

Flag	Type	Default	Description	Visibility
--fix	bool	false	Repair the database in place: tombstone orphan dentries, fix per-inode block counts, and recompute stored counters and size bins from the actual data	Public