Network settings

OpenSearch uses HTTP settings to configure communication with external clients through the REST API and transport settings for internal node-to-node communication within OpenSearch.

To learn more about static and dynamic settings, see Configuring OpenSearch.

OpenSearch supports the following common network settings:

• network.host (Static, list): Binds an OpenSearch node to an address. Use 0.0.0.0 to include all available network interfaces, or specify an IP address assigned to a specific interface. The network.host setting is a combination of network.bind_host and network.publish_host if they are the same value. An alternative to network.host is to configure network.bind_host and network.publish_host separately as needed. See Advanced network settings.

• http.port (Static, single value or range): Binds an OpenSearch node to a custom port or a range of ports for HTTP communication. You can specify an address or a range of addresses. Default is 9200-9300.

• transport.port (Static, single value or range): Binds an OpenSearch node to a custom port for communication between nodes. You can specify an address or a range of addresses. Default is 9300-9400.

Advanced network settings

OpenSearch supports the following advanced network settings:

• network.bind_host (Static, list): Binds an OpenSearch node to an address or addresses for incoming connections. Default is the value in network.host.

• network.publish_host (Static, list): Specifies an address or addresses that an OpenSearch node publishes to other nodes in the cluster so that they can connect to it.

General TCP settings

OpenSearch supports the following TCP settings that apply to all network connections, including both the HTTP and transport layers:

• network.tcp.keep_alive (Static, Boolean): Enables or disables TCP keep-alive for all TCP connections used by OpenSearch, including the HTTP and transport layers. When enabled, the operating system will send periodic keep-alive packets to detect dead connections. Default is true.

• network.tcp.no_delay (Static, Boolean): Enables or disables the TCP_NODELAY option for all TCP connections. When enabled, disables Nagle’s algorithm, which can reduce latency for small messages at the cost of increased network traffic. This applies to both HTTP and transport connections. Default is true.

• network.tcp.receive_buffer_size (Static, byte unit): Sets the size of the TCP receive buffer for all TCP connections used by OpenSearch. This affects both HTTP and transport connections. A larger buffer can improve throughput for high-bandwidth connections. By default, this is not explicitly set and uses the operating system default.

• network.tcp.reuse_address (Static, Boolean): Controls whether TCP addresses can be reused for all TCP connections. This affects socket binding behavior for both HTTP and transport connections. Default is true on non-Windows machines and false on Windows.

• network.tcp.send_buffer_size (Static, byte unit): Sets the size of the TCP send buffer for all TCP connections used by OpenSearch. This affects both HTTP and transport connections. A larger buffer can improve throughput for high-bandwidth connections. By default, this is not explicitly set and uses the operating system default.

• network.server (Static, Boolean): Enables network server functionality. Default is true.

• network.tcp.keep_count (Static, integer): Number of TCP keep-alive probes before connection is dropped. Default is -1 (system default). Minimum is -1.

• network.tcp.keep_idle (Static, integer): The amount of time, in seconds, before starting TCP keep-alive probes. Default is -1 (system default). Minimum is -1. Maximum is 300.

• network.tcp.keep_interval (Static, integer): The time interval, in seconds, between TCP keep-alive probes. Default is -1 (system default). Minimum is -1. Maximum is 300.

• network.tcp.connect_timeout (Static, time unit): Sets the timeout for establishing TCP connections across all network layers. This setting applies to both HTTP and transport connections and controls how long to wait for a connection to be established before timing out. Default is 30s.

Advanced HTTP settings

OpenSearch supports the following advanced network settings for HTTP communication:

• http.host (Static, list): Sets the address of an OpenSearch node for HTTP communication. The http.host setting is a combination of http.bind_host and http.publish_host if they are the same value. An alternative to http.host is to configure http.bind_host and http.publish_host separately as needed.

• http.bind_host (Static, list): Specifies an address or addresses to which an OpenSearch node binds to listen for incoming HTTP connections.

• http.publish_host (Static, list): Specifies an address or addresses that an OpenSearch node publishes to other nodes for HTTP communication.

