Cache Management

Note

Proxy servers are an Enterprise feature.

The proxy server maintains a local disk cache for block data. Understanding how to size and tune this cache is critical for optimal performance.

Disk cache

Cache folder

The --diskFolder flag sets the path where cached blocks are stored. The proxy server creates two subdirectories:

• <diskFolder>/clean — Blocks that have been read from object storage (read cache).
• <diskFolder>/dirty — Blocks that have been written by clients but not yet flushed to object storage (writeback cache).

Default: /cache

Choose a path on fast local storage (NVMe SSD is recommended). The cache folder should have enough free space to accommodate the configured quota.

Cache quota

The --diskQuota flag controls the maximum disk usage for the block cache. It accepts absolute sizes or percentages of the filesystem:

proxy.flexfs start --diskQuota 500G      # 500 GiB absolute
proxy.flexfs start --diskQuota 80%       # 80% of the filesystem containing --diskFolder

Default: 95%

Caution

The disk quota must be greater than zero. The proxy server will not start without a valid cache quota.

Cache eviction

When the cache approaches its quota, the proxy server evicts the least recently used (LRU) clean blocks to make room. Dirty blocks (pending writeback) are never evicted — they must be flushed to object storage first.

Writeback tuning

Writeback mode allows the proxy server to acknowledge writes immediately after persisting them to local disk, then asynchronously flush them to object storage in the background. This significantly reduces write latency, especially for cross-network deployments.

Writeback flags

Flag	Type	Default	Description
--noWriteback	bool	false	[internal] Disable writeback entirely. All writes pass through directly to object storage.
--writebackActive	uint32	auto	[internal] Maximum number of concurrent writeback operations. Default: same as --maxBops.
--writebackDelay	uint32	0	[internal] Milliseconds to sleep between writeback operations. Useful for throttling writeback to avoid saturating network bandwidth.
--sync	bool	false	Fsync every dirty block write to disk for full crash durability. Reduces writeback throughput but ensures no data loss on power failure.

Writeback concurrency

The --writebackActive flag controls how many blocks can be flushed to object storage simultaneously. The default is the same as --maxBops, which is auto-calculated based on CPU count and architecture:

• On x86_64: max(1.5 * numCPU, max(8, 16 * floor(log2(numCPU))))
• On arm64: The numCPU value is doubled before the formula is applied.

Increase --writebackActive if the proxy server has sufficient network bandwidth and you want faster flush times. Decrease it if writeback is saturating the network.

Writeback delay

The --writebackDelay flag introduces an artificial delay between writeback operations. This can be useful to:

• Throttle object storage API calls to avoid rate limiting.
• Reduce network bandwidth consumption during peak hours.
• Smooth out writeback bursts.

A value of 0 (default) means writeback operations run as fast as possible.

Database memory tuning

The proxy server uses a database for cache metadata (tracking which blocks are cached and their locations). The --dbMemCapacity flag controls the memory allocated to the database index cache.

Flag	Type	Default	Description
--dbMemCapacity	string	10%	[internal] Memory allocated to the cache database index. Accepts percentages of system RAM or absolute values (e.g. 5%, 64M, 1G).

For proxy servers with large caches (hundreds of GiB or more), increasing this value can improve cache lookup performance. A good rule of thumb: allocate 1% of the cache size to the database index, with a minimum of 64 MiB.

Block operation concurrency

The --maxBops flag controls the maximum number of block operations (reads from and writes to object storage) that can run in parallel.

Flag	Type	Default	Description
--maxBops	uint32	auto	[internal] Maximum number of active parallel block operations.

The default auto-calculation matches --writebackActive. Increase this for high-throughput deployments with fast network links.

Monitoring

The proxy server exposes Prometheus metrics at the /metrics endpoint. Key cache-related metrics include:

• Cache hit/miss rates
• Disk cache utilization
• Writeback queue depth
• Block operation latencies

See Observability for the full metrics catalog.

Server-side encryption

The --sse flag enables S3 server-side encryption (AES256) on all blocks written to S3. This flag is independent of flexFS end-to-end encryption.

Flag	Type	Default	Description
--sse	bool	false	[internal] Enable S3 server-side encryption on PutObject calls.