Configuration reference

This reference describes the Clustron Zaris store configuration file — the on-disk settings that define a cluster and its behavior — and the smaller client configuration an application uses to connect. Every setting has a default, so a minimal store file is just a cluster id, a node list, and a replication factor.

The store schema is published at https://schemas.clustron.io/zaris/v1/store.schema.json; referencing it with a $schema property enables autocomplete and validation in editors that support it.

Store configuration

The store file is Zaris-owned and uses Zaris's own naming. A minimal file looks like this:

{
  "$schema": "https://schemas.clustron.io/zaris/v1/store.schema.json",
  "clusterId": "orders",
  "nodes": [
    { "id": "10.0.0.11-n0", "host": "10.0.0.11", "clusterPort": 7811, "clientPort": 7861 }
  ],
  "replication": { "factor": 1 }
}

A complete example

Everything except clusterId, nodes, and replication.factor has a default, so you only set what you want to change. The file below shows every section in its place — a three-node cluster at replication factor 2 with the default values spelled out — so you can see where each setting goes. The per-section field tables that follow explain each value.

{
  "$schema": "https://schemas.clustron.io/zaris/v1/store.schema.json",
  "clusterId": "orders",
  "version": "1",
  "nodes": [
    { "id": "10.0.0.11-n0", "host": "10.0.0.11", "clusterPort": 7811, "clientPort": 7861, "preferredPrimary": true },
    { "id": "10.0.0.12-n0", "host": "10.0.0.12", "clusterPort": 7811, "clientPort": 7861 },
    { "id": "10.0.0.13-n0", "host": "10.0.0.13", "clusterPort": 7811, "clientPort": 7861 }
  ],
  "topology": { "partitionCount": null },
  "replication": { "factor": 2, "mode": "Async", "quorum": "All", "syncAckTimeoutSeconds": 5 },
  "reads": { "allowReplicaReads": false },
  "memory": { "maxSizeBytes": null },
  "runtime": {
    "partitionGroupEvictionWindowSeconds": 30,
    "runtimeSyncPeerResponseTimeoutSeconds": 2,
    "runtimeOwnershipSuspectEscalationTimeoutSeconds": 10
  },
  "membership": {
    "readinessMinNodes": 1,
    "readinessTimeoutSeconds": 30,
    "stableMembershipDurationSeconds": 3,
    "nodeGraceWindowSeconds": 30,
    "membershipStabilityWindowSeconds": 8,
    "discoveryPeerWaitSeconds": 1
  },
  "transport": { "useDuplex": true },
  "retry": { "maxAttempts": 2, "delayMilliseconds": 500 },
  "pushMetrics": { "pushTargetUrl": null, "rollingWindowSeconds": 120, "timeoutMilliseconds": 60000 },
  "logClusterViewIntervalSeconds": 10,
  "security": {
    "enabled": false,
    "issuer": "clustron://zaris",
    "publicKeys": [],
    "tls": {
      "enabled": false,
      "mode": "Off",
      "minProtocol": "Tls12",
      "peerVerification": "CaAndIdentity",
      "issuerNodeId": "",
      "ca": { "source": "Generate", "providedRootPath": "", "providedRootPasswordRef": "" },
      "lifetimes": { "caValidityDays": 3650, "leafValidityDays": 90, "renewAtFraction": 0.66, "enrollmentTokenTtlMinutes": 15 },
      "nodeCertificate": { "path": "", "passwordRef": "" },
      "trustAnchors": []
    }
  },
  "logging": {
    "logLevel": { "Default": "Information", "Microsoft": "Warning", "Clustron.Zaris": "Information" },
    "console": { "enabled": true },
    "file": { "enabled": true, "path": "logs/zaris.log", "rollingInterval": "Day" }
  },
  "telemetry": {
    "tracing": { "enabled": false, "sampleRatio": 1.0, "console": false },
    "metrics": { "enabled": null },
    "otlp": { "endpoint": "" }
  }
}

note

null is shown for topology.partitionCount and memory.maxSizeBytes to mark where those optional fields go — leaving them out applies the same defaults (one partition per node; a 1 GiB memory ceiling). Advanced knobs read from environment or raw config paths (see Environment variables and Advanced runtime tuning) are not part of this file.

Top-level fields

Field	Type	Default	Description
clusterId	string	""	The cluster's identity. Required.
version	string	"1"	Config schema version.
nodes	array	[]	The authoritative node list (see below).
logClusterViewIntervalSeconds	int	10	How often the cluster view is logged.

nodes[]

Each node is declared once and carries both of its ports, so the addressing table is complete and never repeated.

