admin.flexfs
admin.flexfs is the central management server for flexFS Enterprise. It stores accounts, volumes, block stores, metadata stores, proxy groups, and volume tokens. Mount clients connect to it for volume settings and binary updates, and configure.flexfs uses its REST API to manage resources.
Persistent Flags
Section titled “Persistent Flags”These flags apply to every subcommand.
| Flag | Type | Default | Description | Visibility |
|---|---|---|---|---|
--reportErrors | bool | false | Report errors and panics to Paradigm4. Governs what this server reports about itself only — to require reporting on mount clients, see --reportMountErrors below | Public |
Subcommands
Section titled “Subcommands”| Subcommand | Description | Visibility |
|---|---|---|
deinit creds | Remove the credentials file | Public |
deinit systemd | Remove the systemd service unit | Public |
import free | Import the volume of a Community installation | Internal |
init creds | Initialize the credentials file | Public |
init systemd | Create and enable a systemd service unit | Public |
license | Print license information | Public |
start | Start the admin server | Public |
version | Print the build version | Public |
deinit creds
Section titled “deinit creds”admin.flexfs deinit creds [flags]Removes the credentials file for the admin server. If the credentials file is referenced by a systemd unit, the command refuses unless --force is passed, in which case it removes the references too.
| Flag | Type | Default | Description | Visibility |
|---|---|---|---|---|
--credsFile | string | ~/.flexfs/admin/creds | Credentials file path | Public |
--force | bool | false | Remove creds even if referenced by systemd (removes references too) | Public |
deinit systemd
Section titled “deinit systemd”sudo admin.flexfs deinit systemdRemoves the systemd service unit (flexfs-admin.service) for the admin server. Requires root.
import free
Section titled “import free”admin.flexfs import free [flags]Adds the volume of a Community installation to the admin server’s database, so that the admin server can replace the free.flexfs server at the same address. The admin server then serves the same volume: the same volume ID and volume token, the same metadata server address and token, and the same object storage location and credentials. The metadata server, its data, and existing mounts keep working unchanged. The account in the admin database takes the Community account token, so tools that use that token keep working. If the database does not exist yet, it is created.
The command reads the Community credentials file and changes only the admin database, so it can run while the Community, metadata, and admin servers are running. It checks the settings the admin server would serve against those the Community server serves and saves nothing unless they match. Running it again once the volume is imported changes nothing.
It refuses, changing nothing, when:
- the metadata server credentials hold a different token than the Community credentials
- the volume ID, the volume name
free, the volume token, or the metadata server token already belong to different settings in the admin database - the admin database has more than one account, or already has volumes and a different account token
- the Community storage settings are invalid, or would be stored in a different form (for example, an endpoint with a trailing slash)
Without --keepLimits, the imported volume has no storage or file limits. With it, the volume keeps the Community limits of 5 TiB and 5 million files. A repeated run leaves the limits as they are.
On success the command prints one line, or with --json an object with the fields block_store_id, imported, meta_store_id, volume_id, volume_name, and volume_token. imported is false when the volume was already present; with --dryRun it is true when the volume can be imported. On failure it prints the reason to standard error and exits with a non-zero status.
| Flag | Type | Default | Description | Visibility |
|---|---|---|---|---|
--dbFolder | string | ~/.flexfs/admin | Database folder path | Public |
--dryRun | bool | false | Check the import without saving it. Creates no database when none exists | Public |
--freeCredsFile | string | ~/.flexfs/free/creds | Community server credentials file path | Public |
--json | bool | false | Print the result as JSON | Public |
--keepLimits | bool | false | Keep the Community limits of 5 TiB and 5 million files | Public |
--metaCredsFile | string | ~/.flexfs/meta/creds | Metadata server credentials file path, whose token must match the Community metadata token. Empty skips the check | Public |
init creds
Section titled “init creds”admin.flexfs init creds [flags]Initializes a credentials file for the admin server. If --token is omitted, the command prompts for it interactively. The token is your Enterprise license key, which the server uses to authenticate to the stat server. init on its own does the same thing as init creds.
| Flag | Type | Default | Description | Visibility |
|---|---|---|---|---|
--credsFile | string | ~/.flexfs/admin/creds | Credentials file path | Public |
--force | bool | false | Overwrite existing credentials file | Public |
--statAddr | string | stat.flexfs.io | Stat server address | Public |
--token | string | "" | License key, a UUID (will prompt if omitted) | Public |
init systemd
Section titled “init systemd”sudo admin.flexfs init systemd [flags]Creates and enables a systemd service unit (flexfs-admin.service) for the admin server. Requires root. Optional: the server can also be run directly with start by any user. The service runs as root, so it uses root’s /root/.flexfs defaults, credentials included, unless --startFlags names other paths.
| Flag | Type | Default | Description | Visibility |
|---|---|---|---|---|
--force | bool | false | Overwrite existing systemd unit file | Public |
--now | bool | false | Start the service immediately after enabling | Public |
--startFlags | string | "" | Additional flags to pass to the start command | Public |
admin.flexfs start [flags]Starts the admin server, binding the management endpoint. Any user can run it, and ~ in the defaults is that user’s home folder. A non-root user needs a --bindAddr port above 1023.
| Flag | Type | Default | Description | Visibility |
|---|---|---|---|---|
--accessFile | string | ~/.flexfs/admin/access | API access file path — whitelists the source addresses allowed to reach each endpoint. Absent = all endpoints unrestricted | Public |
--basicStats | bool | false | Relay only basic stats to the stat server | Public |
--bindAddr | string | 0.0.0.0:443 | Address and port to bind | Public |
--credsFile | string | ~/.flexfs/admin/creds | Credentials file path | Public |
--dbFolder | string | ~/.flexfs/admin | Database folder path | Public |
--deployFolder | string | ~/.flexfs/admin/deploy | Folder for mount client deploy binaries | Public |
--noSSL | bool | false | Serve the REST API and deploy endpoints over plain HTTP. Every client must then use its Internal --noAdminSSL flag: mount.flexfs (start and init creds), configure.flexfs, meta.flexfs (start and missing-objects), and analyze.flexfs, dedup.flexfs, and find.flexfs (queries and init creds). The CSI driver has no such flag and needs HTTPS. | Public |
--noStatSSL | bool | false | Disable SSL for stat server connections | Internal |
--pprof | bool | false | Enable pprof profiler | Internal |
--pprofPort | int | 6060 | Pprof server port | Internal |
--reportMountErrors | bool | false | Require error reporting on the mount clients of every volume this server serves. The reporterrors flag is added to the volume settings the server hands out (see Accepted Volume and Token Flags). Independent of --reportErrors, which covers only this server’s own panics | Public |
--sqliteOpts | string | _journal=WAL&_cache_size=10240&_fk=true&_timeout=5000 | SQLite database connection options | Internal |
--sslCert | string | ~/.flexfs/ssl/cert | SSL certificate file path. A self-signed certificate and key are created if neither exists. | Public |
--sslKey | string | ~/.flexfs/ssl/key | SSL private key file path | Public |
--statAddr | string | "" | Stat server address (overrides credentials file) | Internal |
--token | string | "" | License key (overrides credentials file) | Internal |
--verbose, -v | bool | false | Enable verbose logging | Public |
API access control
Section titled “API access control”--accessFile names a TOML file listing the IP addresses and CIDR blocks allowed to reach each endpoint. There is no file by default and nothing creates one, so every endpoint is unrestricted until you write it. It is re-read every two seconds, so a change takes effect within seconds without a restart; deleting it lifts all restrictions.
Most callers of this API are machines rather than people — mount clients fetch volume settings and rotate secret ids, the metadata server posts stats and reads rate bins, and the CSI driver provisions volumes. A rule written to fence off configure.flexfs gates those endpoints too unless they are opened back up, so read the global rule gates: line the server logs whenever it loads a file with a global list. The /deploy/ tree is the exception: its URLs are baked into published install commands, so it is reached only by a rule naming it explicitly — and one [endpoint."/deploy/"] rule covers the whole tree, the installer script included.
A file that cannot be parsed, or that names an endpoint this server does not serve, is refused: the server will not start on one, and a running server keeps the rules already in force. Blocked requests are answered 403 with the usual {"code":403,"text":"forbidden"} body.
See API Access Control for the file format and the rule precedence.
Deploy Endpoints
Section titled “Deploy Endpoints”The admin server serves mount client binaries and an installer script for auto-update and client deployment:
| Endpoint | Description |
|---|---|
/deploy/install-mount.sh | Shell script that downloads and configures the mount client |
/deploy/production/ | Production channel mount client binaries |
/deploy/staging/ | Staging channel mount client binaries |