[[options]]
= Options

[partintro]
--

Options are settings used by <<actions,actions>>.

* <<option_allocation_type,allocation_type>>
* <<option_continue,continue_if_exception>>
* <<option_count,count>>
* <<option_delay,delay>>
* <<option_delete_aliases,delete_aliases>>
* <<option_disable,disable_action>>
* <<option_extra_settings,extra_settings>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_ignore,ignore_unavailable>>
* <<option_include_aliases,include_aliases>>
* <<option_include_gs,include_global_state>>
* <<option_indices,indices>>
* <<option_key,key>>
* <<option_mns,max_num_segments>>
* <<option_name,name>>
* <<option_partial,partial>>
* <<option_rename_pattern,rename_pattern>>
* <<option_rename_replacement,rename_replacement>>
* <<option_repository,repository>>
* <<option_retry_count,retry_count>>
* <<option_retry_interval,retry_interval>>
* <<option_routing_type,routing_type>>
* <<option_setting,setting>>
* <<option_skip_fsck,skip_repo_fs_check>>
* <<option_timeout_override,timeout_override>>
* <<option_value,value>>
* <<option_wfc,wait_for_completion>>

Starting in Curator 4.1, you can use <<envvars,environment variables>> in your
configuration files.
--

[[option_allocation_type]]
== allocation_type

NOTE: This setting is used only when using the <<allocation,allocation action>>

The value of this setting must be one of `require`, `include`, or `exclude`.

Read more about these settings at {ref}/shard-allocation-filtering.html

The default value for this setting is `require`.

[[option_continue]]
== continue_if_exception

NOTE: This setting is available in all actions.

If `continue_if_exception` is set to `True`, Curator will attempt to continue on
to the next action, if any, even if an exception is encountered. Curator will
log but ignore the exception that was raised.

The default value for this setting is `False`

[[option_count]]
== count

NOTE: This setting is required when using the <<replicas,replicas action>>.

The value for this setting is the number of replicas to assign to matching
indices.

There is no default value. This setting must be set by the user or an exception
will be raised, and execution will halt.

[[option_delay]]
== delay

NOTE: This setting is only used by the <<forcemerge,forceMerge action>>, and is
    optional.

The value for this setting is the number of seconds to delay between
forceMerging indices, to allow the cluster to quiesce.

There is no default value.

[[option_delete_aliases]]
== delete_aliases

NOTE: This setting is only used by the <<close,close action>>, and is
    optional.

The value for this setting determines whether aliases will be deleted from
indices before closing.

The default value is `False`.

[[option_disable]]
== disable_action

NOTE: This setting is available in all actions.

If `disable_action` is set to `True`, Curator will ignore the current action.
This may be useful for temporarily disabling actions in a large configuration
file.

The default value for this setting is `False`

[[option_extra_settings]]
== extra_settings

This setting should be nested YAML.  The values beneath `extra_settings` will be
used by whichever action uses the option.

There is no default value.

[[option_ignore_empty]]
== ignore_empty_list

This setting must be either `True` or `False`.

Depending on your indices, and how you've filtered them, an empty list may be
presented to the action.  This results in an error condition.

When the ignore_empty_list option is set to `True`, the action will exit with an
INFO level log message indicating such.  If ignore_empty_list is set to `False`,
an ERROR level message will be logged, and Curator will exit with code 1.

The default value of this setting is `False`

[[option_ignore]]
== ignore_unavailable

NOTE: This setting is only used by the <<snapshot,snapshot>> action.

This setting must be either `True` or `False`.

When the ignore_unavailable option is `False` and an index is missing the
snapshot request will fail.

The default value of this setting is `False`

[[option_include_aliases]]
== include_aliases

NOTE: This setting is only used by the <<restore,restore>> action.

This setting must be either `True` or `False`.

The value of this setting determines whether Elasticsearch should include index
aliases when restoring the snapshot.

The default value of this setting is `False`

[[option_include_gs]]
== include_global_state

NOTE: This setting is only used by the <<snapshot,snapshot>> action.

This setting must be either `True` or `False`.

The value of this setting determines whether Elasticsearch should include the
global cluster state with the snapshot.

The default value of this setting is `True`

[[option_indices]]
== indices

NOTE: This setting is only used by the <<restore,restore>> action.

