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.