---
title: Configuration File
description: The configuration file contains client connection and settings for logging.  It looks like this: It is a YAML configuration file.  The two root keys must...
url: https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/configfile
products:
  - Elasticsearch
  - Elasticsearch Curator
---

# Configuration File
<note>
  The default location of the configuration file is `~/.curator/curator.yml`, but another location can be specified using the `--config` flag on the [command-line](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/command-line).
</note>

<note>
  You can use [environment variables](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/envvars) in your configuration files.
</note>

The configuration file contains client connection and settings for logging.  It looks like this:
```sh
---
# Remember, leave a key empty if there is no value.  None will be a string,
# not a Python "NoneType"
elasticsearch:
  client:
    hosts:
      - http://127.0.0.1:9200
    cloud_id:
    ca_certs:
    client_cert:
    client_key:
    verify_certs:
    request_timeout: 30
  other_settings:
    master_only: False
    username:
    password:
    api_key:
      id:
      api_key:
      token:

logging:
  loglevel: INFO
  logfile:
  logformat: default
  blacklist: ['elastic_transport', 'urllib3']
```

It is a YAML configuration file.  The two root keys must be `elasticsearch` and `logging`.  The subkeys of each of these will be described here.
There are other keys available for the `client` subkey of the `elasticsearch` root key, many of which are listed [here](https://es-client.readthedocs.io/en/latest/defaults.html). The most commonly used ones (listed above) are described as follows:

## hosts

<important>
  All hosts must be in `HTTP[S]://FQDN.DOMAIN.TLD:PORT` form or they will be rejected and Curator will exit with an error. The only exception to this is `HTTPS://FQDN.DOMAIN.TLD` (without port), in which case `:443` is implicit, and is, in fact, appended automatically.
</important>

<warning>
  If both `cloud_id` and `hosts` keys are populated an exception will be thrown and Curator will exit.
</warning>

A `hosts` definition can be a single value:
```sh
hosts: http://127.0.0.1:9200
```

Or multiple values in the 3 acceptable YAML ways to render sequences, or arrays:
<warning>
  Curator can only work with one cluster at a time.  Including clients from multiple clusters in the `hosts` setting will result in errors.
</warning>

Flow:
```sh
hosts: [ "<HOST_IP_1>:9200", "<HOST_IP_2>:9200" ]
```

Spanning:
```sh
hosts: [ "<HOST_IP_1>:9200",
    "<HOST_IP_2>:9200" ]
```

Block:
```sh
hosts:
  - <HOST_IP_1>:9200
  - <HOST_IP_2>:9200
```


## cloud_id

The value should encapsulated in quotes because of the included colon:
```sh
cloud_id: 'deployment_name:BIG_HASH_VALUE'
```

<warning>
  If both `cloud_id` and `hosts` keys are populated an exception will be thrown and Curator will exit.
</warning>


## ca_certs

This should be a file path to your CA certificate, or left empty.
```sh
ca_certs:
```

This setting allows the use of a specified CA certificate file to validate the SSL certificate used by Elasticsearch.
There is no default.
<admonition title="File paths">
  File paths can be specified as follows:**For Windows:**
  ```sh
  'C:\path\to\file'
  ```
  **For Linux, BSD, Mac OS:**
  ```sh
  '/path/to/file'
  ```
  Using single-quotes around your file path is encouraged, especially with Windows file paths.
</admonition>


## client_cert

This should be a file path to a client certificate (public key), or left empty.
```sh
client_cert:
```

Allows the use of a specified SSL client cert file to authenticate to Elasticsearch. The file may contain both an SSL client certificate and an SSL key, in which case [client_key](#client_key) is not used. If specifying `client_cert`, and the file specified does not also contain the key, use [client_key](#client_key) to specify the file containing the SSL key. The file must be in PEM format, and the key part, if used, must be an unencrypted key in PEM format as well.
<admonition title="File paths">
  File paths can be specified as follows:**For Windows:**
  ```sh
  'C:\path\to\file'
  ```
  **For Linux, BSD, Mac OS:**
  ```sh
  '/path/to/file'
  ```
  Using single-quotes around your file path is encouraged, especially with Windows file paths.
</admonition>


## client_key

This should be a file path to a client key (private key), or left empty.
```sh
client_key:
```

Allows the use of a specified SSL client key file to authenticate to Elasticsearch. If using [client_cert](#client_cert) and the file specified does not also contain the key, use `client_key` to specify the file containing the SSL key. The key file must be an unencrypted key in PEM format.
<admonition title="File paths">
  File paths can be specified as follows:**For Windows:**
  ```sh
  'C:\path\to\file'
  ```
  **For Linux, BSD, Mac OS:**
  ```sh
  '/path/to/file'
  ```
  Using single-quotes around your file path is encouraged, especially with Windows file paths.
</admonition>


## verify_certs

This should be `True`, `False` or left empty.
```sh
verify_certs:
```

If access to your Elasticsearch instance is protected by SSL encryption, you may set `verify_certs` to `False` to disable SSL certificate verification.
Valid use cases for doing so include the use of self-signed certificates that cannot be otherwise verified and would generate error messages.
<warning>
  Setting `verify_certs` to `False` will likely result in a warning message that your SSL certificates are not trusted. This is expected behavior.
</warning>

The default value is `True`.

## request_timeout

This should be an integer number of seconds, or left empty.
```sh
request_timeout:
```

You can change the default client connection timeout value with this setting.
The default value is `30` (seconds) should typically not be changed to be very large.  If a longer timeout is necessary for a given action, such as [snapshot](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/snapshot), [restore](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/restore), or [forcemerge](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/forcemerge), the client timeout can be overridden on per action basis by setting [timeout_override](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/option_timeout_override) in the action [options](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/curator/options). There are default override values for some of those longer running actions.

## master_only

This should be `True`, `False` or left empty.
```sh
master_only:
```

In some situations, primarily with automated deployments, it makes sense to install Curator on every node. But you wouldn’t want it to run on each node. By setting `master_only` to `True`, this is possible. It tests for, and will only continue running on the node that is the elected master.
<warning>
  If `master_only` is `True`, and [hosts](#hosts) has more than one value, Curator will raise an Exception.  This setting should *only* be used with a single host in [hosts](#hosts), as its utility centers around deploying to all nodes in the cluster.
</warning>

The default value is `False`.

## username

The HTTP Basic Authentication username

## password

The HTTP Basic Authentication password

## id

This should be the `id` portion of an API Key pair.
```sh
api_key:
  id:
```

This setting combined with the other subkey `api_key` allows API Key authentication to an Elasticsearch instance.
The default is empty.

## api_key

This should be the `api_key` portion of an API Key pair.
```sh
api_key:
  api_key:
```

This setting combined with the other subkey `id` allows API Key authentication to an Elasticsearch instance.
The default is empty.

## token

This should be a base64 encoded representation of an API Key pair.
```sh
api_key:
  token:
```

This setting will override any values provided for the `id` or `api_key` subkeys of `api_key`.
The default is empty.

## loglevel

This should be `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or left empty.
```sh
loglevel:
```

Set the minimum acceptable log severity to display.
- `CRITICAL` will only display critical messages.
- `ERROR` will only display error and critical messages.
- `WARNING` will display error, warning, and critical messages.
- `INFO` will display informational, error, warning, and critical messages.
- `DEBUG` will display debug messages, in addition to all of the above.

The default value is `INFO`.

## logfile

This should be a path to a log file, or left empty.
```sh
logfile:
```

<admonition title="File paths">
  File paths can be specified as follows:**For Windows:**
  ```sh
  'C:\path\to\file'
  ```
  **For Linux, BSD, Mac OS:**
  ```sh
  '/path/to/file'
  ```
  Using single-quotes around your file path is encouraged, especially with Windows file paths.
</admonition>

The default value is empty, which will result in logging to `STDOUT`, or the console.

## logformat

This should `default`, `json`, `logstash`, `ecs` or left empty.
```sh
logformat:
```

The `default` format looks like:
```sh
2016-04-22 11:53:09,972 INFO      Action #1: ACTIONNAME
```

The `json` or `logstash` formats look like:
```sh
{"@timestamp": "2016-04-22T11:54:29.033Z", "function": "cli", "linenum": 178,
"loglevel": "INFO", "message": "Action #1: ACTIONNAME", "name": "curator.cli"}
```

The `ecs` format looks like:
```sh
{"@timestamp":"2020-02-22T11:55:00.022Z","log.level":"info","message":"Action #1:
ACTIONNAME","ecs":{"version":"1.6.0"},"log":{"logger":"curator.cli","origin":
{"file":{"line":178,"name":"cli.py"},"function":"run"},"original":"Action #1:
ACTIONNAME"},"process":{"name":"MainProcess","pid":12345,"thread":
{"id":123456789886543,"name":"MainThread"}}}
```

The default value is `default`.

## blacklist

This should be an empty array `[]`, an array of log handler strings, or left empty.
```sh
blacklist: ['elastic_transport', 'urllib3']
```

The default value is `['elastic_transport', 'urllib3']`, which will result in logs for the `elastic_transport` and `urllib3` Python modules *not* being output. These can be quite verbose, so unless you need them to debug an issue, you should accept the default value.
<tip>
  If you do need to troubleshoot an issue, set `blacklist` to `[]`, which is an empty array.  Leaving it unset will result in the default behavior, which is to filter out `elastic_transport` and `urllib3` log traffic.
</tip>