Edit Elasticsearch user settingsedit
Change how Elasticsearch runs by providing your own user settings. Elasticsearch Add-On for Heroku appends these
settings to each node’s elasticsearch.yml
configuration file.
Elasticsearch Add-On for Heroku automatically rejects elasticsearch.yml
settings that could break your
cluster. For a list of supported settings, check
Supported Elasticsearch settings.
You can also update dynamic cluster settings using Elasticsearch’s update cluster settings API. However, Elasticsearch Add-On for Heroku doesn’t reject unsafe setting changes made using this API. Use with caution.
To add or edit user settings:
- Log in to the Elasticsearch Add-On for Heroku console.
-
On the deployments page, select your deployment.
Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list.
- From your deployment menu, go to the Edit page.
- In the Elasticsearch section, select Manage user settings and extensions.
- Update the user settings.
- Select Save changes.
In some cases, you may get a warning saying "User settings are different across Elasticsearch instances". To fix this issue, ensure that your user settings (including the comments sections and whitespaces) are identical across all Elasticsearch nodes (not only the data tiers, but also the Master, Machine Learning, and Coordinating nodes).
Supported Elasticsearch settingsedit
Elasticsearch Add-On for Heroku supports the following elasticsearch.yml
settings.
-
http.cors.*
-
Enables cross-origin resource sharing (CORS) settings for the HTTP module.
If your use case depends on the ability to receive CORS requests and you have a cluster that was provisioned prior to January 25th 2019, you must manually set
http.cors.enabled
totrue
and allow a specific set of hosts withhttp.cors.allow-origin
. Applying these changes in your Elasticsearch configuration allows cross-origin resource sharing requests. -
http.compression
-
Support for compression when possible (with Accept-Encoding). Defaults to
true
. -
repositories.url.allowed_urls
- Enables explicit allowing of read-only URL repositories.
-
reindex.remote.whitelist
-
Explicitly allows the set of hosts that can be reindexed from remotely. Expects a YAML array of
host:port
strings. Consists of a comma-delimited list ofhost:port
entries. Defaults to["\*.io:*", "\*.com:*"]
. -
reindex.ssl.*
- To learn more on how to configure reindex SSL user settings, check configuring reindex SSL parameters.
-
script.painless.regex.enabled
- Enables regular expressions for the Painless scripting language.
-
action.auto_create_index
- Automatically create index if it doesn’t already exist.
-
action.destructive_requires_name
-
When set to
true
, users must specify the index name to delete an index. It’s not possible to delete _all or use wildcards. -
xpack.notification.webhook.additional_token_enabled
-
When set to
true
, Elasticsearch automatically sets a token which enables the bypassing of traffic filters for calls initiated by Watcher towards Elasticsearch or Kibana. The default isfalse
and the feature is available starting with Elasticsearch version 8.7.1 and later. -
cluster.indices.close.enable
-
Enables closing indices in Elasticsearch version 2.2 and later. Defaults to
true
for versions 7.2.0 and later, and tofalse
for previous versions. In versions 7.1 and below, closed indices represent a data loss risk: if you close an index, it is not included in snapshots and you will not be able to restore the data. Similarly, closed indices are not included when you make cluster configuration changes, such as scaling to a different capacity, failover, and many other operations. Lastly, closed indices can lead to inaccurate disk space counts.For versions 7.1 and below, closed indices represent a data loss risk. Enable this setting only temporarily for these versions.
- Circuit breaker settings
-
The following circuit breaker settings are supported:
-
indices.breaker.total.limit
- Configures the parent circuit breaker settings.
-
indices.breaker.fielddata.limit
- Configures the limit for the fielddata breaker.
-
indices.breaker.fielddata.overhead
- Configures a constant that all field data estimations are multiplied with to determine a final estimation.
-
indices.breaker.request.limit
- Configures the limit for the request breaker.
-
indices.breaker.request.overhead
- Configures a constant that all request estimations are multiplied by to determine a final estimation.
-
- Indexing pressure settings (for version 7.9 and later)
-
The following indexing pressure settings are supported:
-
indexing_pressure.memory.limit
- Configures the indexing pressure settings.
-
- Searchable Snapshots settings (for versions 7.12.0 and 7.12.1 only)
-
The following searchable snapshots setting is supported:
-
xpack.searchable.snapshot.shared_cache.size
- Configures the size of the searchable snapshots shared cache.
From version 7.13.0 and later, this setting is automatically configured to 90% of total disk space for dedicated frozen data tier nodes and to
0b
for non-frozen data tier nodes. -
- X-Pack (for version 7.6 and later)
-
The following X-Pack settings are supported:
-
xpack.ml.inference_model.time_to_live
- Sets the duration of time that the trained models are cached. Check Machine learning settings.
-
- X-Pack (for versions from 6.8.9 to 7.0.0 and 7.6 and later)
-
The following X-Pack settings are supported:
-
xpack.security.loginAssistanceMessage
- Adds a message to the login screen. Useful for displaying corporate messages.
-
- X-Pack (for version 6.0 and later)
-
The following X-Pack settings are supported:
- SAML
- All SAML settings are allowlisted.
-
xpack.security.authc.realms.saml.*
- To learn more on how to enable SAML and related user settings, check secure your clusters with SAML.
- OpenID Connect
- All OpenID Connect settings are allowlisted.
-
xpack.security.authc.realms.oidc.*
- To learn more on how to enable OpenID Connect and related user settings, check secure your clusters with OpenID Connect.
- Kerberos
- All Kerberos settings are allowlisted.
-
xpack.security.authc.realms.kerberos.*
- To learn more on how to enable Kerberos and relate user settings, check secure your clusters with Kerberos.
- JWT
- All JWT settings are allowlisted.
-
xpack.security.authc.realms.jwt.*
- To learn more on how to enable JWT and related user settings, check secure your clusters with JWT.
- X-Pack (for version 5.0 and later)
-
The following X-Pack settings are supported:
-
xpack.security.authc.anonymous.*
- To learn more on how to enable anonymous access, check Enabling anonymous access
-
xpack.notification.slack
-
Configures Slack notification settings
(up to 6.2 | 6.3 and later). Note that you need to add
secure_url
as a secret value to the keystore. -
xpack.notification.hipchat
- Configures HipChat notification settings (up to 6.2 | 6.3 to 6.7).
-
xpack.notification.pagerduty
- Configures PagerDuty notification settings (up to 6.2 | 6.3 and later).
-
xpack.watcher.trigger.schedule.engine
- Defines when the watch should start, based on date and time (6.3 and later).
-
xpack.notification.email.html.sanitization.*
- Enables email notification settings to sanitize HTML elements in emails that are sent.
-
xpack.monitoring.collection.interval
- Controls how often data samples are collected.
-
xpack.monitoring.collection.min_interval_seconds
-
Specifies the minimum number of seconds that a time bucket in a chart can represent. If you modify the
xpack.monitoring.collection.interval
, use the same value in this setting.Defaults to
10
(10 seconds). -
xpack.monitoring.history.duration
- Sets the retention duration beyond which the indices created by a monitoring exporter will be automatically deleted.
-
xpack.watcher.history.cleaner_service.enabled
- Controls whether old watcher indices are automatically deleted (requires 5.6.4 or greater).
-
xpack.http.ssl.cipher_suites
- Controls the list of supported cipher suites for all outgoing TLS connections.
-
xpack.security.transport.ssl.trust_restrictions.x509_fields
- For versions 8.5.3 and newer. Also supported in 7.x as of 7.17.8: Specifies which field(s) from the TLS certificate is used to match for the restricted trust management that is used for remote clusters connections. This should only be set when a self managed cluster can not create certificates that follow the Elastic Cloud pattern. The default value is ["subjectAltName.otherName.commonName"], the Elastic Cloud pattern. "subjectAltName.dnsName" is also supported and can be configured in addition to or in replacement of the default.
-
- Scripting 5.x
-
The following settings are supported in Elasticsearch 5.x clusters:
-
script.inline
-
script.stored
-
script.file
-
script.allowed_types
-
script.allowed_contexts
-
To learn more, check Allowed script types setting and Allowed script contexts setting.
- Scripting 6.x
-
The following settings are supported in Elasticsearch 6.x clusters:
-
script.allowed_types
-
script.allowed_contexts
-
To learn more, check Allowed script types setting and Allowed script contexts setting.
- Search
-
The following setting is supported in Elasticsearch 7.13.2 clusters and higher:
-
search.aggs.rewrite_to_filter_by_filter
-
- Watcher and Marvel (for versions before 5.0)
-
The following Watcher and Marvel settings are supported:
-
watcher.actions.slack.service
- Configures Slack notification settings.
-
watcher.actions.hipchat.service
-
Configures HipChat notification settings.
Deprecated in all versions.
Hipchat has ceased operation.
-
watcher.actions.pagerduty.service
- Configures Configures PagerDuty notification settings.
-
marvel.agent.interval
- Controls how often data samples are collected.
-
watcher.trigger.schedule.engine
- Defines when the watch should start, based on date and time.
-
- Disk-based shard allocation settings
-
The following disk-based allocation settings are supported:
-
cluster.routing.allocation.disk.threshold_enabled
-
Enable or disable disk allocation decider and defaults to
true
. -
cluster.routing.allocation.disk.watermark.low
- Configures disk-based shard allocation’s low watermark.
-
cluster.routing.allocation.disk.watermark.high
- Configures disk-based shard allocation’s high watermark.
-
cluster.routing.allocation.disk.watermark.flood_stage
- Configures disk-based shard allocation’s flood_stage (available only on 6.x and higher).
Remember to update user settings for alerts when performing a major version upgrade. For version 5.0 and later, the syntax is different when compared to earlier versions.
-
- Enrich settings
- The following enrich settings are supported:
-
enrich.cache_size
- introduced in 7.16: Maximum number of searches to cache for enriching documents. Defaults to 1000. There is a single cache for all enrich processors in the cluster. This setting determines the size of that cache.
-
enrich.coordinator_proxy.max_concurrent_requests
- Maximum number of concurrent multi-search requests to run when enriching documents. Defaults to 8.
-
enrich.coordinator_proxy.max_lookups_per_request
- Maximum number of searches to include in a multi-search request when enriching documents. Defaults to 128.
-
enrich.coordinator_proxy.queue_capacity
- coordinator queue capacity, defaults to max_concurrent_requests * max_lookups_per_request
- Audit settings
- The following audit settings are supported:
-
xpack.security.audit.enabled
- Enables auditing on Elasticsearch cluster nodes. Defaults to false.
-
xpack.security.audit.logfile.events.include
- Specifies which events to include in the auditing output.
-
xpack.security.audit.logfile.events.exclude
- Specifies which events to exclude from the output. No events are excluded by default.
-
xpack.security.audit.logfile.events.emit_request_body
- Specifies whether to include the request body from REST requests on certain event types, for example authentication_failed. Defaults to false.
-
xpack.security.audit.logfile.emit_node_name
- For versions above 6.5.0: Specifies whether to include the node name as a field in each audit event. Defaults to true.
-
xpack.security.audit.logfile.prefix.emit_node_name
- For versions below 6.5.0: Specifies whether to include the node name as a field in each audit event. Defaults to true.
-
xpack.security.audit.logfile.emit_node_host_address
- For versions above 6.5.0: Specifies whether to include the node’s IP address as a field in each audit event. Defaults to false.
-
xpack.security.audit.logfile.prefix.emit_node_host_address
- For versions below 6.5.0: Specifies whether to include the node’s IP address as a field in each audit event. Defaults to false.
-
xpack.security.audit.logfile.emit_node_host_name
- For versions above 6.5.0: Specifies whether to include the node’s host name as a field in each audit event. Defaults to false.
-
xpack.security.audit.logfile.prefix.emit_node_host_name
- For versions below 6.5.0: Specifies whether to include the node’s host name as a field in each audit event. Defaults to false.
-
xpack.security.audit.logfile.emit_node_id
- For versions above 6.5.0: Specifies whether to include the node ID as a field in each audit event. Defaults to true.
-
xpack.security.audit.logfile.events.ignore_filters.<policy_name>.users
- A list of user names or wildcards. The specified policy will not print audit events for users matching these values.
-
xpack.security.audit.logfile.events.ignore_filters.<policy_name>.realms
- A list of authentication realm names or wildcards. The specified policy will not print audit events for users in these realms.
-
xpack.security.audit.logfile.events.ignore_filters.<policy_name>.roles
- A list of role names or wildcards. The specified policy will not print audit events for users that have these roles.
-
xpack.security.audit.logfile.events.ignore_filters.<policy_name>.indices
- A list of index names or wildcards. The specified policy will not print audit events when all the indices in the event match these values.
-
xpack.security.audit.logfile.events.ignore_filters.<policy_name>.actions
- For versions 7.13.0 and above: A list of action names or wildcards. The specified policy will not print audit events for actions matching these values.
To enable auditing you must first enable deployment logging.
- Universal Profiling settings
- The following settings for Elastic Universal Profiling are supported:
-
xpack.profiling.enabled
- For version 8.7.0 and later: Specifies whether the Universal Profiling Elasticsearch plugin is enabled. Defaults to true.
-
xpack.profiling.templates.enabled
- For version 8.9.0 and later: Specifies whether Universal Profiling related index templates should be created on startup. Defaults to false.