The Nagios enterprise monitoring tool generates a variety of events. The principal events generated are the results...
of monitoring applications, databases, devices, services and hosts. Also generated is performance data and notification events such as outages and downtime. There are a number of ways to integrate and utilize these events. The most advanced and effective event integration mechanism is the Nagios Event Broker (NEB).
NEB uses callback routines that are executed when events occur in the Nagios server. Using NEB you can write broker modules that can process these events. NEB allows you to output and integrate events into a variety of tools including MySQL databases, SNMP traps, syslog messages or use the event data in a variety of other applications and tools.
Nagios Event Broker functions and triggers
NEB uses shared code libraries called modules that are hooked into the Nagios server when it is executed. Each module can register callback procedures that are able to receive and process events. When an event occurs, NEB checks for the presence of a registered callback and, if detected, sends the event to the module. The module receives the event and performs whatever actions are coded into it.
The broker can process a large number of events including, amongst others:
- Nagios process startup and shutdown
- Host and Service checks
- Plug-in commands and notifications
- External commands and event handlers
- Flapping, comments and downtime
You can see a full list of the callbacks in the nebcallbacks.h include file located in the include directory of the Nagios source package.
Enabling Nagios Event Broker
NEB should be enabled by default when you compile Nagios (unless you disable it). If you want to ensure that NEB gets compiled then specify the --enable-neb configure option when configuring Nagios.
# ./configure --enable-neb
Registering modules with Nagios Event Broker
Modules are included into the Nagios configuration by using broker_module configuration options in the nagios.cfg configuration file. For example:
This line would load a module called testmodule.o located in the /usr/local/nagios/bin directory. You can also specify a configuration file for a module like so:
You need to restart Nagios for any newly defined modules to take effect.
Writing modules for Nagios Event Broker
NEB Modules can be written in C or C++. You can see an example of a module in the Nagios package. Located in the module directory off the root of the package is the helloworld module. You can create it by compiling the helloworld.c file.
# gcc -shared -o helloworld.o helloworld.c
You can then add this module to Nagios using the broker_module directive in the nagios.cfg configuration file. Restart Nagios and the module is now loaded.
The Helloworld module is extremely simple. Helloworld logs a message to the default Nagios log file when Nagios is started and stopped and when aggregated status updates start and finish. The message looks like:
 helloworld: An aggregated status update just started.  helloworld: An aggregated status update just finished.
You can review the contents of this module (which includes some basic inline documentation)
Available modules for Nagios Event Broker
There are not a lot of NEB modules available, so far. The most well-known NEB module is the NDO Utilities module. The NDO Utilities module is written by Nagios' developer, Ethan Galstad, and is designed to output events and data from Nagios to standard file or a Unix socket. It also comes with a module, NDO2DB, that can write Nagios data to a MySQL or PostgreSQL database. It should provide (together with the helloworld module) a good introduction to NEB and help you get started on writing your own modules.
You can also find the following NEB modules:
Further help with Nagios Event Broker
There is not a lot of documentation available for NEB thus far. The only major piece of documentation available is about the NEB API. You can also review the Nagios source code relevant to NEB, particularly the include files.
As always the Nagios development and user mailing lists are good starting places for assistance.