proxy.flexfs

Note

Proxy groups are an Enterprise-only feature.

proxy.flexfs is a CDN-like block caching server that sits between mount clients and object storage. Multiple proxy servers form a proxy group. Mount clients select a group by measured round-trip time and send each block to one member of the group, chosen from the block’s key, so every client uses the same server for a given block.

Persistent Flags

These flags apply to every subcommand.

Flag	Type	Default	Description	Visibility
--reportErrors	bool	false	Report errors and panics to Paradigm4	Public

Subcommands

Subcommand	Description	Visibility
deinit creds	Remove the credentials file	Public
deinit systemd	Remove the systemd service unit	Public
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 proxy server	Public
version	Print the build version	Public

deinit creds

proxy.flexfs deinit creds [flags]

Removes the credentials file for the proxy 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/proxy/creds	Credentials file path	Public
--force	bool	false	Remove creds even if referenced by systemd (removes references too)	Public

deinit systemd

sudo proxy.flexfs deinit systemd

Removes the systemd service unit (flexfs-proxy.service) for the proxy server. Requires root.

init creds

proxy.flexfs init creds [flags]

Initializes a credentials file for the proxy server with block storage credentials. With neither --blockUser nor --blockPass, no file is written. init on its own does the same thing as init creds.

Flag	Type	Default	Description	Visibility
--blockPass	string	""	Block storage password	Public
--blockUser	string	""	Block storage username	Public
--credsFile	string	~/.flexfs/proxy/creds	Credentials file path	Public
--force	bool	false	Overwrite existing credentials file	Public

init systemd

sudo proxy.flexfs init systemd [flags]

Creates and enables a systemd service unit (flexfs-proxy.service) for the proxy 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 an 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

start

proxy.flexfs start [flags]

Starts the proxy server, binding the block-cache 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 and a --diskFolder it can write.

Flag	Type	Default	Description	Visibility
--bindAddr	string	0.0.0.0:443	Address and port to bind	Public
--blockPass	string	""	Block storage password (overrides credentials file)	Internal
--blockUser	string	""	Block storage username (overrides credentials file)	Internal
--bufferSize	string	1M	I/O buffer size, given as a size (1M) or bytes (1048576). Minimum 4K.	Internal
--credsFile	string	~/.flexfs/proxy/creds	Credentials file path	Public
--dbFolder	string	~/.flexfs/proxy/data	Database folder path	Public
--dbMemCapacity	string	10%	Database memory cache capacity (e.g. 5%, 64M)	Internal
--diskFolder	string	/cache	On-disk block cache folder path	Public
--diskQuota	string	90%	On-disk block cache capacity (e.g. 5%, 64M). Must be greater than zero; the server will not start otherwise.	Public
--maxBops	uint32	0 = auto	Maximum number of parallel block operations	Internal
--minDiskAvail	string	1G	Minimum free space on the database folder filesystem (e.g. 2%, 512M; 0 = disabled)	Public
--noSSL	bool	false	Serve the block-cache endpoint over plain HTTP. Mount clients must then use their Internal --noProxySSL flag; otherwise their probes fail and they bypass the proxy.	Public
--noWriteback	bool	false	Never upload written blocks to object storage; they exist only in this proxy’s cache	Internal
--pprof	bool	false	Enable pprof profiler	Internal
--pprofPort	int	6066	Pprof server port	Internal
--sse	bool	false	Request S3 server-side encryption (AES256)	Public
--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
--sync	bool	false	Fsync dirty block writes for full crash durability	Public
--verbose, -v	bool	false	Enable verbose logging	Public
--writebackActive	uint32	0 = auto	Maximum number of parallel writeback operations	Internal
--writebackDelay	string	0	How long each writeback should sleep, given as a duration (250ms, 1s) or whole milliseconds (0). 0 = disabled.	Internal

Auto-computed defaults

When --maxBops or --writebackActive is left at 0, the proxy sizes it automatically.

Low disk space protection

The proxy tracks its cached blocks in a database under --dbFolder, which cannot be written safely on a filesystem that has run out of space. The server therefore guards that filesystem:

• On startup, it refuses to start if the available space is already below --minDiskAvail.
• While running, it re-checks every minute and shuts down gracefully as soon as available space drops below --minDiskAvail. Both events are logged, naming the folder and the space available.

The block cache under --diskFolder is bounded separately by --diskQuota, so this guard is about the database folder; when both live on the same filesystem, it covers them together. Watch flexfs_proxy_db_folder_disk_available_bytes to catch this well before it happens; see Alerting. Setting --minDiskAvail to 0 disables both checks.