Enterprise: Install

The Enterprise installer is an interactive shell script that sets up a complete single-node flexFS deployment — admin server, metadata server, optional caching proxy, and your first volume — in a single run. After installation you will have a working system ready for mount clients to connect.

Before You Begin

Ensure you have:

A Linux host meeting the prerequisites
Root access
A flexFS license key (UUID format, obtained from Paradigm4)
An object storage bucket, with credentials for it or a cloud identity attached to the host that grants access to it

Run the Installer

Download and run the installer as root:

curl -fsSL https://get.flexfs.io/enterprise/install.sh | sudo bash

The script runs interactively, prompting for configuration at each step. The sections below describe each prompt in order.

Each answer is saved as it is given to /root/.flexfs-enterprise-install.answers, a file only root can read. If the installer is interrupted, running it again offers the saved answers as defaults. The secret access key, the storage account access key, the license key, and confirmations are not saved and must be entered again. The file is deleted when the installation completes; delete it to start over.

Installation Walkthrough

Pre-flight Checks

The installer begins by verifying that:

You are running as root (uid 0)
curl and systemctl are available on the host

If any check fails the script exits immediately with an error message.

License Key Validation

License key: ________

Enter your Enterprise license key; it is not shown as you type and is asked for twice. The installer validates that it is a properly formatted UUID, then contacts the flexFS licensing service to verify it. If validation fails you will see one of:

invalid license key: not a UUID — the key is not in UUID format
invalid license key: unauthorized — the key was rejected by the licensing service
subscription is not active — the key’s subscription (for example, an AWS Marketplace subscription) has failed or ended
unable to validate license key (stat server returned HTTP <code>) — the licensing service could not be reached or returned an unexpected response

Existing Installation Detection

If the installer finds an existing flexFS installation at ~root/.flexfs, it prompts:

An existing flexFS installation was found at /root/.flexfs.
Overwrite existing installation? [no]: ________

Answering yes shows a warning and asks you to type overwrite to confirm. Once you confirm the installation summary, the installer unmounts every flexFS mount on the host (aborting if one is still in use), stops all flexFS services, and permanently deletes ~root/.flexfs, including the metadata database of every volume served from this host; without it, the data those volumes keep in object storage cannot be read. To move an existing installation to a new version, use manage.flexfs upgrade instead of re-running the installer.

Upgrading a Community Installation

If the existing installation is a Community installation, the installer instead asks:

An existing flexFS Community installation was found at /root/.flexfs.
Upgrade it to Enterprise, overwrite it, or abort? (upgrade, overwrite, abort) [upgrade]: ________

overwrite behaves as described above. upgrade converts the installation to Enterprise in place, keeping its volume and data:

The Enterprise admin server replaces the Community server at the same address, and serves the same volume (free, with the same volume ID and object storage), the same volume token, and the same account token. The metadata server and its data are left untouched, and existing mounts, including fstab mounts, keep running.
The cloud, storage, credential, port, proxy, and volume questions are skipped, since those settings are taken from the Community installation. The installer asks whether to keep the Community limits of 5 TiB and 5 million files on the volume (by default they are lifted), and asks the error and usage reporting questions. The error reporting question defaults to the Community server’s --reportErrors setting.
The admin server keeps the Community server’s bind address, TLS settings, API access file, and --reportMountErrors setting. The Community --noInstaller flag has no Enterprise equivalent: the admin server always serves the mount client installer script, and the installer points this out before asking for confirmation.
If the Community server is running, the installer asks whether it may stop it, and aborts if the answer is no. The server is stopped just before the admin server starts, so new mounts wait a few seconds while the admin server takes over.
Before asking for confirmation, the installer checks that the Community installation can be imported without changing anything on the host. It refuses to upgrade when the metadata server does not run on this host or the Community credentials are incomplete; when the Community server uses a custom credentials file, a start command the installer does not recognize (including quoting, spaces, systemd specifiers, relative certificate or access file paths in the systemd unit, or an ExecStart override in a drop-in file), or runs as a user other than root; when the flexfs-free service is defined outside /etc/systemd/system; when an admin server is already running on the host; or when an admin database in ~root/.flexfs/admin already holds other volumes or cannot be read.
The volume keeps its 2 MiB block size and lz4 compression, and stays without end-to-end encryption. New volumes can use any Enterprise setting.
After the upgrade, the flexfs-free systemd service and the free.flexfs binary are removed, and the Community settings folder is kept as ~root/.flexfs/free.backup.