• http.compression (Static, Boolean): Enables support for compression using Accept-Encoding when applicable. When HTTPS is enabled, the default is false, otherwise, the default is true. Disabling compression for HTTPS helps mitigate potential security risks, such as BREACH attacks. To enable compression for HTTPS traffic, explicitly set http.compression to true.

• http.max_header_size: (Static, string) The maximum combined size of all HTTP headers allowed in a request. Default is 16KB.

• http.compression_level (Static, integer): Defines the compression level to use for HTTP responses when compression is enabled. Valid values are in the range of 1 (minimum compression) to 9 (maximum compression). Higher values provide better compression but use more CPU resources. Default is 3.

• http.max_chunk_size (Static, byte unit): Sets the maximum size of HTTP chunks for request and response processing. This setting controls how HTTP messages are broken into smaller pieces for transmission. Larger chunk sizes can improve throughput for large requests but may increase memory usage. Default is 8kb.

• http.max_content_length (Static, byte unit): Sets the maximum content length allowed for HTTP requests. Requests exceeding this limit will be rejected. This setting helps prevent memory issues caused by extremely large requests. Default is 100mb.

• http.max_initial_line_length (Static, byte unit): Sets the maximum length allowed for HTTP URLs in the initial request line. URLs exceeding this limit will be rejected. Default is 4kB.

• http.max_warning_header_count (Static, integer): Sets the maximum number of warning headers that can be included in HTTP responses to clients. Warning headers provide additional information about the request processing. Default is unbounded (no limit).

• http.max_warning_header_size (Static, byte unit): Sets the maximum total size of all warning headers combined in HTTP responses to clients. This helps prevent response headers from becoming too large. Default is unbounded (no limit).

• http.pipelining.max_events (Static, integer): Sets the maximum number of events that can be queued up in memory before an HTTP connection is closed. This setting helps manage memory usage for HTTP pipelining. Default is 10000.

• http.publish_port (Static, integer): Specifies the port that HTTP clients should use when communicating with this node. This setting is useful when a cluster node is behind a proxy or firewall and the actual http.port is not directly addressable from outside the network. Default is the actual port assigned via http.port.

• http.tcp.no_delay (Static, Boolean): Controls the TCP_NODELAY option for HTTP connections. When enabled, disables Nagle’s algorithm, which can reduce latency for small messages at the cost of increased network traffic. Default is true.

HTTP CORS settings

OpenSearch supports the following Cross-Origin Resource Sharing (CORS) settings for HTTP:

• http.cors.enabled (Static, Boolean): Enables or disables CORS for HTTP requests. When enabled, OpenSearch processes CORS preflight requests and responds with appropriate Access-Control-Allow-Origin headers if the request origin is permitted. When disabled, OpenSearch ignores the Origin request header, effectively disabling CORS. Default is false.

• http.cors.allow-origin (Static, list): Specifies which origins are allowed for CORS requests. You can use wildcards (*) to allow all origins, though this is considered to be a security risk. You can also use regular expressions by wrapping the value with forward slashes (for example, /https?:\/\/localhost(:[0-9]+)?/). Default is no origins allowed.

• http.cors.allow-methods (Static, list): Specifies which HTTP methods are allowed for CORS requests. Default is OPTIONS, HEAD, GET, POST, PUT, DELETE.

• http.cors.allow-headers (Static, list): Specifies which HTTP headers are allowed in CORS requests. Default is X-Requested-With, Content-Type, Content-Length.

• http.cors.allow-credentials (Static, Boolean): Controls whether the Access-Control-Allow-Credentials header should be included in CORS responses. This header is only returned when this setting is true. Default is false.

• http.cors.max-age (Static, time unit): Defines for how long browsers should cache the results of CORS preflight OPTIONS requests. Browsers send preflight requests to determine CORS settings before making actual cross-origin requests. Default is 1728000 seconds (20 days).

HTTP error handling settings

OpenSearch supports the following HTTP error handling settings:

