Node Settings

Every running instance of Elasticsearch is a node. A group of connected nodes forms a cluster. Each node can handle HTTP and transport traffic by default — the transport layer is used for node-to-node communication, while the HTTP layer serves REST clients. All nodes know about every other node in the cluster and can forward client requests to the appropriate node.

Core identity settings

Configure these in elasticsearch.yml on every node.

cluster.name

Nodes join a cluster by sharing the same cluster.name. A node can only join one cluster.

cluster.name: my-production-cluster

Defaults to elasticsearch. Use a unique name per cluster to prevent nodes from accidentally joining the wrong cluster.

node.name

A human-readable identifier for the node. Included in API responses and log output. Defaults to the machine hostname at startup.

node.name: prod-data-2

path.data

The directory where shard data, index metadata, and cluster state are stored. Defaults to $ES_HOME/data.

path.data: /var/elasticsearch/data

Or on the command line:

./bin/elasticsearch -Epath.data=/var/elasticsearch/data

The contents of path.data must persist across restarts. Each Elasticsearch node must have its own data path — do not share a data directory between nodes.

Do not modify the contents of the data directory with external tools, run virus scanners on it, or take filesystem-level backups of it. Use Snapshot and restore instead.

path.logs

The directory where Elasticsearch writes log files. Defaults to $ES_HOME/logs.

path.logs: /var/log/elasticsearch

When using .zip or .tar.gz distributions, configure both path.data and path.logs outside $ES_HOME so the home directory can be upgraded without losing data or logs.

Network settings

network.host

The address the node binds to and publishes for both HTTP and transport traffic. Accepts an IP address, hostname, or a special value.

network.host: 192.168.1.10

Special values:

Value	Resolves to
`_local_`	Loopback addresses (e.g. `127.0.0.1`)
`_site_`	Site-local addresses
`_global_`	Globally-routable addresses

Do not set network.host: 0.0.0.0 without also enabling and configuring Elasticsearch security. Binding to all interfaces on an unsecured node exposes the cluster to the network.

http.port

The port for HTTP client traffic. Accepts a single port or a range; Elasticsearch uses the first available port in the range.

http.port: 9200

Defaults to 9200-9300.

transport.port

The port for inter-node transport communication. Accepts a single port or a range.

transport.port: 9300

Defaults to 9300-9400.

Node roles

Set node.roles in elasticsearch.yml to assign specific responsibilities to a node. If node.roles is not set, the node is assigned all roles automatically.

node.roles: [ master, data, ingest ]

If you set node.roles explicitly, you must include every role your cluster requires. Every cluster needs at least one master-eligible node and either a data node or both data_content and data_hot nodes.

Available roles

master

Eligible to be elected as the cluster master. The master node manages cluster-wide state and coordinates shard allocation.

data

Holds shards and handles data-related operations (CRUD, search, aggregations). Encompasses all data tiers.

data_content

Holds content data that does not belong to a time-series lifecycle. Required alongside data_hot when not using the generic data role.

data_hot

Holds the most recent time-series data, typically on the fastest hardware.

data_warm

Holds older time-series data that is queried less frequently.

data_cold

Holds infrequently accessed time-series data. Optimized for low cost over query speed.

ingest

Executes ingest pipelines to transform documents before indexing. Required for Fleet, Stack Monitoring, and ingest pipeline use.

ml

Runs machine learning jobs such as anomaly detection. Required for all ML features.

remote_cluster_client

Can connect to remote clusters. Required for cross-cluster search (CCS) and cross-cluster replication (CCR).

transform

Runs transform jobs. Required by Fleet, the Security app, and Kibana transforms.

Coordinating-only nodes

Setting node.roles to an empty array makes the node a coordinating-only node. It routes requests and aggregates results but holds no data and is not master-eligible.

node.roles: []

Use coordinating-only nodes as smart load balancers in large clusters to offload scatter-gather work from data nodes.

Discovery and cluster formation

These settings are required when forming a new cluster or when nodes need to find each other.

discovery.seed_hosts
cluster.initial_master_nodes

A list of hosts that a new node should contact to discover the cluster. Accepts hostnames or IP addresses, optionally with a port.

discovery.seed_hosts:
  - 192.168.1.10:9300
  - 192.168.1.11
  - es-node-3.example.com

If no port is specified, the value of transport.profiles.default.port is used, falling back to transport.port.

The list of master-eligible node names used only during the very first cluster formation. Required to bootstrap a brand-new cluster.

cluster.initial_master_nodes:
  - node-1
  - node-2
  - node-3

Remove cluster.initial_master_nodes from elasticsearch.yml on all nodes after the cluster has formed successfully. If this setting is present when a node restarts into an already-running cluster, it can cause a split-brain scenario. This setting must only be used once, for initial cluster bootstrapping.

JVM heap sizing

Elasticsearch automatically sets the JVM heap size based on node roles and available memory. Override only when the automatic sizing does not fit your workload.

Create a JVM options file

Add a file with an .options extension to the jvm.options.d/ directory. Do not edit the root jvm.options file.

Distribution	Options directory
tar.gz / .zip	`config/jvm.options.d/`
Debian / RPM	`/etc/elasticsearch/jvm.options.d/`
Docker	`/usr/share/elasticsearch/config/jvm.options.d/`

Set Xms and Xmx to the same value

Always set minimum (Xms) and maximum (Xmx) heap to the same value to prevent heap resizing at runtime.

-Xms4g
-Xmx4g

Observe the 50% RAM limit

Do not allocate more than 50% of the total available RAM to the JVM heap. Elasticsearch needs the remaining memory for off-heap network buffers and the OS filesystem cache.

# On a 16 GB node, cap heap at 8 GB
-Xms8g
-Xmx8g

Stay below the compressed oops threshold

Keep heap at or below approximately 26–30 GB to benefit from compressed ordinary object pointers (oops), which significantly reduces memory overhead. Confirm the setting in the Elasticsearch log:

heap size [1.9gb], compressed ordinary object pointers [true]

Or query the nodes info API:

GET _nodes/_all/jvm

For testing only, you can set heap size via the ES_JAVA_OPTS environment variable:

ES_JAVA_OPTS="-Xms2g -Xmx2g" ./bin/elasticsearch

Do not use ES_JAVA_OPTS in production — it overrides all other JVM options.

Custom node attributes

Assign arbitrary key-value attributes to a node for use in shard allocation filtering or allocation awareness:

node.attr.rack_id: rack_one
node.attr.zone: us-east-1a

Or set them at startup:

./bin/elasticsearch -Enode.attr.rack_id=rack_one

Attributes are dynamic and do not require a node restart to take effect when used in allocation rules.

Get Started

Core Concepts

Indexing & Data

Search & Analytics

Configuration & Operations

Core identity settings

Network settings

Node roles

Available roles

master

data

data_content

data_hot

data_warm

data_cold

ingest

ml

remote_cluster_client

transform

Coordinating-only nodes

Discovery and cluster formation

JVM heap sizing

Custom node attributes

Build docs developers (and LLMs) love

Get Started

Core Concepts

Indexing & Data

Search & Analytics

Configuration & Operations

​Core identity settings

​Network settings

​Node roles

​Available roles

master

data

data_content

data_hot

data_warm

data_cold

ingest

ml

remote_cluster_client

transform

​Coordinating-only nodes

​Discovery and cluster formation

​JVM heap sizing

​Custom node attributes

Build docs developers (and LLMs) love

Core identity settings

Network settings

Node roles

Available roles

Coordinating-only nodes

Discovery and cluster formation

JVM heap sizing

Custom node attributes