Cache Management
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
Section titled “Disk cache”Cache folder
Section titled “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
Section titled “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 absoluteproxy.flexfs start --diskQuota 80% # 80% of the filesystem containing --diskFolderDefault: 90%
Separately from the cache quota, --minDiskAvail (default 1G) guards free space on the proxy’s database folder (--dbFolder): the proxy refuses to start below the threshold and shuts down gracefully if free space drops below it while running. If you place --dbFolder and --diskFolder on the same filesystem, size the cache quota to leave that headroom.
Cache eviction
Section titled “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
Section titled “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. The number of parallel writeback operations is sized automatically from the host’s CPU count.
Durability
Section titled “Durability”| Flag | Description |
|---|---|
--sync | Fsync every dirty block write to disk for full crash durability. Reduces writeback throughput but ensures no data loss on power failure. |
See the proxy.flexfs CLI reference for types and defaults.
Monitoring
Section titled “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
Section titled “Server-side encryption”The --sse flag requests S3 server-side encryption (AES256) on all blocks written to S3. This flag is independent of flexFS end-to-end encryption.
| Flag | Description |
|---|---|
--sse | Request S3 server-side encryption (AES256). |
See the proxy.flexfs CLI reference for types and defaults.