Setup and Configuration

Installation

The metadata server binary (meta.flexfs) is included in the flexFS installation. It is typically deployed via the admin server’s deploy endpoint or the manage.flexfs tool.

Initialize credentials

The metadata server requires credentials to authenticate with the admin server and (optionally) access block storage. Initialize them before starting:

meta.flexfs init creds \
  --adminAddr admin.example.com:443 \
  --token $TOKEN \
  --blockUser $USERNAME \
  --blockPass $PASSWORD

If --token is omitted, the command prompts interactively. This writes a TOML credentials file to the default location (~/.flexfs/meta/creds):

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

init creds flags:

Flag	Type	Default	Description
--adminAddr	string	(required)	Admin server address (host:port)
--blockPass	string	(empty)	Block storage password / secret key
--blockUser	string	(empty)	Block storage username / access key ID
--force	bool	false	Overwrite an existing credentials file
--token	string	(prompts)	Metadata server authentication token (UUID)

Note

The metadata server token is generated by the admin server during meta store creation (via configure.flexfs). It is distinct from volume tokens used by mount clients.

Tip

When running on a cloud instance with an attached IAM role, managed identity, or instance principal, the blockUser and blockPass fields can be omitted. The metadata server uses the platform’s native credential chain.

Create systemd service

sudo meta.flexfs init systemd --now

This creates and enables a systemd unit at /etc/systemd/system/flexfs-meta.service and optionally starts it immediately. The metadata service unit includes a 1-second startup delay (ExecStartPre=/bin/sleep 1) to allow dependent services to initialize.

To pass additional flags:

sudo meta.flexfs init systemd --now \
  --startFlags "--dbFolder /data/meta-db"

init systemd flags:

Flag	Type	Default	Description
--force	bool	false	Overwrite an existing systemd unit file
--now	bool	false	Start the service immediately after enabling
--startFlags	string	(empty)	Additional flags passed to meta.flexfs start

Start flags

The meta.flexfs start command accepts the following flags:

Visible flags

Flag	Type	Default	Description
--bindAddr	string	0.0.0.0:443	Address and port to bind the server
--dbFolder	string	~/.flexfs/meta/data	Path to the metadata database folder
--noSSL	bool	false	Disable TLS for the REST API and RPC
--sslCert	string	~/.flexfs/ssl/cert	Path to the TLS certificate file
--sslKey	string	~/.flexfs/ssl/key	Path to the TLS private key file
--sync	bool	false	Fsync every write for full crash durability
--verbose / -v	bool	false	Enable verbose logging

Hidden flags [internal]

Flag	Type	Default	Description
--adminAddr	string	(from creds)	Admin server address (overrides credentials file)
--blockPass	string	(from creds)	Block storage password (overrides credentials file)
--blockUser	string	(from creds)	Block storage username (overrides credentials file)
--dbMemCapacity	string	40%	Memory allocated to the database cache (e.g. 5%, 64M, 4G)
--fallback	string	(empty)	Fallback RPC protocol version for older mount clients (e.g. v1.4)
--noAdminSSL	bool	false	Disable TLS for connections to the admin server
--pprof	bool	false	Enable the Go pprof profiler
--pprofPort	int	6062	Pprof server port
--sizeBins	bool	false	Group volume size statistics into access-time bins
--token	string	(from creds)	Metadata server auth token (overrides credentials file)

Hidden subcommands [internal]

Subcommand	Description
migrate	Migrate the metadata database to a new format
verify	Verify the integrity of the metadata database

TLS certificates

By default, the metadata server auto-generates a self-signed TLS certificate if none exists at the configured paths. To use custom certificates:

meta.flexfs start \
  --sslCert /etc/ssl/meta.crt \
  --sslKey /etc/ssl/meta.key

Verifying the server

After starting, the metadata server logs its configuration:

   meta.flexfs | v1.9.0
--------------------------------------------------------------------------------
     adminAddr | admin.example.com:443
      bindAddr | 0.0.0.0:443
     credsFile | ~/.flexfs/meta/creds
      dbFolder | ~/.flexfs/meta/data
       sslCert | ~/.flexfs/ssl/cert
        sslKey | ~/.flexfs/ssl/key
--------------------------------------------------------------------------------
Binding to 0.0.0.0:443 (encrypted)