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