Configuration Keys Reference

The settings you will actually touch — tuning, reproducing a bug, or reading someone's cluster — grouped by area, each with its default, its scope, and the chapter that explains the machinery behind it. Read the chapter before you change a key in a PR; a setting is the public face of a subsystem.

Two scope axes matter, and both are in every table:

Warning: Defaults drift across versions. The defaults below are representative, not gospel — a minor release can change one. Confirm the real value and scope in your version:

# From a running cluster (defaults included, flat keys):
curl -s 'localhost:9200/_cluster/settings?include_defaults=true&flat_settings=true' | python3 -m json.tool
curl -s 'localhost:9200/my-index/_settings?include_defaults=true&flat_settings=true&pretty'

# From source — find the Setting definition (default + scope live in the Setting.* call):
grep -rn "number_of_replicas" server/src/main/java/org/opensearch/cluster/metadata/IndexMetadata.java
grep -rn "refresh_interval\|REFRESH_INTERVAL" server/src/main/java/org/opensearch/index/IndexSettings.java
# Most setting *keys* are declared in a *Settings class — grep for it:
grep -rln "public static final Setting" server/src/main/java/org/opensearch/ | grep Settings

Note: "cluster manager" (formerly "master") is the current term. The bootstrap setting is cluster.initial_cluster_manager_nodes; the old cluster.initial_master_nodes is a deprecated alias. Several *master* keys have *cluster_manager* equivalents — grep both.

Jump to: Bootstrap & discovery · Allocation · Index basics · Store · Translog · Refresh · Merge · Search · Circuit breakers · k-NN · Slow logs · Security

Node & cluster bootstrap

How a cluster first forms and which nodes can become cluster manager. Read ../deep-dives/discovery-coordination.md.

Warning: Setting cluster.initial_cluster_manager_nodes on an already-bootstrapped cluster is a classic mistake — it is honored only on the very first formation. After that it does nothing and should be removed.

Allocation & routing

How shards are placed and rebalanced. Read ../deep-dives/shard-allocation.md.

Index basics

The shape of an index. Read ../deep-dives/index-shard-lifecycle.md and the sharding masterclass.

Note: number_of_shards is the single most consequential static setting. Too many small shards wastes cluster-state and overhead; too few caps parallelism. See the sharding masterclass for the sizing model.

Store

How a shard's files are accessed on disk. Read ../masterclass/storage-engine/lab-03-store-types-mmap.md.

Warning: mmapfs/hybridfs need a high vm.max_map_count (the bootstrap check enforces 262144). If you can't raise it, set index.store.type: niofs or node.store.allow_mmap: false.

Translog

Durability between commits. Read ../deep-dives/translog.md.

Warning: index.translog.durability: async trades durability for indexing throughput — a crash can lose up to sync_interval of writes. Only choose it when the data source can replay.

Refresh

Search visibility (near-real-time). Read ../deep-dives/refresh-flush-merge.md.

Note: Setting index.refresh_interval: -1 during a large bulk load, then restoring it and forcing one refresh, is the standard ingest-throughput win — at the cost of visibility during the load.

Merge

Background segment consolidation. Read ../lucene/indexwriter-and-merges.md.

Search

Query execution and safety. Read ../deep-dives/search-execution.md and the concurrent segment search masterclass.

Note: search.concurrent_segment_search.* setting names have changed across versions (an early .enabled boolean, later a .mode enum). Grep grep -rn "concurrent_segment_search" server/src/main/java/ to see your version's exact keys; the masterclass covers the model.

Circuit breakers

Memory guards that reject before they OOM. Read ../deep-dives/circuit-breakers-memory.md.

k-NN

Vector search settings (the k-NN plugin). Read ../knn/native-jni-and-memory.md and ../knn/architecture.md.

Warning: The k-NN native memory breaker (knn.memory.circuit_breaker.limit) guards off-heap memory used by faiss/nmslib, which is invisible to the JVM circuit breakers. Size it against system RAM, not heap. See ../knn/native-jni-and-memory.md.

Slow logs

Per-shard logging of slow operations. Read the debugging masterclass.

# Turn on a 200ms query slow log on one index, then watch the per-shard log:
curl -s -XPUT 'localhost:9200/my-index/_settings' -H 'Content-Type: application/json' -d'
{ "index.search.slowlog.threshold.query.warn": "200ms" }'
# logs land in <logs>/<cluster>_index_search_slowlog.json

Security

The bundled security plugin's TLS and transport settings (opensearch.yml). Read the security masterclass.

Warning: When security is enabled, transport TLS is not optional — the plugin refuses to start nodes without it. The HTTP layer can run plaintext for local dev, but never in production. See ../masterclass/security/lab-01-authn-tls.md.

Reading effective settings end to end

Two commands turn "what is actually set?" into a definitive answer:

# Every cluster setting, defaults included, as flat keys you can grep:
curl -s 'localhost:9200/_cluster/settings?include_defaults=true&flat_settings=true' \
  | python3 -m json.tool | grep -i 'watermark\|breaker\|concurrent'

# One index's effective settings (persistent + transient + defaults):
curl -s 'localhost:9200/my-index/_settings?include_defaults=true&flat_settings=true&pretty'

To change a dynamic cluster setting live (persistent survives restart, transient does not):

curl -s -XPUT 'localhost:9200/_cluster/settings' -H 'Content-Type: application/json' -d'
{ "persistent": { "cluster.routing.allocation.enable": "primaries" } }'

Note: A setting the API rejects as "unknown" usually means it is registered by a plugin that isn't installed, was renamed, or is static (and so cannot be set via _cluster/settings at all). Confirm by grepping the owning *Settings class — the Setting.*Setting(...) call shows the exact key, default, scope, and Property.Dynamic / Property.NodeScope flags.