If the upgrade fails after the Community server was stopped, the installer stops the admin server and restarts the Community server, so the volume stays available; a Community server that was not started by systemd has to be started again by hand. Running the installer again retries the upgrade. If an earlier attempt already imported the volume, the retry keeps the limits chosen then. Mounts added after the upgrade use the Enterprise mount command, which takes the volume token (shown at the end of the upgrade).

Cloud Auto-Detection

The installer automatically detects the cloud provider (AWS, GCP, Azure, or OCI) and region from the host’s instance metadata. If detection succeeds, the provider and region are pre-filled as defaults. On a host outside a cloud, such as an on-premises server, the installer reports that no cloud environment was detected and you enter them yourself.

Cloud Configuration

Object storage provider (e.g. aws, gcp, azure, oci, dc-1) [detected]: ________
Region (e.g. us-east-1) [detected]: ________
Object storage API (s3, gcs, azure, oci) [derived]: ________

The provider is the one whose object storage holds the bucket, which need not be where the host runs: an on-premises host can store its data in AWS, GCP, Azure or OCI object storage. For other S3-compatible storage, such as MinIO or Ceph, enter a name of your choice (for example onprem); the region prompt then explains that the region is used to sign requests and defaults to us-east-1, which such storage usually accepts.

The storage API is derived from the provider (aws maps to s3, gcp to gcs, azure to azure, oci to oci, and any other name to s3) but can be overridden, for example to use a cloud’s S3-compatible interface.

The installer then prompts for the object storage endpoint. With a cloud provider’s own API (aws with s3, gcp with gcs, azure with azure, or oci with oci) the endpoint is optional:

Custom endpoint (leave blank for the provider default) []: ________

Leave it blank to use the provider’s default endpoint, or set it for a private or sovereign-cloud endpoint. For any other combination the endpoint is required, since there is no default to fall back on:

Object storage endpoint (e.g. https://storage.example.com:9000): ________

With gcp and the s3 API it defaults to https://storage.googleapis.com. The endpoint, bucket name, OCI namespace, OCIDs, and key fingerprint are checked as they are entered and asked for again if invalid; IPv6 addresses in an endpoint go in brackets. When a saved answer from an interrupted run is offered as the default for an optional prompt, enter - to clear it.

Next, provide the bucket name:

Bucket name: ________

Choosing the oci API then prompts for the tenancy’s object storage namespace. When the OCI CLI is installed the installer looks it up and offers it as the default:

Object storage namespace [<namespace>]: ________

Finally, provide the key prefix:

Key prefix [flexfs]: ________

The key prefix is a path within the bucket that flexFS uses to namespace its data. The default flexfs is suitable for most deployments.

Object Storage Credentials

When the host is detected on the cloud chosen as the provider and the storage API is that cloud’s native one (aws with s3, gcp with gcs, azure with azure, or oci with oci), the installer offers the host’s own cloud identity:

Use this instance's IAM instance role for object storage access? [yes]: ________

The question names the IAM instance role (AWS), attached service account (GCP), managed identity (Azure), or instance principal (OCI). Accept the default if that identity grants access to the bucket (see Cloud IAM Setup). On an EC2 instance with no IAM role attached, the installer says so and the question defaults to no. With the managed identity and no custom endpoint, the installer then asks for the storage account name, which it needs to form the default service URL:

Storage account name: ________

If you answer no, or the question is not asked (off-cloud, or a provider or API that does not match the detected cloud), the installer asks for credentials for the chosen API:

API	Prompts
`s3`	`Access key ID`, `Secret access key`
`gcs`	`Path to the service account key file` (JSON)
`azure`	`Storage account name`, `Storage account access key`
`oci`	`User OCID`, `Tenancy OCID`, `API key fingerprint`, `Path to the API private key file (PEM)`

The secret access key and the storage account access key are not shown as you type and are asked for twice. Key files are read from the path given and checked; the installer asks again if a file cannot be read, does not contain a private key, or holds an encrypted key.

With the s3, gcs, or oci API, when root already has credentials configured for that API and the servers would use them, the installer first offers a choice between entering credentials and using the configured ones:

Credential type:
  1) access key ID and secret access key
  2) AWS credentials already configured in /root/.aws