• http.detailed_errors.enabled (Static, Boolean): Controls whether detailed error messages and stack traces are included in HTTP response output. When set to false, only simple error messages are returned unless the error_trace request parameter is specified (which will return an error when detailed errors are disabled). Default is true.

HTTP debugging settings

OpenSearch supports the following HTTP debugging settings for tracing HTTP communication:

• http.tracer.include (Dynamic, list): Specifies a comma-separated list of HTTP request paths or wildcard patterns to include in HTTP tracing. When configured, only HTTP requests matching these patterns are traced in the logs. This setting is useful for debugging specific HTTP endpoints or API calls. Default is [] (empty list, traces all requests when HTTP tracing is enabled).

• http.tracer.exclude (Dynamic, list): Specifies a comma-separated list of HTTP request paths or wildcard patterns to exclude from HTTP tracing. HTTP requests matching these patterns are not traced in the logs, even if HTTP tracing is enabled. This setting is useful for reducing noise from frequent or unimportant endpoints. Default is [] (empty list, no exclusions when HTTP tracing is enabled).

• http.netty.receive_predictor_size (Static, byte size): The initial receive buffer size prediction for Netty HTTP transport. Default is 64kb.

• http.netty.worker_count (Static, integer): The number of worker threads for Netty HTTP transport. Default is 0 (auto-detect).

• http.read_timeout (Static, time unit): The read timeout for HTTP connections. A default of 0 means no read timeout. Default is 0. Minimum is 0.

• http.reset_cookies (Static, Boolean): Whether to reset cookies in HTTP responses. Disabled by default since cookies aren’t typically needed. Default is false.

• http.tcp.keep_alive (Static, Boolean): Enables TCP keep-alive for HTTP connections. Default is true.

• http.tcp.keep_count (Static, integer): The number of TCP keep-alive probes before connection is dropped. Default is system default. Minimum is -1.

• http.tcp.keep_idle (Static, integer): The amount of time, in seconds, before starting TCP keep-alive probes. Default is system default. Minimum is -1. Maximum is 300.

• http.tcp.keep_interval (Static, integer): The time interval, in seconds, between TCP keep-alive probes. Default is system default. Minimum is -1. Maximum is 300.

• http.tcp.receive_buffer_size (Static, byte size): The TCP receive buffer size for HTTP connections. Default is system default.

• http.tcp.reuse_address (Static, Boolean): Enables TCP address reuse for HTTP connections. Default is system default.

• http.tcp.send_buffer_size (Static, byte size): The TCP send buffer size for HTTP connections. Default is system default.

Experimental HTTP settings

OpenSearch supports the following experimental HTTP settings:

• http.protocol.http3.enabled (Static, Boolean): Enables the HTTP/3 protocol if it is supported by the operating system and architecture. Default is false.

  The HTTP/3 transport is currently experimental and should be used with caution.

  It is not possible to determine in advance whether a target server supports HTTP/3. Additionally, existing HTTP/1.1 or HTTP/2 connections cannot be upgraded to HTTP/3 because HTTP/1.1 and HTTP/2 are built on TCP streams, whereas HTTP/3 uses QUIC over UDP datagrams. When enabled, the HTTP/3 transport is available on the same port as the HTTP/1.1 and HTTP/2 transports by default.

  The implementation relies on native libraries and uses direct NIO buffers, unlike the HTTP/1.1 and HTTP/2 transports. Take this into account when estimating native memory usage.

  HTTP/3 is secure by default and is available only when SSL/TLS is enabled for HTTP transports. OpenSearch advertises HTTP/3 availability using the Alt-Svc header, for example:

    < HTTP/2 200
    < alt-svc: h3=":9200"; ma=3600
    < x-opensearch-version: OpenSearch/3.5.0 (opensearch)
    < content-type: application/json; charset=UTF-8
    < content-length: 572
  

  The following platforms/architectures are currently supported:

  • Linux/Aarch64
  • Linux/x86_64
  • OSX/Aarch64
  • OSX/x86_64
  • Windows/x86_64

Advanced transport settings

OpenSearch supports the following advanced network settings for transport communication:

