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)