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

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 identify the poller.

<instance>42</instance>

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 non-thread-safe use of time-related functions.

<log_timestamp>1</log_timestamp>

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 logger definition.

<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 input stream definition.

<input>
  <type>tcp</type>
  <port>5668</port>
  <protocol>bbdo</protocol>
</input>

output

Start an output stream definition.

<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 temporary stream definition.

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

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.

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 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. The filtering is base on category (neb, storage, correlation).

<filters>
  <category>
    neb
  </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 the SQL module will commit its current transaction, the compression module will compress data without waiting for a full buffer, …

<read_timeout>
  10
</read_timeout>

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