[[cli]]
= Running Curator

[partintro]
--
* <<command-line,Command Line Interface>>
* <<singleton-cli,Singleton Command Line Interface>>
* <<exit-codes,Exit Codes>>
--

[[command-line]]
== Command Line Interface

Most common client configuration settings are now available at the command-line.

IMPORTANT: While both the configuration file and the command-line arguments can be used together,
  it is important to note that command-line options will override file-based configuration of the
  same setting.

The most basic 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>>.

For other client configuration options, 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

  The default $HOME/.curator/curator.yml configuration file (--config) can be used but is not needed.

  Command-line settings will always override YAML configuration settings.

  Some less-frequently used client configuration options are now hidden. To see the full list, run:

      curator_cli -h

Options:
  --config PATH                   Path to configuration file.
  --hosts TEXT                    Elasticsearch URL to connect to.
  --cloud_id TEXT                 Elastic Cloud instance id
  --api_token TEXT                The base64 encoded API Key token
  --id TEXT                       API Key "id" value
  --api_key TEXT                  API Key "api_key" value
  --username TEXT                 Elasticsearch username
  --password TEXT                 Elasticsearch password
  --request_timeout FLOAT         Request timeout in seconds
  --verify_certs / --no-verify_certs
                                  Verify SSL/TLS certificate(s)  [default: verify_certs]
  --ca_certs TEXT                 Path to CA certificate file or directory
  --client_cert TEXT              Path to client certificate file
  --client_key TEXT               Path to client key file
  --dry-run                       Do not perform any changes.
  --loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level
  --logfile TEXT                  Log file
  --logformat [default|ecs]       Log output format
  -v, --version                   Show the version and exit.
  -h, --help                      Show this message and exit.

  Learn more at https://www.elastic.co/guide/en/elasticsearch/client/curator/8.0/command-line.html
-------

You can use <<envvars,environment variables>> in your configuration files.

=== Running Curator from Docker

Running Curator from the command-line using Docker requires only a few additional steps.

Should you desire to use them, Docker-based Curator requires you to map a volume for your
configuration and/or log files. Attempting to read a YAML configuration file if you have
neglected to volume map your configuration directory to `/.curator` will not work.

It looks like this:

[source,sh]
-------
docker run [-t] --rm --name myimagename \
  -v /PATH/TO/MY/CONFIGS:/.curator      \
  untergeek/curator:mytag               \
--config /.curator/config.yml /.curator/actionfile.yml
-------

NOTE: While testing, adding the `-t` flag will allocate a pseudo-tty, allowing you to see terminal
  output that would otherwise be hidden.

Both of the files `config.yml` and `actionfile.yml` should already exist in the path
`/PATH/TO/MY/CONFIGS` before run time.

The `--rm` in the command means that the container (not the image) will be deleted after
completing execution. You definitely want this as there is no reason to keep creating
containers for each run. The eventual cleanup from this would be unpleasant.

&nbsp;

[[singleton-cli]]
== Singleton Command Line Interface

The `curator_cli` command 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!

IMPORTANT: While both the configuration file and the command-line arguments can be used together,
  it is important to note that command-line options will override file-based configuration of the
  same setting.

[source,sh]
---------
$ curator_cli --help
Usage: curator_cli [OPTIONS] COMMAND [ARGS]...

  Curator CLI (Singleton Tool)

  Run a single action from the command-line.

  The default $HOME/.curator/curator.yml configuration file (--config) can be used but is not needed.

  Command-line settings will always override YAML configuration settings.

Options:
  --config PATH                   Path to configuration file.
  --hosts TEXT                    Elasticsearch URL to connect to.
  --cloud_id TEXT                 Elastic Cloud instance id
  --api_token TEXT                The base64 encoded API Key token
  --id TEXT                       API Key "id" value
  --api_key TEXT                  API Key "api_key" value
  --username TEXT                 Elasticsearch username
  --password TEXT                 Elasticsearch password
  --bearer_auth TEXT              Bearer authentication token
  --opaque_id TEXT                X-Opaque-Id HTTP header value
  --request_timeout FLOAT         Request timeout in seconds
  --http_compress / --no-http_compress
                                  Enable HTTP compression  [default: no-http_compress]
  --verify_certs / --no-verify_certs
                                  Verify SSL/TLS certificate(s)  [default: verify_certs]
  --ca_certs TEXT                 Path to CA certificate file or directory
  --client_cert TEXT              Path to client certificate file
  --client_key TEXT               Path to client key file
  --ssl_assert_hostname TEXT      Hostname or IP address to verify on the node's certificate.
  --ssl_assert_fingerprint TEXT   SHA-256 fingerprint of the node's certificate. If this value is given then root-of-trust
                                  verification isn't done and only the node's certificate fingerprint is verified.
  --ssl_version TEXT              Minimum acceptable TLS/SSL version
  --master-only / --no-master-only
                                  Only run if the single host provided is the elected master  [default: no-master-only]
  --skip_version_test / --no-skip_version_test
                                  Elasticsearch version compatibility check  [default: no-skip_version_test]
  --dry-run                       Do not perform any changes.
  --loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Log level
  --logfile TEXT                  Log file
  --logformat [default|ecs]       Log output format
  -v, --version                   Show the version and exit.
  -h, --help                      Show this message and exit.

Commands:
  alias             Add/Remove Indices to/from Alias
  allocation        Shard Routing Allocation
  close             Close Indices
  delete-indices    Delete Indices
  delete-snapshots  Delete Snapshots
  forcemerge        forceMerge Indices (reduce segment count)
  open              Open Indices
  replicas          Change Replica Count
  restore           Restore Indices
  rollover          Rollover Index associated with Alias
  show-indices      Show Indices
  show-snapshots    Show Snapshots
  shrink            Shrink Indices to --number_of_shards
  snapshot          Snapshot Indices

  Learn more at https://www.elastic.co/guide/en/elasticsearch/client/curator/8.0/singleton-cli.html
---------

The option flags for the given commands match those used for the same
<<actions,actions>>.  The only difference is how filtering is handled.

=== Running Curator from Docker

Running `curator_cli` from the command-line using Docker requires only a few additional steps.

Should you desire to use them, Docker-based `curator_cli` requires you to map a volume for your
configuration and/or log files. Attempting to read a YAML configuration file if you have
neglected to volume map your configuration directory to `/.curator` will not work.

It looks like this:

[source,sh]
-------
docker run [-t] --rm --name myimagename  \
  --entrypoint /curator/curator_cli      \
  -v /PATH/TO/MY/CONFIGS:/.curator       \
  untergeek/curator:mytag                \
  --config /.curator/config.yml [OPTIONS] COMMAND [ARGS]...
-------

NOTE: While testing, adding the `-t` flag will allocate a pseudo-tty, allowing you to see terminal
  output that would otherwise be hidden.

The `config.yml` file should already exist in the path `/PATH/TO/MY/CONFIGS` before run time.

The `--rm` in the command means that the container (not the image) will be deleted after
completing execution. You definitely want this as there is no reason to keep creating
containers for each run. The eventual cleanup from this would be unpleasant.

=== 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. Not all actions have singleton analogs. For example, <<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.

  Learn more at https://www.elastic.co/guide/en/elasticsearch/client/curator/8.0/singleton-cli.html#_show_indicessnapshots
-----------

[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.

  Learn more at https://www.elastic.co/guide/en/elasticsearch/client/curator/8.0/singleton-cli.html#_show_indicessnapshots
-----------

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
-----------

&nbsp;

[[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.

&nbsp;