Proxy Server Setup

Note

Proxy servers are an Enterprise feature.

Installation

The Enterprise installer installs the proxy server binary (proxy.flexfs) and sets up a proxy server on the same host only when Enable caching proxy? is answered yes (the default is no). The installer’s proxy port defaults to 9443. To add a proxy server on any other host, install the binary with sudo manage.flexfs download proxy --install (see manage.flexfs).

Initialize credentials

Tip

When running on AWS EC2 with an instance role, GCP with a service account, or OCI with instance principal, no credentials file is needed: the proxy server uses the platform’s native credential chain automatically. On Azure, the proxy server can also authenticate without a key (for example, with a managed identity), but unless the block store sets an address, blockUser must still be set to the storage account name: run proxy.flexfs init creds --blockUser <storage-account> without --blockPass.

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

proxy.flexfs init creds \
  --blockUser <username> \
  --blockPass <password>

This writes a TOML credentials file to ~/.flexfs/proxy/creds in that user’s home folder (/root/.flexfs/proxy/creds for root):

blockPass = "<password>"
blockUser = "<username>"

To keep it elsewhere, pass the same --credsFile to both init creds and start.

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

Run the proxy server

Run proxy.flexfs start as any user. A non-root user needs a --bindAddr port above 1023 and a --diskFolder it can write, since the defaults are port 443 and /cache:

proxy.flexfs start --bindAddr 0.0.0.0:9443 --diskFolder ~/proxy-cache

Optional: systemd service

To run the proxy server as a root service that starts at boot, create a systemd unit:

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. The service runs as root, so it reads /root/.flexfs/proxy/creds unless --startFlags names another --credsFile; create the credentials with sudo proxy.flexfs init creds.

To pass additional flags to the proxy server at startup:

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

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

Start flags

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

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. Every mount client using the proxy group must then be started with the Internal --noProxySSL flag. Mount clients without it fail the probe, log a warning, treat the group as unreachable, and read and write object storage directly. See Disabling TLS.

Verifying the server

After starting, the proxy server logs its configuration. This example is a server run as root with default flags and static credentials:

--------------------------------------------------------------------------------
           proxy.flexfs | v1.9.1 linux/amd64 (2026-09-01 12:00)
--------------------------------------------------------------------------------
               bindAddr | 0.0.0.0:443
              blockPass | <provided>
              blockUser | <username>
             bufferSize | 1M (1.00 MiB)
              credsFile | /root/.flexfs/proxy/creds
               dbFolder | /root/.flexfs/proxy/data
          dbMemCapacity | 10% (6.40 GiB)
             diskFolder | /cache
              diskQuota | 90% (450.00 GiB)
                maxBops | 80
           minDiskAvail | 1G (1.00 GiB)
                sslCert | /root/.flexfs/ssl/cert
                 sslKey | /root/.flexfs/ssl/key
        writebackActive | 80
--------------------------------------------------------------------------------
Cache run nonce: 924658582df78c73
Loading cache index...
Index loaded | clean blocks: 0 (0 B) / dirty blocks: 0 (0 B)
Binding to 0.0.0.0:443 (encrypted)

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