[[actions]]
= Actions

[partintro]
--

Actions are the tasks which Curator can perform on your indices.  Snapshots,
once created, can only be deleted.

* <<alias,Alias>>
* <<allocation,Allocation>>
* <<close,Close>>
* <<cluster_routing,Cluster Routing>>
* <<create_index,Create Index>>
* <<delete_indices,Delete Indices>>
* <<delete_snapshots,Delete Snapshots>>
* <<open,Open>>
* <<forcemerge,forceMerge>>
* <<replicas,Replicas>>
* <<restore,Restore>>
* <<snapshot,Snapshot>>
--

[[alias]]
== Alias

[source,yaml]
-------------
action: alias
description: "Add/Remove selected indices to or from the specified alias"
options:
  name: alias_name
  extra_settings:
  timeout_override:
  continue_if_exception: False
  disable_action: False
add:
  filters:
  - filtertype: ...
remove:
  filters:
  - filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action adds and/or removes indices from the alias identified by
 <<option_name,name>>

The <<filters,filters>> under the `add` and `remove` directives define which
indices will be added and/or removed.  This is an atomic action, so adds and
removes happen instantaneously.

The <<option_extra_settings,extra_settings>> option allows the addition of extra
settings with the `add` directive.  These settings are ignored for `remove`.  An
example of how these settings can be used to create a filtered alias might be:

[source,yaml]
-------------
extra_settings:
  filter:
    term:
      user: kimchy
-------------

WARNING: Before creating a filtered alias, first ensure that the fields already
  exist in the mapping.

Learn more about adding filtering and routing to aliases in the
{ref}/indices-aliases.html[Elasticsearch Alias API documentation].

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_name,name>> (required)

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_extra_settings,extra_settings>> (No default value.)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_alias,here>>.

[[allocation]]
== Allocation

[source,yaml]
-------------
action: allocation
description: "Apply shard allocation filtering rules to the specified indices"
options:
  key:
  value:
  allocation_type:
  wait_for_completion: False
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action changes the shard routing allocation for the selected indices.

See https://www.elastic.co/guide/en/elasticsearch/reference/current/shard-allocation-filtering.html
for more information.

You can optionally set `wait_for_completion` to `True`
to have Curator wait for the shard routing to complete before continuing.  If
this option is chosen, it is advisable to use the
<<option_timeout_override,timeout_override>> option in order to avoid client
timeouts.

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_key,key>> (required)
* <<option_value,value>> (required)

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_allocation_type,allocation_type>> (has a default value which can
    optionally be changed)
* <<option_wfc,wait_for_completion>> (has a default value which can optionally
    be changed)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_allocation,here>>.

[[close]]
== Close

[source,yaml]
-------------
action: close
description: "Close selected indices"
options:
  delete_aliases: False
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action closes the selected indices, and optionally deletes associated
aliases beforehand.

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_delete_aliases,delete_aliases>> (has a default value which can
    optionally be changed)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_close,here>>.

[[cluster_routing]]
== Cluster Routing

[source,yaml]
-------------
action: cluster_routing
description: "Apply routing rules to the entire cluster"
options:
  routing_type:
  value:
  setting: enable
  wait_for_completion: False
  timeout_override:
  continue_if_exception: False
  disable_action: False
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action changes the shard routing allocation for the selected indices.

See https://www.elastic.co/guide/en/elasticsearch/reference/current/shards-allocation.html
for more information.

You can optionally set `wait_for_completion` to `True`
to have Curator wait for the shard routing to complete before continuing.  If
this option is chosen, it is advisable to use the
<<option_timeout_override,timeout_override>> option in order to avoid client
timeouts.

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_routing_type,routing_type>> (required)
* <<option_value,value>> (required)
* <<option_setting,setting>> Currently must be set to `enable`.  This setting
  is a placeholder for potential future expansion.

[float]
Optional settings
~~~~~~~~~~~~~~~~~

* <<option_wfc,wait_for_completion>> (has a default value which can optionally
    be changed)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_cluster_routing,here>>.

[[create_index]]
== Create Index

[source,yaml]
-------------
action: create_index
description: "Create index as named"
options:
  name:
  extra_settings:
  timeout_override:
  continue_if_exception: False
  disable_action: False
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action creates the named index.

The <<option_extra_settings,extra_settings>> option allows the addition of extra
settings, such as index settings and mappings.  An example of how these settings
can be used to create an index might be:

[source,yaml]
-------------
extra_settings:
  settings:
    number_of_shards: 1
    number_of_replicas: 0
  mappings:
    type1 :
      properties:
        field1:
          type: string
          index: not_analyzed
-------------

[float]
Required settings
~~~~~~~~~~~~~~~~~
* <<option_name,name>>

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_extra_settings,extra_settings>> No default value.  You can add any
    acceptable index settings and mappings as nested YAML.  See the
    {ref}/indices-create-index.html[Elasticsearch Create Index API documentation]
    for more information.
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_create_index,here>>.

[[delete_indices]]
== Delete Indices

[source,yaml]
-------------
action: delete_indices
description: "Delete selected indices"
options:
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action deletes the selected indices.

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_delete_indices,here>>.


[[delete_snapshots]]
== Delete Snapshots

[source,yaml]
-------------
action: delete_snapshots
description: "Delete selected snapshots from 'repository'"
options:
  repository:
  retry_interval:
  retry_count:
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action deletes the selected snapshots from the selected
<<option_repository,repository>>.  If issues are encountered, it will retry
up to <<option_retry_count,retry_count>> times, with a delay of
<<option_retry_interval,retry_interval>> seconds between retries.

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_repository,repository>> (required)

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_retry_interval,retry_interval>> (has a default value which can
    optionally be changed)
