Setup and Configuration

Installation

The metadata server binary (meta.flexfs) is installed to /sbin by the Enterprise and Community server installers. To install it on another host, or to upgrade it, use manage.flexfs (for example, sudo manage.flexfs install meta). See manage.flexfs.

Initialize credentials

The metadata server requires credentials to authenticate with the admin server and (optionally) access block storage. Initialize them as the user that runs the metadata server, before starting it:

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 ~/.flexfs/meta/creds in that user’s home folder (/root/.flexfs/meta/creds for root):

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

To keep it elsewhere, pass the same --credsFile to both init creds and start.

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

blockUser and blockPass apply only to volumes whose block store has no password of its own, and only when blockPass is set. When they are omitted, the metadata server obtains credentials from its own cloud identity and passes them to mount clients: the instance role (AWS), managed identity (Azure), application default credentials (Google Cloud), or instance principal (OCI). On AWS and OCI, when no instance identity is available, it falls back to local credentials: the AWS SDK default chain (environment variables, shared credentials and config files, web identity, or container credentials), or the OCI configuration file (~/.oci/config) of the user it runs as. Grant the storage permissions to that identity. On Azure only a managed identity works for this: service principal environment variables or az login on the metadata server host do not give mount clients access.

Run the metadata server

Run meta.flexfs start as any user. A non-root user needs a --bindAddr port above 1023, since the default is port 443:

meta.flexfs start --bindAddr 0.0.0.0:8443

Optional: systemd service

To run the metadata server as a root service that starts at boot, create a systemd unit:

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 service runs as root, so it reads /root/.flexfs/meta/creds unless --startFlags names another --credsFile; create the credentials with sudo meta.flexfs init creds. 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"

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

Start flags

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

Hidden subcommands [internal]

See meta.flexfs subcommands for the internal migrate, missing-objects, and verify subcommands.

Restricting API access

--accessFile names a TOML file of IP addresses and CIDR blocks allowed to reach each endpoint. It defaults to ~/.flexfs/meta/access. Nothing creates that file, and while it is absent every endpoint is unrestricted; the file is re-read every couple of seconds, so access can be tightened or widened without a restart.

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

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. This example is a server run as root with default flags and static credentials:

--------------------------------------------------------------------------------
            meta.flexfs | v1.9.1 linux/amd64 (2026-09-01 12:00)
--------------------------------------------------------------------------------
             accessFile | /root/.flexfs/meta/access
              adminAddr | admin.example.com:443
               bindAddr | 0.0.0.0:443
              blockPass | <provided>
              blockUser | <username>
              credsFile | /root/.flexfs/meta/creds
               dbFolder | /root/.flexfs/meta/data
          dbMemCapacity | 50% (32.00 GiB)
           minDiskAvail | 1G (1.00 GiB)
         minRESTVersion | 2
       requestRetention | 6h
                sslCert | /root/.flexfs/ssl/cert
                 sslKey | /root/.flexfs/ssl/key
--------------------------------------------------------------------------------
No access file at "/root/.flexfs/meta/access" - all endpoints unrestricted
Binding to 0.0.0.0:443 (encrypted)