ReductStore Settings

ReductStore can be configured using environment variables. The following sections describe the available settings and how to use them.

Remote Backend Settings

ReductStore supports using a remote object storage as a backend to store data.

Common settings

These settings are common for all supported remote backends:

Name	Default	Description
RS_REMOTE_BACKEND_TYPE	File system	Remote backend type: s3 or azure.
RS_REMOTE_ENDPOINT		Object storage endpoint URL. Optional for public clouds; required for custom endpoints (MinIO/Azurite).
RS_REMOTE_BUCKET		Storage container name. For s3 this is a bucket; for azure this is a container. Must exist first.
RS_REMOTE_CACHE_PATH		Path to a local cache folder used before upload and for hot reads.
RS_REMOTE_CACHE_SIZE	1GB	Maximum size of local cache. Oldest data is removed when the limit is reached.
RS_REMOTE_SYNC_INTERVAL	0.1, 60 for S3 and Azure	Synchronization interval with the remote backend in seconds.

Backend-specific settings

Every remote backend has its own specific settings. The following table describes the settings for S3 and Azure backends:

Name	S3	Azure
RS_REMOTE_REGION	S3 region (for example, us-east-1).	Not used.
RS_REMOTE_ACCESS_KEY	Access key ID. Optional when using the AWS default credential provider chain.	Storage account name.
RS_REMOTE_SECRET_KEY	Secret access key. Optional when using the AWS default credential provider chain.	Storage account key. Optional if RS_REMOTE_SAS_TOKEN is set.
RS_REMOTE_SESSION_TOKEN	Optional session token for temporary credentials.	Not used.
RS_REMOTE_SAS_TOKEN	Not used.	Optional SAS token. Use with RS_REMOTE_ACCESS_KEY=<storage-account-name>.

By default, ReductStore uses the local file system to store data. To use a remote backend, set RS_REMOTE_BACKEND_TYPE to s3 or azure and configure the other variables accordingly. When the remote backend is enabled, ReductStore caches data in the folder specified by the RS_REMOTE_CACHE_PATH variable, thereby reducing the number of requests made to the remote backend. The RS_DATA_PATH variable is ignored when the remote backend is enabled.

Default AWS Credentials

For Amazon S3, you can omit RS_REMOTE_ACCESS_KEY and RS_REMOTE_SECRET_KEY entirely and let the AWS SDK resolve credentials from its default provider chain. In this case, you can use any supported authentication method (e.g., environment variables starting with AWS_, EC2 instance roles, or ECS task roles) without needing to configure ReductStore specifically for AWS.

For end-to-end deployment examples (standalone, active-passive, and read-only replicas) using cloud storage, see the Cloud Storage integration guide.

Zenoh API Settings

ReductStore includes an optional Zenoh API that lets you ingest and retrieve data using the Zenoh pub/sub and query protocol alongside the existing HTTP API. The following environment variables configure it:

Name	Default	Description
RS_ZENOH_ENABLED	false	Set to true, 1, yes, or on to enable the Zenoh API
RS_ZENOH_CONFIG		Inline Zenoh session config string, e.g. mode=client;connect/endpoints=[tcp/127.0.0.1:7447]. Takes precedence over RS_ZENOH_CONFIG_PATH
RS_ZENOH_CONFIG_PATH		Path to a Zenoh JSON5 config file
RS_ZENOH_BUCKET	zenoh	Target ReductStore bucket. Created automatically if it does not exist.
RS_ZENOH_SUB_KEYEXPRS		Key expression for the subscriber (write path). Disabled if unset.
RS_ZENOH_QUERY_KEYEXPRS		Key expression for the queryable (read path). Disabled if unset.
RS_ZENOH_QUERY_LOCALITY	Any	Allowed origin for query replies. One of SessionLocal, Remote, or Any.

Inline Zenoh Credentials

When using TLS or user-password authentication with RS_ZENOH_CONFIG, Zenoh normally requires file paths for certificates and dictionaries. These variables let you supply the file contents directly as environment variables instead. This is useful in Docker or Kubernetes environments where mounting files is inconvenient. Each value is written to a temporary file at startup and its path is injected into the Zenoh session config automatically.