This setting must be a list of indices to restore.  Any valid YAML format for
lists are acceptable here.  If `indices` is left empty, or unset, all indices in
the snapshot will be restored.

The default value of this setting is `None`

[[option_key]]
== key

NOTE: This setting is required when using the <<allocation,allocation action>>.

The value of this setting should correspond to a node setting on one or more
nodes in your cluster.

For example, you might have set

[source,sh]
-----------
node.tag: myvalue
-----------

in your `elasticsearch.yml` file for one or more of your nodes.  To match
allocation in this case, set key to `tag`.

These special attributes are also supported:

[cols="2*", options="header"]
|===
|attribute
|description

|`_name`
|Match nodes by node name

|`_host_ip`
|Match nodes by host IP address (IP associated with hostname)

|`_publish_ip`
|Match nodes by publish IP address

|`_ip`
|Match either `_host_ip` or `_publish_ip`

|`_host`
|Match nodes by hostname
|===

There is no default value. This setting must be set by the user or an exception
will be raised, and execution will halt.

[[option_mns]]
== max_num_segments

NOTE: This setting is required when using the <<forcemerge,forceMerge action>>
    or the <<filtertype_forcemerged,forcemerged filtertype>>.

The value for this setting is the cutoff number of segments per shard.  Indices
which have more than this number of segments per shard will remain in the index
list.

There is no default value. This setting must be set by the user or an exception
will be raised, and execution will halt.


[[option_name]]
== name

NOTE: This setting is used by the <<alias,alias>>, <<snapshot,snapshot>>, and
    <<create_index,create_index>> actions.

The value of this setting is the name of the alias, snapshot, or index,
depending on which action makes use of `name`.

This setting may contain a valid Python strftime string.  Curator will
extract the strftime identifiers and replace them with the corresponding values.

The Python strftime identifiers that Curator currently recognizes include:

* `Y`: A 4 digit year
* `y`: A 2 digit year
* `m`: The 2 digit month
* `W`: The 2 digit week of the year
* `d`: The 2 digit day of the month
* `H`: The 2 digit hour of the day, in 24 hour notation
* `M`: The 2 digit minute of the hour
* `S`: The 2 digit number of second of the minute
* `j`: The 3 digit day of the year

This option is required by the <<alias,alias>> action, and has no default
setting in that context.

For the <<create_index,create_index>> action, there is no default setting.

For the <<snapshot,snapshot>> action, the default value of this setting is
`curator-%Y%m%d%H%M%S`



[[option_partial]]
== partial

NOTE: This setting is only used by the <<snapshot,snapshot>> action.

This setting must be either `True` or `False`.

The entire snapshot will fail if one or more indices being added to the
snapshot don’t have all primary shards available. This behavior can be changed
by setting partial to `True`.

The default value of this setting is `False`

[[option_rename_pattern]]
== rename_pattern

NOTE: This setting is only used by the <<restore, restore>> action.

[TIP]
.from the Elasticsearch documentation
======================================
The <<option_rename_pattern,rename_pattern>> and
<<option_rename_replacement,rename_replacement>> options can be also used to
rename indices on restore using regular expression that supports referencing the
original text as explained
http://docs.oracle.com/javase/6/docs/api/java/util/regex/Matcher.html#appendReplacement(java.lang.StringBuffer,%20java.lang.String)[here].
======================================

Read more about this setting at {ref}/modules-snapshots.html#_restore

There is no default value.

[[option_rename_replacement]]
== rename_replacement

NOTE: This setting is only used by the <<restore, restore>> action.

[TIP]
.From the Elasticsearch documentation
======================================
The <<option_rename_pattern,rename_pattern>> and
<<option_rename_replacement,rename_replacement>> options can be also used to
rename indices on restore using regular expression that supports referencing the
original text as explained
http://docs.oracle.com/javase/6/docs/api/java/util/regex/Matcher.html#appendReplacement(java.lang.StringBuffer,%20java.lang.String)[here].
======================================

Read more about this setting at {ref}/modules-snapshots.html#_restore

There is no default value.

[[option_repository]]
== repository

NOTE: This setting is only used by the <<snapshot, snapshot>>, and
    <<delete_snapshots, delete snapshots>> actions.

There is no default value. This setting must be set by the user or an exception
will be raised, and execution will halt.


[[option_retry_count]]
== retry_count

