#############
Configuration
#############

The following chapters define how to configure Centreon Broker directly
with plain-text files. This is not however the recommended way to configure
software if you're using the Centreon Web interface. More preferably,
refer to Centreon Web's documentation.

******
Basics
******

Centreon Broker’s configuration is based on *XML*. This format allows
module configuration within the main configuration file without
interfering with core options. The core options are listed in the table
below. They must be specified right under the root node (whose name is
of no importance).

.. note::
   If you use configuration files generated by Centreon, you might
   find that some configuration values are within a markup called
   *CDATA*. This syntax is used to prevent security issues.

Please remember that basically, Centreon Broker is an I/O multiplexer.
This means that it receives input events and forward them to some
output streams. Centreon Broker does not directly know which events are
handled. This is the job of the :ref:`modules <user_modules>`.

.. _config_daemon:

The daemon
==========

The Daemon, called *cbd*, is the exact result of the description above.
A standalone program that multiplex events. In a monitoring setup,
having only daemons would be useless, as none of them generate
monitoring events. They can however be configured to perform some
specific tasks. For example a daemon can handle all RRD graphs creation,
another can insert events in database, ...

Daemon init script
******************

The daemon can be started by the init script cbd. By default
(*/etc/init.d/cbd*).

This startup script use a configuration file master.run (by default
*/etc/centreon-broker/master.run*)

This file contains the list of cbd daemons to start. This list must correspond
to the list configured in Centreon Web.

The format of this file is::

  daemon_name	config_file	start	reload

Examples::

  cbd		cbd-broker.xml	y	y
  cbd-rrd	cbd-rrd.xml	y	n

The **daemon_name** is the name for distinct daemon each other.

The **config_file** is the configuration file for start the daemon.

If **start** is set to y, the daemon will be start and stop with init script.

If **reload** is set to y, the daemon will be reload with init script.

The module
==========

The Module is called *cbmod* and is fully compatible with Centreon
Engine, Nagios and Icinga. It is *cbmod*'s job to generate monitoring
information that will be processed further. Obviously, the module
configuration shall contain at least one *output stream*, as explained
below, for events to be treated.

Options
=======

The following options must be placed directly under the root of the
XML file.

============================ ======================================================== =============================================
Option                       Description                                              Example
============================ ======================================================== =============================================
module_directory             Where Centreon Broker’s modules are stored.              ::

                                                                                        <module_directory>
                                                                                          /var/lib/centreon/broker/
                                                                                        </module_directory>
module                       If you do not want to load all modules of a
                             *module_directory* you can use this directive to load    ::
                             only one module. This directive can be repeated as much
                             as wanted.                                                 <module>
                                                                                          /usr/lib/centreon-broker/10-neb.so
                                                                                        </module>
                                                                                        <module>
                                                                                          /usr/lib/centreon-broker/50-tcp.so
                                                                                        </module>
                                                                                        <module>
                                                                                          /usr/lib/centreon-broker/80-bbdo.so
                                                                                        </module>
instance                     Only useful if Centreon Broker is loaded as              ::
                             a module of a monitoring engine (Centreon
                             Engine, Nagios ...). Unique number that                    <instance>42</instance>
                             identify the poller.
instance_name                An optional name used to identify a poller (see          ::
                             *instance* above).
                                                                                        <instance_name>MyPoller</instance_name>
include                      Include another Centreon Broker configuration file that
                             must respect the same syntax.                            ::

                                                                                        <include>
                                                                                          /etc/centreon-broker/common.xml
                                                                                        </include>
cache_directory              Cache directory of Centreon Broker.                      ::

                                                                                        <cache_directory>
                                                                                          /var/lib/centreon-broker/cache
                                                                                        </cache_directory>
event_queue_max_size         Maximum number of events that can be stored in memory.   ::
                             Exceeding this limit will launch the **temporary**.
                                                                                        <event_queue_max_size>
                                                                                          1000000
                                                                                        </event_queue_max_size>
flush_logs                   Enable or not log flushing. Flushing (aka syncing) tends
                             to slow the software down. Default is disabled and we    ::
                             recommend to only enable flushing in case of abnormal
                             process failures.                                          <flush_logs>0</flush_logs>
log_thread_id                Enable or not thread ID logging. This option will        ::
                             affect all loggers. Default is 0 (disabled).
                                                                                        <log_thread_id>1</log_thread_id>
log_timestamp                Enable or not timestamp logging. This option will
                             affect all loggers. Default is 1 (enabled) except when   ::
                             Broker is loaded as a monitoring engine module to
                             prevent incompatibilities that might arise with            <log_timestamp>1</log_timestamp>
                             non-thread-safe use of time-related functions.
log_human_readable_timestamp Enable a human readable timestamp in the logs. This      ::
                             option affect all loggers. If this option is set to
                             true, it implies log_timestamp = true.                     <log_human_readable_timestamp>1</log_human_readable_timestamp>

logger                       Start a :ref:`logger definition
                             <user_configuration_logger>`.                            ::

                                                                                        <logger>
                                                                                          <type>file</type>
                                                                                          <name>/var/log/centreon/broker.log</name>
                                                                                          <config>1</config>
                                                                                          <debug>0</debug>
                                                                                          <error>1</error>
                                                                                          <info>1</info>
                                                                                          <level>medium</level>
                                                                                        </logger>
input                        Start an :ref:`input stream definition
                             <user_configuration_input_output_temporary>`.            ::

                                                                                        <input>
                                                                                          <type>tcp</type>
                                                                                          <port>5668</port>
                                                                                          <protocol>bbdo</protocol>
                                                                                        </input>