Name	Default	Description
RS_ZENOH_TLS_ROOT_CA		PEM content of the root CA certificate used to verify the Zenoh router or peer (transport/link/tls/root_ca_certificate)
RS_ZENOH_TLS_CONNECT_CERT		PEM content of the client certificate for mutual TLS (transport/link/tls/connect_certificate)
RS_ZENOH_TLS_CONNECT_KEY		PEM content of the client private key for mutual TLS (transport/link/tls/connect_private_key)
RS_ZENOH_AUTH_DICTIONARY		User-password dictionary content, one user:password entry per line (transport/auth/usrpwd/dictionary_file)

For usage examples, deployment patterns, and a full explanation of key expressions, selectors, and encoding, see the Zenoh API integration guide.

Instance Rate Limiting Settings

ReductStore can enforce rate limits for both HTTP and Zenoh APIs. Limits are optional and disabled by default. The limits are applied per connection (IP address) for HTTP API and per instance for Zenoh API. The following table describes the available environment variables for rate limiting:

Name	Default	Description
RS_RATE_LIMIT_API		Maximum API request rate. Example: 100req/s, 100000req/h, or 1000 (defaults to per hour).
RS_RATE_LIMIT_INGRESS		Maximum ingress throughput (writes). Example: 10MB/s, 10GB/h, or 500MB (defaults to per hour).
RS_RATE_LIMIT_EGRESS		Maximum egress throughput (reads/replies). Example: 50MB/s, 1GB/m, or 2GB (defaults to per hour).

Rate format: <amount>/<period>.

• amount:
  • RS_RATE_LIMIT_API: number of requests (optional req suffix)
  • RS_RATE_LIMIT_INGRESS and RS_RATE_LIMIT_EGRESS: byte size (for example KB, MB, GB)
• period: duration such as s, m, h, ms (or full duration strings like 60s)
• if /period is omitted, ReductStore treats the limit as per hour

When a limit is exceeded, ReductStore returns 429 Too Many Requests with a retry hint in the error details.

I/O Settings

In addition to general settings, you can configure I/O settings to optimize communication over HTTP with the storage engine. The following table describes the available environment variables:

Name	Default	Description
RS_IO_BATCH_MAX_SIZE	8MB	Maximum size of a batch of records sent to the client.
RS_IO_BATCH_MAX_RECORDS	85	Maximum number of records in a batch sent and received from the client.
RS_IO_BATCH_MAX_METADATA_SIZE	8KB	Maximum size of metadata in a batch of records sent and received from the client.
RS_IO_BATCH_TIMEOUT	5	Maximum time in seconds for a batch of records to be prepared and sent to the client. If the batch is not full, it will be sent after the timeout.
RS_IO_BATCH_RECORD_TIMEOUT	1	Maximum time in seconds to wait for a record to be added to a batch. If the record is not added, the unfinished batch will be sent to the client.
RS_IO_OPERATION_TIMEOUT	60	Maximum time in seconds for an I/O operation (e.g., read or write). If the operation takes longer, it will be aborted.
RS_IO_MAX_WRITERS_IN_FLIGHT		Optional maximum number of storage write operations that can run at the same time. Positive integers enable the limit; unset or 0 disables it.

Most of the I/O settings are related to batching and specify the size of the batch, the number of records in the batch, and the timeout for preparing and sending the batch on the server side.

The in-flight writer limit is optional and disabled by default. It is useful for exposed or multi-tenant deployments where you need to bound concurrent storage writes and protect disk or remote-backend resources from overload. If all writer slots are busy, ReductStore waits up to RS_IO_OPERATION_TIMEOUT; if no slot becomes available, the request fails with 429 Too Many Requests.

However, if a client is using the HTTP/1.1 protocol, the RS_IO_BATCH_MAX_METADATA_SIZE and RS_IO_BATCH_MAX_RECORDS settings are used to limit the size of the headers in the HTTP request from the client. This means that the client can't send more records in a single batch than specified by the RS_IO_BATCH_MAX_RECORDS and the size of the headers in the request can't exceed the value of the RS_IO_BATCH_MAX_METADATA_SIZE setting.

Read more about batching in the HTTP API Reference.

