Configuration

The configuration touch points an operator (or a developer testing things) most often reaches for. Authoritative reference is the official user docs at elastic.co/guide.

elasticsearch.yml

Ships with safe defaults at distribution/src/config/elasticsearch.yml. Common keys:

Setting	Purpose
cluster.name	Logical cluster name; nodes with the same name can join
node.name	Human-friendly node id
node.roles	Subset of [master, data, data_hot, data_warm, data_cold, data_frozen, data_content, ingest, ml, transform, remote_cluster_client, voting_only]
path.data, path.logs	Storage paths
network.host	Bind address (0.0.0.0 for all, _local_ for loopback)
http.port, transport.port	HTTP and transport ports
discovery.seed_hosts	Seed list for cluster discovery
cluster.initial_master_nodes	Initial voting configuration (only on first bring-up)
xpack.security.enabled	Toggle security (default: true)
xpack.security.http.ssl.*	HTTP TLS
xpack.security.transport.ssl.*	Transport TLS
tracing.apm.enabled	OTLP tracing

Cluster-level settings (cluster.routing.allocation.*, etc.) are usually changed via _cluster/settings rather than elasticsearch.yml.

Cluster, index, and node scoped settings

Setting<T> objects declare scope:

• Property.NodeScope — node-level, set in elasticsearch.yml.
• Property.IndexScope — per-index, set on index creation or via _settings.
• Property.Dynamic — can be changed at runtime.
• Property.Final — cannot be changed after first set.
• Property.Filtered — never logged or returned in API responses (used for secrets fallback before keystore).

Search the codebase for Setting.<type>(...). to discover settings owned by each subsystem.

JVM options

config/jvm.options plus override files in config/jvm.options.d/. The bundled defaults set:

• Heap min/max (see auto-detection in distribution/tools/server-cli/).
• GC: G1 by default; ZGC for very large heaps via -XX:+UseZGC.
• -XX:+HeapDumpOnOutOfMemoryError.
• Vector API: --add-modules=jdk.incubator.vector (for SIMD vectors).

Production deployments should let Elasticsearch choose the heap (default: half the host RAM, capped at 32GB) unless they have specific reasons to override.

Keystore

Encrypted JCA keystore for secrets. Managed by:

bin/elasticsearch-keystore create
bin/elasticsearch-keystore add s3.client.default.access_key
bin/elasticsearch-keystore add s3.client.default.secret_key
bin/elasticsearch-keystore list

Reload across the cluster via POST /_nodes/reload_secure_settings.

Index settings

Per-index settings set on creation or modified via PUT /<index>/_settings. Common ones:

Setting	Purpose
index.number_of_shards, index.number_of_replicas	Shard counts
index.refresh_interval	How often to make new docs searchable
index.translog.durability	request (sync per op) or async
index.translog.sync_interval	Interval for async durability
index.routing.allocation.*	Tag-based filtering
index.lifecycle.name	ILM policy reference
index.search.idle.after	Idle threshold before refresh skipping
index.codec	Lucene codec (default, best_compression)

Reserved state

config/operator/settings.json is the reserved-state mechanism: settings declared there are read-only at runtime and override anything set by API. Used by Elastic Cloud and serverless to lock down customer-visible toggles.

Logging

Loggers are configured in config/log4j2.properties. At runtime, change levels via:

PUT /_cluster/settings
{
  "transient": { "logger.org.elasticsearch.cluster.coordination": "TRACE" }
}

null resets a logger to its declared default.