NOTE: This setting is only used by the <<delete_snapshots, delete snapshots action>>.

The value of this setting is the number of times to retry deleting a snapshot.

The default for this setting is `3`.

[[option_retry_interval]]
== retry_interval

NOTE: This setting is only used by the <<delete_snapshots, delete snapshots action>>.

The value of this setting is the number of seconds to delay between retries.

The default for this setting is `120`.

[[option_routing_type]]
== routing_type

NOTE: This setting is only used by the <<cluster_routing, cluster_routing action>>.

The value of this setting must be either `allocation` or `rebalance`

There is no default value. This setting must be set by the user or an exception
will be raised, and execution will halt.

[[option_setting]]
== setting

NOTE: This setting is only used by the <<cluster_routing, cluster_routing action>>.

The value of this must be `enable` at present.  It is a placeholder for future
expansion.

There is no default value. This setting must be set by the user or an exception
will be raised, and execution will halt.


[[option_skip_fsck]]
== skip_repo_fs_check

NOTE: This setting is only used by the <<snapshot,snapshot>> action.

This setting must be either `True` or `False`.

Each master and data node in the cluster _must_ have write access to the shared
filesystem used by the repository.  Some filesystems may take longer to respond
to a check, which results in a false positive for the filesystem access check.
For these cases, it is desirable to bypass this verification step, by setting
this to `True.`

The default value of this setting is `False`


[[option_timeout_override]]
== timeout_override

NOTE: This setting is available in all actions.

Actions <<snapshot,snapshot>>, <<restore,restore>>, and
    <<forcemerge,forcemerge>> will override this value to `21600` if
    `timeout_override` is unset.  The <<close,close>> action will override the
    value to 180 if unset.

Some actions have a default value for `timeout_override`. The following table
shows these default values:

[cols="m,", options="header"]
|===
|Action Name |Default `timeout_override` Value
|close |180
|forcemerge |21600
|restore |21600
|snapshot |21600
|===

All other actions have no default value for `timeout_override`.

This setting must be an integer number of seconds, or an error will result.

This setting is particularly useful for the <<forcemerge,forceMerge>> action,
the <<snapshot,snapshot>> action, and any other action where a longer timeout
from the client-defined default would be desirable.


[[option_value]]
== value

NOTE: This setting is required when using the <<allocation,allocation action>>
    or the <<cluster_routing,cluster_routing action>>.

=== <<allocation,allocation>> value

For the <<allocation,allocation action>>, the value of this setting should
correspond to a node setting on one or more nodes in your cluster.

For example, you might have set

[source,sh]
-----------
node.tag: myvalue
-----------

in your `elasticsearch.yml` file for one or more of your nodes.  To match
allocation in this case, set value to `myvalue`. Additonally, if you used one of
the special attribute names `_ip`, `_name`, `_id`, or `_host` for
<<option_key,key>>, value can match the one of the node ip addresses, names,
ids, or host names, respectively.

=== <<cluster_routing,cluster_routing>> value

For the <<cluster_routing,cluster_routing action>>, the acceptable values for
this setting depend on the value of <<option_routing_type,routing_type>>.

Acceptable values when <<option_routing_type,routing_type>> is either
`allocation` or `rebalance` are `all`, `primaries`, and  `none` (string, not
`NoneType`).

If `routing_type` is `allocation`, this can also be `new_primaries`. If
`routing_type` is `rebalance`, then the value can also be `replicas`.

There is no default value. This setting must be set by the user or an exception
will be raised, and execution will halt.

[[option_wfc]]
== wait_for_completion

NOTE: This setting is used by the <<allocation,allocation>>,
    <<replicas,replicas>>, <<restore,restore>>, and <<snapshot,snapshot>>
    actions.

This setting must be either `True` or `False`.

This setting specifies whether or not the request should return immediately or
wait for the operation to complete before returning.


TIP: During snapshot initialization, information about all previous snapshots is
    loaded into the memory, which means that in large repositories it may take
    several seconds (or even minutes) for this command to return even if the
    `wait_for_completion` setting is set to `False`.

The default value of this setting differs for each action.  The default for the
<<allocation,allocation>> and <<replicas,replicas>> actions is `False`.  The
default for the <<restore,restore>> and <<snapshot,snapshot>> actions is `True`.