Lock File Settings

ReductStore uses a lock file to prevent multiple instances from accessing the same data folder. The lock file is created in the data folder specified by the RS_DATA_PATH variable, using the same storage backend as the data. You can configure the lock file settings using the following environment variables:

Name	Default	Description
RS_LOCK_FILE_POLLING_INTERVAL	10	Interval in seconds between attempts to acquire the lock file or rewrite the acquired lock file to update its timestamp.
RS_LOCK_FILE_TTL	30	Time-to-live in seconds for the lock file. If the lock file is not updated within the TTL, it is considered stale and can be overwritten by another instance.
RS_LOCK_FILE_TIMEOUT	60	Timeout in seconds for acquiring the lock file. If the lock file is not acquired within the timeout, the storage will exit. When set to 0, the storage will wait indefinitely.
RS_LOCK_FILE_FAILURE_ACTION	abort	Action to take if the lock file can't be acquired. It can be abort or proceed. If set to abort, the storage will exit. If set to proceed, the storage will overwrite the lock file and continue.

The lock file is enabled when the RS_INSTANCE_ROLE variable is set to PRIMARY or SECONDARY. If the variable is not set, the lock file mechanism is disabled.

Storage Engine Settings

A user can configure storage engine settings to change behavior of data storage and retrieval. The following table describes the available environment variables:

Name	Default	Description
RS_ENGINE_COMPACTION_INTERVAL	60	Interval in seconds between compaction WALs into blocks and synchronization of the storage state to the backend.
RS_ENGINE_REPLICA_UPDATE_INTERVAL	60	Interval in seconds between updates of bucket, entry lists and indexes from the backend in the read-only mode.
RS_ENGINE_ENABLE_INTEGRITY_CHECKS	true	If set to false, the storage engine skips integrity checks at startup to improve performance.
RS_ENGINE_MAX_STORAGE_SIZE		Maximum total size of all buckets. Accepts SI units (KB, MB, GB, TB), for example 500GB or 2TB. If unset or invalid, the limit is disabled.

When the configured global limit is reached, ReductStore rejects new writes across all ingestion paths (HTTP and Zenoh) with a 500 Internal Server Error and a storage limit exceeded message.

Replication Settings

ReductStore supports data replication between different instances. You can configure replication settings using the following environment variables:

Name	Default	Description
RS_REPLICATION_TIMEOUT	5	Timeout in seconds for attempts to reconnect to the target server.
RS_REPLICATION_LOG_SIZE	1000000	Maximum number of pending records in the replication log. The oldest records are overwritten when the limit is reached.
RS_REPLICATION_VERIFY_SSL	true	If set to false, the replication client skips TLS certificate verification for destination instances.
RS_REPLICATION_CA_PATH		Path to a PEM-encoded CA certificate used to verify destination TLS certificates during replication.

Audit Settings

ReductStore can persist aggregated API interactions in the $audit system bucket. You can configure audit behavior with the following environment variables:

Name	Default	Description
RS_AUDIT_ENABLED	auto	Enable or disable audit collection and persistence. If unset, audit defaults to true when RS_API_TOKEN is set, otherwise false. When false, ReductStore skips audit writes.
RS_AUDIT_QUOTA_SIZE		Optional size limit for the $audit bucket (for example 1GB, 500MB). When set, $audit uses FIFO eviction.
RS_AUDIT_REMOTE_VERIFY_SSL	true	For replica audit forwarding over HTTPS: verify TLS certificates of remote nodes.
RS_AUDIT_REMOTE_CA_PATH		For replica audit forwarding: path to a PEM-encoded CA certificate used to verify remote TLS certificates.
RS_AUDIT_REMOTE_TIMEOUT	5	Timeout in seconds for replica audit HTTP communication with primary/secondary nodes.

Notes:

• If RS_AUDIT_ENABLED is unset, audit defaults to true when RS_API_TOKEN is set, otherwise false.
• RS_AUDIT_ENABLED explicitly overrides the token-based default.
• RS_AUDIT_QUOTA_SIZE is applied only when audit is enabled.
• If RS_AUDIT_QUOTA_SIZE is unset, $audit capacity is unlimited.