* <<option_retry_count,retry_count>> (has a default value which can optionally
    be changed)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_delete_snapshots,here>>.


[[open]]
== Open

[source,yaml]
-------------
action: open
description: "open selected indices"
options:
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action opens the selected indices.

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_open,here>>.


[[forcemerge]]
== Forcemerge

[source,yaml]
-------------
action: forcemerge
description: "Perform a forceMerge on selected indices to 'max_num_segments' per shard"
options:
  max_num_segments:
  delay:
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action performs a forceMerge on the selected indices, merging them to
<<option_mns,max_num_segments>> per shard, with an optional pause between each
merge of <<option_delay,delay>> seconds to allow the cluster to quiesce.

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_mns,max_num_segments>> (required)

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_delay,delay>> (has a default value which can optionally be changed)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_forcemerge,here>>.



[[replicas]]
== Replicas

[source,yaml]
-------------
action: replicas
description: >- Set the number of replicas per shard for selected
    indices to 'count'
options:
  count:
  wait_for_completion: False
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action will set the number of replicas per shard to the value of
<<option_count,count>>.  You can optionally set `wait_for_completion` to `True`
to have Curator wait for the replication operation to complete before
continuing.  If this option is chosen, it is advisable to use the
<<option_timeout_override,timeout_override>> option in order to avoid client
timeouts.

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_count,count>> (required)

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_wfc,wait_for_completion>> (has a default value which can optionally
    be changed)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_replicas,here>>.

[[restore]]
== Restore

[source,yaml]
-------------
actions:
  1:
    action: restore
    description: >-
      Restore all indices in the most recent snapshot with state SUCCESS.  Wait
      for the restore to complete before continuing.  Do not skip the repository
      filesystem access check.  Use the other options to define the index/shard
      settings for the restore.
    options:
      repository:
      # Leaving name blank will result in restoring the most recent snapshot by age
      name:
      # Leaving indices blank will result in restoring all indices in the snapshot
      indices:
      include_aliases: False
      ignore_unavailable: False
      include_global_state: True
      partial: False
      rename_pattern:
      rename_replacement:
      extra_settings:
      wait_for_completion: True
      skip_repo_fs_check: False
      timeout_override:
      continue_if_exception: False
      disable_action: False
    filters:
    - filtertype: state
      state: SUCCESS
      exclude:
    - filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action will restore indices from the indicated
<<option_repository,repository>>, from the most recent snapshot identified by
the applied filters, or the snapshot identified by <<option_name,name>>.

The other options are usually okay to leave at the defaults, but feel free to
read about them and change them accordingly.

The <<option_extra_settings,extra_settings>> option allows the addition of extra
settings, such as index settings and mappings.  An example of how these settings
can be used to change settings for an index being restored might be:

[source,yaml]
-------------
extra_settings:
  settings:
    number_of_shards: 1
    number_of_replicas: 0
  mappings:
    type1 :
      properties:
        field1:
          type: string
          index: not_analyzed
-------------

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_repository,repository>> (required)

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_name,name>> (has no default value)
* <<option_include_aliases,include_aliases>> (has a default value which can
    optionally be changed)
* <<option_indices,indices>> (has a default value which can optionally be
    changed)
* <<option_ignore,ignore_unavailable>> (has a default value which can optionally
    be changed)
* <<option_include_gs,include_global_state>> (has a default value which can
    optionally be changed)
* <<option_partial,partial>> (has a default value which can optionally be
    changed)
* <<option_rename_pattern,rename_pattern>> (has no default value)
* <<option_rename_replacement,rename_replacement>> (has no default value)
* <<option_extra_settings,extra_settings>> (has no default value.)
* <<option_wfc,wait_for_completion>> (has a default value which can optionally
    be changed)
* <<option_skip_fsck,skip_repo_fs_check>> (has a default value which can
    optionally be changed)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_restore,here>>.

[[snapshot]]
== Snapshot

[source,yaml]
-------------
action: snapshot
description: >-
  Snapshot selected indices to 'repository' with the snapshot name or name
  pattern in 'name'.  Use all other options as assigned
options:
  repository:
  # Leaving name blank will result in the default 'curator-%Y%m%d%H%M%S'
  name:
  ignore_unavailable: False
  include_global_state: True
  partial: False
  wait_for_completion: True
  skip_repo_fs_check: False
  timeout_override:
  continue_if_exception: False
  disable_action: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action will snapshot indices to the indicated
<<option_repository,repository>>, with a name, or name pattern, as identified by
<<option_name,name>>.

The other options are usually okay to leave at the defaults, but feel free to
read about them and change them accordingly.

[float]
Required settings
~~~~~~~~~~~~~~~~~

* <<option_repository,repository>> (required)

[float]
Optional settings
~~~~~~~~~~~~~~~~~
* <<option_name,name>> (has a default value which can optionally be changed)
* <<option_ignore,ignore_unavailable>> (has a default value which can optionally
    be changed)
* <<option_include_gs,include_global_state>> (has a default value which can
    optionally be changed)
* <<option_partial,partial>> (has a default value which can optionally be
    changed)
* <<option_wfc,wait_for_completion>> (has a default value which can optionally
    be changed)
* <<option_skip_fsck,skip_repo_fs_check>> (has a default value which can
    optionally be changed)
* <<option_ignore_empty,ignore_empty_list>> (can override the default)
* <<option_timeout_override,timeout_override>> (can override the default
    <<timeout,timeout>>)
* <<option_continue,continue_if_exception>> (has a default value which can
    optionally be changed)
* <<option_disable,disable_action>> (has a default value which can optionally
    be changed)

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_snapshot,here>>.