Field	Type	Default	Description
id	string	""	Node id, conventionally <host>-n<index>.
host	string	""	The node's address.
clusterPort	int	—	Peer/gossip and inter-node transport port.
clientPort	int	—	Client/data protocol port.
preferredPrimary	bool	false	Placement hint for initial primary selection.
machineId	string	host	Physical machine, used to co-locate multiple nodes on one host in supervisor mode.
roles	array	["member"]	Optional role overrides.
dataDirectory	string	derived	Optional data-directory override.

topology

Field	Type	Default	Description
partitionCount	int / null	null	Number of partitions. null means system-determined (one partition per node).

replication

Governs how many copies of the data exist and how writes acknowledge. See Partitioning and replication and Consistency.

Field	Type	Default	Description
factor	int	1	Number of copies of each partition. 1 = no replica; 2+ recommended for production.
mode	enum	Async	Async (primary returns immediately; replicas may lag) or Sync (primary waits for replicas per the quorum).
quorum	enum	All	Sync acknowledgement policy: All, Majority, or BestEffort. Only meaningful when mode is Sync.
syncAckTimeoutSeconds	int	5	How long a sync write waits for replica acknowledgement.

reads

Field	Type	Default	Description
allowReplicaReads	bool	false	When true, reads may be served by replicas (faster, potentially stale). When false, reads go to the primary.

memory

Controls the node memory ceiling. See Memory and eviction for the full model.

Field	Type	Default	Description
maxSizeBytes	long / null	null	Per-process ceiling on actively owned data. null applies the 1 GiB default. There is no unbounded setting.

runtime

Runtime timings tied to partition and ownership behavior.

Field	Type	Default	Description
partitionGroupEvictionWindowSeconds	int	30	Grace window after all members of a partition group go unavailable before the partition is evicted — its map regenerated from live members and its keyspace folded onto survivors (its in-memory data is lost). Any member returning within the window cancels the eviction. See Failure and recovery.
runtimeSyncPeerResponseTimeoutSeconds	int	2	Timeout for a peer's runtime-sync response.
runtimeOwnershipSuspectEscalationTimeoutSeconds	int	10	How long a suspected ownership issue waits before escalation.

membership

Membership and discovery timings, forwarded to the clustering layer.

Field	Type	Default	Description
readinessMinNodes	int	1	Minimum nodes before the cluster is considered ready.
readinessTimeoutSeconds	int	30	How long to wait for readiness.
stableMembershipDurationSeconds	int	3	Membership must be stable this long to settle.
nodeGraceWindowSeconds	int	30	Grace window before a missing node is acted on.
membershipStabilityWindowSeconds	int	8	Window used to judge membership stability.
discoveryPeerWaitSeconds	int	1	Wait for peers during discovery.

transport

Field	Type	Default	Description
useDuplex	bool	true	Use duplex peer connections.

retry

Connection-retry options for the clustering layer.

Field	Type	Default	Description
maxAttempts	int	2	Connection retry attempts.
delayMilliseconds	int	500	Delay between attempts.

pushMetrics

Legacy push-metrics options, distinct from telemetry. See also Monitoring.

Field	Type	Default	Description
pushTargetUrl	string / null	null	Where to push metrics.
rollingWindowSeconds	int	120	Rolling metrics window.
timeoutMilliseconds	int	60000	Push timeout.

security

Cluster-wide token security, disabled by default. The concepts are covered in the security guide; the fields and defaults are below.

Field	Type	Default	Description
enabled	bool	false	Master switch for token authentication. See Authentication and tokens.
issuer	string	clustron://zaris	Token issuer to trust.
publicKeys[].keyId	string	""	Stable id of a public signing key.
publicKeys[].spkiBase64	string	""	The key's SubjectPublicKeyInfo (DER), base64, for offline token verification.

security.tls

Transport-layer security (TLS / mTLS), cluster-wide and disabled by default. For the concepts and step-by-step setup see TLS encryption and CA trust modes.

