STRATA_* environment variables#

Every STRATA_* knob, grouped by the layer that consumes it. CLI flags on strata server (--listen, --vhost-pattern, --log-level, --workers=) override the matching env var.

This is the operator-facing tuning manual; see the reference index for the rest of the reference material.

Gateway (core HTTP)#

See Concepts — S3 surface for what the gateway speaks and Architecture — router for the dispatch shape.

VariableDefaultRangeNotesTOML key
STRATA_LISTEN:9000host:portHTTP listen address. CLI: --listen.listen
STRATA_REGIONstrata-localstringDefault region tag advertised by the gateway and stamped on bucket-create.region
STRATA_DATA_BACKENDmemorymemory | rados | s3Data-backend selector. Required at boot.data_backend
STRATA_META_BACKENDmemorymemory | cassandra | tikvMeta-backend selector. Required at boot.meta_backend
STRATA_BUCKET_SHARDS64positive intPer-bucket default shard count for the objects table; see sharded objects.default_bucket_shards
STRATA_CHUNK_CRC_VERIFYtruetrue | falseRead-path per-chunk CRC32C verification (US-009). On: a byte-flip in a stored plaintext chunk fails the read loud (ErrChecksumMismatch) instead of a corrupted 200. Off: operator escape hatch.chunk_crc_verify
STRATA_SHUTDOWN_WAIT10sGo durationGraceful-shutdown drain window before http.Server.Close.shutdown_wait
STRATA_HTTP_READ_HEADER_TIMEOUT10sGo duration ≥ 0Slowloris-safe ceiling on header receipt. 0 = disabled (net/http semantic).http.read_header_timeout
STRATA_HTTP_READ_TIMEOUT60sGo duration ≥ 0Header + body receipt ceiling. 0 = disabled.http.read_timeout
STRATA_HTTP_WRITE_TIMEOUT30mGo duration in [0, 24h]Response-write ceiling. 30m default ≈ 2.8 MB/s minimum on a 5 GiB body (cellular safe). 0 = disabled.http.write_timeout
STRATA_HTTP_IDLE_TIMEOUT120sGo duration ≥ 0Keep-alive idle ceiling. 0 = disabled.http.idle_timeout
STRATA_HTTP_MAX_HEADER_BYTES1048576 (1 MiB)int in [0, 16777216]Header byte cap per request. 0 = net/http default (1 MiB).http.max_header_bytes
STRATA_TLS_CERT_FILEemptypathPEM certificate (server + optional intermediates) for the built-in TLS listener. Empty → plain HTTP. Must be set together with STRATA_TLS_KEY_FILE.tls.cert_file
STRATA_TLS_KEY_FILEemptypathPEM private key matching STRATA_TLS_CERT_FILE.tls.key_file
STRATA_TLS_MIN_VERSIONTLS1.2TLS1.2 | TLS1.3Minimum negotiated TLS protocol version.tls.min_version
STRATA_TLS_CIPHER_PROFILEmozilla-modernmozilla-modern | mozilla-intermediate | go-defaultTLS 1.2 cipher suite selection. mozilla-modern pins TLS 1.3 AEAD suites only (TLS 1.2 clients rejected). Informational on TLS 1.3 connections per RFC 8446.tls.cipher_profile
STRATA_TLS_CERT_DIRemptypathSNI multi-cert directory (US-003). Walked for *.crt + matching *.key pairs; cert dispatched per-handshake via tls.Config.GetCertificate. Mutually exclusive with STRATA_TLS_CERT_FILE.tls.cert_dir
STRATA_TLS_CLIENT_CA_FILEemptypathPEM CA bundle for client-cert verification. When set, the gateway requires mTLS (ClientAuth=RequireAndVerifyClientCert).tls.client_ca_file
STRATA_TLS_RELOAD_INTERVAL60sGo duration in [10s, 1h] or 0Periodic re-stat fallback for fsnotify drops + k8s ConfigMap atomic-symlink swaps. 0 disables (fsnotify-only).tls.reload_interval
STRATA_ADMIN_LISTENemptyhost:portBind /admin/v1/, /console/, /metrics, /healthz, /readyz on a SECOND listener (US-008 harden-gateway). Empty → single-port shape (admin shares STRATA_LISTEN). Recommended for prod: 127.0.0.1:9001 (loopback) or RFC1918.admin_listen.listen
STRATA_ADMIN_HTTP_READ_HEADER_TIMEOUT10sGo duration ≥ 0Slowloris-safe ceiling on header receipt for the admin listener. 0 = disabled.admin_listen.http.read_header_timeout
STRATA_ADMIN_HTTP_READ_TIMEOUT60sGo duration ≥ 0Header + body receipt ceiling on the admin listener. 0 = disabled.admin_listen.http.read_timeout
STRATA_ADMIN_HTTP_WRITE_TIMEOUT2mGo duration in [0, 24h]Response-write ceiling on the admin listener. 2m default — no large multipart on admin. 0 = disabled.admin_listen.http.write_timeout
STRATA_ADMIN_HTTP_IDLE_TIMEOUT120sGo duration ≥ 0Keep-alive idle ceiling on the admin listener. 0 = disabled.admin_listen.http.idle_timeout
STRATA_ADMIN_HTTP_MAX_HEADER_BYTES1048576 (1 MiB)int in [0, 16777216]Header byte cap per admin-listener request.admin_listen.http.max_header_bytes
STRATA_ADMIN_TLS_CERT_FILEemptypathPEM certificate for the admin listener. Empty → plain HTTP (typical loopback shape). Must be paired with STRATA_ADMIN_TLS_KEY_FILE. No SNI / hot-reload (admin is a single endpoint per replica).admin_listen.tls.cert_file
STRATA_ADMIN_TLS_KEY_FILEemptypathPEM private key matching STRATA_ADMIN_TLS_CERT_FILE.admin_listen.tls.key_file
STRATA_ADMIN_TLS_CLIENT_CA_FILEemptypathPEM CA bundle for admin-listener mTLS. When set, the admin listener requires every connection to present a client cert signed by the CA (ClientAuth=RequireAndVerifyClientCert).admin_listen.tls.client_ca_file
STRATA_RATE_LIMIT_PER_KEY0int in [0, 100000]Per-access-key req/sec on the S3 hot path (US-009 harden-gateway). 0 disables. Empty access key (anonymous mode) skips this layer. Refusal returns HTTP 429 + <Code>SlowDown</Code> + Retry-After: 1.rate_limit.per_key
STRATA_RATE_LIMIT_PER_IP0int in [0, 100000]Per-remote-IP req/sec on the S3 hot path (US-009 harden-gateway). 0 disables. Client IP is resolved via STRATA_TRUSTED_PROXIES when a trusted proxy CIDR matches.rate_limit.per_ip
STRATA_RATE_LIMIT_BURST0 (= 2 × max(per_key, per_ip))int in [0, 1000000]Token-bucket burst capacity (peak above the sustained rate).rate_limit.burst
STRATA_RATE_LIMIT_CACHE_SIZE100000int in [1000, 10000000]LRU cap for the per-(key|IP) limiter entries. Eviction on full forgets the bucket; the next hit for that client gets a fresh token bucket.rate_limit.cache_size
STRATA_VHOST_PATTERN*.s3.localcomma-separated *.<suffix>; - to disableVirtual-hosted-style routing. CLI: --vhost-pattern.vhost.pattern
STRATA_TRUSTED_PROXIESemptycomma-separated CIDR list (IPv4 / IPv6)Upstream proxies allowed to set X-Forwarded-* / X-Real-IP. Default empty → forwarded headers ignored (safe for direct exposure). Set to your ingress / LB source range when fronting Strata with a TLS terminator (US-007 harden-gateway).trusted_proxies
STRATA_LOG_LEVELINFODEBUG | INFO | WARN | ERRORslog handler level. CLI: --log-level.logging.level
STRATA_LOG_FORMATjsonjson | textslog handler format.logging.format
STRATA_NODE_IDhostname-derivedstringReplica identity, stamped on heartbeats + leader leases.node.id
STRATA_WORKERSemptycomma listWorkers to run on this replica (gc,lifecycle,...). CLI: --workers=. Unknown names exit 2 at startup.workers.enabled
STRATA_CONFIG_FILEemptypathOptional TOML config; env vars + CLI flags layer on top.—
STRATA_VERSIONemptystringVersion label overridden at build time; surfaced via /version + admin metadata.—
STRATA_CLUSTER_NAMEemptystringLogical cluster name surfaced to the admin console.cluster.name
STRATA_PROMETHEUS_URLemptyURLPromQL endpoint for hot-bucket / lag / metrics dashboards. Unset → admin reports metrics_available=false.prometheus.url
STRATA_PPROF_ENABLEDfalseboolMaster switch for /debug/pprof/* (US-004 prod-observability). Opt-in even when admin listener set — heap profiles may leak in-flight buffer contents.pprof.enabled
STRATA_PPROF_LISTENemptyhost:portOptional dedicated pprof listener (e.g. 127.0.0.1:9002). Empty + STRATA_PPROF_ENABLED=true → handlers attach to STRATA_ADMIN_LISTEN. Boot fails when both empty.pprof.listen
STRATA_PPROF_BLOCK_RATE0intruntime.SetBlockProfileRate(N) argument. 0 keeps block profile data empty.pprof.block_rate
STRATA_PPROF_MUTEX_RATE0intruntime.SetMutexProfileFraction(N) argument. 0 keeps mutex profile data empty.pprof.mutex_rate
STRATA_PROM_PUSHGATEWAYemptyURLPushgateway target for strata admin bench-* throughput gauges.—
STRATA_ALERTMANAGER_URLemptyURLstrata admin slo-report Alertmanager target (lists active SLO-labelled alerts). CLI default; not server config.—
STRATA_AUDIT_RETENTION720h (30d)Go duration or <N>dRow TTL on audit_log. See audit log retention.audit_log.retention
STRATA_MANIFEST_FORMATprotoproto | jsonWrite-format for objects.manifest. Read path sniffs both.manifest.format
STRATA_MFA_SECRETSemptyserial:base32,...Optional TOTP secrets for MFA Delete; see auth.mfa.secrets
STRATA_STORAGE_HEALTH_OVERRIDEemptyhealthy | degraded | downAdmin-console health override for canary deploys.—
STRATA_ADMIN_ENDPOINThttp://localhost:9000URLstrata admin <subcmd> client target.—
STRATA_ADMIN_PRINCIPALemptystringTest harness — populates X-Test-Principal on admin CLI calls.—
STRATA_BUCKETSTATS_INTERVALunset → 1hGo durationBucketstats sampler cadence. Sub-second values accepted for e2e.bucket_stats.interval
STRATA_BUCKETSTATS_TOPN100positive intTop-N cap for the per-shard distribution sampler.bucket_stats.top_n

Meta backend — Cassandra / ScyllaDB#

ScyllaDB is a CQL-compatible drop-in for Cassandra; the same envs apply. See Concepts — workers and Architecture — meta-store for the meta-backend contract.

VariableDefaultRangeNotesTOML key
STRATA_CASSANDRA_HOSTS127.0.0.1comma-separated host listContact points.cassandra.hosts
STRATA_CASSANDRA_KEYSPACEstratastringKeyspace name; created at boot if missing.cassandra.keyspace
STRATA_CASSANDRA_DCdatacenter1stringLocal datacenter for LOCAL_QUORUM routing.cassandra.local_dc
STRATA_CASSANDRA_REPLICATION{'class': 'SimpleStrategy', 'replication_factor': '1'}CQL replication strategyUsed only when the keyspace is created by strata.cassandra.replication
STRATA_CASSANDRA_USERemptystringAuth user.cassandra.username
STRATA_CASSANDRA_PASSWORDemptystringAuth password.cassandra.password
STRATA_CASSANDRA_TIMEOUT10sGo durationPer-query timeout.cassandra.timeout
STRATA_CASSANDRA_SLOW_MS100positive int (ms)Slow-query WARN threshold for the Cassandra query observer.cassandra.slow_ms
STRATA_CASSANDRA_LIST_CONCURRENCY16int [1, 256]Per-request shard fan-out cap for ListObjects / ListObjectVersions. Bounds gocql connections/goroutines regardless of a bucket’s shard count (US-012). 0/unset → 16; above 256 clamps.cassandra.list_concurrency
STRATA_CASSANDRA_TLS_CA_FILEemptypathPEM CA bundle for server-cert verification. Empty → system root pool (when any TLS field is set) or plain-TCP (when all TLS fields unset).cassandra.tls.ca_file
STRATA_CASSANDRA_TLS_CERT_FILEemptypathPEM client certificate for mutual TLS. Must be paired with STRATA_CASSANDRA_TLS_KEY_FILE.cassandra.tls.cert_file
STRATA_CASSANDRA_TLS_KEY_FILEemptypathPEM private key matching STRATA_CASSANDRA_TLS_CERT_FILE.cassandra.tls.key_file
STRATA_CASSANDRA_TLS_SKIP_VERIFYfalseboolDisables server-cert verification (sets tls.Config.InsecureSkipVerify + gocql.SslOptions.EnableHostVerification=false). Bumps strata_backend_tls_skip_verify{backend="cassandra"}=1 and logs a WARN at boot. Never set in production.cassandra.tls.skip_verify

Meta backend — TiKV#

See Architecture — backends/TiKV for the meta-backend contract + range-scan short-circuit.

VariableDefaultRangeNotesTOML key
STRATA_TIKV_PD_ENDPOINTSemptycomma-separated PD addrsRequired when STRATA_META_BACKEND=tikv.tikv.pd_endpoints
STRATA_TIKV_TLS_CA_FILEemptypathPEM CA bundle for server-cert verification. Required when any other STRATA_TIKV_TLS_* knob is set (tikv-client-go’s Security.ToTLSConfig short-circuits on empty ClusterSSLCA). Empty all-four → plain-gRPC.tikv.tls.ca_file
STRATA_TIKV_TLS_CERT_FILEemptypathPEM client certificate for mutual TLS. Must be paired with STRATA_TIKV_TLS_KEY_FILE.tikv.tls.cert_file
STRATA_TIKV_TLS_KEY_FILEemptypathPEM private key matching STRATA_TIKV_TLS_CERT_FILE.tikv.tls.key_file
STRATA_TIKV_TLS_SKIP_VERIFYfalseboolDisables server-cert verification on the PD HTTP control plane. Bumps strata_backend_tls_skip_verify{backend="tikv"}=1 and logs a WARN at boot. Never set in production.tikv.tls.skip_verify
STRATA_GC_DUAL_WRITEonon | offDual-write the legacy + denormalised GC tables. Flipped off after a migration cycle drains the legacy queue. Applies to Cassandra + TiKV.workers.gc.dual_write

Data backend — RADOS#

See Architecture — data-backend.

VariableDefaultRangeNotesTOML key
STRATA_RADOS_CONF/etc/ceph/ceph.confpathceph.conf for the implicit default cluster.rados.config_file
STRATA_RADOS_USERadminshort user idclient.<id> resolved via go-ceph.NewConnWithUser.rados.user
STRATA_RADOS_KEYRINGemptypathKeyring override (defaults to [client.<user>] in ceph.conf).rados.keyring
STRATA_RADOS_POOLstrata.rgw.buckets.datapool nameDefault data pool.rados.pool
STRATA_RADOS_NAMESPACEemptystringOptional RADOS namespace prefix.rados.namespace
STRATA_RADOS_CLASSESempty<class>=<pool>,...Per-storage-class pool override map.rados.classes
STRATA_RADOS_CLUSTERSempty<id>:<conf-path>:<keyring-path>,...Multi-cluster connection specs. The implicit default cluster uses the single-cluster envs above.rados.clusters
STRATA_RADOS_PUT_CONCURRENCY32[1, 256]Parallel chunk-PUT bound. See parallel chunks tuning.rados.put_concurrency
STRATA_RADOS_GET_PREFETCH4[1, 64]GET-path prefetch depth. See parallel chunks tuning.rados.get_prefetch
STRATA_RADOS_HEALTH_OIDstrata-readyz-canaryRADOS OIDCanary object stat’d by /readyz. Internal — debug only.rados.health_oid
STRATA_RADOS_POOL_SIZE1[1, 32]Per-cluster connection-pool depth.rados.pool_size
STRATA_RADOS_BATCH_OPSfalsetrue | falseToggle WriteOp/ReadOp batched helpers.rados.batch_ops

Data backend — S3 pass-through#

VariableDefaultRangeNotesTOML key
STRATA_S3_CLUSTERSemptyJSON array of S3ClusterSpecRequired when STRATA_DATA_BACKEND=s3. See S3 multi-cluster routing.s3.clusters
STRATA_S3_CLASSESemptyJSON object of ClassSpecRequired when STRATA_DATA_BACKEND=s3. See S3 multi-cluster routing.s3.classes
STRATA_S3_TLS_CA_FILEemptyPEM pathS3-upstream mTLS — PEM-encoded CA bundle for server-cert validation. Global default; per-cluster tls.ca_file on STRATA_S3_CLUSTERS overrides outright.s3.tls.ca_file
STRATA_S3_TLS_CERT_FILEemptyPEM pathS3-upstream mTLS — PEM-encoded client certificate. Paired with STRATA_S3_TLS_KEY_FILE; half-pair rejected at boot.s3.tls.cert_file
STRATA_S3_TLS_KEY_FILEemptyPEM pathS3-upstream mTLS — PEM-encoded client private key. Paired with STRATA_S3_TLS_CERT_FILE.s3.tls.key_file
STRATA_S3_TLS_SKIP_VERIFYfalseboolDisable server-cert validation on the S3-upstream client. Bumps strata_backend_tls_skip_verify{backend="s3",cluster=<id>}=1 for every cluster that resolves to this bundle. Never set in production.s3.tls.skip_verify

Auth + admin console#

See Architecture — auth and Best practices — operator console.

VariableDefaultRangeNotesTOML key
STRATA_AUTH_MODEoffoff | disabled | required | optionalSigV4 enforcement mode.auth.mode
STRATA_STATIC_CREDENTIALSemptyak:sk,...Static credential store (bootstrap before IAM is populated).auth.static_credentials
STRATA_STS_DURATION1hGo duration ∈ [15m, 12h]Default AssumeRole TTL when the client omits DurationSeconds. Out-of-range values clamp + WARN.auth.sts_duration
STRATA_CONSOLE_JWT_SECRETemptyhex 32 bytesAdmin-console session signing key. Empty → ephemeral 32-byte secret (sessions invalidate on restart).console.jwt_secret
STRATA_JWT_SECRET_FILE/etc/strata/jwt-secretpathOn-disk JWT secret read at boot. Lower precedence than STRATA_CONSOLE_JWT_SECRET.jwt.secret_file
STRATA_JWT_SHAREDemptypathShared JWT secret mount for cross-replica session validation (multi-replica labs).jwt.shared_file
STRATA_CONSOLE_THEME_DEFAULTsystemsystem | light | darkAdmin-console default theme.console.theme_default

SSE + KMS + master keys#

See Best practices — compliance for the operator workflow and Architecture — auth for the SSE wrap + KMS provider contract.

Precedence inside the master-key resolver: STRATA_SSE_MASTER_KEYS > STRATA_SSE_MASTER_KEY_VAULT > STRATA_SSE_MASTER_KEY_FILE > STRATA_SSE_MASTER_KEY.

VariableDefaultRangeNotesTOML key
STRATA_SSE_MASTER_KEYSempty<id>:<hex64>,...Rotation provider (active = first). Required for strata admin rewrap.sse.master_keys
STRATA_SSE_MASTER_KEYemptyhex 64Single static master key.sse.master_key
STRATA_SSE_MASTER_KEY_IDemptystringIdentifier paired with the static key.sse.master_key_id
STRATA_SSE_MASTER_KEY_FILEemptypathFile-backed master key with mtime hot-reload.sse.master_key_file
STRATA_SSE_MASTER_KEY_VAULTempty<addr>:<transit-export-path>Vault Transit-export provider.sse.master_key_vault
STRATA_SSE_VAULT_ROLE_IDemptystringAppRole role id (shared with STRATA_KMS_VAULT_*).kms.vault.role_id
STRATA_SSE_VAULT_SECRET_IDemptystringAppRole secret id (shared with STRATA_KMS_VAULT_*).kms.vault.secret_id
STRATA_KMS_ADAPTERemptyvault | aws | local_hsmExplicit SSE-KMS provider; empty falls back to auto-precedence (vault > aws > local_hsm).kms.adapter
STRATA_KMS_AWS_REGIONemptyAWS regionEnables AWS KMS provider; SDK client factory must also be wired.kms.aws.region
STRATA_KMS_AWS_ENDPOINTemptyURLOptional custom AWS KMS endpoint (LocalStack/moto).kms.aws.endpoint
STRATA_KMS_AWS_ROLE_ARNemptyARNOptional STS assume-role for KMS client credentials.kms.aws.role_arn
STRATA_KMS_LOCAL_HSM_SEEDemptyhex 32Deterministic local HSM stand-in for tests. Internal — debug only.kms.local_hsm.seed
STRATA_KMS_VAULT_ADDRemptyURLVault Transit endpoint.kms.vault.address
STRATA_KMS_VAULT_PATHemptystringVault Transit mount path (e.g. transit).kms.vault.mount
STRATA_KMS_VAULT_TOKENemptystringOptional static Vault token; alternative to AppRole.kms.vault.token
STRATA_DEK_CACHE_TTL5mGo duration ∈ [30s, 1h]TTL for the per-bucket signing-key DEK cache on the SigV4 hot path (US-001 auth-dx-trailer-lima). Plaintext DEK is zeroed via subtle.ConstantTimeCopy on eviction. Out-of-range values clamp + WARN.kms.dek_cache_ttl
STRATA_KEY_MAX_AGE2160h (90d)Go duration ∈ [24h, 8760h]Max age for a per-bucket signing key before the SigV4 path rejects requests with 401 KeyExpired (US-002 auth-dx-trailer-lima). Operator must POST /admin/v1/buckets/{name}/signing-key/rotate to recover. Default 90 days matches PCI-DSS / SOX rotation policy; out-of-range values clamp + WARN.auth.key_max_age
STRATA_KMS_DEFAULT_KEY_IDemptyKMS CMK handleDefault CMK applied by POST /signing-key/rotate when the operator omits key_id (US-002). Empty falls back to the bucket name (works for AWS KMS aliases + Vault Transit).kms.default_key_id

GC worker (--workers=gc)#

See Best practices — GC & lifecycle tuning.

VariableDefaultRangeNotesTOML key
STRATA_GC_INTERVAL30sGo durationTick cadence.workers.gc.interval
STRATA_GC_GRACE5mGo durationGrace before a queued chunk is eligible for delete.workers.gc.grace
STRATA_GC_BATCH_SIZE0 (backend default)non-negative intPer-tick batch cap; 0 uses the meta backend’s preferred batch size.workers.gc.batch_size
STRATA_GC_CONCURRENCY1positive intPer-shard delete workers.workers.gc.concurrency
STRATA_GC_SHARDS1[1, 1024]Fan-out shard count (also drives lifecycle leader-replica selection). Out-of-range → clamped + WARN at boot.workers.gc.shards
STRATA_GC_METRICS_LISTEN:9100host:portLegacy GC metrics listener (subsumed by the main gateway exporter).workers.gc.metrics_listen

Lifecycle worker (--workers=lifecycle)#

See Best practices — GC & lifecycle tuning.

VariableDefaultRangeNotesTOML key
STRATA_LIFECYCLE_INTERVAL60sGo durationTick cadence.workers.lifecycle.interval
STRATA_LIFECYCLE_UNITdayday | hour (test fixtures may inject other values)Granularity for Days/Date evaluation.workers.lifecycle.unit
STRATA_LIFECYCLE_CONCURRENCY1positive intPer-tick transition/expire workers.workers.lifecycle.concurrency
STRATA_LIFECYCLE_METRICS_LISTEN:9101host:portLegacy lifecycle metrics listener.workers.lifecycle.metrics_listen

Rebalance worker (--workers=rebalance)#

See Placement & rebalance.

VariableDefaultRangeNotesTOML key
STRATA_REBALANCE_INTERVAL5m[1m, 24h]Tick cadence; out-of-range → clamped.workers.rebalance.interval
STRATA_REBALANCE_RATE_MB_S100[1, 10000]Token-bucket budget (read+write share the same bucket).workers.rebalance.rate_mb_s
STRATA_REBALANCE_INFLIGHT4[1, 64]Per-Move errgroup bound.workers.rebalance.inflight
STRATA_REBALANCE_SHARDS1[1, 1024]Per-shard leader-elected fan-out count.workers.rebalance.shards

Notify worker (--workers=notify)#

See Concepts — workers.

VariableDefaultRangeNotesTOML key
STRATA_NOTIFY_TARGETSemptytype:arn=<url>|<secret>,...Required when worker is enabled.workers.notify.targets
STRATA_NOTIFY_INTERVAL5sGo durationPoll cadence.workers.notify.interval
STRATA_NOTIFY_MAX_RETRIES6non-negative intRetry cap before DLQ.workers.notify.max_retries
STRATA_NOTIFY_BACKOFF_BASE1sGo durationExponential-backoff base.workers.notify.backoff_base
STRATA_NOTIFY_POLL_LIMIT100positive intPer-poll row cap.workers.notify.poll_limit

Replicator worker (--workers=replicator)#

See Concepts — workers.

VariableDefaultRangeNotesTOML key
STRATA_REPLICATOR_INTERVAL5sGo durationPoll cadence.workers.replicator.interval
STRATA_REPLICATOR_MAX_RETRIES6non-negative intRetry cap before DLQ.workers.replicator.max_retries
STRATA_REPLICATOR_BACKOFF_BASE1sGo durationExponential-backoff base.workers.replicator.backoff_base
STRATA_REPLICATOR_POLL_LIMIT100positive intPer-poll row cap.workers.replicator.poll_limit
STRATA_REPLICATOR_HTTP_TIMEOUT30sGo durationPer-request peer HTTP timeout.workers.replicator.http_timeout
STRATA_REPLICATOR_PEER_SCHEMEhttpshttp | httpsPeer URL scheme.workers.replicator.peer_scheme

Access-log worker (--workers=access-log)#

See Concepts — workers.

VariableDefaultRangeNotesTOML key
STRATA_ACCESS_LOG_INTERVAL5mGo durationFlush cadence.workers.access_log.interval
STRATA_ACCESS_LOG_MAX_FLUSH_BYTES5242880 (5 MiB)positive int64Per-flush bytes cap.workers.access_log.max_flush_bytes
STRATA_ACCESS_LOG_POLL_LIMIT10000positive intPer-poll row cap.workers.access_log.poll_limit

Inventory worker (--workers=inventory)#

See Concepts — workers.

VariableDefaultRangeNotesTOML key
STRATA_INVENTORY_INTERVAL5mGo durationTick cadence.workers.inventory.interval
STRATA_INVENTORY_REGIONdeps.Region fallbackstringRegion tag for target-bucket writes.workers.inventory.region

Audit-export worker (--workers=audit-export)#

See Best practices — compliance.

VariableDefaultRangeNotesTOML key
STRATA_AUDIT_EXPORT_BUCKETemptybucket nameRequired when worker is enabled.workers.audit_export.bucket
STRATA_AUDIT_EXPORT_PREFIXemptyobject-key prefixOptional path prefix inside the export bucket.workers.audit_export.prefix
STRATA_AUDIT_EXPORT_AFTER720h (30d)Go durationDrain partitions older than this.workers.audit_export.after
STRATA_AUDIT_EXPORT_INTERVAL24hGo durationTick cadence.workers.audit_export.interval

Manifest-rewriter worker (--workers=manifest-rewriter)#

See Concepts — workers.

VariableDefaultRangeNotesTOML key
STRATA_MANIFEST_REWRITER_INTERVAL24hGo durationTick cadence.workers.manifest_rewriter.interval
STRATA_MANIFEST_REWRITER_BATCH_LIMIT500positive intPer-tick rewrite cap.workers.manifest_rewriter.batch_limit
STRATA_MANIFEST_REWRITER_DRY_RUNfalsetrue | falseSkip the write phase; log diffs only.workers.manifest_rewriter.dry_run

Reshard worker (--workers=reshard)#

Leader-elected background worker that drains queued online-reshard jobs (POST /admin/bucket/reshard). Idempotent + resumable from each job’s LastKey watermark, so a crash mid-job is recovered on the next tick. Cassandra does the physical row migration; memory/TiKV are shard-agnostic (immediate-complete no-op). Enable on at least one replica.

VariableDefaultRangeNotesTOML key
STRATA_RESHARD_INTERVAL30sGo duration [1s, 1h]Poll cadence between drain passes.workers.reshard.interval
STRATA_RESHARD_BATCH_LIMIT500positive intObject-walk page size; a crash resumes from the last watermark.workers.reshard.batch_limit

Quota-reconcile worker (--workers=quota-reconcile)#

See Quotas + billing.

VariableDefaultRangeNotesTOML key
STRATA_QUOTA_RECONCILE_INTERVAL6hGo durationTick cadence.workers.quota_reconcile.interval

Usage-rollup worker (--workers=usage-rollup)#

See Quotas + billing.

VariableDefaultRangeNotesTOML key
STRATA_USAGE_ROLLUP_INTERVAL24hGo durationTick cadence.workers.usage_rollup.interval
STRATA_USAGE_ROLLUP_AT00:00 (UTC)HH:MMAnchor time for the daily rollup.workers.usage_rollup.at
STRATA_USAGE_ROLLUP_SAMPLES_PER_DAY24positive intSamples emitted per UTC day per (bucket, storage_class).workers.usage_rollup.samples_per_day

Tracing (OpenTelemetry)#

See Tracing best-practices.

VariableDefaultRangeNotesTOML key
STRATA_OTEL_EXPORTER_ENDPOINTemptyURLOverrides OTEL_EXPORTER_OTLP_ENDPOINT. Empty + ringbuf=false → no-op tracer provider.otel.endpoint
STRATA_OTEL_SAMPLE_RATIO0.01[0, 1]Tail sampler ratio; failing spans always export.otel.sample_ratio
STRATA_OTEL_RINGBUFonon | offIn-process span ring buffer (powers /admin/v1/diagnostics/trace).otel.ringbuf
STRATA_OTEL_RINGBUF_BYTES4194304 (4 MiB)[1 MiB, 1 GiB]Ring-buffer byte budget.otel.ringbuf_bytes

The standard W3C OTEL_EXPORTER_OTLP_ENDPOINT controls OTLP/HTTP export (unset disables export entirely). STRATA_OTEL_EXPORTER_ENDPOINT / [otel].endpoint take precedence when set.

Retired / legacy#

VariableStatusNotesTOML key
STRATA_DRAIN_STRICTRetiredUS-007 made drain unconditionally strict. WARN-logged at boot if set; ignored.—
STRATA_S3_BACKEND_* (_ENDPOINT, _REGION, _BUCKET, _ACCESS_KEY, _SECRET_KEY, _FORCE_PATH_STYLE, _PART_SIZE, _UPLOAD_CONCURRENCY, _MAX_RETRIES, _OP_TIMEOUT_SECS, _MULTIPART_TIMEOUT_SECS, _SSE_MODE, _SSE_KMS_KEY_ID)Retired in ralph/s3-multi-clusterReplaced by STRATA_S3_CLUSTERS + STRATA_S3_CLASSES. Boot fails loud if the legacy envs are still set without the JSON replacements.—

Test-only#

VariableNotesTOML key
STRATA_TIKV_TEST_PD_ENDPOINTSOperator-provided PD endpoints for TiKV integration tests (bypasses testcontainers).—
STRATA_SCYLLA_TEST / STRATA_SCYLLA_IMAGEGates + image override for the ScyllaDB contract suite.—
STRATA_CASSANDRA_IMAGE / STRATA_CASSANDRA_MAX_HEAP / STRATA_CASSANDRA_NEW_HEAPImage override + JVM heap sizing for the Cassandra integration testcontainer (US-010 CI gate).—
STRATA_TEST_AK / STRATA_TEST_SKStatic AK/SK pair consumed by the S3 multi-cluster contract suite via CredentialsEnv.—
STRATA_TEST_CEPH_CONF / STRATA_TEST_CEPH_POOL / STRATA_TEST_CEPH_CLASSESRADOS integration-test cluster wiring.—
STRATA_TEST_REBALANCE_SRC_POOL / STRATA_TEST_REBALANCE_TGT_POOLRADOS rebalance mover integration-test pools.—
Edit Edit this page
Backward Reference Admin API surface Forward