1[[options]] 2= Options 3 4[partintro] 5-- 6 7Options are settings used by <<actions,actions>>. 8 9* <<option_allocation_type,allocation_type>> 10* <<option_allow_ilm,allow_ilm_indices>> 11* <<option_continue,continue_if_exception>> 12* <<option_count,count>> 13* <<option_delay,delay>> 14* <<option_delete_aliases,delete_aliases>> 15* <<option_skip_flush,skip_flush>> 16* <<option_disable,disable_action>> 17* <<option_extra_settings,extra_settings>> 18* <<option_ignore_empty,ignore_empty_list>> 19* <<option_ignore,ignore_unavailable>> 20* <<option_include_aliases,include_aliases>> 21* <<option_include_gs,include_global_state>> 22* <<option_indices,indices>> 23* <<option_key,key>> 24* <<option_max_age,max_age>> 25* <<option_max_docs,max_docs>> 26* <<option_max_size,max_size>> 27* <<option_mns,max_num_segments>> 28* <<option_max_wait,max_wait>> 29* <<option_migration_prefix,migration_prefix>> 30* <<option_migration_suffix,migration_suffix>> 31* <<option_name,name>> 32* <<option_new_index,new_index>> 33* <<option_node_filters,node_filters>> 34* <<option_number_of_replicas,number_of_replicas>> 35* <<option_number_of_shards,number_of_shards>> 36* <<option_partial,partial>> 37* <<option_refresh,refresh>> 38* <<option_remote_aws_key,remote_aws_key>> 39* <<option_remote_aws_region,remote_remote_aws_region>> 40* <<option_remote_aws_secret_key,remote_aws_secret_key>> 41* <<option_remote_certificate,remote_certificate>> 42* <<option_remote_client_cert,remote_client_cert>> 43* <<option_remote_client_key,remote_client_key>> 44* <<option_remote_filters,remote_filters>> 45* <<option_remote_ssl_no_validate,remote_ssl_no_validate>> 46* <<option_remote_url_prefix,remote_url_prefix>> 47* <<option_rename_pattern,rename_pattern>> 48* <<option_rename_replacement,rename_replacement>> 49* <<option_repository,repository>> 50* <<option_request_body,request_body>> 51* <<option_requests_per_second,requests_per_second>> 52* <<option_retry_count,retry_count>> 53* <<option_retry_interval,retry_interval>> 54* <<option_routing_type,routing_type>> 55* <<option_setting,setting>> 56* <<option_shrink_node,shrink_node>> 57* <<option_slices,slices>> 58* <<option_skip_fsck,skip_repo_fs_check>> 59* <<option_timeout,timeout>> 60* <<option_timeout_override,timeout_override>> 61* <<option_value,value>> 62* <<option_wait_for_active_shards,wait_for_active_shards>> 63* <<option_wfc,wait_for_completion>> 64* <<option_wait_for_rebalance,wait_for_rebalance>> 65* <<option_wait_interval,wait_interval>> 66* <<option_warn_if_no_indices,warn_if_no_indices>> 67 68You can use <<envvars,environment variables>> in your configuration files. 69-- 70 71[[option_allocation_type]] 72== allocation_type 73 74NOTE: This setting is used only when using the <<allocation,allocation action>> 75 76[source,yaml] 77------------- 78action: allocation 79description: "Apply shard allocation filtering rules to the specified indices" 80options: 81 key: ... 82 value: ... 83 allocation_type: ... 84filters: 85- filtertype: ... 86------------- 87 88The value of this setting must be one of `require`, `include`, or `exclude`. 89 90Read more about these settings at {ref}/shard-allocation-filtering.html 91 92The default value for this setting is `require`. 93 94[[option_allow_ilm]] 95== allow_ilm_indices 96 97This option allows Curator to manage ILM-enabled indices. Exercise caution that 98ILM policies and Curator actions will not interfere with each other. 99 100IMPORTANT: Read more about Curator and Index Lifecycle Management 101 <<ilm,here>>. 102 103[source,yaml] 104------------- 105action: delete_indices 106description: "Delete the specified indices" 107options: 108 allow_ilm_indices: true 109filters: 110- filtertype: ... 111------------- 112 113The value of this setting must be either `true` or `false`. 114 115The default value for this setting is `false`. 116 117[[option_continue]] 118== continue_if_exception 119 120[IMPORTANT] 121.Using `ignore_empty_list` rather than `continue_if_exception` 122==================================== 123Curator has two general classifications of exceptions: Empty list exceptions, 124and everything else. The empty list conditions are `curator.exception.NoIndices` 125and `curator.exception.NoSnapshots`. The `continue_if_exception` option _only_ 126catches conditions _other_ than empty list conditions. In most cases, you will 127want to use `ignore_empty_list` instead of `continue_if_exception`. 128 129So why are there two kinds of exceptions? When Curator 4 was released, the 130ability to continue in the event of any exception was covered by the 131`continue_if_exception` option. However, an empty list is a _benign_ condition. 132In fact, it's expected with brand new clusters, or when new index patterns are 133added. The decision was made to split the exceptions, and have a new option 134catch the empty lists. 135 136See <<option_ignore_empty,`ignore_empty_list`>> for more information. 137==================================== 138 139NOTE: This setting is available in all actions. 140 141[source,yaml] 142------------- 143action: delete_indices 144description: "Delete selected indices" 145options: 146 continue_if_exception: False 147filters: 148- filtertype: ... 149------------- 150 151If `continue_if_exception` is set to `True`, Curator will attempt to continue on 152to the next action, if any, even if an exception is encountered. Curator will 153log but ignore the exception that was raised. 154 155The default value for this setting is `False` 156 157 158[[option_copy_aliases]] 159== copy_aliases 160 161NOTE: This setting is only used by the <<shrink,shrink>> action. 162 163[source,yaml] 164------------- 165action: shrink 166description: >- 167 Shrink selected indices on the node with the most available space. 168 Reimplement source index aliases on target index after successful shrink. 169options: 170 shrink_node: DETERMINISTIC 171 copy_aliases: True 172filters: 173 - filtertype: ... 174------------- 175 176The default value of this setting is `False`. If `True`, after an index has been successfully 177shrunk, any aliases associated with the source index will be copied to the target index. 178 179 180[[option_count]] 181== count 182 183NOTE: This setting is required when using the <<replicas,replicas action>>. 184 185[source,yaml] 186------------- 187action: replicas 188description: >- Set the number of replicas per shard for selected 189 indices to 'count' 190options: 191 count: ... 192filters: 193- filtertype: ... 194------------- 195 196The value for this setting is the number of replicas to assign to matching 197indices. 198 199There is no default value. This setting must be set by the user or an exception 200will be raised, and execution will halt. 201 202[[option_delay]] 203== delay 204 205NOTE: This setting is only used by the <<forcemerge,forceMerge action>>, and is 206 optional. 207 208[source,yaml] 209------------- 210action: forcemerge 211description: >- 212 Perform a forceMerge on selected indices to 'max_num_segments' per shard 213options: 214 max_num_segments: 2 215 timeout_override: 21600 216 delay: 120 217filters: 218- filtertype: ... 219------------- 220 221The value for this setting is the number of seconds to delay between 222forceMerging indices, to allow the cluster to quiesce. 223 224There is no default value. 225 226 227[[option_delete_after]] 228== delete_after 229 230NOTE: This setting is only used by the <<shrink,shrink>> action. 231 232[source,yaml] 233------------- 234action: shrink 235description: >- 236 Shrink selected indices on the node with the most available space. 237 Delete source index after successful shrink. 238options: 239 shrink_node: DETERMINISTIC 240 delete_after: True 241filters: 242 - filtertype: ... 243------------- 244 245The default value of this setting is `True`. After an index has been successfully 246shrunk, the source index will be deleted or preserved based on the value of this setting. 247 248 249[[option_delete_aliases]] 250== delete_aliases 251 252NOTE: This setting is only used by the <<close,close action>>, and is 253 optional. 254 255[source,yaml] 256------------- 257action: close 258description: "Close selected indices" 259options: 260 delete_aliases: False 261filters: 262- filtertype: ... 263------------- 264 265The value for this setting determines whether aliases will be deleted from 266indices before closing. 267 268The default value is `False`. 269 270[[option_skip_flush]] 271== skip_flush 272 273NOTE: This setting is only used by the <<close,close action>>, and is 274 optional. 275 276[source,yaml] 277------------- 278action: close 279description: "Close selected indices" 280options: 281 skip_flush: False 282filters: 283- filtertype: ... 284------------- 285 286If `skip_flush` is set to `True`, Curator will not flush indices to disk 287before closing. This may be useful for closing red indices before restoring. 288 289The default value is `False`. 290 291[[option_disable]] 292== disable_action 293 294NOTE: This setting is available in all actions. 295 296[source,yaml] 297------------- 298action: delete_indices 299description: "Delete selected indices" 300options: 301 disable_action: False 302filters: 303- filtertype: ... 304------------- 305 306If `disable_action` is set to `True`, Curator will ignore the current action. 307This may be useful for temporarily disabling actions in a large configuration 308file. 309 310The default value for this setting is `False` 311 312[[option_extra_settings]] 313== extra_settings 314 315This setting should be nested YAML. The values beneath `extra_settings` will be 316used by whichever action uses the option. 317 318=== <<alias,alias>> 319 320[source,yaml] 321------------- 322action: alias 323description: "Add/Remove selected indices to or from the specified alias" 324options: 325 name: alias_name 326 extra_settings: 327 filter: 328 term: 329 user: kimchy 330add: 331 filters: 332 - filtertype: ... 333remove: 334 filters: 335 - filtertype: ... 336------------- 337 338=== <<create_index,create_index>> 339 340[source,yaml] 341------------- 342action: create_index 343description: "Create index as named" 344options: 345 name: myindex 346 # ... 347 extra_settings: 348 settings: 349 number_of_shards: 1 350 number_of_replicas: 0 351 mappings: 352 type1: 353 properties: 354 field1: 355 type: string 356 index: not_analyzed 357------------- 358 359=== <<restore,restore>> 360 361See the {ref}/snapshots-restore-snapshot.html#change-index-settings-during-restore[official Elasticsearch Documentation]. 362 363[source,yaml] 364------------- 365actions: 366 1: 367 action: restore 368 description: >- 369 Restore all indices in the most recent snapshot with state SUCCESS. Wait 370 for the restore to complete before continuing. Do not skip the repository 371 filesystem access check. Use the other options to define the index/shard 372 settings for the restore. 373 options: 374 repository: 375 # If name is blank, the most recent snapshot by age will be selected 376 name: 377 # If indices is blank, all indices in the snapshot will be restored 378 indices: 379 extra_settings: 380 index_settings: 381 number_of_replicas: 0 382 wait_for_completion: True 383 max_wait: 3600 384 wait_interval: 10 385 filters: 386 - filtertype: state 387 state: SUCCESS 388 exclude: 389 - filtertype: ... 390------------- 391 392=== <<rollover,rollover>> 393 394[source,yaml] 395------------- 396action: rollover 397description: >- 398 Rollover the index associated with alias 'name', which should be in the 399 form of prefix-000001 (or similar), or prefix-yyyy.MM.DD-1. 400options: 401 name: aliasname 402 conditions: 403 max_age: 1d 404 max_docs: 1000000 405 extra_settings: 406 index.number_of_shards: 3 407 index.number_of_replicas: 1 408 timeout_override: 409 continue_if_exception: False 410 disable_action: False 411------------- 412 413=== <<shrink,shrink>> 414 415NOTE: https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-shrink-index.html#_shrinking_an_index[Only `settings` and `aliases` are acceptable] when used in <<shrink,shrink>>. 416 417[source,yaml] 418------------- 419action: shrink 420description: >- 421 Shrink selected indices on the node with the most available space. 422 Delete source index after successful shrink, then reroute the shrunk 423 index with the provided parameters. 424options: 425 shrink_node: DETERMINISTIC 426 extra_settings: 427 settings: 428 index.codec: best_compression 429 aliases: 430 my_alias: {} 431filters: 432 - filtertype: ... 433------------- 434 435There is no default value. 436 437[[option_ignore_empty]] 438== ignore_empty_list 439 440This setting must be either `True` or `False`. 441 442[source,yaml] 443------------- 444action: delete_indices 445description: "Delete selected indices" 446options: 447 ignore_empty_list: True 448filters: 449- filtertype: ... 450------------- 451 452Depending on your indices, and how you've filtered them, an empty list may be 453presented to the action. This results in an error condition. 454 455When the ignore_empty_list option is set to `True`, the action will exit with an 456INFO level log message indicating such. If ignore_empty_list is set to `False`, 457an ERROR level message will be logged, and Curator will exit with code 1. 458 459The default value of this setting is `False` 460 461[[option_ignore_sync_failures]] 462== ignore_sync_failures 463 464NOTE: This setting is only used by the <<close,close action>>, and is 465 optional. 466 467[source,yaml] 468------------- 469action: close 470description: "Close selected indices" 471options: 472 ignore_sync_failures: false 473filters: 474- filtertype: ... 475------------- 476 477If `ignore_sync_failures` is set to `true`, Curator will ignore failures during 478the synced flush that normally takes place before closing. This may be useful 479for closing a list of indices which may include active indices. 480 481The default value is `false`. 482 483[[option_ignore]] 484== ignore_unavailable 485 486NOTE: This setting is used by the <<snapshot,snapshot>>, <<restore,restore>>, 487and <<index_settings,index_settings>> actions. 488 489This setting must be either `True` or `False`. 490 491The default value of this setting is `False` 492 493=== <<restore,restore>> 494 495[source,yaml] 496------------- 497actions: 498 1: 499 action: restore 500 description: Restore my_index from my_snapshot in my_repository 501 options: 502 repository: my_repository 503 name: my_snapshot 504 indices: my_index 505 ignore_unavailable: True 506 wait_for_completion: True 507 max_wait: 3600 508 wait_interval: 10 509 filters: 510 - filtertype: state 511 state: SUCCESS 512 exclude: 513 - filtertype: ... 514------------- 515 516When the `ignore_unavailable` option is `False` and an index is missing the 517restore request will fail. 518 519=== <<snapshot,snapshot>> 520 521[source,yaml] 522------------- 523action: snapshot 524description: >- 525 Snapshot selected indices to 'repository' with the snapshot name or name 526 pattern in 'name'. Use all other options as assigned 527options: 528 repository: my_repository 529 name: my_snapshot 530 ignore_unavailable: False 531 wait_for_completion: True 532 max_wait: 3600 533 wait_interval: 10 534filters: 535- filtertype: ... 536------------- 537 538When the `ignore_unavailable` option is `False` and an index is missing, the 539snapshot request will fail. This is not frequently a concern in Curator, as 540it should only ever find indices that exist. 541 542=== <<index_settings,index_settings>> 543 544[source,yaml] 545------------- 546action: index_settings 547description: "Change settings for selected indices" 548options: 549 index_settings: 550 index: 551 refresh_interval: 5s 552 ignore_unavailable: False 553 preserve_existing: False 554filters: 555- filtertype: ... 556------------- 557 558When the `ignore_unavailable` option is `False` and an index is missing, 559or if the request is to apply a 560https://www.elastic.co/guide/en/elasticsearch/reference/5.4/index-modules.html#_static_index_settings[static] 561setting and the index is opened, the index setting request will fail. 562The `ignore_unavailable` option allows these indices to be skipped, when set to 563`True`. 564 565NOTE: https://www.elastic.co/guide/en/elasticsearch/reference/5.4/index-modules.html#dynamic-index-settings[Dynamic] 566index settings can be applied to either open or closed indices. 567 568[[option_include_aliases]] 569== include_aliases 570 571NOTE: This setting is only used by the <<restore,restore>> action. 572 573[source,yaml] 574------------- 575actions: 576 1: 577 action: restore 578 description: Restore my_index from my_snapshot in my_repository 579 options: 580 repository: my_repository 581 name: my_snapshot 582 indices: my_index 583 include_aliases: True 584 wait_for_completion: True 585 max_wait: 3600 586 wait_interval: 10 587 filters: 588 - filtertype: state 589 state: SUCCESS 590 exclude: 591 - filtertype: ... 592------------- 593 594This setting must be either `True` or `False`. 595 596The value of this setting determines whether Elasticsearch should include index 597aliases when restoring the snapshot. 598 599The default value of this setting is `False` 600 601[[option_include_gs]] 602== include_global_state 603 604NOTE: This setting is used by the <<snapshot,snapshot>> and 605<<restore,restore>> actions. 606 607This setting must be either `True` or `False`. 608 609The value of this setting determines whether Elasticsearch should include the 610global cluster state with the snapshot or restore. 611 612When performing a <<snapshot,snapshot>>, the default value of this setting is 613`True`. 614 615When performing a <<restore,restore>>, the default value of this setting is 616`False`. 617 618=== <<restore,restore>> 619 620[source,yaml] 621------------- 622actions: 623 1: 624 action: restore 625 description: Restore my_index from my_snapshot in my_repository 626 options: 627 repository: my_repository 628 name: my_snapshot 629 indices: my_index 630 include_global_state: False 631 wait_for_completion: True 632 max_wait: 3600 633 wait_interval: 10 634 filters: 635 - filtertype: state 636 state: SUCCESS 637 exclude: 638 - filtertype: ... 639------------- 640 641=== <<snapshot,snapshot>> 642 643[source,yaml] 644------------- 645action: snapshot 646description: >- 647 Snapshot selected indices to 'repository' with the snapshot name or name 648 pattern in 'name'. Use all other options as assigned 649options: 650 repository: my_repository 651 name: my_snapshot 652 include_global_state: True 653 wait_for_completion: True 654 max_wait: 3600 655 wait_interval: 10 656filters: 657- filtertype: ... 658------------- 659 660[[option_indices]] 661== indices 662 663NOTE: This setting is only used by the <<restore,restore>> action. 664 665=== <<restore,restore>> 666 667[source,yaml] 668------------- 669actions: 670 1: 671 action: restore 672 description: Restore my_index from my_snapshot in my_repository 673 options: 674 repository: my_repository 675 name: my_snapshot 676 indices: my_index 677 wait_for_completion: True 678 max_wait: 3600 679 wait_interval: 10 680 filters: 681 - filtertype: state 682 state: SUCCESS 683 exclude: 684 - filtertype: ... 685------------- 686 687This setting must be a list of indices to restore. Any valid YAML format for 688lists are acceptable here. If `indices` is left empty, or unset, all indices in 689the snapshot will be restored. 690 691The default value of this setting is an empty setting. 692 693[[option_key]] 694== key 695 696NOTE: This setting is required when using the <<allocation,allocation action>>. 697 698[source,yaml] 699------------- 700action: allocation 701description: "Apply shard allocation filtering rules to the specified indices" 702options: 703 key: ... 704 value: ... 705 allocation_type: ... 706filters: 707- filtertype: ... 708------------- 709 710The value of this setting should correspond to a node setting on one or more 711nodes in your cluster. 712 713For example, you might have set 714 715[source,sh] 716----------- 717node.tag: myvalue 718----------- 719 720in your `elasticsearch.yml` file for one or more of your nodes. To match 721allocation in this case, set key to `tag`. 722 723These special attributes are also supported: 724 725[cols="2*", options="header"] 726|=== 727|attribute 728|description 729 730|`_name` 731|Match nodes by node name 732 733|`_host_ip` 734|Match nodes by host IP address (IP associated with hostname) 735 736|`_publish_ip` 737|Match nodes by publish IP address 738 739|`_ip` 740|Match either `_host_ip` or `_publish_ip` 741 742|`_host` 743|Match nodes by hostname 744|=== 745 746There is no default value. This setting must be set by the user or an exception 747will be raised, and execution will halt. 748 749[[option_max_age]] 750== max_age 751 752[source,yaml] 753------------- 754action: rollover 755description: >- 756 Rollover the index associated with alias 'aliasname', which should be in the 757 form of prefix-000001 (or similar), or prefix-yyyy.MM.DD-1. 758options: 759 name: aliasname 760 conditions: 761 max_age: 1d 762------------- 763 764NOTE: At least one of <<option_max_age,max_age>>, <<option_max_docs,max_docs>>, 765<<option_max_size,max_size>> or any combinations of the three are required as 766`conditions:` for the <<rollover,Rollover>> action. 767 768The maximum age that is allowed before triggering a rollover. It _must_ be 769nested under `conditions:` There is no default value. If this condition is 770specified, it must have a value, or Curator will generate an error. 771 772Ages such as `1d` for one day, or `30s` for 30 seconds can be used. 773 774[[option_max_docs]] 775== max_docs 776 777[source,yaml] 778------------- 779action: rollover 780description: >- 781 Rollover the index associated with alias 'aliasname', which should be in the 782 form of prefix-000001 (or similar), or prefix-yyyy.MM.DD-1. 783options: 784 name: aliasname 785 conditions: 786 max_docs: 1000000 787------------- 788 789NOTE: At least one of <<option_max_age,max_age>>, <<option_max_docs,max_docs>>, 790<<option_max_size,max_size>> or any combinations of the three are required as 791`conditions:` for the <<rollover,Rollover>> action. 792 793The maximum number of documents allowed in an index before triggering a 794rollover. It _must_ be nested under `conditions:` There is no default value. 795If this condition is specified, it must have a value, or Curator will generate 796an error. 797 798[[option_max_size]] 799== max_size 800 801[source,yaml] 802------------- 803action: rollover 804description: >- 805 Rollover the index associated with alias 'aliasname', which should be in the 806 form of prefix-000001 (or similar), or prefix-yyyy.MM.DD-1. 807options: 808 name: aliasname 809 conditions: 810 max_size: 5gb 811------------- 812 813NOTE: At least one of <<option_max_age,max_age>>, <<option_max_docs,max_docs>>, 814<<option_max_size,max_size>> or any combinations of the three are required as 815`conditions:` for the <<rollover,Rollover>> action. 816 817The maximum approximate size an index is allowed to be before triggering a 818rollover. Sizes must use Elasticsearch approved 819{ref}/common-options.html#byte-units[byte units]. It _must_ be nested under 820`conditions:` There is no default value. If this condition is specified, it 821must have a value, or Curator will generate an error. 822 823 824[[option_mns]] 825== max_num_segments 826 827NOTE: This setting is required when using the <<forcemerge,forceMerge action>>. 828 829[source,yaml] 830------------- 831action: forcemerge 832description: >- 833 Perform a forceMerge on selected indices to 'max_num_segments' per shard 834options: 835 max_num_segments: 2 836 timeout_override: 21600 837filters: 838- filtertype: ... 839------------- 840 841The value for this setting is the cutoff number of segments per shard. Indices 842which have more than this number of segments per shard will remain in the index 843list. 844 845There is no default value. This setting must be set by the user or an exception 846will be raised, and execution will halt. 847 848 849[[option_max_wait]] 850== max_wait 851 852NOTE: This setting is used by the <<allocation,allocation>>, 853 <<cluster_routing,cluster_routing>>, <<reindex,reindex>>, 854 <<replicas,replicas>>, <<restore,restore>>, and <<snapshot,snapshot>> actions. 855 856This setting must be a positive integer, or `-1`. 857 858This setting specifies how long in seconds to wait to see if the action has 859completed before giving up. This option is used in conjunction with 860<<option_wait_interval,wait_interval>>, 861which is the number of seconds to wait between checking to see if the given 862action is complete. 863 864The default value for this setting is `-1`, meaning that Curator will wait 865indefinitely for the action to complete. 866 867=== <<allocation,allocation>> 868 869[source,yaml] 870------------- 871action: allocation 872description: "Apply shard allocation filtering rules to the specified indices" 873options: 874 key: ... 875 value: ... 876 allocation_type: ... 877 wait_for_completion: True 878 max_wait: 300 879 wait_interval: 10 880filters: 881- filtertype: ... 882------------- 883 884=== <<cluster_routing,cluster_routing>> 885 886[source,yaml] 887------------- 888action: cluster_routing 889description: "Apply routing rules to the entire cluster" 890options: 891 routing_type: 892 value: ... 893 setting: enable 894 wait_for_completion: True 895 max_wait: 300 896 wait_interval: 10 897------------- 898 899=== <<reindex,reindex>> 900 901[source,yaml] 902------------- 903actions: 904 1: 905 description: "Reindex index1 into index2" 906 action: reindex 907 options: 908 wait_interval: 9 909 max_wait: -1 910 request_body: 911 source: 912 index: index1 913 dest: 914 index: index2 915 filters: 916 - filtertype: none 917------------- 918 919=== <<replicas,replicas>> 920 921[source,yaml] 922------------- 923action: replicas 924description: >- Set the number of replicas per shard for selected 925 indices to 'count' 926options: 927 count: ... 928 wait_for_completion: True 929 max_wait: 600 930 wait_interval: 10 931filters: 932- filtertype: ... 933------------- 934 935=== <<restore,restore>> 936 937[source,yaml] 938------------- 939actions: 940 1: 941 action: restore 942 description: Restore my_index from my_snapshot in my_repository 943 options: 944 repository: my_repository 945 name: my_snapshot 946 indices: my_index 947 include_global_state: False 948 wait_for_completion: True 949 max_wait: 3600 950 wait_interval: 10 951 filters: 952 - filtertype: state 953 state: SUCCESS 954 exclude: 955 - filtertype: ... 956------------- 957 958=== <<snapshot,snapshot>> 959 960[source,yaml] 961------------- 962action: snapshot 963description: >- 964 Snapshot selected indices to 'repository' with the snapshot name or name 965 pattern in 'name'. Use all other options as assigned 966options: 967 repository: my_repository 968 name: my_snapshot 969 include_global_state: True 970 wait_for_completion: True 971 max_wait: 3600 972 wait_interval: 10 973filters: 974- filtertype: ... 975------------- 976 977 978[[option_migration_prefix]] 979== migration_prefix 980 981NOTE: This setting is used by the <<reindex,reindex>> action. 982 983If the destination index is set to `MIGRATION`, Curator will reindex all 984selected indices one by one until they have all been reindexed. By configuring 985`migration_prefix`, a value can prepend each of those index names. For example, 986if I were reindexing `index1`, `index2`, and `index3`, and `migration_prefix` 987were set to `new-`, then the reindexed indices would be named `new-index1`, 988`new-index2`, and `new-index3`: 989 990[source,yaml] 991------------- 992actions: 993 1: 994 description: >- 995 Reindex index1, index2, and index3 with a prefix of new-, resulting in 996 indices named new-index1, new-index2, and new-index3 997 action: reindex 998 options: 999 wait_interval: 9 1000 max_wait: -1 1001 migration_prefix: new- 1002 request_body: 1003 source: 1004 index: ["index1", "index2", "index3"] 1005 dest: 1006 index: MIGRATION 1007 filters: 1008 - filtertype: none 1009------------- 1010 1011`migration_prefix` can be used in conjunction with <<option_migration_suffix>> 1012 1013 1014[[option_migration_suffix]] 1015== migration_suffix 1016 1017NOTE: This setting is used by the <<reindex,reindex>> action. 1018 1019If the destination index is set to `MIGRATION`, Curator will reindex all 1020selected indices one by one until they have all been reindexed. By configuring 1021`migration_suffix`, a value can be appended to each of those index names. For 1022example, if I were reindexing `index1`, `index2`, and `index3`, and 1023`migration_suffix` were set to `-new`, then the reindexed indices would be named 1024`index1-new`, `index2-new`, and `index3-new`: 1025 1026[source,yaml] 1027------------- 1028actions: 1029 1: 1030 description: >- 1031 Reindex index1, index2, and index3 with a suffix of -new, resulting in 1032 indices named index1-new, index2-new, and index3-new 1033 action: reindex 1034 options: 1035 wait_interval: 9 1036 max_wait: -1 1037 migration_suffix: -new 1038 request_body: 1039 source: 1040 index: ["index1", "index2", "index3"] 1041 dest: 1042 index: MIGRATION 1043 filters: 1044 - filtertype: none 1045------------- 1046 1047`migration_suffix` can be used in conjunction with <<option_migration_prefix>> 1048 1049 1050[[option_name]] 1051== name 1052 1053NOTE: This setting is used by the <<alias,alias>>, <<create_index,create_index>> 1054 and <<snapshot,snapshot>>, actions. 1055 1056The value of this setting is the name of the alias, snapshot, or index, 1057depending on which action makes use of `name`. 1058 1059=== date math 1060include::inc_datemath.asciidoc[] 1061 1062=== strftime 1063 1064This setting may alternately contain a valid Python strftime string. Curator will 1065extract the strftime identifiers and replace them with the corresponding values. 1066 1067The identifiers that Curator currently recognizes include: 1068 1069[width="50%", cols="<m,", options="header"] 1070|=== 1071|Unit|Value 1072|%Y| 4 digit year 1073|%y| 2 digit year 1074|%m| 2 digit month 1075|%W| 2 digit week of the year 1076|%d| 2 digit day of the month 1077|%H| 2 digit hour of the day, in 24 hour notation 1078|%M| 2 digit minute of the hour 1079|%S| 2 digit second of the minute 1080|%j| 3 digit day of the year 1081|=== 1082 1083 1084=== <<alias,alias>> 1085 1086[source,yaml] 1087------------- 1088action: alias 1089description: "Add/Remove selected indices to or from the specified alias" 1090options: 1091 name: alias_name 1092add: 1093 filters: 1094 - filtertype: ... 1095remove: 1096 filters: 1097 - filtertype: ... 1098------------- 1099 1100This option is required by the <<alias,alias>> action, and has no default 1101setting in that context. 1102 1103=== <<create_index,create_index>> 1104 1105For the <<create_index,create_index>> action, there is no default setting, but 1106you can use strftime: 1107 1108[source,yaml] 1109------------- 1110action: create_index 1111description: "Create index as named" 1112options: 1113 name: 'myindex-%Y.%m' 1114 # ... 1115------------- 1116 1117or use Elasticsearch {ref}/date-math-index-names.html[date math] 1118 1119[source,yaml] 1120------------- 1121action: create_index 1122description: "Create index as named" 1123options: 1124 name: '<logstash-{now/d+1d}>' 1125 # ... 1126------------- 1127 1128to name your indices. See more in the <<create_index,create_index>> 1129documenation. 1130 1131=== <<snapshot,snapshot>> 1132 1133[source,yaml] 1134------------- 1135action: snapshot 1136description: >- 1137 Snapshot selected indices to 'repository' with the snapshot name or name 1138 pattern in 'name'. Use all other options as assigned 1139options: 1140 repository: my_repository 1141 name: 1142 include_global_state: True 1143 wait_for_completion: True 1144 max_wait: 3600 1145 wait_interval: 10 1146filters: 1147- filtertype: ... 1148------------- 1149 1150For the <<snapshot,snapshot>> action, the default value of this setting is 1151`curator-%Y%m%d%H%M%S` 1152 1153[[option_new_index]] 1154== new_index 1155 1156NOTE: This optional setting is only used by the <<rollover,rollover>> action. 1157 1158[source,yaml] 1159------------- 1160description: >- 1161 Rollover the index associated with alias 'name'. Specify new index name using 1162 date math. 1163options: 1164 name: aliasname 1165 new_index: "<prefix-{now/d}-1>" 1166 conditions: 1167 max_age: 1d 1168 wait_for_active_shards: 1 1169------------- 1170 1171IMPORTANT: A new index name for rollover should still end with a dash followed by an 1172 incrementable number, e.g. `my_new_index-1`, or if using date math, `<prefix-{now/d}-1>` 1173 or `<prefix-{now/d}-000001>` 1174 1175=== date_math 1176 1177include::inc_datemath.asciidoc[] 1178 1179There is no default value for `new_index`. 1180 1181[[option_node_filters]] 1182== node_filters 1183 1184NOTE: This setting is only used by the <<shrink,shrink>> action. 1185 1186[source,yaml] 1187------------- 1188action: shrink 1189description: >- 1190 Shrink selected indices on the node with the most available space. 1191 Allow master/data nodes to be potential shrink targets, but exclude 1192 'named_node' from potential selection. 1193options: 1194 shrink_node: DETERMINISTIC 1195 node_filters: 1196 permit_masters: True 1197 exclude_nodes: ['named_node'] 1198filters: 1199 - filtertype: ... 1200------------- 1201 1202There is no default value for `node_filters`. 1203 1204 1205The current sub-options are as follows: 1206 1207=== permit_masters 1208 1209This option indicates whether the shrink action can select master eligible nodes when using 1210`DETERMINISTIC` as the value for <<option_shrink_node,shrink_node>>. The default value is 1211`False`. Please note that this will exclude the elected master, as well as other 1212master-eligible nodes. 1213 1214[IMPORTANT] 1215===================================== 1216If you have a small cluster with only master/data nodes, you must set `permit_masters` to 1217`True` in order to select one of those nodes as a potential <<option_shrink_node,shrink_node>>. 1218===================================== 1219 1220=== exclude_nodes 1221 1222This option provides means to exclude nodes from selection when using `DETERMINISTIC` 1223as the value for <<option_shrink_node,shrink_node>>. It should be noted that you _can_ 1224use a named node for <<option_shrink_node,shrink_node>> and then exclude it here, and 1225it will prevent a shrink from occurring. 1226 1227 1228 1229[[option_number_of_replicas]] 1230== number_of_replicas 1231 1232NOTE: This setting is only used by the <<shrink,shrink>> action. 1233 1234[source,yaml] 1235------------- 1236action: shrink 1237description: >- 1238 Shrink selected indices on the node with the most available space. 1239 Set the number of replicas to 0. 1240options: 1241 shrink_node: DETERMINISTIC 1242 number_of_replicas: 0 1243filters: 1244 - filtertype: ... 1245------------- 1246 1247The value of this setting determines the number of replica shards per primary 1248shard in the target index. The default value is `1`. 1249 1250 1251[[option_number_of_shards]] 1252== number_of_shards 1253 1254NOTE: This setting is only used by the <<shrink,shrink>> action. 1255 1256[source,yaml] 1257------------- 1258action: shrink 1259description: >- 1260 Shrink selected indices on the node with the most available space. 1261 Set the number of shards to 2. 1262options: 1263 shrink_node: DETERMINISTIC 1264 number_of_shards: 2 1265filters: 1266 - filtertype: ... 1267------------- 1268 1269The value of this setting determines the number of primary shards 1270in the target index. The default value is `1`. 1271 1272[IMPORTANT] 1273=========================== 1274The value for `number_of_shards` must meet the following criteria: 1275 1276* It must be lower than the number of primary shards in the source index. 1277* It must be a factor of the number of primary shards in the source index. 1278=========================== 1279 1280[[option_partial]] 1281== partial 1282 1283NOTE: This setting is only used by the <<snapshot,snapshot>> action. 1284 1285[source,yaml] 1286------------- 1287action: snapshot 1288description: >- 1289 Snapshot selected indices to 'repository' with the snapshot name or name 1290 pattern in 'name'. Use all other options as assigned 1291options: 1292 repository: my_repository 1293 name: ... 1294 partial: False 1295 wait_for_completion: True 1296 max_wait: 3600 1297 wait_interval: 10 1298filters: 1299- filtertype: ... 1300------------- 1301 1302This setting must be either `True` or `False`. 1303 1304The entire snapshot will fail if one or more indices being added to the 1305snapshot do not have all primary shards available. This behavior can be changed 1306by setting partial to `True`. 1307 1308The default value of this setting is `False` 1309 1310 1311[[option_post_allocation]] 1312== post_allocation 1313 1314NOTE: This setting is only used by the <<shrink,shrink>> action. 1315 1316[source,yaml] 1317------------- 1318action: shrink 1319description: >- 1320 Shrink selected indices on the node with the most available space. 1321 Apply shard routing allocation to target indices. 1322options: 1323 shrink_node: DETERMINISTIC 1324 post_allocation: 1325 allocation_type: include 1326 key: node_tag 1327 value: cold 1328filters: 1329 - filtertype: ... 1330------------- 1331 1332The only permitted subkeys for `post_allocation` are the same options used by the <<allocation,allocation>> action: <<option_allocation_type,allocation_type>>, <<option_key,key>>, and <<option_value,value>>. 1333 1334If present, these values will be use to apply shard routing allocation to the target index after shrinking. 1335 1336There is no default value for `post_allocation`. 1337 1338[[option_preserve_existing]] 1339== preserve_existing 1340 1341[source,yaml] 1342------------- 1343action: index_settings 1344description: "Change settings for selected indices" 1345options: 1346 index_settings: 1347 index: 1348 refresh_interval: 5s 1349 ignore_unavailable: False 1350 preserve_existing: False 1351filters: 1352- filtertype: ... 1353------------- 1354 1355This setting must be either `True` or `False`. 1356 1357If `preserve_existing` is set to `True`, and the configuration attempts to push 1358a setting to an index that already has any value for that setting, the 1359existing setting will be preserved, and remain unchanged. 1360 1361The default value of this setting is `False` 1362 1363[[option_refresh]] 1364== refresh 1365 1366NOTE: This setting is only used by the <<reindex,reindex>> action. 1367 1368[source,yaml] 1369------------- 1370actions: 1371 1: 1372 description: "Reindex index1 into index2" 1373 action: reindex 1374 options: 1375 wait_interval: 9 1376 max_wait: -1 1377 refresh: True 1378 request_body: 1379 source: 1380 index: index1 1381 dest: 1382 index: index2 1383 filters: 1384 - filtertype: none 1385------------- 1386 1387Setting `refresh` to `True` will cause all re-indexed indexes to be refreshed. 1388This differs from the Index API’s refresh parameter which causes just the 1389_shard_ that received the new data to be refreshed. 1390 1391Read more about this setting at {ref}/docs-reindex.html 1392 1393The default value is `True`. 1394 1395[[option_remote_aws_key]] 1396== remote_aws_key 1397 1398NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1399a remote reindex operation. 1400 1401WARNING: This setting will not work unless the `requests-aws4auth` Python module 1402 has been manually installed first. 1403 1404This should be an AWS IAM access key, or left empty. 1405 1406[source,yaml] 1407------------- 1408actions: 1409 1: 1410 description: "Reindex index1 into index2" 1411 action: reindex 1412 options: 1413 wait_interval: 9 1414 max_wait: -1 1415 remote_aws_key: AWS_KEY 1416 remote_aws_secret_key: AWS_SECRET_KEY 1417 remote_aws_region: us-east-1 1418 request_body: 1419 source: 1420 remote: 1421 host: https://otherhost:9200 1422 index: index1 1423 dest: 1424 index: index2 1425 filters: 1426 - filtertype: none 1427------------- 1428 1429IMPORTANT: You must set your <<hosts,hosts>> to the proper hostname _with_ port. 1430 It may not work setting <<port,port>> and <<hosts,hosts>> to only a host 1431 name due to the different connection module used. 1432 1433 1434 1435[[option_remote_aws_region]] 1436== remote_aws_region 1437 1438NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1439a remote reindex operation. 1440 1441WARNING: This setting will not work unless the `requests-aws4auth` Python module 1442 has been manually installed first. 1443 1444This should be an AWS region, or left empty. 1445 1446[source,yaml] 1447------------- 1448actions: 1449 1: 1450 description: "Reindex index1 into index2" 1451 action: reindex 1452 options: 1453 wait_interval: 9 1454 max_wait: -1 1455 remote_aws_key: AWS_KEY 1456 remote_aws_secret_key: AWS_SECRET_KEY 1457 remote_aws_region: us-east-1 1458 request_body: 1459 source: 1460 remote: 1461 host: https://otherhost:9200 1462 index: index1 1463 dest: 1464 index: index2 1465 filters: 1466 - filtertype: none 1467------------- 1468 1469IMPORTANT: You must set your <<hosts,hosts>> to the proper hostname _with_ port. 1470 It may not work setting <<port,port>> and <<hosts,hosts>> to only a host 1471 name due to the different connection module used. 1472 1473 1474 1475[[option_remote_aws_secret_key]] 1476== remote_aws_secret_key 1477 1478NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1479a remote reindex operation. 1480 1481WARNING: This setting will not work unless the `requests-aws4auth` Python module 1482 has been manually installed first. 1483 1484This should be an AWS IAM secret access key, or left empty. 1485 1486[source,yaml] 1487------------- 1488actions: 1489 1: 1490 description: "Reindex index1 into index2" 1491 action: reindex 1492 options: 1493 wait_interval: 9 1494 max_wait: -1 1495 remote_aws_key: AWS_KEY 1496 remote_aws_secret_key: AWS_SECRET_KEY 1497 remote_aws_region: us-east-1 1498 request_body: 1499 source: 1500 remote: 1501 host: https://otherhost:9200 1502 index: index1 1503 dest: 1504 index: index2 1505 filters: 1506 - filtertype: none 1507------------- 1508 1509IMPORTANT: You must set your <<hosts,hosts>> to the proper hostname _with_ port. 1510 It may not work setting <<port,port>> and <<hosts,hosts>> to only a host 1511 name due to the different connection module used. 1512 1513 1514 1515[[option_remote_certificate]] 1516== remote_certificate 1517 1518This should be a file path to a CA certificate, or left empty. 1519 1520[source,yaml] 1521------------- 1522actions: 1523 1: 1524 description: "Reindex index1 into index2" 1525 action: reindex 1526 options: 1527 wait_interval: 9 1528 max_wait: -1 1529 remote_certificate: /path/to/my/ca.cert 1530 remote_client_cert: /path/to/my/client.cert 1531 remote_client_key: /path/to/my/client.key 1532 request_body: 1533 source: 1534 remote: 1535 host: https://otherhost:9200 1536 index: index1 1537 dest: 1538 index: index2 1539 filters: 1540 - filtertype: none 1541------------- 1542 1543NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1544a remote reindex operation. 1545 1546This setting allows the use of a specified CA certificate file to validate the 1547SSL certificate used by Elasticsearch. 1548 1549There is no default. 1550 1551 1552 1553[[option_remote_client_cert]] 1554== remote_client_cert 1555 1556NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1557a remote reindex operation. 1558 1559This should be a file path to a client certificate (public key), or left empty. 1560 1561[source,yaml] 1562------------- 1563actions: 1564 1: 1565 description: "Reindex index1 into index2" 1566 action: reindex 1567 options: 1568 wait_interval: 9 1569 max_wait: -1 1570 remote_certificate: /path/to/my/ca.cert 1571 remote_client_cert: /path/to/my/client.cert 1572 remote_client_key: /path/to/my/client.key 1573 request_body: 1574 source: 1575 remote: 1576 host: https://otherhost:9200 1577 index: index1 1578 dest: 1579 index: index2 1580 filters: 1581 - filtertype: none 1582------------- 1583 1584Allows the use of a specified SSL client cert file to authenticate to 1585Elasticsearch. The file may contain both an SSL client certificate and an SSL 1586key, in which case <<client_key,client_key>> is not used. If specifying 1587`client_cert`, and the file specified does not also contain the key, use 1588<<client_key,client_key>> to specify the file containing the SSL key. The file 1589must be in PEM format, and the key part, if used, must be an unencrypted key in 1590PEM format as well. 1591 1592 1593 1594[[option_remote_client_key]] 1595== remote_client_key 1596 1597NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1598a remote reindex operation. 1599 1600This should be a file path to a client key (private key), or left empty. 1601 1602[source,yaml] 1603------------- 1604actions: 1605 1: 1606 description: "Reindex index1 into index2" 1607 action: reindex 1608 options: 1609 wait_interval: 9 1610 max_wait: -1 1611 remote_certificate: /path/to/my/ca.cert 1612 remote_client_cert: /path/to/my/client.cert 1613 remote_client_key: /path/to/my/client.key 1614 request_body: 1615 source: 1616 remote: 1617 host: https://otherhost:9200 1618 index: index1 1619 dest: 1620 index: index2 1621 filters: 1622 - filtertype: none 1623------------- 1624 1625Allows the use of a specified SSL client key file to authenticate to 1626Elasticsearch. If using <<client_cert,client_cert>> and the file specified does 1627not also contain the key, use `client_key` to specify the file containing the 1628SSL key. The key file must be an unencrypted key in PEM format. 1629 1630 1631 1632[[option_remote_filters]] 1633== remote_filters 1634 1635NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1636a remote reindex operation. 1637 1638This is an array of <<filters,filters>>, exactly as with regular index 1639selection: 1640 1641[source,yaml] 1642------------- 1643actions: 1644 1: 1645 description: "Reindex matching indices into index2" 1646 action: reindex 1647 options: 1648 wait_interval: 9 1649 max_wait: -1 1650 request_body: 1651 source: 1652 remote: 1653 host: https://otherhost:9200 1654 index: REINDEX_SELECTION 1655 dest: 1656 index: index2 1657 remote_filters: 1658 - filtertype: *first* 1659 setting1: ... 1660 ... 1661 settingN: ... 1662 - filtertype: *second* 1663 setting1: ... 1664 ... 1665 settingN: ... 1666 - filtertype: *third* 1667 filters: 1668 - filtertype: none 1669------------- 1670 1671This feature will only work when the `source` `index` is set to 1672`REINDEX_SELECTION`. It will select _remote_ indices matching the filters 1673provided, and reindex them to the _local_ cluster as the name provided in the 1674`dest` `index`. In this example, that is `index2`. 1675 1676 1677 1678[[option_remote_ssl_no_validate]] 1679== remote_ssl_no_validate 1680 1681This should be `True`, `False` or left empty. 1682 1683[source,yaml] 1684------------- 1685actions: 1686 1: 1687 description: "Reindex index1 into index2" 1688 action: reindex 1689 options: 1690 wait_interval: 9 1691 max_wait: -1 1692 remote_ssl_no_validate: True 1693 request_body: 1694 source: 1695 remote: 1696 host: https://otherhost:9200 1697 index: index1 1698 dest: 1699 index: index2 1700 filters: 1701 - filtertype: none 1702------------- 1703 1704 1705If access to your Elasticsearch instance is protected by SSL encryption, you may 1706set `ssl_no_validate` to `True` to disable SSL certificate verification. 1707 1708Valid use cases for doing so include the use of self-signed certificates that 1709cannot be otherwise verified and would generate error messages. 1710 1711WARNING: Setting `ssl_no_validate` to `True` will likely result in a warning 1712 message that your SSL certificates are not trusted. This is expected 1713 behavior. 1714 1715The default value is `False`. 1716 1717 1718 1719[[option_remote_url_prefix]] 1720== remote_url_prefix 1721 1722NOTE: This option is only used by the <<reindex,Reindex action>> when performing 1723a remote reindex operation. 1724 1725This should be a single value or left empty. 1726 1727[source,yaml] 1728------------- 1729actions: 1730 1: 1731 description: "Reindex index1 into index2" 1732 action: reindex 1733 options: 1734 wait_interval: 9 1735 max_wait: -1 1736 remote_url_prefix: my_prefix 1737 request_body: 1738 source: 1739 remote: 1740 host: https://otherhost:9200 1741 index: index1 1742 dest: 1743 index: index2 1744 filters: 1745 - filtertype: none 1746------------- 1747 1748In some cases you may be obliged to connect to a remote Elasticsearch cluster 1749through a proxy of some kind. There may be a URL prefix before the API URI 1750items, e.g. http://example.com/elasticsearch/ as opposed to 1751http://localhost:9200. In such a case, set the `remote_url_prefix` to the 1752appropriate value, 'elasticsearch' in this example. 1753 1754The default is an empty string. 1755 1756 1757 1758[[option_rename_pattern]] 1759== rename_pattern 1760 1761NOTE: This setting is only used by the <<restore,restore>> action. 1762 1763[TIP] 1764.from the Elasticsearch documentation 1765====================================== 1766The <<option_rename_pattern,rename_pattern>> and 1767<<option_rename_replacement,rename_replacement>> options can be also used to 1768rename indices on restore using regular expression that supports referencing the 1769original text as explained 1770http://docs.oracle.com/javase/6/docs/api/java/util/regex/Matcher.html#appendReplacement(java.lang.StringBuffer,%20java.lang.String)[here]. 1771====================================== 1772 1773[source,yaml] 1774------------- 1775actions: 1776 1: 1777 action: restore 1778 description: >- 1779 Restore all indices in the most recent snapshot with state SUCCESS. Wait 1780 for the restore to complete before continuing. Do not skip the repository 1781 filesystem access check. Use the other options to define the index/shard 1782 settings for the restore. 1783 options: 1784 repository: 1785 # If name is blank, the most recent snapshot by age will be selected 1786 name: 1787 # If indices is blank, all indices in the snapshot will be restored 1788 indices: 1789 rename_pattern: 'index(.+)' 1790 rename_replacement: 'restored_index$1' 1791 wait_for_completion: True 1792 max_wait: 3600 1793 wait_interval: 10 1794 filters: 1795 - filtertype: state 1796 state: SUCCESS 1797 exclude: 1798 - filtertype: ... 1799------------- 1800 1801In this configuration, Elasticsearch will capture whatever appears after `index` 1802and put it after `restored_index`. For example, if I was restoring 1803`index-2017.03.01`, the resulting index would be renamed to 1804`restored_index-2017.03.01`. 1805 1806Read more about this setting at {ref}/snapshots-restore-snapshot.html 1807 1808There is no default value. 1809 1810[[option_rename_replacement]] 1811== rename_replacement 1812 1813NOTE: This setting is only used by the <<restore, restore>> action. 1814 1815[TIP] 1816.From the Elasticsearch documentation 1817====================================== 1818The <<option_rename_pattern,rename_pattern>> and 1819<<option_rename_replacement,rename_replacement>> options can be also used to 1820rename indices on restore using regular expression that supports referencing the 1821original text as explained 1822http://docs.oracle.com/javase/6/docs/api/java/util/regex/Matcher.html#appendReplacement(java.lang.StringBuffer,%20java.lang.String)[here]. 1823====================================== 1824 1825[source,yaml] 1826------------- 1827actions: 1828 1: 1829 action: restore 1830 description: >- 1831 Restore all indices in the most recent snapshot with state SUCCESS. Wait 1832 for the restore to complete before continuing. Do not skip the repository 1833 filesystem access check. Use the other options to define the index/shard 1834 settings for the restore. 1835 options: 1836 repository: 1837 # If name is blank, the most recent snapshot by age will be selected 1838 name: 1839 # If indices is blank, all indices in the snapshot will be restored 1840 indices: 1841 rename_pattern: 'index(.+)' 1842 rename_replacement: 'restored_index$1' 1843 wait_for_completion: True 1844 max_wait: 3600 1845 wait_interval: 10 1846 filters: 1847 - filtertype: state 1848 state: SUCCESS 1849 exclude: 1850 - filtertype: ... 1851------------- 1852 1853In this configuration, Elasticsearch will capture whatever appears after `index` 1854and put it after `restored_index`. For example, if I was restoring 1855`index-2017.03.01`, the resulting index would be renamed to 1856`restored_index-2017.03.01`. 1857 1858Read more about this setting at {ref}/snapshots-restore-snapshot.html 1859 1860There is no default value. 1861 1862[[option_repository]] 1863== repository 1864 1865NOTE: This setting is only used by the <<snapshot, snapshot>>, and 1866 <<delete_snapshots, delete snapshots>> actions. 1867 1868There is no default value. This setting must be set by the user or an exception 1869will be raised, and execution will halt. 1870 1871=== <<restore,restore>> 1872 1873[source,yaml] 1874------------- 1875actions: 1876 1: 1877 action: restore 1878 description: Restore my_index from my_snapshot in my_repository 1879 options: 1880 repository: my_repository 1881 name: my_snapshot 1882 indices: my_index 1883 wait_for_completion: True 1884 max_wait: 3600 1885 wait_interval: 10 1886 filters: 1887 - filtertype: state 1888 state: SUCCESS 1889 exclude: 1890 - filtertype: ... 1891------------- 1892 1893=== <<snapshot,snapshot>> 1894 1895[source,yaml] 1896------------- 1897action: snapshot 1898description: >- 1899 Snapshot selected indices to 'repository' with the snapshot name or name 1900 pattern in 'name'. Use all other options as assigned 1901options: 1902 repository: my_repository 1903 name: my_snapshot 1904 wait_for_completion: True 1905 max_wait: 3600 1906 wait_interval: 10 1907filters: 1908- filtertype: ... 1909------------- 1910 1911[[option_requests_per_second]] 1912== requests_per_second 1913 1914NOTE: This option is only used by the <<reindex,Reindex action>> 1915 1916[source,yaml] 1917------------- 1918actions: 1919 1: 1920 description: "Reindex index1 into index2" 1921 action: reindex 1922 options: 1923 wait_interval: 9 1924 max_wait: -1 1925 requests_per_second: -1 1926 request_body: 1927 source: 1928 index: index1 1929 dest: 1930 index: index2 1931 filters: 1932 - filtertype: none 1933------------- 1934 1935`requests_per_second` can be set to any positive decimal number (1.4, 6, 1000, 1936etc) and throttles the number of requests per second that the reindex issues or 1937it can be set to `-1` to disable throttling. 1938 1939The default value for this is option is `-1`. 1940 1941 1942[[option_request_body]] 1943== request_body 1944 1945NOTE: This setting is only used by the <<reindex,reindex>> action. 1946 1947=== Manual index selection 1948 1949The `request_body` option is the heart of the reindex action. In here, using 1950YAML syntax, you recreate the body sent to Elasticsearch as described in 1951{ref}/docs-reindex.html[the official documentation.] You can manually select 1952indices as with this example: 1953 1954[source,yaml] 1955------------- 1956actions: 1957 1: 1958 description: "Reindex index1 into index2" 1959 action: reindex 1960 options: 1961 wait_interval: 9 1962 max_wait: -1 1963 request_body: 1964 source: 1965 index: index1 1966 dest: 1967 index: index2 1968 filters: 1969 - filtertype: none 1970------------- 1971 1972You can also select multiple indices to reindex by making a list in acceptable 1973YAML syntax: 1974 1975[source,yaml] 1976------------- 1977actions: 1978 1: 1979 description: "Reindex index1,index2,index3 into new_index" 1980 action: reindex 1981 options: 1982 wait_interval: 9 1983 max_wait: -1 1984 request_body: 1985 source: 1986 index: ['index1', 'index2', 'index3'] 1987 dest: 1988 index: new_index 1989 filters: 1990 - filtertype: none 1991------------- 1992 1993IMPORTANT: You _must_ set at least a <<filtertype_none,none>> filter, or the 1994 action will fail. Do not worry. If you've manually specified your indices, 1995 those are the only ones which will be reindexed. 1996 1997=== Filter-Selected Indices 1998 1999Curator allows you to use all indices found by the `filters` section by setting 2000the `source` index to `REINDEX_SELECTION`, like this: 2001 2002[source,yaml] 2003------------- 2004actions: 2005 1: 2006 description: >- 2007 Reindex all daily logstash indices from March 2017 into logstash-2017.03 2008 action: reindex 2009 options: 2010 wait_interval: 9 2011 max_wait: -1 2012 request_body: 2013 source: 2014 index: REINDEX_SELECTION 2015 dest: 2016 index: logstash-2017.03 2017 filters: 2018 - filtertype: pattern 2019 kind: prefix 2020 value: logstash-2017.03. 2021------------- 2022 2023=== Reindex From Remote 2024 2025You can also reindex from remote: 2026 2027[source,yaml] 2028------------- 2029actions: 2030 1: 2031 description: "Reindex remote index1 to local index1" 2032 action: reindex 2033 options: 2034 wait_interval: 9 2035 max_wait: -1 2036 request_body: 2037 source: 2038 remote: 2039 host: http://otherhost:9200 2040 username: myuser 2041 password: mypass 2042 index: index1 2043 dest: 2044 index: index1 2045 filters: 2046 - filtertype: none 2047------------- 2048 2049IMPORTANT: You _must_ set at least a <<filtertype_none,none>> filter, or the 2050 action will fail. Do not worry. Only the indices you specified in `source` 2051 will be reindexed. 2052 2053Curator will create a connection to the host specified as the `host` key in the 2054above example. It will determine which port to connect to, and whether to use 2055SSL by parsing the URL entered there. Because this `host` is specifically used 2056by Elasticsearch, and Curator is making a separate connection, it is important 2057to ensure that both Curator _and_ your Elasticsearch cluster have access to the 2058remote host. 2059 2060If you do not whitelist the remote cluster, you will not be able to reindex. 2061This can be done by adding the following line to your `elasticsearch.yml` file: 2062 2063[source,yaml] 2064------------- 2065reindex.remote.whitelist: remote_host_or_IP1:9200, remote_host_or_IP2:9200 2066------------- 2067 2068or by adding this flag to the command-line when starting Elasticsearch: 2069 2070[source,sh] 2071------------- 2072bin/elasticsearch -Edefault.reindex.remote.whitelist="remote_host_or_IP:9200" 2073------------- 2074 2075Of course, be sure to substitute the correct host, IP, or port. 2076 2077Other client connection arguments can also be supplied in the form of action 2078options: 2079 2080* <<option_remote_url_prefix,remote_url_prefix>> 2081* <<option_remote_certificate,remote_certificate>> 2082* <<option_remote_client_cert,remote_client_cert>> 2083* <<option_remote_client_key,remote_client_key>> 2084* <<option_remote_aws_key,remote_aws_key>> 2085* <<option_remote_aws_secret_key,remote_aws_secret_key>> 2086* <<option_remote_aws_region,remote_remote_aws_region>> 2087 2088=== Reindex From Remote With Filter-Selected Indices 2089 2090You can even reindex from remote with filter-selected indices on the remote 2091side: 2092 2093[source,yaml] 2094------------- 2095actions: 2096 1: 2097 description: >- 2098 Reindex all remote daily logstash indices from March 2017 into local index 2099 logstash-2017.03 2100 action: reindex 2101 options: 2102 wait_interval: 9 2103 max_wait: -1 2104 request_body: 2105 source: 2106 remote: 2107 host: http://otherhost:9200 2108 username: myuser 2109 password: mypass 2110 index: REINDEX_SELECTION 2111 dest: 2112 index: logstash-2017.03 2113 remote_filters: 2114 - filtertype: pattern 2115 kind: prefix 2116 value: logstash-2017.03. 2117 filters: 2118 - filtertype: none 2119------------- 2120 2121IMPORTANT: Even though you are reindexing from remote, you _must_ set at least a 2122 <<filtertype_none,none>> filter, or the action will fail. Do not worry. Only 2123 the indices specified in `source` will be reindexed. 2124 2125Curator will create a connection to the host specified as the `host` key in the 2126above example. It will determine which port to connect to, and whether to use 2127SSL by parsing the URL entered there. Because this `host` is specifically used 2128by Elasticsearch, and Curator is making a separate connection, it is important 2129to ensure that both Curator _and_ your Elasticsearch cluster have access to the 2130remote host. 2131 2132If you do not whitelist the remote cluster, you will not be able to reindex. 2133This can be done by adding the following line to your `elasticsearch.yml` file: 2134 2135[source,yaml] 2136------------- 2137reindex.remote.whitelist: remote_host_or_IP1:9200, remote_host_or_IP2:9200 2138------------- 2139 2140or by adding this flag to the command-line when starting Elasticsearch: 2141 2142[source,sh] 2143------------- 2144bin/elasticsearch -Edefault.reindex.remote.whitelist="remote_host_or_IP:9200" 2145------------- 2146 2147Of course, be sure to substitute the correct host, IP, or port. 2148 2149Other client connection arguments can also be supplied in the form of action 2150options: 2151 2152* <<option_remote_url_prefix,remote_url_prefix>> 2153* <<option_remote_certificate,remote_certificate>> 2154* <<option_remote_client_cert,remote_client_cert>> 2155* <<option_remote_client_key,remote_client_key>> 2156* <<option_remote_aws_key,remote_aws_key>> 2157* <<option_remote_aws_secret_key,remote_aws_secret_key>> 2158* <<option_remote_aws_region,remote_remote_aws_region>> 2159 2160=== Reindex - Migration 2161 2162Curator allows reindexing, particularly from remote, as a migration path. This 2163can be a very useful feature for migrating an older cluster (1.4+) to a new 2164cluster, on different hardware. It can also be a useful tool for serially 2165reindexing indices into newer mappings in an automatable way. 2166 2167Ordinarily, a reindex operation is from either one, or many indices, to a 2168single, named index. Assigning the `dest` `index` to `MIGRATION` tells Curator 2169to treat this reindex differently. 2170 2171[IMPORTANT] 2172============================= 2173**If it is a _local_ reindex,** you _must_ set either 2174<<option_migration_prefix,migration_prefix>>, or 2175<<option_migration_suffix,migration_suffix>>, or both. This prevents 2176collisions and other bad things from happening. By assigning a prefix or a 2177suffix (or both), you can reindex any local indices to new versions of 2178themselves, but named differently. 2179 2180It is true the Reindex API already has this functionality. Curator includes 2181this same functionality for convenience. 2182============================= 2183 2184This example will reindex all of the remote indices matching `logstash-2017.03.` 2185into the local cluster, but preserve the original index names, rather than 2186merge all of the contents into a single index. Internal to Curator, this 2187results in multiple reindex actions: one per index. All other available options 2188and settings are available. 2189 2190[source,yaml] 2191------------- 2192actions: 2193 1: 2194 description: >- 2195 Reindex all remote daily logstash indices from March 2017 into local 2196 versions with the same index names. 2197 action: reindex 2198 options: 2199 wait_interval: 9 2200 max_wait: -1 2201 request_body: 2202 source: 2203 remote: 2204 host: http://otherhost:9200 2205 username: myuser 2206 password: mypass 2207 index: REINDEX_SELECTION 2208 dest: 2209 index: MIGRATION 2210 remote_filters: 2211 - filtertype: pattern 2212 kind: prefix 2213 value: logstash-2017.03. 2214 filters: 2215 - filtertype: none 2216------------- 2217 2218IMPORTANT: Even though you are reindexing from remote, you _must_ set at least a 2219 <<filtertype_none,none>> filter, or the action will fail. Do not worry. Only 2220 the indices specified in `source` will be reindexed. 2221 2222Curator will create a connection to the host specified as the `host` key in the 2223above example. It will determine which port to connect to, and whether to use 2224SSL by parsing the URL entered there. Because this `host` is specifically used 2225by Elasticsearch, and Curator is making a separate connection, it is important 2226to ensure that both Curator _and_ your Elasticsearch cluster have access to the 2227remote host. 2228 2229If you do not whitelist the remote cluster, you will not be able to reindex. 2230This can be done by adding the following line to your `elasticsearch.yml` file: 2231 2232[source,yaml] 2233------------- 2234reindex.remote.whitelist: remote_host_or_IP1:9200, remote_host_or_IP2:9200 2235------------- 2236 2237or by adding this flag to the command-line when starting Elasticsearch: 2238 2239[source,sh] 2240------------- 2241bin/elasticsearch -Edefault.reindex.remote.whitelist="remote_host_or_IP:9200" 2242------------- 2243 2244Of course, be sure to substitute the correct host, IP, or port. 2245 2246Other client connection arguments can also be supplied in the form of action 2247options: 2248 2249* <<option_remote_url_prefix,remote_url_prefix>> 2250* <<option_remote_certificate,remote_certificate>> 2251* <<option_remote_client_cert,remote_client_cert>> 2252* <<option_remote_client_key,remote_client_key>> 2253* <<option_remote_aws_key,remote_aws_key>> 2254* <<option_remote_aws_secret_key,remote_aws_secret_key>> 2255* <<option_remote_aws_region,remote_remote_aws_region>> 2256* <<option_migration_prefix,migration_prefix>> 2257* <<option_migration_suffix,migration_suffix>> 2258 2259=== Other scenarios and options 2260 2261Nearly all scenarios supported by the reindex API are supported in the 2262request_body, including (but not limited to): 2263 2264* Pipelines 2265* Scripting 2266* Queries 2267* Conflict resolution 2268* Limiting by count 2269* Versioning 2270* Reindexing operation type (for example, create-only) 2271 2272Read more about these, and more, at {ref}/docs-reindex.html 2273 2274Notable exceptions include: 2275 2276* You cannot manually specify slices. Instead, use the <<option_slices,slices>> 2277 option for automated sliced reindexing. 2278 2279 2280[[option_retry_count]] 2281== retry_count 2282 2283NOTE: This setting is only used by the <<delete_snapshots, delete snapshots action>>. 2284 2285[source,yaml] 2286------------- 2287action: delete_snapshots 2288description: "Delete selected snapshots from 'repository'" 2289options: 2290 repository: ... 2291 retry_interval: 120 2292 retry_count: 3 2293filters: 2294- filtertype: ... 2295------------- 2296 2297The value of this setting is the number of times to retry deleting a snapshot. 2298 2299The default for this setting is `3`. 2300 2301 2302 2303[[option_retry_interval]] 2304== retry_interval 2305 2306NOTE: This setting is only used by the <<delete_snapshots, delete snapshots action>>. 2307 2308[source,yaml] 2309------------- 2310action: delete_snapshots 2311description: "Delete selected snapshots from 'repository'" 2312options: 2313 repository: ... 2314 retry_interval: 120 2315 retry_count: 3 2316filters: 2317- filtertype: ... 2318------------- 2319 2320The value of this setting is the number of seconds to delay between retries. 2321 2322The default for this setting is `120`. 2323 2324 2325 2326[[option_routing_type]] 2327== routing_type 2328 2329NOTE: This setting is only used by the 2330 <<cluster_routing,cluster_routing action>>. 2331 2332[source,yaml] 2333------------- 2334action: cluster_routing 2335description: "Apply routing rules to the entire cluster" 2336options: 2337 routing_type: 2338 value: ... 2339 setting: enable 2340 wait_for_completion: True 2341 max_wait: 300 2342 wait_interval: 10 2343------------- 2344 2345The value of this setting must be either `allocation` or `rebalance` 2346 2347There is no default value. This setting must be set by the user or an exception 2348will be raised, and execution will halt. 2349 2350[[option_setting]] 2351== setting 2352 2353NOTE: This setting is only used by the 2354 <<cluster_routing,cluster_routing action>>. 2355 2356[source,yaml] 2357------------- 2358action: cluster_routing 2359description: "Apply routing rules to the entire cluster" 2360options: 2361 routing_type: 2362 value: ... 2363 setting: enable 2364 wait_for_completion: True 2365 max_wait: 300 2366 wait_interval: 10 2367------------- 2368 2369The value of this must be `enable` at present. It is a placeholder for future 2370expansion. 2371 2372There is no default value. This setting must be set by the user or an exception 2373will be raised, and execution will halt. 2374 2375 2376[[option_shrink_node]] 2377== shrink_node 2378 2379NOTE: This setting is only used by the <<shrink,shrink>> action. 2380 2381[source,yaml] 2382------------- 2383action: shrink 2384description: >- 2385 Shrink selected indices on the node with the most available space, excluding 2386 master nodes and the node named 'not_this_node' 2387options: 2388 shrink_node: DETERMINISTIC 2389 node_filters: 2390 permit_masters: False 2391 exclude_nodes: ['not_this_node'] 2392 shrink_suffix: '-shrink' 2393filters: 2394 - filtertype: ... 2395------------- 2396 2397This setting is required. There is no default value. 2398 2399The value of this setting must be the valid name of a node in your Elasticsearch cluster, 2400or `DETERMINISTIC`. If the value is `DETERMINISTIC`, Curator will automatically 2401select the data node with the most available free space and make that the target node. 2402Curator will repeat this process for each successive index when the value is `DETERMINISTIC`. 2403 2404If <<option_node_filters,node_filters>>, such as `exclude_nodes` are defined, those nodes will 2405not be considered as potential target nodes. 2406 2407 2408[[option_shrink_prefix]] 2409== shrink_prefix 2410 2411NOTE: This setting is only used by the <<shrink,shrink>> action. 2412 2413[source,yaml] 2414------------- 2415action: shrink 2416description: >- 2417 Shrink selected indices on the node with the most available space. 2418 Prepend target index names with 'foo-' and append a suffix of '-shrink' 2419options: 2420 shrink_node: DETERMINISTIC 2421 shrink_prefix: 'foo-' 2422 shrink_suffix: '-shrink' 2423filters: 2424 - filtertype: ... 2425------------- 2426 2427There is no default value for this setting. 2428 2429The value of this setting will be prepended to target index names. If the source 2430index were `index`, and the `shrink_prefix` were `foo-`, and the `shrink_suffix` 2431were `-shrink`, the resulting target index name would be `foo-index-shrink`. 2432 2433 2434[[option_shrink_suffix]] 2435== shrink_suffix 2436 2437NOTE: This setting is only used by the <<shrink,shrink>> action. 2438 2439[source,yaml] 2440------------- 2441action: shrink 2442description: >- 2443 Shrink selected indices on the node with the most available space. 2444 Prepend target index names with 'foo-' and append a suffix of '-shrink' 2445options: 2446 shrink_node: DETERMINISTIC 2447 shrink_prefix: 'foo-' 2448 shrink_suffix: '-shrink' 2449filters: 2450 - filtertype: ... 2451------------- 2452 2453The default value for this setting is `-shrink`. 2454 2455The value of this setting will be appended to target index names. If the source 2456index were `index`, and the `shrink_prefix` were `foo-`, and the `shrink_suffix` 2457were `-shrink`, the resulting target index name would be `foo-index-shrink`. 2458 2459 2460[[option_slices]] 2461== slices 2462 2463NOTE: This setting is only used by the <<reindex,reindex>> action. 2464 2465This setting can speed up reindexing operations by using 2466{ref}/search-request-body.html#sliced-scroll[Sliced Scroll] to slice on the 2467\_uid. 2468 2469[source,yaml] 2470------------- 2471actions: 2472 1: 2473 description: "Reindex index1,index2,index3 into new_index" 2474 action: reindex 2475 options: 2476 wait_interval: 9 2477 max_wait: -1 2478 slices: 3 2479 request_body: 2480 source: 2481 index: ['index1', 'index2', 'index3'] 2482 dest: 2483 index: new_index 2484 filters: 2485 - filtertype: none 2486------------- 2487 2488=== Picking the number of slices 2489Here are a few recommendations around the number of `slices` to use: 2490 2491* Don’t use large numbers. `500` creates fairly massive CPU thrash, so Curator will not allow a number larger than this. 2492* It is more efficient from a query performance standpoint to use some multiple of the number of shards in the source index. 2493* Using exactly as many shards as are in the source index is the most efficient from a query performance standpoint. 2494* Indexing performance should scale linearly across available resources with the number of slices. 2495* Whether indexing or query performance dominates that process depends on lots of factors like the documents being reindexed and the cluster doing the reindexing. 2496 2497 2498 2499[[option_skip_fsck]] 2500== skip_repo_fs_check 2501 2502NOTE: This setting is used by the <<snapshot,snapshot>> and <<restore,restore>> 2503actions. 2504 2505This setting must be either `True` or `False`. 2506 2507The default value of this setting is `False` 2508 2509=== <<restore,restore>> 2510 2511Each master and data node in the cluster _must_ have write access to the shared 2512filesystem used by the repository for a snapshot to be 100% valid. For the 2513purposes of a <<restore,restore>>, this is a lightweight attempt to ensure that 2514all nodes are _still_ actively able to write to the repository, in hopes that 2515snapshots were from all nodes. It is not otherwise necessary for the purposes 2516of a restore. 2517 2518Some filesystems may take longer to respond to a check, which results in a false 2519positive for the filesystem access check. For these cases, it is desirable to 2520bypass this verification step, by setting this to `True.` 2521 2522[source,yaml] 2523------------- 2524actions: 2525 1: 2526 action: restore 2527 description: Restore my_index from my_snapshot in my_repository 2528 options: 2529 repository: my_repository 2530 name: my_snapshot 2531 indices: my_index 2532 skip_repo_fs_check: False 2533 wait_for_completion: True 2534 max_wait: 3600 2535 wait_interval: 10 2536 filters: 2537 - filtertype: state 2538 state: SUCCESS 2539 exclude: 2540 - filtertype: ... 2541------------- 2542 2543=== <<snapshot,snapshot>> 2544 2545Each master and data node in the cluster _must_ have write access to the shared 2546filesystem used by the repository for a snapshot to be 100% valid. 2547 2548Some filesystems may take longer to respond to a check, which results in a false 2549positive for the filesystem access check. For these cases, it is desirable to 2550bypass this verification step, by setting this to `True.` 2551 2552[source,yaml] 2553------------- 2554action: snapshot 2555description: >- 2556 Snapshot selected indices to 'repository' with the snapshot name or name 2557 pattern in 'name'. Use all other options as assigned 2558options: 2559 repository: my_repository 2560 name: my_snapshot 2561 skip_repo_fs_check: False 2562 wait_for_completion: True 2563 max_wait: 3600 2564 wait_interval: 10 2565filters: 2566- filtertype: ... 2567------------- 2568 2569 2570 2571[[option_timeout]] 2572== timeout 2573 2574NOTE: This setting is only used by the <<reindex,reindex>> action. 2575 2576The `timeout` is the length in seconds each individual bulk request should wait 2577for shards that are unavailable. The default value is `60`, meaning 60 seconds. 2578 2579[source,yaml] 2580------------- 2581actions: 2582 1: 2583 description: "Reindex index1,index2,index3 into new_index" 2584 action: reindex 2585 options: 2586 wait_interval: 9 2587 max_wait: -1 2588 timeout: 90 2589 request_body: 2590 source: 2591 index: ['index1', 'index2', 'index3'] 2592 dest: 2593 index: new_index 2594 filters: 2595 - filtertype: none 2596------------- 2597 2598 2599 2600[[option_timeout_override]] 2601== timeout_override 2602 2603NOTE: This setting is available in all actions. 2604 2605[source,yaml] 2606------------- 2607action: forcemerge 2608description: >- 2609 Perform a forceMerge on selected indices to 'max_num_segments' per shard 2610options: 2611 max_num_segments: 2 2612 timeout_override: 21600 2613filters: 2614- filtertype: ... 2615------------- 2616 2617If `timeout_override` is unset in your configuration, some actions will 2618try to set a sane default value. 2619 2620The following table shows these default values: 2621 2622[cols="m,", options="header"] 2623|=== 2624|Action Name |Default `timeout_override` Value 2625|close |180 2626|delete_snapshots |300 2627|forcemerge |21600 2628|restore |21600 2629|snapshot |21600 2630|=== 2631 2632 2633All other actions have no default value for `timeout_override`. 2634 2635This setting must be an integer number of seconds, or an error will result. 2636 2637This setting is particularly useful for the <<forcemerge,forceMerge>> action, 2638as all other actions have a new polling behavior when using 2639<<option_wfc,wait_for_completion>> that should reduce or prevent client 2640timeouts. 2641 2642 2643 2644[[option_value]] 2645== value 2646 2647NOTE: This setting is optional when using the <<allocation,allocation action>> 2648 and required when using the <<cluster_routing,cluster_routing action>>. 2649 2650=== <<allocation,allocation>> 2651 2652For the <<allocation,allocation action>>, the value of this setting should 2653correspond to a node setting on one or more nodes in your cluster 2654 2655For example, you might have set 2656 2657[source,sh] 2658----------- 2659node.tag: myvalue 2660----------- 2661 2662in your `elasticsearch.yml` file for one or more of your nodes. To match 2663allocation in this case, set value to `myvalue`. Additonally, if you used one of 2664the special attribute names `_ip`, `_name`, `_id`, or `_host` for 2665<<option_key,key>>, value can match the one of the node ip addresses, names, 2666ids, or host names, respectively. 2667 2668NOTE: To remove a routing allocation, the value of this setting should be left 2669empty, or the `value` setting not even included as an option. 2670 2671For example, you might have set 2672 2673[source,sh] 2674----------- 2675PUT test/_settings 2676{ 2677 "index.routing.allocation.exclude.size": "small" 2678} 2679----------- 2680 2681to keep index `test` from allocating shards on nodes that have `node.tag: small`. 2682To remove this shard routing allocation setting, you might use an action file 2683similar to this: 2684 2685[source,yaml] 2686----------- 2687--- 2688 actions: 2689 1: 2690 action: allocation 2691 description: -> 2692 Unset 'index.routing.allocation.exclude.size' for index 'test' by 2693 passing an empty value. 2694 options: 2695 key: size 2696 value: ... 2697 allocation_type: exclude 2698 filters: 2699 - filtertype: pattern 2700 kind: regex 2701 value: '^test$' 2702----------- 2703 2704=== <<cluster_routing,cluster_routing>> 2705 2706For the <<cluster_routing,cluster_routing action>>, the acceptable values for 2707this setting depend on the value of <<option_routing_type,routing_type>>. 2708 2709[source,yaml] 2710------------- 2711action: cluster_routing 2712description: "Apply routing rules to the entire cluster" 2713options: 2714 routing_type: ... 2715 value: ... 2716 setting: enable 2717 wait_for_completion: True 2718 max_wait: 300 2719 wait_interval: 10 2720------------- 2721 2722Acceptable values when <<option_routing_type,routing_type>> is either 2723`allocation` or `rebalance` are `all`, `primaries`, and `none` (string, not 2724`NoneType`). 2725 2726If `routing_type` is `allocation`, this can also be `new_primaries`. If 2727`routing_type` is `rebalance`, then the value can also be `replicas`. 2728 2729There is no default value. This setting must be set by the user or an exception 2730will be raised, and execution will halt. 2731 2732 2733 2734[[option_wait_for_active_shards]] 2735== wait_for_active_shards 2736 2737NOTE: This setting is used by the <<reindex,Reindex>>, <<rollover,Rollover>>, 2738and <<shrink,Shrink>> actions. Each use it similarly. 2739 2740This setting determines the number of shard copies that must be active before 2741the client returns. The default value is 1, which implies only the primary shards. 2742 2743Set to `all` for all shard copies, otherwise set to any non-negative value less 2744than or equal to the total number of copies for the shard (number of 2745replicas + 1) 2746 2747Read {ref}/docs-index_.html#index-wait-for-active-shards[the Elasticsearch documentation] for more information. 2748 2749=== Reindex 2750 2751[source,yaml] 2752------------- 2753actions: 2754 1: 2755 description: "Reindex index1,index2,index3 into new_index" 2756 action: reindex 2757 options: 2758 wait_interval: 9 2759 max_wait: -1 2760 wait_for_active_shards: 2 2761 request_body: 2762 source: 2763 index: ['index1', 'index2', 'index3'] 2764 dest: 2765 index: new_index 2766 filters: 2767 - filtertype: none 2768------------- 2769 2770 2771=== Rollover 2772 2773[source,yaml] 2774------------- 2775action: rollover 2776description: >- 2777 Rollover the index associated with alias 'name', which should be in the 2778 form of prefix-000001 (or similar), or prefix-yyyy.MM.DD-1. 2779options: 2780 name: aliasname 2781 conditions: 2782 max_age: 1d 2783 max_docs: 1000000 2784 wait_for_active_shards: 1 2785 extra_settings: 2786 index.number_of_shards: 3 2787 index.number_of_replicas: 1 2788 timeout_override: 2789 continue_if_exception: False 2790 disable_action: False 2791------------- 2792 2793=== Shrink 2794 2795[source,yaml] 2796------------- 2797action: shrink 2798description: >- 2799 Shrink selected indices on the node with the most available space. 2800 Prepend target index names with 'foo-' and append a suffix of '-shrink' 2801options: 2802 shrink_node: DETERMINISTIC 2803 wait_for_active_shards: all 2804filters: 2805 - filtertype: ... 2806------------- 2807 2808 2809 2810[[option_wfc]] 2811== wait_for_completion 2812 2813NOTE: This setting is used by the <<allocation,allocation>>, 2814 <<cluster_routing,cluster_routing>>, <<reindex,reindex>>, 2815 <<replicas,replicas>>, <<restore,restore>>, and <<snapshot,snapshot>> actions. 2816 2817This setting must be either `True` or `False`. 2818 2819This setting specifies whether or not the request should return immediately or 2820wait for the operation to complete before returning. 2821 2822=== <<allocation,allocation>> 2823 2824[source,yaml] 2825------------- 2826action: allocation 2827description: "Apply shard allocation filtering rules to the specified indices" 2828options: 2829 key: ... 2830 value: ... 2831 allocation_type: ... 2832 wait_for_completion: False 2833 max_wait: 300 2834 wait_interval: 10 2835filters: 2836- filtertype: ... 2837------------- 2838 2839The default value for the <<allocation,allocation>> action is `False`. 2840 2841=== <<cluster_routing,cluster_routing>> 2842 2843[source,yaml] 2844------------- 2845action: cluster_routing 2846description: "Apply routing rules to the entire cluster" 2847options: 2848 routing_type: 2849 value: ... 2850 setting: enable 2851 wait_for_completion: True 2852 max_wait: 300 2853 wait_interval: 10 2854------------- 2855 2856The default value for the <<cluster_routing,cluster_routing>> action is `False`. 2857 2858=== <<reindex,reindex>> 2859 2860[source,yaml] 2861------------- 2862actions: 2863 1: 2864 description: "Reindex index1 into index2" 2865 action: reindex 2866 options: 2867 wait_interval: 9 2868 max_wait: -1 2869 request_body: 2870 source: 2871 index: index1 2872 dest: 2873 index: index2 2874 filters: 2875 - filtertype: none 2876------------- 2877 2878The default value for the <<reindex,reindex>> action is `False`. 2879 2880=== <<replicas,replicas>> 2881 2882[source,yaml] 2883------------- 2884action: replicas 2885description: >- Set the number of replicas per shard for selected 2886 indices to 'count' 2887options: 2888 count: ... 2889 wait_for_completion: True 2890 max_wait: 600 2891 wait_interval: 10 2892filters: 2893- filtertype: ... 2894------------- 2895 2896The default value for the <<replicas,replicas>> action is `False`. 2897 2898=== <<restore,restore>> 2899 2900[source,yaml] 2901------------- 2902actions: 2903 1: 2904 action: restore 2905 description: Restore my_index from my_snapshot in my_repository 2906 options: 2907 repository: my_repository 2908 name: my_snapshot 2909 indices: my_index 2910 wait_for_completion: True 2911 max_wait: 3600 2912 wait_interval: 10 2913 filters: 2914 - filtertype: state 2915 state: SUCCESS 2916 exclude: 2917 - filtertype: ... 2918------------- 2919 2920The default value for the <<restore,restore>> action is `True`. 2921 2922=== <<snapshot,snapshot>> 2923 2924[source,yaml] 2925------------- 2926action: snapshot 2927description: >- 2928 Snapshot selected indices to 'repository' with the snapshot name or name 2929 pattern in 'name'. Use all other options as assigned 2930options: 2931 repository: my_repository 2932 name: my_snapshot 2933 wait_for_completion: True 2934 max_wait: 3600 2935 wait_interval: 10 2936filters: 2937- filtertype: ... 2938------------- 2939 2940The default value for the <<snapshot,snapshot>> action is `True`. 2941 2942TIP: During snapshot initialization, information about all previous snapshots is 2943 loaded into the memory, which means that in large repositories it may take 2944 several seconds (or even minutes) for this command to return even if the 2945 `wait_for_completion` setting is set to `False`. 2946 2947 2948[[option_wait_for_rebalance]] 2949== wait_for_rebalance 2950 2951[source,yaml] 2952------------- 2953action: shrink 2954description: >- 2955 Shrink selected indices on the node with the most available space. 2956 Delete source index after successful shrink, then reroute the shrunk 2957 index with the provided parameters. 2958options: 2959 ignore_empty_list: True 2960 shrink_node: DETERMINISTIC 2961 node_filters: 2962 permit_masters: False 2963 exclude_nodes: ['not_this_node'] 2964 number_of_shards: 1 2965 number_of_replicas: 1 2966 shrink_prefix: 2967 shrink_suffix: '-shrink' 2968 delete_after: True 2969 post_allocation: 2970 allocation_type: include 2971 key: node_tag 2972 value: cold 2973 wait_for_active_shards: 1 2974 extra_settings: 2975 settings: 2976 index.codec: best_compression 2977 wait_for_completion: True 2978 wait_for_rebalance: True 2979 wait_interval: 9 2980 max_wait: -1 2981filters: 2982 - filtertype: ... 2983------------- 2984 2985NOTE: This setting is used by the <<shrink,shrink>> action. 2986 2987This setting must be `true` or `false`. 2988 2989Setting this to `false` will result in the <<shrink,shrink>> action only 2990checking that the index being shrunk has finished being relocated, and 2991not continue to wait for the cluster to fully rebalance all shards. 2992 2993The default value for this setting is `false`. 2994 2995 2996[[option_wait_interval]] 2997== wait_interval 2998 2999NOTE: This setting is used by the <<allocation,allocation>>, 3000 <<cluster_routing,cluster_routing>>, <<reindex,reindex>>, 3001 <<replicas,replicas>>, <<restore,restore>>, and <<snapshot,snapshot>> actions. 3002 3003This setting must be a positive integer between 1 and 30. 3004 3005This setting specifies how long to wait between checks to see if the action has 3006completed or not. This number should not be larger than the client 3007<<timeout,timeout>> or the <<option_timeout_override,timeout_override>>. As the 3008default client <<timeout,timeout>> value for is 30, this should be uncommon. 3009 3010The default value for this setting is `9`, meaning 9 seconds between checks. 3011 3012This option is generally used in conjunction with <<option_max_wait,max_wait>>, 3013which is the maximum amount of time in seconds to wait for the given action to 3014complete. 3015 3016=== <<allocation,allocation>> 3017 3018[source,yaml] 3019------------- 3020action: allocation 3021description: "Apply shard allocation filtering rules to the specified indices" 3022options: 3023 key: ... 3024 value: ... 3025 allocation_type: ... 3026 wait_for_completion: False 3027 max_wait: 300 3028 wait_interval: 10 3029filters: 3030- filtertype: ... 3031------------- 3032 3033=== <<cluster_routing,cluster_routing>> 3034 3035[source,yaml] 3036------------- 3037action: cluster_routing 3038description: "Apply routing rules to the entire cluster" 3039options: 3040 routing_type: 3041 value: ... 3042 setting: enable 3043 wait_for_completion: True 3044 max_wait: 300 3045 wait_interval: 10 3046------------- 3047 3048=== <<reindex,reindex>> 3049 3050[source,yaml] 3051------------- 3052actions: 3053 1: 3054 description: "Reindex index1 into index2" 3055 action: reindex 3056 options: 3057 wait_interval: 9 3058 max_wait: -1 3059 request_body: 3060 source: 3061 index: index1 3062 dest: 3063 index: index2 3064 filters: 3065 - filtertype: none 3066------------- 3067 3068=== <<replicas,replicas>> 3069 3070[source,yaml] 3071------------- 3072action: replicas 3073description: >- Set the number of replicas per shard for selected 3074 indices to 'count' 3075options: 3076 count: ... 3077 wait_for_completion: True 3078 max_wait: 600 3079 wait_interval: 10 3080filters: 3081- filtertype: ... 3082------------- 3083 3084=== <<restore,restore>> 3085 3086[source,yaml] 3087------------- 3088actions: 3089 1: 3090 action: restore 3091 description: Restore my_index from my_snapshot in my_repository 3092 options: 3093 repository: my_repository 3094 name: my_snapshot 3095 indices: my_index 3096 wait_for_completion: True 3097 max_wait: 3600 3098 wait_interval: 10 3099 filters: 3100 - filtertype: state 3101 state: SUCCESS 3102 exclude: 3103 - filtertype: ... 3104------------- 3105 3106=== <<snapshot,snapshot>> 3107 3108[source,yaml] 3109------------- 3110action: snapshot 3111description: >- 3112 Snapshot selected indices to 'repository' with the snapshot name or name 3113 pattern in 'name'. Use all other options as assigned 3114options: 3115 repository: my_repository 3116 name: my_snapshot 3117 wait_for_completion: True 3118 max_wait: 3600 3119 wait_interval: 10 3120filters: 3121- filtertype: ... 3122------------- 3123 3124[[option_warn_if_no_indices]] 3125== warn_if_no_indices 3126 3127NOTE: This setting is only used by the <<alias,alias>> action. 3128 3129This setting must be either `True` or `False`. 3130 3131The default value for this setting is `False`. 3132 3133[source,yaml] 3134------------- 3135action: alias 3136description: "Add/Remove selected indices to or from the specified alias" 3137options: 3138 name: alias_name 3139 warn_if_no_indices: False 3140add: 3141 filters: 3142 - filtertype: ... 3143remove: 3144 filters: 3145 - filtertype: ... 3146------------- 3147 3148This setting specifies whether or not the alias action should continue with a 3149warning or return immediately in the event that the filters in the add or remove 3150section result in an empty index list. 3151 3152[WARNING] 3153.Improper use of this setting can yield undesirable results 3154===================================================================== 3155*Ideal use case:* 3156For example, you want to add the most recent seven days of time-series indices 3157into a _lastweek_ alias, and remove indices older than seven days from this same 3158alias. If you do not not yet have any indices older than seven days, this will 3159result in an empty index list condition which will prevent the entire alias 3160action from completing successfully. If `warn_if_no_indices` were set to `True`, 3161however, it would avert that potential outcome. 3162 3163*Potentially undesirable outcome:* 3164A _non-beneficial_ case would be where if `warn_if_no_indices` is set to `True`, 3165and a misconfiguration results in indices not being found, and therefore not 3166being disassociated from the alias. As a result, an alias that should only 3167query one week now references multiple weeks of data. If `warn_if_no_indices` 3168were set to `False`, this scenario would have been averted because the empty 3169list condition would have resulted in an error. 3170===================================================================== 3171