Proxy Server Setup

Note

Proxy servers are an Enterprise feature.

Installation

The proxy server binary (proxy.flexfs) is included in the flexFS Enterprise installation. It is typically deployed via the admin server’s deploy endpoint or the manage.flexfs tool.

Initialize credentials

Tip

When running on AWS EC2 with an instance role, GCP with a service account, Azure with managed identity, or OCI with instance principal — no credentials file is needed. The proxy server uses the platform’s native credential chain automatically.

If the proxy server needs static block storage credentials (access key and secret), initialize them before starting:

proxy.flexfs init creds \
  --blockUser $USERNAME \
  --blockPass $PASSWORD

This writes a TOML credentials file to the default location (~/.flexfs/proxy/creds):

blockPass = "$PASSWORD"
blockUser = "$USERNAME"

init creds flags:

| Flag | Type | Default | Description | |------|------|---------|-------------| | --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 |

Create systemd service

sudo proxy.flexfs init systemd --now

This creates and enables a systemd unit at /etc/systemd/system/flexfs-proxy.service and optionally starts it immediately.

To pass additional flags to the proxy server at startup:

sudo proxy.flexfs init systemd --now \
  --startFlags "--diskFolder /data/proxy-cache --diskQuota 500G"

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 proxy.flexfs start |

Start flags

The proxy.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 HTTPS server | | --dbFolder | string | ~/.flexfs/proxy/data | Cache database folder path | | --diskFolder | string | /cache | On-disk block cache folder path | | --diskQuota | string | 95% | Maximum disk usage for the block cache (e.g. 5%, 64M, 500G). Must be greater than zero. | | --noSSL | bool | false | Disable TLS for the REST API | | --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 dirty block writes for full crash durability | | --verbose / -v | bool | false | Enable verbose logging |

Hidden flags [internal]

| Flag | Type | Default | Description | |------|------|---------|-------------| | --blockPass | string | (from creds) | Block storage password (overrides credentials file) | | --blockUser | string | (from creds) | Block storage username (overrides credentials file) | | --bufferSize | uint32 | 1048576 | I/O buffer size in bytes | | --dbMemCapacity | string | 10% | Memory allocated to the cache database index (e.g. 5%, 64M) | | --maxBops | uint32 | auto | Maximum number of active parallel block operations | | --noWriteback | bool | false | Disable writeback to persistent object storage | | --pprof | bool | false | Enable the Go pprof profiler | | --pprofPort | int | 6064 | Pprof server port | | --sse | bool | false | Enable S3 server-side encryption (AES256) on writes | | --writebackActive | uint32 | auto | Maximum number of active parallel writeback operations (default: maxBops) | | --writebackDelay | uint32 | 0 | Milliseconds to sleep between writeback operations |

TLS certificates

By default, the proxy server auto-generates a self-signed TLS certificate if none exists at the configured paths. To use custom certificates:

proxy.flexfs start \
  --sslCert /etc/ssl/proxy.crt \
  --sslKey /etc/ssl/proxy.key

For testing or internal networks, --noSSL disables TLS entirely.

Verifying the server

After starting, the proxy server logs its configuration:

proxy.flexfs | v1.9.0
--------------------------------------------------------------------------------
      bindAddr | 0.0.0.0:443
    diskFolder | /cache
     diskQuota | 95% (475.00 GiB)
       sslCert | ~/.flexfs/ssl/cert
        sslKey | ~/.flexfs/ssl/key
--------------------------------------------------------------------------------
Binding to 0.0.0.0:443 (encrypted)

The server is ready to accept block requests from mount clients once the bind message appears.