[[cluster-update-settings]]
=== Cluster update settings API
++++
<titleabbrev>Cluster update settings</titleabbrev>
++++

Updates cluster-wide settings.


[[cluster-update-settings-api-request]]
==== {api-request-title}

`PUT /_cluster/settings`

[[cluster-update-settings-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `manage`
<<privileges-list-cluster,cluster privilege>> to use this API.

[[cluster-update-settings-api-desc]]
==== {api-description-title}

With specifications in the request body, this API call can update cluster
settings. Updates to settings can be persistent, meaning they apply across
restarts, or transient, where they don't survive a full cluster restart.

You can reset persistent or transient settings by assigning a `null` value. If a
transient setting is reset, the first one of these values that is defined is
applied:

* the persistent setting
* the setting in the configuration file
* the default value.

The order of precedence for cluster settings is:

1. transient cluster settings
2. persistent cluster settings
3. settings in the `elasticsearch.yml` configuration file.

It's best to set all cluster-wide settings with the `settings` API and use the
`elasticsearch.yml` file only for local configurations. This way you can be sure that
the setting is the same on all nodes. If, on the other hand, you define different
settings on different nodes by accident using the configuration file, it is very
difficult to notice these discrepancies.

NOTE: Transient settings are deprecated and will be removed in a future release.
Prefer using persistent cluster settings instead.

[[cluster-update-settings-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=flat-settings]

`include_defaults`::
    (Optional, Boolean) If `true`, returns all default cluster settings.
    Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]


[[cluster-update-settings-api-example]]
==== {api-examples-title}

An example of a persistent update:

[source,console]
--------------------------------------------------
PUT /_cluster/settings
{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}
--------------------------------------------------


An example of a transient update:

[source,console]
--------------------------------------------------
PUT /_cluster/settings?flat_settings=true
{
  "transient" : {
    "indices.recovery.max_bytes_per_sec" : "20mb"
  }
}
--------------------------------------------------
// TEST[warning:[transient settings removal] Updating cluster settings through transientSettings is deprecated. Use persistent settings instead.]

The response to an update returns the changed setting, as in this response to
the transient example:

[source,console-result]
--------------------------------------------------
{
  ...
  "persistent" : { },
  "transient" : {
    "indices.recovery.max_bytes_per_sec" : "20mb"
  }
}
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]


This example resets a setting:

[source,console]
--------------------------------------------------
PUT /_cluster/settings
{
  "transient" : {
    "indices.recovery.max_bytes_per_sec" : null
  }
}
--------------------------------------------------
// TEST[warning:[transient settings removal] Updating cluster settings through transientSettings is deprecated. Use persistent settings instead.]


The response does not include settings that have been reset:

[source,console-result]
--------------------------------------------------
{
  ...
  "persistent" : {},
  "transient" : {}
}
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"acknowledged": true,/]


You can also reset settings using wildcards. For example, to reset
all dynamic `indices.recovery` settings:

[source,console]
--------------------------------------------------
PUT /_cluster/settings
{
  "transient" : {
    "indices.recovery.*" : null
  }
}
--------------------------------------------------
// TEST[warning:[transient settings removal] Updating cluster settings through transientSettings is deprecated. Use persistent settings instead.]