output                       Start an :ref:`output stream definition
                             <user_configuration_input_output_temporary>`.            ::

                                                                                        <output>
                                                                                          <type>sql</type>
                                                                                          <db_type>mysql</db_type>
                                                                                          <db_host>localhost</db_host>
                                                                                          <db_port>3306</db_port>
                                                                                          <db_user>centreon</db_user>
                                                                                          <db_password>noertnec</db_password>
                                                                                          <db_name>centreon_storage</db_name>
                                                                                        </output>
temporary                    Start an :ref:`temporary stream definition
                             <user_configuration_input_output_temporary>`.            ::

                                                                                        <temporary>
                                                                                          <type>file</type>
                                                                                          <path>/tmp/brokertemp</path>
                                                                                          <protocol>bbdo</protocol>
                                                                                        </temporary>
============================ ======================================================== =============================================

.. _user_configuration_logger:

******
Logger
******

A logger is an object that receives log messages generated by Centreon
Broker.

Here’s an example of a full logger definition placed right under the
root XML node::

  <logger>
    <type>file</type>
    <config>1</config>
    <debug>0</debug>
    <error>1</error>
    <info>1</info>
    <level>high</level>
    <name>/var/log/centreon/broker/cbd.log</name>
  </logger>

Options
=======

The list of available options for use within a logger block are defined
in the table below:

====== ==============================================================
Option Description
====== ==============================================================
type   One of file, standard or syslog. File to write logs to a file,
       standard to write on the process’ stdout or stderr and syslog
       to write on syslog.
config Enable or disable logging of config messages.
debug  Enable or disable logging of debug messages.
error  Enable or disable logging of error messages.
info   Enable or disable logging of informational messages.
level  Log verbosity. Range from 0 (no message) to 3 (highly detailed
       messages).
name   For file loggers, path to the log file. For standard loggers,
       one of stdout or stderr.
====== ==============================================================

.. _user_configuration_input_output_temporary:

****************************
Input,  Output and Temporary
****************************

Streams and Layers
==================

Input and output streams are the two end of Centreon Broker's core : the
*multiplexer*. This *multiplexer* receives monitoring events from input
streams and forward them to output streams. The exact definition of what
an input or output stream is, is handled by :ref:`modules <user_modules>`.
Centreon Broker only directly knows that input streams can be **read from**
whereas output streams can be **written to** and that multiple protocols
can be stacked together to create input streams.

Temporary object alows to dump event into a stream when the event queue
limit is reached.

Protocols
=========

To create input or output streams, user specifies which protocols a
stream uses. To properly stack protocols one upon another, Centreon
Broker uses a layer system, very similar to the OSI layers. Layers
ranges from 1 to 7, 1 being a raw protocol and 7 an event-generator
layer. Each stream definition must have at least one protocol which
handles the first layer and one that handles the last one (ie.
intermediate layers are not required but can provide additional
features). Also one layer can only be handled by one protocol maximum.

Centreon recommands to use the *BBDO* protocol by default. This
optimized protocol uses very low resources and provide feature
negotiation which usually enables encryption and compression without
any configuration.

Common Options
==============

This table lists all options that can be specified on every endpoint.
Note that some of them might be useless on some endpoint types.

================== =============================== ======================
Option             Description                     Example
================== =============================== ======================
buffering_timeout  Number of seconds to wait       ::
                   before launching the endpoint
                   *failover*.                       <buffering_timeout>
                                                       10
                                                     </buffering_timeout>
filters (category) This parameter is used by       ::
                   endpoint to skip usless events
                   for a specific endpoint.          <filters>
                   The filtering is base on            <category>
                   category (neb, storage,               neb
                   correlation).                       </category>
                                                       <category>
                                                         storage
                                                       </storage>
                                                     </filters>
name               An optional name, mostly used   ::
                   to identify a *failover*.
                                                     <name>
                                                       MyEndpoint
                                                     </name>
read_timeout       This parameter is used by some
                   output endpoints to take some   ::
                   action after an inactivity of
                   specified seconds. For example    <read_timeout>
                   the *SQL* module will commit        10
                   its current transaction, the      </read_timeout>
                   *compression* module will
                   compress data without waiting
                   for a full buffer, ...
retry_interval     Number of seconds to wait       ::
                   between two reconnections to
                   the same endpoint.                <retry_interval>
                                                       60
                                                     </retry_interval>
type               Endpoint type, as specified
                   by modules.
================== =============================== ======================

Configuration File
==================

Input objects are defined using an input block. Output objects are
defined using an output block. Either input or output blocks have
**one mandatory tag** called ``type`` used to build the protocol stack
associated with this endpoint.

Here’s an example of a input/output definition::

  <?xml version="1.0" encoding="UTF-8" ?>
    <broker>
      <input>
        <type>tcp</type>
        ...
      </input>
      <output>
        <type>sql</type>
        ...
      </output>
    </broker>

Specific configuration entries are specified in the
:ref:`modules <user_modules>` chapter.

********
Failover
********

The failover feature is a key concept in Centreon Broker. This feature
allows you to redirect event stream from a failed output to another
output. One common use case is when a database becomes unavailable
(network outage, DB server shutdown, ...) events are temporarily stored
in a file. When the server is back online, data is read from the file
and stored back in the database.

Centreon Broker’s failover feature is a generalization of this process.
You can use any output as a failover to another. Of course the data
replaying process is only available if the protocol supports it.

All endpoints can have a ``<name>`` tag that is used by the ``<failover>`` tag
to identify which endpoint if the failover of another.

Here’s an example of a failover definition placed right under to root
XML node::

  <output>
    <name>MyFile</name>
    <type>file</type>
    <protocol>bbdo</protocol>
  </output>
  <output>
    <name>MyDB</name>
    <type>sql</type>
    ...
    <failover>MyFile</failover>
  </output>

In this example, the MyFile endpoint will only be activated if the
output to MyDB fails.