• transport.host (Static, list): Sets the address of an OpenSearch node for transport communication. The transport.host setting is a combination of transport.bind_host and transport.publish_host if they are the same value. An alternative to transport.host is to configure transport.bind_host and transport.publish_host separately as needed.

• transport.bind_host (Static, list): Specifies an address or addresses to which an OpenSearch node binds to listen for incoming transport connections.

• transport.publish_host (Static, list): Specifies an address or addresses that an OpenSearch node publishes to other nodes for transport communication.

• transport.netty.boss_count (Static, integer): The number of boss threads for Netty transport. Default is 1. Minimum is 1.

• transport.netty.receive_predictor_max (Static, byte size): The maximum receive buffer size prediction for Netty transport. Default is 64kb.

• transport.netty.receive_predictor_min (Static, byte size): The minimum receive buffer size prediction for Netty transport. Default is 64kb.

• transport.netty.receive_predictor_size (Static, byte size): The initial receive buffer size prediction for Netty transport. Default is 64kb.

• transport.ssl.dual_mode.enabled (Static, Boolean): Enables dual-mode SSL for transport layer (both SSL and non-SSL). Default is false.

Transport connection settings

OpenSearch supports the following transport connection settings that control the number of connections established between nodes for different types of operations:

• transport.connections_per_node.bulk (Static, integer): Sets the number of connections per node dedicated to bulk operations such as bulk indexing and bulk update requests. These connections handle high-throughput data transfer operations between nodes. Higher values can improve bulk operation performance in large clusters but consume more network resources. Default is 3. Minimum is 1.

• transport.connections_per_node.ping (Static, integer): Sets the number of connections per node used for ping operations and basic connectivity checks between nodes. Ping connections are used for cluster health monitoring and node discovery. Default is 1. Minimum is 1.

• transport.connections_per_node.recovery (Static, integer): Sets the number of connections per node dedicated to shard recovery operations, including replica recovery and shard rebalancing. Recovery connections handle the transfer of shard data between nodes during recovery processes. Higher values can speed up recovery operations but may increase network load. Default is 2. Minimum is 1.

• transport.connections_per_node.reg (Static, integer): Sets the number of regular connections per node used for general cluster operations, search requests, and administrative tasks. These are the primary connections for most inter-node communication. This setting has the highest default value as regular operations are the most common. Default is 6. Minimum is 1.

• transport.connections_per_node.state (Static, integer): Sets the number of connections per node used for cluster state synchronization and metadata operations. State connections handle the distribution of cluster state updates, mapping changes, and other metadata operations. Default is 1. Minimum is 1.

Transport debugging settings

OpenSearch supports the following transport debugging settings for tracing transport communication:

• transport.tracer.include (Dynamic, list): Specifies a comma-separated list of transport actions or patterns to include in transport tracing. When configured, only transport communications matching these patterns are traced in the logs. This setting is useful for debugging specific internal OpenSearch operations. Default is [] (empty list, traces all actions when transport tracing is enabled).

• transport.tracer.exclude (Dynamic, list): Specifies a comma-separated list of transport actions or patterns to exclude from transport tracing. Transport communications matching these patterns are not traced in the logs, even if transport tracing is enabled. This setting is useful for reducing noise from frequent or unimportant operations. Default is [] (empty list, no exclusions when transport tracing is enabled).

Transport profile settings

OpenSearch supports the following transport profile settings that allow configuration of multiple transport profiles for different types of connections.

Transport profiles allow you to bind to multiple ports on different interfaces for different types of connections. The default profile serves as a fallback for other profiles and controls how this node connects to other nodes in the cluster. The following settings can be configured for each transport profile:

• transport.profiles.<profile_name>.port (Dynamic, single value or range): Sets the port or port range to bind for this transport profile. Different profiles can use different ports to separate types of traffic.

• transport.profiles.<profile_name>.bind_host (Dynamic, list): Specifies which network interfaces this transport profile should bind to for incoming connections. Different profiles can bind to different network interfaces.

