Introduction to the Nagios 2.0 Event Broker Interface (NEB)
Of all the features to come out of the 2.0 branch of development for Nagios, the event broker interface is perhaps the most important and most powerful. The purpose of the Event Broker interface is to give 3rd party developers the capacity to develop callback routines which are performed whenever certain events occur during the Nagios monitoring process; however, there are additional possible benefits to this interface which can prove to be powerful but dangerous.

What is the Event Broker?
The Event Broker is an interface in Nagios which links shared code libraries into the Nagios core process at run-time. When an event occurs during the Nagios process, the Event Broker will be ordered to send notification of these events and their relevant data to registered callback procedures which are inside the shared libraries (known as NEB Modules).

What is a NEB Module?
A NEB (Nagios Event Broker) Module is a shared library (usually written in C, but support for C++ is now included). With a common entry-point procedure, it registers callback procedures with the Event Broker and asks to be notified whenever specific events occur. After the point of receiving the notification of an event occurring, the possibilities of what the NEB module can do at that point is endless. Common ideas for the purposes of NEB Modules are:

• Store event data into a database (since db support is removed from Nagios)
• Convert events into other formats (SNMP traps, syslog)

What kind of events can a NEB Module process?
When a Nagios Event Broker module initializes, and technically any other time the Nagios code pointer is within one of it’s procedures, it can register a callback to be processed whenever any of these events occur:

• Related to Process Data (Nagios startup, shutdown, etc)
• Timed Events (When they’re added, executed, or removed)
• Logged Events (When written to log files, or logs rotated)
• System Commands (plugins, notification commands)
• Event Handlers (Host, Service and Global handlers)
• Notifications (When they begin and end)
• Service Checks (When initiated and processed)
• Host Checks (When initiated and processed)
• Comments (When added, deleted or loaded)
• Flapping (When started or stopped for a host/service)
• Downtime (When added or deleted, and started and stopped)
• Status Updates (For the Nagios process, host or service)
• “Adaptive Updates” (When configuration for the process/host/service changes during runtime)
• External Commands (When they have started)
• Aggregated Status Updates (When status dumps start and end)
• Retention Data (When it has been loaded, and when it has been saved)

These events cover pretty much every aspect of the Nagios monitoring system. Whenever an event like the ones described above occurs, the Event Broker gets called into action. The event broker will look to see what callbacks have been registered for the event which has occurred. It will then call every callback in sequential order (based on what order they were added). When a callback has been entered, it is given pointers to the appropriate data structures which holds the information related to the event. For example, if the event type was that of a host status changing, the pointer would point to a nebstruct_host_status_struct, which contains various elements in regards to the status update. In that structure is yet another pointer to the main host structure. In this structure you can see every thing in regards to the host. The configuration, the status information and statistical information. Much more information than what you would find by reading the Nagios log files. This goes for every other event. You can deeply introspect the Nagios daemon.

Because you are linked into the Nagios daemon itself, you have the capacity of doing some major things to evaluate and possibly modify the Nagios monitoring system. Nagios has a habit of keeping all control variables in global scope. (This includes process configuration information, scheduling information, status information, etc). Nagios also has extension functions to add / remove scheduled events from the scheduling queue (more sophisticated event broker modules may ask to call a procedure every 5 seconds, for example). You also have access to all the various output procedures (to print things to the log messages, console, etc). Because there is no data abstraction in place, there is the possibility to change the configuration of Nagios during run-time. Possibilities are:

• Reading configuration from different sources (databases, directories, etc)
• Add/remove/edit host/service/hostgroup/contacts, etc during run-time (removing the need for restarting the daemon)
• Saving information to different targets (databases, directories, flat files, traps, syslogs)

The event broker interface was designed with a specific purpose. To get event data and do with it what you want. However, because of the design, there is the chance of hacking the Nagios daemon to provide further functionality than designed. A lot of these ideas may be present in the 3.0 roadmap; however, with some tinkering, we can achieve these features now.

Join me each week as I post a new blog entry on extending the Nagios daemon with the Event Broker interface. The first blog entry next week will go into the development of a very small event broker to go over the required code to get you up and running.

Taylor Dondich
IT Groundwork Staff Developer

This entry was posted on Tuesday, December 6th, 2005 at 7:33 pm and is filed under GroundWork Source, GroundWork Community. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.