Server Configuration
crab-cache-server reads a TOML file passed with --config.
Required sections:
[auth][origin]
All other sections are optional.
Minimal Example
[auth]
mechanism = "psk"
psk_hash = "0dc7af953ee2c2e947d4dd2a73828ed42dff776f8bd6b3fb230798fc3a6addd1"
[origin]
url = "s3://my-bucket"The example hash is for your-shared-secret. Generate your own:
printf '%s' "your-shared-secret" | b3sum | cut -d' ' -f1Full Example
[server]
listen_addr = "0.0.0.0:8443"
drain_timeout_secs = 30
mutable_path_mode = "strict"
policy_path = "/etc/crab-cache-server/policy.yaml"
[tls]
cert_path = "/etc/crab-cache-server/tls/cert.pem"
key_path = "/etc/crab-cache-server/tls/key.pem"
[auth]
mechanism = "psk"
psk_hash = "<64-character-blake3-hash>"
[origin]
url = "s3://my-bucket"
[cache]
root = "/data/crab-cache"
max_bytes = 1099511627776
[dedup]
scope = "all"
[eviction]
high_water_ratio = 0.95
low_water_ratio = 0.90
[logging]
format = "json"
level = "info"Server
| Field | Default | Description |
|---|---|---|
listen_addr | 0.0.0.0:8443 | Address and port to bind. |
drain_timeout_secs | 30 | Grace period for shutdown. |
mutable_path_mode | strict | strict rejects mutable paths; transparent proxies them without caching. |
policy_path | unset | Optional YAML authorization policy. |
Keep mutable_path_mode = "strict" unless you explicitly need the service to proxy non-cacheable paths.
TLS
| Field | Description |
|---|---|
cert_path | Server certificate PEM. |
key_path | Server private key PEM. |
Omit [tls] when TLS is terminated by a load balancer, ingress, or service mesh.
For mTLS, validate client certificates at a trusted proxy or service mesh and forward the validated identity to the cache service. See Authentication.
Auth
| Field | Description |
|---|---|
mechanism | psk, bearer, or mtls. |
psk_hash | Required for PSK. Blake3 hash of the shared secret. |
jwks_url | Reserved for future bearer-token validation. |
Bearer mode currently accepts non-empty bearer tokens but does not validate signatures. Do not expose bearer mode to untrusted networks.
Origin
| Field | Description |
|---|---|
url | Object-store URL, such as s3://my-bucket or file:///var/lib/crab-origin. |
The cache server needs read access to origin. Clients still perform normal pushes directly to origin.
For S3-compatible stores, provide the usual AWS environment variables, including endpoint and region when needed.
Cache
| Field | Default | Description |
|---|---|---|
root | /data/crab-cache | Local cache directory. Use durable SSD or NVMe storage. |
max_bytes | 1099511627776 | Cache size budget in bytes. |
The cache can be rebuilt from origin, but losing it temporarily reduces hit rate and dedup effectiveness.
Dedup
| Field | Default | Description |
|---|---|---|
scope | all | Intended dedup scope. |
Use separate cache instances when dedup visibility must be isolated by team, tenant, environment, or regulatory boundary.
Eviction
| Field | Default | Description |
|---|---|---|
high_water_ratio | 0.95 | Start eviction when the cache exceeds this fill level. |
low_water_ratio | 0.90 | Evict down to this fill level. |
Lower both values if writes frequently hit disk pressure.
Logging
| Field | Default | Description |
|---|---|---|
format | text | text or json. Use json in production. |
level | info | Log level. |
RUST_LOG can override the configured level.
Environment Overrides
| Variable | Overrides |
|---|---|
CRAB_CACHE_ORIGIN_URL | Origin URL. |
CRAB_CACHE_TLS_CERT | TLS certificate path. |
CRAB_CACHE_TLS_KEY | TLS private key path. |
RUST_LOG | Log filter. |
There is no CRAB_CACHE_PSK_HASH override. Render auth.psk_hash into the config file from your deployment system.