Configuration
=============

Since Crate Data has sensible defaults, there is no configuration
needed at all for basic operation.

Crate Data is mainly configured via a configuration file, which is
located at ``config/crate.yml``. The vanilla configuration file
distributed with the package has all available settings as comments
in it along with the according default value.

The location of the config file can be specified upon startup like
this::

  sh$ ./bin/crate -Des.config=/path/to/config.yml

Any option can be configured either by the config file or as system
property. If using system properties the required prefix 'es.' will be
ignored.

For example, configuring the cluster name by using system properties
will work this way::

 sh$ ./bin/crate -Des.cluster.name=cluster

This is exactly the same as setting the cluster name in the config
file::

 cluster.name = cluster

Settings will get applied in the following order where the latter one
will overwrite the prior one:

 1. internal defaults
 2. system properties
 3. options from config file


Hosts
-----

Per default Crate Data will bind itself to the ``0.0.0.0`` address.
If you want to change this behaviour, adjust the ``network.host`` setting.

This setting sets both the ``network.bind_host`` and ``network.publish_host`` values.

``network.bind_host`` is ``0.0.0.0`` by default.
This setting determines to which address crate should bind itself to.
To only bind to localhost, set it to any local address or ``_local_``.

The ``network.publish_host`` value is used
by the crate node to publish its own address to the rest of the cluster.
Per default it is the first non local address.

To explicitly bind crate to a specific interface use the interface name between underscores.
For example ``_eth0_``.

This resolves to the ip address of this interface. With ``_eth0:ipv{4,6}_`` you explicitly listen on
 an ipv6 or ipv4 address.

Ports
-----

Per default Crate Data will listen to the first free port in the range of ``4200-4300`` for HTTP Requests.
If there is no crate process already running on that machine, it will usually be ``4200``.

You can change the HTTP port range by adjusting the ``http.port`` setting.

For internal cluster communication crate uses TCP and listens on the first free port
in the range of ``4300-4400``.

You can change the TCP port range by adjusting the ``transport.tcp.port`` setting.

Logging
-------

Crate Data comes, out of the box, with Log4j_ 1.2.x. It tries to simplify log4j
configuration by using YAML to configure it. The logging configuration
file is at ``config/logging.yml``.

The yaml file is used to prepare a set of properties used for logging configuration
using the `PropertyConfigurator`_ but without the tediously repeating ``log4j`` prefix.
Here is a small example of a working logging configuration::

    rootLogger: INFO, console

    logger:
      # log action execution errors for easier debugging
      action: DEBUG


    appender:
      console:
        type: console
        layout:
          type: consolePattern
          conversionPattern: "[%d{ISO8601}][%-5p][%-25c] %m%n"

And here is a snippet of the generated properties ready for use with log4j. You get the point.
::

   log4j.rootLogger=INFO, console

   log4j.logger.action=DEBUG

   log4j.appender.console=org.elasticsearch.common.logging.log4j.ConsoleAppender
   log4j.appender.console.layout=org.apache.log4j.PatternLayout
   log4j.appender.console.layout.conversionPattern=[%d{ISO8601}][%-5p][%-25c] %m%n

   ...


.. _YAML: http://en.wikipedia.org/wiki/YAML

.. _Log4j: https://logging.apache.org/log4j/1.2/

.. _PropertyConfigurator: https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PropertyConfigurator.html