Choose 1 or 2 [1]: ________

API	Configured credentials
`s3`	The `[default]` profile in `/root/.aws/credentials`, or credentials or a role in the `[default]` profile of `/root/.aws/config`
`gcs`	`/root/.config/gcloud/application_default_credentials.json`
`oci`	The `[DEFAULT]` profile in `/root/.oci/config`

Choose 2 to have the servers use the configured credentials; no further credentials are asked for. The choice is not offered on an EC2 instance with an IAM role attached or on an OCI instance, because the servers use the instance’s identity ahead of configured credentials there. On GCP, application default credentials configured for root take precedence over the attached service account, and the installer says so when you choose the service account.

Host and Ports

Host IP address [auto-detected]: ________
Admin server port [443]: ________
Metadata server port [8443]: ________

The host IP address is auto-detected from the local network interface. The admin and metadata ports must be different. These are the addresses that mount clients will use to connect to the server.

Proxy Configuration

Enable caching proxy? [no]: ________

Proxy groups provide a CDN-like caching layer between mount clients and object storage. If you answer yes, the installer prompts for:

Proxy bind port [9443]: ________
Proxy cache folder [/cache]: ________
Proxy cache disk quota [95%]: ________
Max proxied blocks per file (0 = all) [0]: ________

The cache folder should be on a fast local disk (NVMe or SSD). The disk quota controls how much space the proxy’s on-disk cache can use, specified as a percentage or absolute size (e.g. 95%, 500GB, 1TiB). Max proxied blocks per file caps how many of each file’s leading blocks are served through the proxy — 0 proxies every block; a positive value proxies only that many leading blocks per file. It is a volume setting, applied to the volume created below, and only takes effect once a proxy exists.

Volume Configuration

(Block size, compression, and encryption cannot be changed after creation)

Volume name [vol-01]: ________
Block size (e.g. 1M, 2M, 4M) [4M]: ________
Compression algorithm (lz4, snappy, zstd, none) [lz4]: ________
Enable end-to-end encryption? [no]: ________

Setting	Choices	Notes
Volume name	3-63 letters, digits, `.`, `-`, `_`	Human-readable identifier for the volume. Must start and end with a letter or digit and cannot contain `..`.
Block size	256KiB — 8MiB (power of 2)	Larger blocks suit large sequential files; smaller blocks suit many small files. Cannot be changed after creation.
Compression	`lz4`, `snappy`, `zstd`, `none`	LZ4 is the fastest; zstd provides the highest ratio. Cannot be changed after creation.
Encryption	yes / no	Enables AES-256 end-to-end encryption. Cannot be changed after creation.

If the volume cannot be created, the installer shows the error and prompts for these settings again.

Error Reporting

Report errors to Paradigm4? [no]: ________

FlexFS can report errors and panics to Paradigm4 to help diagnose problems. Reports carry the error text, a stack trace, and the failing service’s log. Reporting is off by default; answer yes to enable it for the servers and mount clients.

Usage Reporting

Withhold session details from usage reports? [no]: ________

The admin server reports hourly volume usage to Paradigm4 for licensing and billing. By default, the reports also include session details for each mount client: host addresses, versions, command, kernel, CPUs, RAM, UID/GID, and I/O counts. Session details are not needed for billing. Answer yes to withhold them; the installer then starts the admin server with --basicStats. Session details are still recorded by your own admin server either way.

Summary and Confirmation

Before making any changes, the installer displays a full summary:

================================================================================
Installation Summary
================================================================================
Provider      aws
Region        us-east-1
API           s3
Bucket        <bucket>
Prefix        flexfs
Creds         IAM instance role