Field	Type	Default	Description
tls.enabled	bool	false	Master switch for transport TLS.
tls.mode	enum	Off	Off, ServerAuth (client validates node certs), or MutualTls (both sides present certs).
tls.minProtocol	enum	Tls12	Minimum protocol: Tls12 or Tls13.
tls.peerVerification	enum	CaAndIdentity	CaOnly, CaAndIdentity, or FullHostname.
tls.issuerNodeId	string	""	Node that acts as the CA issuer for enrollment.
tls.ca.source	enum	Generate	Generate (Zaris creates the CA) or Provided (bring your own).
tls.ca.providedRootPath	string	""	Path to a provided CA (PKCS#12), when source is Provided.
tls.ca.providedRootPasswordRef	string	""	Reference to the provided CA's password.
tls.lifetimes.caValidityDays	int	3650	Validity of a generated CA.
tls.lifetimes.leafValidityDays	int	90	Validity of an issued node (leaf) certificate.
tls.lifetimes.renewAtFraction	double	0.66	Fraction of a leaf's lifetime after which it auto-renews.
tls.lifetimes.enrollmentTokenTtlMinutes	int	15	Lifetime of a node enrollment token.
tls.nodeCertificate.path	string	""	Path to a pre-issued node certificate (mode-dependent).
tls.nodeCertificate.passwordRef	string	""	Reference to that certificate's password.
tls.trustAnchors[]	array of {keyId, pem}	[]	Additional trust anchors to accept.

logging and telemetry

The store file's logging block configures log levels and the console/file sinks; the Telemetry section configures OpenTelemetry traces and metrics (OTLP). Both are documented in full, with every field and default, in Logging and tracing.

Advanced runtime tuning

These are power-user knobs read directly from the configuration paths below (not part of the store-file schema, so they only take effect when the path is present). Most deployments never set them; the defaults are tuned for typical clusters. Change them only with a specific reason.

Config path	Type	Default	Description
runtime:preferredPrimaryRestoreDwellSeconds	int	8	How long a returning preferred primary waits before reclaiming active ownership. ≤ 0 promotes immediately.
runtime:runtimeAntiEntropySeconds	int	15	Interval for the runtime anti-entropy sweep. ≤ 0 disables it.
runtime:maplessDigestFreshnessSeconds	int	12	Freshness window for mapless-mint peer digests.
runtime:maplessColdStabilityWindowSeconds	int	8	Cold-start stability window before a mapless mint.
runtime:maplessProvisionalBackstopSeconds	int	30	Backstop before a provisional mapless decision.

Client configuration

An application connecting to a store is configured by one connection string. The string says which transport to use, where to reach the store, which store to open, and — for a secured cluster — how to authenticate and trust it. There is no client Mode or Seeds setting; the scheme and host list of the string express those.

Connection strings live in the standard ConnectionStrings section of appsettings.json, keyed by a name you choose, exactly as with SQL Server or any other database:

{
  "ConnectionStrings": {
    "orders": "zariss://10.0.0.11:7863,10.0.0.12:7863/orders?ca=/etc/zaris/ca.pem&token=env:ZARIS_TOKEN"
  }
}

Connection string grammar

scheme://host[:port][,host[:port]...]/store[?option=value&option=value...]

Element	Required	Description
Scheme	yes	zaris for a plaintext connection, zariss to enable TLS. The trailing s is the only thing that turns TLS on.
Hosts	yes	One or more comma-separated host:port seeds. The client uses them to discover the rest of the cluster and to fail over between them. For an embedded store, use the reserved host inproc with no port.
Store	yes	The path segment is the store name, which must equal the cluster's id. Always required.
Options	no	&-separated key=value query parameters (see below).

The reserved host inproc selects an in-process (embedded) store — zaris://inproc/orders — that runs in memory inside your process. An in-process store cannot use TLS, so zariss://inproc/... is invalid.

Options

Option	Example	Description
token	token=env:ZARIS_TOKEN	Bearer token for a secured cluster. Three forms: env:VAR reads an environment variable, file:/path reads a file, or a literal token value inline. Prefer env: or file: over a literal so the secret stays out of configuration.
ca	ca=/etc/zaris/ca.pem	Path to the cluster CA (PEM) used to validate node certificates. Used with the zariss scheme.
tlsInsecure	tlsInsecure=true	Dev only — accept any node certificate without validation. Never use in production.
connectTimeoutMs	connectTimeoutMs=5000	Connection timeout in milliseconds.
requestTimeoutMs	requestTimeoutMs=5000	Per-request timeout in milliseconds.

Some client settings cannot be expressed as text in a connection string — a rotating-token callback, a client log-file path, or a fully-populated TLS options object. Supply those through the advanced registration overload's ZarisClientOptions callback (o.TokenProvider, o.LogFilePath, o.Tls); see Getting a client.

For securing a client end to end, see Connect to a secured store and the secured-client tutorial. For the equivalent in code, see Getting started: configuration.

Environment variables

Some settings are read from environment variables rather than the configuration file — chiefly client tuning, telemetry, and container-oriented node bootstrap. Set them on the relevant process (your application for the client variables; the node/host process for the rest). All have working defaults; change them only for a specific reason.

Client tuning

Read by the .NET client process. See Tuning the client.

Variable	Default	Effect
ZARIS_REQUEST_TIMEOUT	60 (s)	Per-request timeout; accepts seconds or infinite / none / 0.
ZARIS_CONNECT_TIMEOUT_MS	3000	Connection timeout in ms (min 100).
ZARIS_DISABLE_RETRIES	unset	true turns off the automatic retry loop.
ZARIS_MAX_INFLIGHT	4096	Max concurrent in-flight requests per connection.
ZARIS_CONNECTIONS	1	Connections opened per node.
ZARIS_TOKEN	unset	Bearer token used by the environment token provider on a secured cluster.

Node and host

Read by the node/host process.

Variable	Default	Effect
ZARIS_DATA_ROOT	platform default	Root directory for a node's data directory (config and certificates).
CLUSTRON_NODE_ID	derived	Overrides the node's identity.
ZARIS_MIN_THREADS	CPU count × 4	Minimum thread-pool threads.
ZARIS_MGMT_MODE	supervisor	Control-plane mode of the management service (supervisor vs attach).
ZARIS_MGMT_PORT	7801	Management port override.
ZARIS_SERVER_MAX_WORKERS	CPU count × 16 (clamped 64–1024)	Hard override (1–4096) for the node's request-dispatch worker pool width. Reads are microsecond in-memory lookups, so the pool is set wide by default to keep cores busy; raise it only if a node has spare CPU and requests are queuing.
ZARIS_SERVER_MIN_WORKERS	max(4, CPU count × 4)	Lower bound (1–4096) on the dispatch pool width.
ZARIS_OWNERSHIP_BACKBONE	1 (on)	The deterministic ownership backbone is on by default. Set ZARIS_OWNERSHIP_BACKBONE=0 to opt out (not recommended).
ZARIS_READY_FRESH_SECONDS	20 (clamped 2–600)	Freshness window (seconds) the manager's GET /health/ready uses to decide a node is "serving" — i.e. has pushed a metrics snapshot within this window. The Kubernetes chart points the console's readiness gate at /health/ready, so the web-console URL goes live only once a store is attached and a node is reporting inside this window.
ZARIS_ATTACH_STORE_NAME · _RF · _PARTITIONS · _TLS · _NODES	unset	Attach-mode self-registration. When set, the manager adopts (registers) the store on boot so it appears in the console with no manual step. _NODES is a comma-separated host:clientPort:clusterPort list. The Helm chart supplies all of these from cluster.id, the replication factor, the partition count, and the node roster (manager.attach.enabled, default on) — you don't set them by hand for a chart deploy.
ZARIS_SECURITY	unset (off)	1/true turns control-plane enforcement ON at boot (console + management API require authentication). A persisted runtime toggle wins over this once set from the console/PowerShell.
ZARIS_ADMIN_USERNAME · ZARIS_ADMIN_PASSWORD	unset	With ZARIS_SECURITY on, the manager self-provisions the first admin (a real login identity with ClusterAdmin@root) on boot — the in-process equivalent of POST /security/provision. It runs before the manager becomes Ready, so the readiness-gated console URL is never published un-provisioned (closing the bootstrap race where anyone could claim admin). Idempotent. The Helm chart supplies these from a Secret when manager.security.enabled — see the Kubernetes deployment guide.

Telemetry

See Logging and tracing.

Variable	Default	Effect
CLUSTRON_TELEMETRY	enabled	Anonymous usage telemetry is sent unless this is set to false. Set CLUSTRON_TELEMETRY=false to opt out.
OTEL_EXPORTER_OTLP_ENDPOINT	unset	OTLP endpoint; setting it also switches tracing on.
OTEL_EXPORTER_OTLP_PROTOCOL	unset	OTLP protocol (for example grpc or http/protobuf).
ZARIS_METRICS_RETENTION_SECONDS	600	How long the management service keeps pushed metric snapshots — the window the web console's throughput/latency charts draw. Clamped to 60 s–24 h. Raise it to see a longer trend on the charts.
ZARIS_TRACE	unset	1 enables verbose node trace logging at startup.

CLUSTRON_TELEMETRY also governs install telemetry: the Windows installer reports one anonymous install event (product, version, OS, arch, install kind, and a random per-install id — no machine or user identifiers). The install event also includes a server-derived IP and coarse location (country / region / city) resolved from the request by the Clustron server; the installer itself never captures or sends IP or location. Set CLUSTRON_TELEMETRY=false before running the installer to skip it.

TLS enrollment (containers)

Used to enroll a node into a TLS-secured cluster in attach/container deployments. See CA trust modes.

Variable	Effect
ZARIS_TLS_ENROLL	Enables node certificate enrollment on startup.
ZARIS_TLS_ISSUER_URL	URL of the CA issuer to enroll against.
ZARIS_TLS_ENROLL_TOKEN	Enrollment token (from New-ZrEnrollmentToken).
ZARIS_TLS_CA_THUMBPRINT	Expected cluster-CA thumbprint to pin during enrollment.

Next steps

• Status and exception reference
• Limits and defaults
• Memory and eviction
• Security overview