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%. A proxy server set up by the Enterprise installer uses /cache and a 95% quota unless changed at its prompts.
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.
If the cache is above 99% of its quota, a read that misses the cache waits up to 5 seconds for eviction to make room. When dirty blocks alone fill the cache, or the wait runs out, the proxy fetches the block from object storage and passes it through without caching it. A block write waits up to 5 seconds for space and then fails with 503. Mount clients retry for up to 15 seconds, then send all their block traffic directly to object storage for 5 minutes. Size the quota well above the writeback backlog you expect, so that dirty blocks alone never fill it.
Writeback tuning
Section titled “Writeback tuning”Proxy servers always use writeback: they acknowledge writes immediately after persisting them to local disk, then upload them to object storage in the background, each block individually by parallel workers. There is no write-through mode. This significantly reduces write latency, especially for cross-network deployments. The number of parallel uploads is sized automatically from the host’s CPU count.
Until a dirty block is uploaded, the proxy server’s disk holds the only copy. Drain a proxy server before removing it; see Removing a proxy server.
Durability
Section titled “Durability”| Flag | Description |
|---|---|
--sync | Fsync every dirty block write to disk for full crash durability. Adds latency to every client block write and reduces write throughput, but ensures no data loss on power failure. |
See the proxy.flexfs CLI reference for types and defaults.
Without --sync, a host crash or power loss can leave the most recently written blocks empty or incomplete on disk. The proxy server checks each dirty block at startup and again before it uploads it. A block found empty or incomplete is not uploaded, so it cannot replace a good copy already in object storage: the proxy server logs an error naming it and renames the file with a .corrupt suffix for you to inspect and delete. Unless the block reached object storage before the crash, its data is lost. Dirty blocks written by an earlier proxy server release can only be checked for being empty, so an incomplete one is uploaded as is. Clean blocks already on disk when the proxy server starts are checked the first time they are served, and a damaged clean block is deleted and read again from object storage.
Monitoring
Section titled “Monitoring”The proxy server exposes Prometheus metrics at the /metrics endpoint. Key cache-related metrics include:
- Clean and dirty cached bytes and blocks (dirty blocks are the writeback backlog)
- Disk cache quota and the capacity of the cache filesystem
- Free space on the database folder’s filesystem
- REST request counts and 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.