Host          10.0.1.50
Admin         :443
Meta          :8443

Volume        vol-01
Block size    4MiB
Compression   lz4
E2EE          disabled

Reporting     disabled
Sessions      included in usage reports

Required TCP ports (ensure these are reachable by mount clients):

    443  - admin.flexfs (admin API and mount client installer)
   8443  - meta.flexfs  (metadata service)

Proceed with installation? [yes]: ________

Answer yes to begin the installation.

The Creds line describes the chosen credentials, such as IAM instance role or access key (ID: <access-key-id>). An Endpoint line follows API when an object storage endpoint is set, and a Namespace line follows Bucket for OCI. The summary above shows a deployment without a caching proxy. When a proxy is enabled, the summary also lists a Proxy line (its bind port, cache folder, and disk quota), a Proxied line (how many leading blocks per file are served through the proxy), and the proxy’s port under Required TCP ports.

What Gets Installed

After confirmation, the installer executes the following steps automatically:

Downloads binaries to /sbin/:
- admin.flexfs — admin server
- meta.flexfs — metadata server
- configure.flexfs — resource configuration CLI
- manage.flexfs — host management CLI
- proxy.flexfs — caching proxy (if enabled)
Binaries are downloaded from https://get.flexfs.io/ for the detected platform (linux/amd64 or linux/arm64). SELinux contexts are restored if restorecon is available.
Initializes and starts the admin server
- Creates credential file at ~root/.flexfs/admin/
- Creates a systemd unit (flexfs-admin.service)
- Starts the service and waits up to 30 seconds for the health endpoint to respond
Saves the license grant for offline validation
Initializes configure.flexfs with the admin server address and account token
Creates the infrastructure using configure.flexfs:
- A provider (e.g. aws, gcp)
- A region (e.g. us-east-1)
- A block store linking the provider, region, bucket, and credentials
- A meta store pointing to the metadata server address (an authentication token is auto-generated)
- A proxy group (if proxy was enabled), linking the provider, region, and proxy address
Initializes and starts the metadata server
- Creates credentials with the admin server address, the meta store token, and any object storage credentials entered
- Creates a systemd unit (flexfs-meta.service)
- Starts the service
Initializes and starts the proxy server (if enabled)
- Creates credentials, including any object storage credentials entered
- Creates a systemd unit (flexfs-proxy.service) with the configured bind address, cache folder, and disk quota
- Starts the service
Deploys mount client binaries to the admin server’s deploy folder using manage.flexfs deploy
Creates the volume with the specified block size, compression, and encryption settings
Creates a volume token for client authentication
Links the volume to the proxy group (if proxy was enabled)
Verifies that the admin server answers on its /status endpoint and that the metadata server (and proxy server, if enabled) services are running, printing a warning for any that are not

After Installation

When the installer completes successfully, it displays:

================================================================================
flexFS Enterprise Edition Is Running!
================================================================================

Admin server:  https://10.0.1.50:443
Meta server:   https://10.0.1.50:8443

Management:

  configure.flexfs    configure volume, proxies, and tokens
  manage.flexfs       manage, monitor, and update this server

To mount flexFS on a client machine, run:

  curl -fksSL https://10.0.1.50:443/deploy/install-mount.sh | sudo bash -s /mnt/flexfs/vol-01 <volume-token>

================================================================================

The mount command shown uses the volume token created during installation. You can copy this command and run it on any client host to mount the filesystem.

Systemd Services

The installer creates the following systemd units:

Service	Unit name
Admin server	`flexfs-admin.service`
Metadata server	`flexfs-meta.service`
Proxy server	`flexfs-proxy.service` (if enabled)

Check status with:

systemctl status flexfs-admin flexfs-meta flexfs-proxy

You can also use the manage.flexfs utility to monitor and control services:

sudo manage.flexfs status

See manage.flexfs for the full set of commands (start, stop, restart, upgrade, watch, and more).

Next Steps

Enterprise: Configuration — learn how to manage resources with configure.flexfs
Enterprise: First Mount — install the mount client on a remote host