Configuring OpenSearch

There are two types of OpenSearch settings: dynamic and static.

Dynamic settings

Dynamic index settings are settings that you can update at any time. You can configure dynamic OpenSearch settings through the Cluster Settings API. For details, see Update cluster settings using the API.

Whenever possible, use the Cluster Settings API; opensearch.yml is local to each node, whereas the API applies the setting to all nodes in the cluster.

Static settings

Certain operations are static and require you to modify the opensearch.yml configuration file and restart the cluster. In general, these settings relate to networking, cluster formation, and the local file system. To learn more, see Cluster formation.

Specifying settings as environment variables

You can specify environment variables in the following ways.

Arguments at startup

You can specify environment variables as arguments using -E when launching OpenSearch:

  1. ./opensearch -Ecluster.name=opensearch-cluster -Enode.name=opensearch-node1 -Ehttp.host=0.0.0.0 -Ediscovery.type=single-node

copy

Directly in the shell environment

You can configure the environment variables directly in a shell environment before starting OpenSearch, as shown in the following example:

  1. export OPENSEARCH_JAVA_OPTS="-Xms2g -Xmx2g"
  2. export OPENSEARCH_PATH_CONF="/etc/opensearch"
  3. ./opensearch

copy

Systemd service file

When running OpenSearch as a service managed by systemd, you can specify environment variables in the service file, as shown in the following example:

  1. # /etc/systemd/system/opensearch.service.d/override.conf
  2. [Service]
  3. Environment="OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g"
  4. Environment="OPENSEARCH_PATH_CONF=/etc/opensearch"

After creating or modifying the file, reload the systemd configuration and restart the service using the following command:

  1. sudo systemctl daemon-reload
  2. sudo systemctl restart opensearch

copy

Docker environment variables

When running OpenSearch in Docker, you can specify environment variables using the -e option with docker run command, as shown in the following command:

  1. docker run -e "OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g" -e "OPENSEARCH_PATH_CONF=/usr/share/opensearch/config" opensearchproject/opensearch:latest

copy

Updating cluster settings using the API

The first step in changing a setting is to view the current settings by sending the following request:

  1. GET _cluster/settings?include_defaults=true

copy

For a more concise summary of non-default settings, send the following request:

  1. GET _cluster/settings

copy

Three categories of setting exist in the cluster settings API: persistent, transient, and default. Persistent settings, well, persist after a cluster restart. After a restart, OpenSearch clears transient settings.

If you specify the same setting in multiple places, OpenSearch uses the following precedence:

  1. Transient settings
  2. Persistent settings
  3. Settings from opensearch.yml
  4. Default settings

To change a setting, use the Cluster Settings API and specify the new value as either persistent or transient. This example shows the flat settings form:

  1. PUT _cluster/settings
  2. {
  3.   "persistent" : {
  4.     "action.auto_create_index" : false
  5.   }
  6. }

copy

You can also use the expanded form, which lets you copy and paste from the GET response and change existing values:

  1. PUT _cluster/settings
  2. {
  3.   "persistent": {
  4.     "action": {
  5.       "auto_create_index": false
  6.     }
  7.   }
  8. }

copy

Configuration file

You can find opensearch.yml in /usr/share/opensearch/config/opensearch.yml (Docker) or /etc/opensearch/opensearch.yml (most Linux distributions) on each node.

You can edit the OPENSEARCH_PATH_CONF=/etc/opensearch to change the config directory location. This variable is sourced from /etc/default/opensearch(Debian package) and /etc/sysconfig/opensearch(RPM package).

If you set your customized OPENSEARCH_PATH_CONF variable, be aware that other default environment variables will not be loaded.

You don’t mark settings in opensearch.yml as persistent or transient, and settings use the flat form:

  1. cluster.name: my-application
  2. action.auto_create_index: true
  3. compatibility.override_main_response_version: true

The demo configuration includes a number of settings for the Security plugin that you should modify before using OpenSearch for a production workload. To learn more, see Security.

(Optional) CORS header configuration

If you are working on a client application running against an OpenSearch cluster on a different domain, you can configure headers in opensearch.yml to allow for developing a local application on the same machine. Use Cross Origin Resource Sharing so that your application can make calls to the OpenSearch API running locally. Add the following lines in your custom-opensearch.yml file (note that the “-“ must be the first character in each line).

  1. - http.host:0.0.0.0
  2. - http.port:9200
  3. - http.cors.allow-origin:"http://localhost"
  4. - http.cors.enabled:true
  5. - http.cors.allow-headers:X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization
  6. - http.cors.allow-credentials:true