• transport.profiles.<profile_name>.publish_host (Dynamic, list): Specifies the address that this transport profile publishes to other nodes so they can connect to it. This is useful when the bind address differs from the externally accessible address.

• transport.profiles.<profile_name>.tcp.no_delay (Dynamic, Boolean): Controls the TCP_NODELAY option for connections on this transport profile. When enabled, disables Nagle’s algorithm to reduce latency for small messages.

• transport.profiles.<profile_name>.tcp.keep_alive (Dynamic, Boolean): Controls the SO_KEEPALIVE option for connections on this transport profile. When enabled, the operating system sends periodic keep-alive packets to detect dead connections.

• transport.profiles.<profile_name>.tcp.keep_idle (Dynamic, time unit): Sets the amount of time a connection must be idle before starting to send TCP keep alive probes. Only available on Linux and Mac with JDK 11 or later. Default is -1 (uses system default).

• transport.profiles.<profile_name>.tcp.keep_interval (Dynamic, time unit): Sets the interval between TCP keep alive probes for connections on this transport profile. Only available on Linux and Mac with JDK 11 or later. Default is -1 (uses system default).

• transport.profiles.<profile_name>.tcp.keep_count (Dynamic, integer): Sets the number of TCP keep alive probes that can be unacknowledged before the connection is dropped. Only available on Linux and Mac with JDK 11 or later. Default is -1 (uses system default).

• transport.profiles.<profile_name>.tcp.reuse_address (Dynamic, Boolean): Controls the SO_REUSEADDR option for sockets on this transport profile, allowing address reuse after socket closure.

• transport.profiles.<profile_name>.tcp.send_buffer_size (Dynamic, byte unit): Sets the TCP send buffer size for connections on this transport profile. Larger buffers can improve throughput for high-bandwidth connections.

• transport.profiles.<profile_name>.tcp.receive_buffer_size (Dynamic, byte unit): Sets the TCP receive buffer size for connections on this transport profile. Larger buffers can improve throughput for high-bandwidth connections.

Advanced transport settings

OpenSearch supports the following advanced transport settings:

• transport.compress (Static, Boolean): Enables DEFLATE compression for all inter-node transport communications. When enabled, data transmitted between nodes is compressed to reduce network bandwidth usage, which can be beneficial for clusters connected over slower network links. However, compression adds CPU overhead for compression and decompression operations. Default is false.

• transport.connect_timeout (Static, time unit): Sets the timeout period for establishing new transport connections between nodes. If a connection attempt does not complete within this time limit, it is considered to be failed. This setting helps prevent nodes from hanging indefinitely when trying to connect to unresponsive or unreachable nodes. Default is 30s.

• transport.ping_schedule (Static, time unit): Configures the interval for sending application-level ping messages to maintain transport connections between nodes. When set to a positive value, nodes will send periodic ping messages to detect and prevent idle connection timeouts. Setting this to -1 disables application-level pings. It is generally recommended to use TCP keep-alive settings instead because they provide more comprehensive connection monitoring for all connection types. Default is -1 (disabled).

• transport.publish_port (Static, integer): Specifies the port that other nodes should use when connecting to this node for transport communication. This setting is particularly useful when nodes are behind proxies, firewalls, or NAT configurations where the actual bind port differs from the externally accessible port. If not specified, other nodes will use the port determined by the transport.port setting. Default is the actual port assigned via transport.port.

Transport TCP settings

OpenSearch supports the following transport layer TCP settings that control low-level TCP behavior for inter-node communication:

• transport.tcp.keep_alive (Static, Boolean): Enables TCP keep-alive for transport connections between nodes. When enabled, the operating system sends periodic keep-alive packets to detect dead connections and maintain connection state. This helps detect network failures and unresponsive nodes more quickly. Default is true.

• transport.tcp.keep_count (Static, integer): Sets the number of TCP keep-alive probes that can be sent without receiving a response before the connection is considered dead and closed. This setting only takes effect when TCP keep-alive is enabled. Default is -1 (uses system default). Minimum is -1.

