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.