Admin Server (Enterprise)

admin.flexfs is the central management server for flexFS Enterprise. It stores volume definitions, accounts, block stores, metadata stores, proxy groups, and volume tokens in its database. Mount clients connect to it for configuration and binary updates, metadata servers connect to it for volume settings and to report usage, and configure.flexfs uses its REST API to manage resources.

Subcommands

Subcommand	Description
`deinit creds`	Remove the credentials file
`deinit systemd`	Remove the systemd service unit
`import free`	Import the volume of a Community installation (internal; see `import free`)
`init creds`	Initialize the credentials file
`init systemd`	Create and enable a systemd service unit
`license`	Print license information
`start`	Start the admin server
`version`	Print the build version

Starting the Server

admin.flexfs start

The start subcommand launches the admin server and begins listening for API requests. All configuration is provided through flags or the credentials file. Any user can run it; a non-root user needs a --bindAddr port above 1023, since the default is port 443.

Start Flags

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

On startup, the server reads the credentials file (TOML format), opens its database, generates a self-signed TLS certificate if none exists at the configured path, and binds to the specified address.

Credential Initialization

Before starting the server for the first time, initialize the credentials file as the user that runs the server:

admin.flexfs init creds --token <admin-token>

If --token is omitted, the command prompts interactively. The token must be a valid UUID.

init creds Flags

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

The credentials file is written with 0600 permissions to the path specified by --credsFile, by default ~/.flexfs/admin/creds in that user’s home folder (/root/.flexfs/admin/creds for root). It is a TOML file containing the token and, if non-default, the stat server address.

Credential File Format

token = "<admin-token>"

Systemd Integration

Optionally, to run the admin server as a root service that starts at boot, create and enable a systemd service unit:

sudo admin.flexfs init systemd --now

init systemd Flags

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

This creates the unit file flexfs-admin.service and enables it. The --now flag additionally starts the service immediately. Requires root. The service runs as root, so it reads /root/.flexfs/admin/creds unless --startFlags names another --credsFile; create the credentials with sudo admin.flexfs init creds.

Teardown

Remove Credentials

admin.flexfs deinit creds

Removes the credentials file. If the file is referenced by a systemd unit, the command refuses unless --force is passed, in which case the referencing units are also removed.

See admin.flexfs deinit creds for its flags and their defaults.

Remove Systemd Unit

sudo admin.flexfs deinit systemd

Stops and removes the flexfs-admin.service unit. Requires root.

TLS

By default the admin server listens over TLS. If no certificate exists at the configured paths, a self-signed certificate is generated automatically. To use custom certificates, provide --sslCert and --sslKey pointing to your certificate and private key files.

Use --noSSL only for testing behind a TLS-terminating load balancer.

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.

Take care here: mount clients, the metadata server and the CSI driver all call this API directly, so a rule meant to fence off configure.flexfs can cut off the cluster. Whenever it loads a file with a global list, the server logs every endpoint that list gates. See API Access Control.

Deploy Folder

The admin server serves mount client binaries from its deploy folder. Mount clients poll the admin server for updates and download new versions from the /deploy/ endpoints. Use manage.flexfs deploy to populate the deploy folder with the latest binaries for staging and production channels. Run it as the user that runs the admin server, or with sudo and --adminPath naming this server’s database folder; either way, the admin server can read what it deploys.

License Validation

The admin server continuously validates the Enterprise license grant file located in the database folder (grant.json). If the grant is missing or expired, all volumes are flagged read-only until a valid grant is restored.

At startup, before the server binds, it checks that file and requests a fresh grant from the stat server when the grant is missing, expired, or about to expire. The request needs the credentials in the admin server’s credentials file; it is given up to 30 seconds, and a server whose grant could not be renewed still starts, with its volumes read-only. Grants are also renewed as volume statistics are reported, so a running server normally keeps its grant current without restarting.

If the subscription behind the license key is not active, for example an AWS Marketplace subscription that was canceled, the stat server stops issuing grants and the admin server logs Warning: subscription is not active: volumes become read-only when the grant expires at <time> each time it reports statistics. Volumes stay read-write until the current grant expires.