1[[cli]] 2= Running Curator 3 4[partintro] 5-- 6* <<command-line,Command Line Interface>> 7* <<singleton-cli,Singleton Command Line Interface>> 8* <<exit-codes,Exit Codes>> 9-- 10 11[[command-line]] 12== Command Line Interface 13 14The command-line arguments are as follows: 15 16[source,sh] 17------- 18curator [--config CONFIG.YML] [--dry-run] ACTION_FILE.YML 19------- 20 21The square braces indicate optional elements. 22 23If `--config` and `CONFIG.YML` are not provided, Curator will look in 24`~/.curator/curator.yml` for the configuration file. `~` is the home directory 25of the user executing Curator. In a Unix system, this might be 26`/home/username/.curator/curator.yml`, while on a Windows system, it might be 27`C:\Users\username\.curator\curator.yml` 28 29If `--dry-run` is included, Curator will simulate the action(s) in 30ACTION_FILE.YML as closely as possible without actually making any changes. The 31results will be in the logfile, or STDOUT/command-line if no logfile is 32specified. 33 34`ACTION_FILE.YML` is a YAML <<actionfile, actionfile>>. 35 36Command-line help is never far away: 37 38[source,sh] 39------- 40curator --help 41------- 42 43The help output looks like this: 44 45[source,sh] 46------- 47$ curator --help 48Usage: curator [OPTIONS] ACTION_FILE 49 50 Curator for Elasticsearch indices. 51 52 See http://elastic.co/guide/en/elasticsearch/client/curator/current 53 54Options: 55 --config PATH Path to configuration file. Default: ~/.curator/curator.yml 56 --dry-run Do not perform any changes. 57 --version Show the version and exit. 58 --help Show this message and exit. 59------- 60 61You can use <<envvars,environment variables>> in your configuration files. 62 63TIP: See <<faq_unicode,this FAQ about Python 3 requiring a Unicode locale>> 64 65 66 67[[singleton-cli]] 68== Singleton Command Line Interface 69 70The `curator_cli` command allows users to run a single, supported action from 71the command-line, without needing either the client or action YAML configuration 72file, though it does support using the client configuration file if you want. 73As an important bonus, the command-line options allow you to override the 74settings in the `curator.yml` file! 75 76[source,sh] 77--------- 78$ curator_cli --help 79Usage: curator_cli [OPTIONS] COMMAND [ARGS]... 80 81Options: 82 --config PATH Path to configuration file. Default: 83 ~/.curator/curator.yml 84 --host TEXT Elasticsearch host. 85 --url_prefix TEXT Elasticsearch http url prefix. 86 --port TEXT Elasticsearch port. 87 --use_ssl Connect to Elasticsearch through SSL. 88 --certificate TEXT Path to certificate to use for SSL validation. 89 --client-cert TEXT Path to file containing SSL certificate for client auth. 90 --client-key TEXT Path to file containing SSL key for client auth. 91 --ssl-no-validate Do not validate SSL certificate 92 --http_auth TEXT Use Basic Authentication ex: user:pass 93 --timeout INTEGER Connection timeout in seconds. 94 --master-only Only operate on elected master node. 95 --dry-run Do not perform any changes. 96 --loglevel TEXT Log level 97 --logfile TEXT log file 98 --logformat TEXT Log output format [default|logstash|json|ecs]. 99 --version Show the version and exit. 100 --help Show this message and exit. 101 102Commands: 103 allocation Shard Routing Allocation 104 close Close indices 105 delete_indices Delete indices 106 delete_snapshots Delete snapshots 107 forcemerge forceMerge index/shard segments 108 open Open indices 109 replicas Change replica count 110 show_indices Show indices 111 show_snapshots Show snapshots 112 snapshot Snapshot indices 113--------- 114 115The option flags for the given commands match those used for the same 116<<actions,actions>>. The only difference is how filtering is handled. 117 118TIP: See <<faq_unicode,this FAQ about Python 3 requiring a Unicode locale>> 119 120=== Command-line filtering 121 122Recent improvements in Curator include schema and setting validation. With 123these improvements, it is possible to validate filters and their many 124permutations if passed in a way that Curator can easily digest. 125 126[source,sh] 127----------- 128--filter_list TEXT JSON string representing an array of filters. 129----------- 130 131This means that filters need to be passed as a single object, or an array of 132objects in JSON format. 133 134Single: 135[source,sh] 136----------- 137--filter_list '{"filtertype":"none"}' 138----------- 139 140Multiple: 141[source,sh] 142----------- 143--filter_list '[{"filtertype":"age","source":"creation_date","direction":"older","unit":"days","unit_count":13},{"filtertype":"pattern","kind":"prefix","value":"logstash"}]' 144----------- 145 146This preserves the power of chained filters, making them available on the 147command line. 148 149NOTE: You may need to escape all of the double quotes on some platforms, or 150 shells like PowerShell, for instance. 151 152Caveats to this approach: 153 1541. Only one action can be taken at a time. 1552. Not all actions have singleton analogs. For example, <<alias,Alias>> and + 156 <<restore,Restore>> do not have singleton actions. 157 158=== Show Indices/Snapshots 159 160One feature that the singleton command offers that the other cannot is to show 161which indices and snapshots are in the system. It's a great way to visually 162test your filters without causing any harm to the system. 163 164[source,sh] 165----------- 166$ curator_cli show_indices --help 167Usage: curator_cli show_indices [OPTIONS] 168 169 Show indices 170 171Options: 172 --verbose Show verbose output. 173 --header Print header if --verbose 174 --epoch Print time as epoch if --verbose 175 --filter_list TEXT JSON string representing an array of filters. 176 [required] 177 --help Show this message and exit. 178----------- 179 180[source,sh] 181----------- 182$ curator_cli show_snapshots --help 183Usage: curator_cli show_snapshots [OPTIONS] 184 185 Show snapshots 186 187Options: 188 --repository TEXT Snapshot repository name [required] 189 --filter_list TEXT JSON string representing an array of filters. 190 [required] 191 --help Show this message and exit. 192----------- 193 194The `show_snapshots` command will only show snapshots matching the provided 195filters. The `show_indices` command will also do this, but also offers a few 196extra features. 197 198* `--verbose` adds state, total size of primary and all replicas, the document 199 count, the number of primary and replica shards, and the creation date in 200 ISO8601 format. 201* `--header` adds a header that shows the column names. This only occurs if 202 `--verbose` is also selected. 203* `--epoch` changes the date format from ISO8601 to epoch time. If `--header` 204 is also selected, the column header title will change to `creation_date` 205 206There are no extra columns or `--verbose` output for the `show_snapshots` 207command. 208 209Without `--epoch` 210[source,sh] 211----------- 212Index State Size Docs Pri Rep Creation Timestamp 213logstash-2016.10.20 close 0.0B 0 5 1 2016-10-20T00:00:03Z 214logstash-2016.10.21 open 763.3MB 5860016 5 1 2016-10-21T00:00:03Z 215logstash-2016.10.22 open 759.1MB 5858450 5 1 2016-10-22T00:00:04Z 216logstash-2016.10.23 open 757.8MB 5857456 5 1 2016-10-23T00:00:04Z 217logstash-2016.10.24 open 771.5MB 5859720 5 1 2016-10-24T00:00:00Z 218logstash-2016.10.25 open 771.0MB 5860112 5 1 2016-10-25T00:00:01Z 219logstash-2016.10.27 open 658.3MB 4872830 5 1 2016-10-27T00:00:03Z 220logstash-2016.10.28 open 655.1MB 5237250 5 1 2016-10-28T00:00:00Z 221----------- 222 223With `--epoch` 224[source,sh] 225----------- 226Index State Size Docs Pri Rep creation_date 227logstash-2016.10.20 close 0.0B 0 5 1 1476921603 228logstash-2016.10.21 open 763.3MB 5860016 5 1 1477008003 229logstash-2016.10.22 open 759.1MB 5858450 5 1 1477094404 230logstash-2016.10.23 open 757.8MB 5857456 5 1 1477180804 231logstash-2016.10.24 open 771.5MB 5859720 5 1 1477267200 232logstash-2016.10.25 open 771.0MB 5860112 5 1 1477353601 233logstash-2016.10.27 open 658.3MB 4872830 5 1 1477526403 234logstash-2016.10.28 open 655.1MB 5237250 5 1 1477612800 235----------- 236 237 238 239[[exit-codes]] 240== Exit Codes 241 242Exit codes will indicate success or failure. 243 244* `0` — Success 245* `1` — Failure 246* `-1` - Exception raised that does not result in a `1` exit code. 247 248 249