150 lines
5.3 KiB
Plaintext
150 lines
5.3 KiB
Plaintext
[[settings]]
|
|
== Configuring Elasticsearch
|
|
|
|
Elasticsearch ships with good defaults and requires very little configuration.
|
|
Most settings can be changed on a running cluster using the
|
|
<<cluster-update-settings>> API.
|
|
|
|
The configuration files should contain settings which are node-specific (such
|
|
as `node.name` and paths), or settings which a node requires in order to be
|
|
able to join a cluster, such as `cluster.name` and `network.host`.
|
|
|
|
[float]
|
|
=== Config file location
|
|
|
|
Elasticsearch has two configuration files:
|
|
|
|
* `elasticsearch.yml` for configuring Elasticsearch, and
|
|
* `logging.yml` for configuring Elasticsearch logging.
|
|
|
|
These files are located in the config directory, whose location defaults to
|
|
`$ES_HOME/config/`. The Debian and RPM packages set the config directory
|
|
location to `/etc/elasticsearch/`.
|
|
|
|
The location of the config directory can be changed with the `path.conf`
|
|
setting, as follows:
|
|
|
|
[source,sh]
|
|
-------------------------------
|
|
./bin/elasticsearch -Epath.conf=/path/to/my/config/
|
|
-------------------------------
|
|
|
|
[float]
|
|
=== Config file format
|
|
|
|
The configuration format is http://www.yaml.org/[YAML]. Here is an
|
|
example of changing the path of the data and logs directories:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
path:
|
|
data: /var/lib/elasticsearch
|
|
logs: /var/log/elasticsearch
|
|
--------------------------------------------------
|
|
|
|
Settings can also be flattened as follows:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
path.data: /var/lib/elasticsearch
|
|
path.logs: /var/log/elasticsearch
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
=== Environment variable subsitution
|
|
|
|
Environment variables referenced with the `${...}` notation within the
|
|
configuration file will be replaced with the value of the environment
|
|
variable, for instance:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
node.name: ${HOSTNAME}
|
|
network.host: ${ES_NETWORK_HOST}
|
|
--------------------------------------------------
|
|
|
|
[float]
|
|
=== Prompting for settings
|
|
|
|
For settings that you do not wish to store in the configuration file, you can
|
|
use the value `${prompt.text}` or `${prompt.secret}` and start Elasticsearch
|
|
in the foreground. `${prompt.secret}` has echoing disabled so that the value
|
|
entered will not be shown in your terminal; `${prompt.text}` will allow you to
|
|
see the value as you type it in. For example:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
node:
|
|
name: ${prompt.text}
|
|
--------------------------------------------------
|
|
|
|
When starting Elasticsearch, you will be prompted to enter the actual value
|
|
like so:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
Enter value for [node.name]:
|
|
--------------------------------------------------
|
|
|
|
NOTE: Elasticsearch will not start if `${prompt.text}` or `${prompt.secret}`
|
|
is used in the settings and the process is run as a service or in the background.
|
|
|
|
[float]
|
|
=== Setting default settings
|
|
|
|
New default settings may be specified on the command line using the
|
|
`default.` prefix. This will specify a value that will be used by
|
|
default unless another value is specified in the config file.
|
|
|
|
For instance, if Elasticsearch is started as follows:
|
|
|
|
[source,sh]
|
|
---------------------------
|
|
./bin/elasticsearch -Edefault.node.name=My_Node
|
|
---------------------------
|
|
|
|
the value for `node.name` will be `My_Node`, unless it is overwritten on the
|
|
command line with `es.node.name` or in the config file with `node.name`.
|
|
|
|
[float]
|
|
[[logging]]
|
|
== Logging configuration
|
|
|
|
Elasticsearch uses an internal logging abstraction and comes, out of the
|
|
box, with http://logging.apache.org/log4j/1.2/[log4j]. It tries to simplify
|
|
log4j configuration by using http://www.yaml.org/[YAML] to configure it,
|
|
and the logging configuration file is `config/logging.yml`. The
|
|
http://en.wikipedia.org/wiki/JSON[JSON] and
|
|
http://en.wikipedia.org/wiki/.properties[properties] formats are also
|
|
supported. Multiple configuration files can be loaded, in which case they will
|
|
get merged, as long as they start with the `logging.` prefix and end with one
|
|
of the supported suffixes (either `.yml`, `.yaml`, `.json` or `.properties`).
|
|
The logger section contains the java packages and their corresponding log
|
|
level, where it is possible to omit the `org.elasticsearch` prefix. The
|
|
appender section contains the destinations for the logs. Extensive information
|
|
on how to customize logging and all the supported appenders can be found on
|
|
the http://logging.apache.org/log4j/1.2/manual.html[log4j documentation].
|
|
|
|
Additional Appenders and other logging classes provided by
|
|
http://logging.apache.org/log4j/extras/[log4j-extras] are also available,
|
|
out of the box.
|
|
|
|
[float]
|
|
[[deprecation-logging]]
|
|
=== Deprecation logging
|
|
|
|
In addition to regular logging, Elasticsearch allows you to enable logging
|
|
of deprecated actions. For example this allows you to determine early, if
|
|
you need to migrate certain functionality in the future. By default,
|
|
deprecation logging is disabled. You can enable it in the `config/logging.yml`
|
|
file by setting the deprecation log level to `DEBUG`.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
deprecation: DEBUG, deprecation_log_file
|
|
--------------------------------------------------
|
|
|
|
This will create a daily rolling deprecation log file in your log directory.
|
|
Check this file regularly, especially when you intend to upgrade to a new
|
|
major version.
|