Skip to content
flexFS

Setup and Configuration

Installation

Section titled “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

Section titled “Initialize credentials”

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

Terminal window
meta.flexfs init creds \
  --adminAddr admin.example.com:443 \
  --token <meta-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 = "<meta-token>"

See meta.flexfs init creds for the full list of flags and their defaults.

Create systemd service

Section titled “Create systemd service”
Terminal window
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:

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

See meta.flexfs init systemd for the full list of flags and their defaults.

Start flags

Section titled “Start flags”

See meta.flexfs start for the full list of flags and their defaults.

Hidden subcommands [internal]

Section titled “Hidden subcommands [internal]”

See meta.flexfs subcommands for the internal migrate and verify subcommands.

Restricting API access

Section titled “Restricting API access”

--accessFile names a TOML file of IP addresses and CIDR blocks allowed to reach each endpoint. There is no file by default, so every endpoint is unrestricted; the file is re-read every couple of seconds, so access can be tightened or widened without a restart.

~/.flexfs/meta/access
allow = ["10.0.0.0/8", "127.0.0.1", "::1"]


[endpoint."DELETE /locks"]
allow = ["10.1.2.3"]

The WebSocket root (/), which is how mount clients reach this server, is left alone by the global list — only a rule naming it explicitly gates it. Everything else is covered, /metrics included, so whitelist the host that scrapes it. See API Access Control.

TLS certificates

Section titled “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:

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

Verifying the server

Section titled “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)