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.

Subcommands

Subcommand	Description
deinit creds	Remove the credentials file
deinit systemd	Remove the systemd service unit
init creds	Initialize the credentials file
init systemd	Create and enable a systemd service unit
license	Print license information
migrate	Run database migrations
missing-objects	Report meta-tracked block keys absent from the block store
start	Start the metadata server
verify	Verify database integrity
version	Print the build version

Caution

The verify, migrate, and missing-objects subcommands are internal and should only be used under guidance from Paradigm4 support.

Usage

meta.flexfs start [flags]

Persistent Flags

These flags apply to all subcommands:

Flag	Type	Default	Description
--credsFile	string	~/.flexfs/meta/creds	Credentials file path
--dbFolder	string	~/.flexfs/meta/data	Database folder path

Start Flags

Flag	Type	Default	Description	Visibility
--adminAddr	string		Admin server address (overrides creds file)	Internal
--bindAddr	string	0.0.0.0:443	Address and port to bind	Public
--blockPass	string		Block storage password (overrides creds file)	Internal
--blockUser	string		Block storage username (overrides creds file)	Internal
--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 available space required on the database folder filesystem (e.g. 2%, 512M; 0 disables)	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	6062	Pprof server port	Internal
--sizeBins	bool	false	Deprecated — size bins are now always enabled	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 creds file)	Internal
--verbose, -v	bool	false	Enable verbose logging	Public

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 memtables 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.

Init Creds

meta.flexfs init creds [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
--adminAddr	string	""	Admin server address
--blockPass	string	""	Block storage password
--blockUser	string	""	Block storage username
--force	bool	false	Overwrite existing creds file
--token	string	""	Metadata server auth token (will prompt if omitted)

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
--force	bool	false	Overwrite existing systemd unit file
--now	bool	false	Start the service immediately after enabling
--startFlags	string	""	Additional flags to pass to the start command

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
--force	bool	false	Remove creds even if referenced by systemd (removes references too)

Deinit Systemd

sudo meta.flexfs deinit systemd

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

Verify (Internal)

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
--fix	bool	false	Fix mismatched counts by recomputing from actual data

Migrate (Internal)

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
--srcFolder	string	~/.flexfs/meta/data	Source data folder

Missing Objects (Internal)

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 Pebble database, so the meta service must be stopped (Pebble 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
--concurrency	int	32	Number of parallel HEAD requests
--live-only	bool	false	Only check live block keys
--retired-only	bool	false	Only check retired block keys
--noAdminSSL	bool	false	Disable SSL for admin server connections

Credentials File

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

adminAddr = "admin.example.com:443"
token = "$TOKEN"
blockUser = "$USERNAME"
blockPass = "$PASSWORD"

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.