• transport.tcp.keep_idle (Static, integer): Sets the amount of time, in seconds, that a transport connection must be idle before starting to send TCP keep-alive probes. This setting controls when the keep-alive mechanism activates for idle connections. Default is -1 (uses system default). Minimum is -1. Maximum is 300.

• transport.tcp.keep_interval (Static, integer): Sets the time interval, in seconds, between TCP keep-alive probes for transport connections. Once keep-alive probes start, this setting determines how frequently they are sent. Default is -1 (uses system default). Minimum is -1. Maximum is 300.

• transport.tcp.receive_buffer_size (Static, byte unit): Sets the TCP receive buffer size for transport connections. This controls how much data the operating system buffers for incoming transport messages. Larger buffers can improve throughput for high-bandwidth inter-node communication but consume more memory. Default is -1 (uses system default).

• transport.tcp.reuse_address (Static, Boolean): Controls the SO_REUSEADDR socket option for transport connections. When enabled, allows the transport layer to reuse TCP addresses immediately after connection closure, which can be helpful during rapid node restarts or high connection turnover. Default depends on the operating system (typically true on non-Windows systems and false on Windows).

• transport.tcp.send_buffer_size (Static, byte unit): Sets the TCP send buffer size for transport connections. This controls how much data the operating system buffers for outgoing transport messages. Larger buffers can improve throughput for high-bandwidth inter-node communication but consume more memory. Default is -1 (uses system default).

• transport.tcp.no_delay (Static, Boolean): Controls the TCP_NODELAY option for transport connections between nodes. When enabled, disables Nagle’s algorithm, which can reduce latency for small messages at the cost of increased network traffic. This setting is particularly important for cluster communication where low latency is critical. Default is true.

• transport.tcp.compress (Static, Boolean): Enables DEFLATE compression for transport layer communication between nodes. When enabled, reduces network bandwidth usage at the cost of additional CPU overhead for compression and decompression. This setting is superseded by the newer transport.compress setting. Default is false.

• transport.tcp.connect_timeout (Static, time unit): Sets the timeout for establishing TCP connections at the transport layer between nodes. If a connection attempt does not complete within this time limit, it is considered failed. This setting is superseded by the newer transport.connect_timeout setting. Default is 30s.

• transport.tcp_no_delay (Static, Boolean): Deprecated. Legacy setting that controls the TCP_NODELAY option for transport connections. This setting has been replaced by transport.tcp.no_delay and is maintained for backward compatibility. Use transport.tcp.no_delay instead. Default is true.

Transport features settings

OpenSearch supports the following transport features settings that control optional transport layer functionality:

• transport.features.* (Static, group setting): Controls which transport features are enabled for inter-node communication. This is a group setting that allows enabling or disabling specific transport layer features such as compression, security enhancements, or protocol extensions. Individual feature names are appended as suffixes to configure specific transport capabilities. These settings must be configured consistently across all nodes in the cluster to ensure compatibility.

Transport and HTTP type settings

OpenSearch supports settings that control the default transport and HTTP implementation types used by the cluster.

OpenSearch supports the following static transport and HTTP type settings:

• transport.type.default (Static, string): Sets the default transport implementation type for inter-node communication. This setting determines which transport implementation OpenSearch uses when no specific transport type is configured. The default implementation is netty4, which provides efficient asynchronous networking based on Netty 4. Alternative implementations can be provided by plugins. Default is netty4.

• http.type.default (Static, string): Sets the default HTTP implementation type for client communication. This setting determines which HTTP implementation OpenSearch uses when no specific HTTP type is configured. The default implementation is netty4, which provides efficient asynchronous HTTP processing based on Netty 4. Alternative implementations like reactor-netty4 can be provided by plugins. Default is netty4.

Selecting the transport

The default OpenSearch transport is provided by the transport-netty4 module and uses the Netty 4 engine for both internal TCP-based communication between nodes in the cluster and external HTTP-based communication with clients. This communication is fully asynchronous and non-blocking. The following table lists other available transport plugins that can be used interchangeably.