Event Configuration How-To

From OpenNMS
Jump to navigation Jump to search

Simpleicons Business pencil-on-a-notes-paper.svg Information in this article has been migrated to the official Admin guide. This effort is tracked under issue NMS-9926.



This How-To is one in a series designed to serve as a reference for getting started with OpenNMS. These documents cover everything necessary to get OpenNMS installed and running in your environment.


Content is available under a Creative Commons Attribution-NonCommercial-ShareAlike2.5 License.


OpenNMS has three main functional areas:

  • Determining Availability of Network Services (discussed in part 3 of this series)
  • Gathering Performance Data via SNMP (discussed in part 4 of this series)
  • Event Management and Notifications

The last area: Events, is the subject of this How-To. Notifications will be handled in the next part.

Events are a staple of any network management system (NMS). In fact, the main function of an NMS can be described as detecting changes within the network, and every change can be thought of as an event.

OpenNMS manages events through a process called eventd. There are two main types of events: those generated internally by the OpenNMS software and those generated via external SNMP traps. Processes can generate events, such as when the discovery process generates a newSuspect event when an interface responds to a ping, and processes can "subscribe" to events, as when the Provisiond process asks to be notified whenever a newSuspect event occurs so it can scan the new address.

When an event is generated, various parameters can be set, such as its description, a log message and a severity. In addition, automatic actions can be launched to send event parameters to an external script. This is controlled through the eventconf.xml file.

OpenNMS also comes with a feature rich Notification system. Particular events can be chosen to cause a notification to be sent, such as a page or e-mail.

The following sections will discuss Events in detail.


The eventconf.xml file is the configuration file that controls how events are handled. Let's look for a moment at the top of that file:

<events xmlns="http://xmlns.opennms.org/xsd/eventconf">

Every file that contains events starts with an <events> tag and ends with an </events> tag.

The eventd process listens on port 5817, so other processes, even those external to OpenNMS, can send events to the system. The <security> tag is there so that these events cannot override the actions defined in the eventconf.xml file. This way, no one with access to the OpenNMS machine could send in an "autoaction" to open, say, a root window on their machine.

Internal Events

Now, after the global settings section of the eventconf.xml file come the events. Each event must be defined in order to be properly treated by the OpenNMS system. Let's look at a common event: nodeLostService:

  <event-label>OpenNMS-defined node event: nodeLostService</event-label>
    &#38lt;p&#38gt;A %service% outage was identified on interface
    %interface%.&#38lt;/p&#38gt; &#38lt;p&#38gt;A new Outage record has been
    created and service level availability calculations will be
    impacted until this outage is resolved.&#38lt;/p&#38gt;
  <logmsg dest='logndisplay'>
          %service% outage identified on interface %interface%.

Every event is bracketed by an <event> tag. Within those tags are various other definitions:

The "Universal Event Identifier" is simply a label to uniquely identify the event. The original intent was that this would be some sort of XML namespace, hence the "http://", but it really is just a label. In version 1.1 and beyond, the "http://" has been removed. Note: for internal OpenNMS events, the UEI is generated directly by the code and cannot be changed without modifying the source.
This is a plain text label for the event, sometimes used in the web user interface.
is the description of the event. You can embed HTML entities should you wish to format the description more fully. Note that there are replacement tokens such as %interface% that you can place in the event description and log message (which will be described later in this document).
Is a short description or summary of the event. The "dest" attribute can take on a number of values:
Both log the event in the database and display it in the Web UI.
Log the event in the database, but do not display it.
Neither log the event in the database or display it.
Do not log the event in the database, but still send it to OpenNMS daemons that are listening for this type of event (e.g.: this can be used to generate notifications). Note that the eventd and alarmd don't process this type of events.
This only applies to traps coming in via trapd. This will cause trapd to discard the trap without creating an event. Other OpenNMS daemons that are listening for this type of event will not receive this event. This feature was first available in OpenNMS 1.3.0.
This indicates the severity of the event. See the section below for a description of each severity.
This is a set of instructions for the NMS operator when the event occurs.
This can be text to be displayed when the mouse is placed over the event in the event browser of the Web UI.
The text following this tag must be the complete path to an executable program. The program will be executed every time the event occurs.

Note that each tag must be closed with its corresponding "/" tag.


When setting severities for events, I often think back to a scene from the movie Spinal Tap. This movie is a "documentary" about an aging hard rock band. In one scene the interviewer is asking a band member to what he attributes the band's popularity. He points to the amplifiers and says "while most amplifiers go to 10, ours go to 11". The interviewer asks why not make them go to 10, but just make 10 louder, to which the band member replies "but ours go to 11".

I have seen this when people set out to set severities for the events in their NMS. Events are either "Critical" (something's wrong with my network!) or "Normal". The severities between the two tend to be ignored. Unfortunately, it makes it really hard to highlight really important events when everything is either green or red. So rather than put everything "at 11", I suggest setting normal network outages as Minor or Major (but treat them just the same as you normally would), and reserving Critical for those events that really matter.

Another way to look at this is to assign actions to severities. Thus a "Critical" event means you wake up the president of your company on Christmas morning and ruin his holiday. So if Helmut's backup ISDN circuit goes down, it is doubtful you would want the severity to be Critical. However, if the entire network backbone is down, it might warrant that phone call.

The following is a list of severities that come with OpenNMS, and my personal description of what they mean. Currently, the default events in OpenNMS don't exactly conform to this list, but they will in the future:

Critical (dark red) 
This event means numerous devices on the network are affected by the event. Everyone who can should stop what they are doing and focus on fixing the problem.
Major (light red) 
A device is completely down or in danger of going down. Attention needs to be paid to this problem immediately.
Minor (orange) 
A part of a device (a service, and interface, a power supply, etc.) has stopped functioning. The device needs attention.
Warning (yellow) 
An event has occurred that may require action. This severity can also be used to indicate a condition that should be noted (logged) but does not require direct action.
Normal (green) 
Informational message. No action required.
Cleared (light grey) 
This event indicates that a prior error condition has been corrected and service is restored.
Indeterminate (yellow-green) 
The severity of the event cannot be determined.

Replacement Tokens

Various tokens can be included in the description, log message, operator instruction and automatic actions for each event. These tokens will be replaced by values from the current event when the text for the event is constructed. Not all events will have values for all tokens, and some refer to SNMP traps, which will be discussed in the next section.

The event's ID
The Universal Event Identifier for the event.
The source of the event (what process).
The time of the event.
The distributed poller that the event was received on (see also Dpname).
The node ID of the device that caused the event.
Returns the node label for the node given in %nodeid% if available.
The interface associated with the event.
Does a reverse lookup on the %interface% and returns its name if available.
The service associated with the event.
The severity of the event.
The host of the SNMP agent that generated the event.
The SNMP Enterprise OID for the event.
The decoded (human-readable) SNMP Enterprise OID for the event (?).
The interface' SNMP ifAlias.
The Generic trap number for the event.
The Specific trap number for the event.
The community string for the trap.
The SNMP version of the trap.
The SNMP information associated with the event.
The operator instructions for the event.
The mouse over text for the event.

There is also a family of parm tokens that will be discussed later.

You can edit $OPENNMS_HOME/etc/log4j2.xml (log4j.properties prior OpenNMS 14) and set the logging level for the eventd to DEBUG. Then check the eventd.log and you will see the parameters and their values for each incoming event.

The parm Replacement Token

Some events, especially SNMP traps, have additional information sent with them called "variable bindings" or "varbinds" for short. They can be accessed using the parm replacement token. Each parameter consists of a name and a value.

Will return a space-separated list of all parameter values in the form parmName1="parmValue1" parmName2="parmValue2" etc.
Will return a space-separated list of all parameter values associated with the event.
Will return a space-separated list of all parameter names associated with the event.
Will return the value of the parameter named <name> if it exists.
Will return the total number of parameters.
Will return the value of parameter number <num>.
Will return the name of parameter number <num>.

The structure of the eventconf.xml file

As mentioned above, the eventconf.xml file controls the definition of both internal and external events in OpenNMS. The order in which the events are listed is very important as it is possible to have numerous event definitions for a given event if you start to filter on variable bindings.

This has caused the file to grow very large over the years. In 1.0.2, eventconf.xml was over 3.1 MB of text. In order to make this file easier to manage, a new tag was introduced in 1.1.0 called <event-file>. This allows files to be "included" as part of eventconf.xml. The new file now looks like:


The included files must start with a <events> tag and end with an </events> tag. In between will be <event> definitions just like in the original eventconf.xml file.

All of the events have been broken out by vendor. When OpenNMS starts, each file will be loaded in order, so again the order in which the files are listed is important. There are also still some events in eventconf.xml. These will be loaded before any included files, and best practice states to only list the internal OpenNMS events in that file directly.

At the very bottom of the file is <event-file>/opt/OpenNMS/etc/events/default.events.xml</event-file>. This contains the generic default events and should always be listed last.

A few tips:

  • Since the system has to scan through all of the events to find a match, it is best to remove event files you are not using.
  • If you customize a file, such as Cisco events, you may want to simply copy it to "my.Cisco.events.xml" and list your file first. This way you will have less work should the default file be changed in a future release.

Activate changes in event configurations

After changing the event configurations use

   $OPENNMS_HOME/bin/send-event.pl uei.opennms.org/internal/reloadDaemonConfig -p 'daemonName Eventd'

For versions 1.8 through 1.12.6 use

   $OPENNMS_HOME/bin/send-event.pl uei.opennms.org/internal/eventsConfigChange

Versions 1.6.9 or earlier use

   $OPENNMS_HOME/bin/send-event.pl  uei.opennms.org/internal/reloadEventConfig. 

to inform opennms that the event configuration has been changed and needs to be reloaded. See also Configuration_File_Index for more details about reloading changes.

Test your event configuration

There are two very useful tools to test event configurations:




Start the scripts with the '--help' parameter to get an explanation how to use them.

The Database

Each event that occurs in OpenNMS is written to the database in the events table. To see them, simply access the database with "psql -U opennms opennms" and then browse the events with "SELECT * FROM events;".

One great troubleshooting tool is to look at the eventparms that get sent with the event. For example:

SELECT eventparms FROM events WHERE eventid=204;

(1 row)

Here are all of the parameters sent during a highThresholdRearmed event, and they can be used in event filters if needed.

Finally, it is worth noting that the database can get very full, and it may be necessary to delete events from the events table that are no longer needed. If you know SQL, this is pretty simple, but since OpenNMS events are sometimes referenced in the outages table and in notifications, you may not want to delete those (the outage table is required for availability calculation). Here is a sample SQL to delete non-referenced events:

svclosteventid FROM
outages) AND eventid NOT IN (SELECT
svcregainedeventid FROM outages WHERE svcregainedeventid IS NOT NULL);


Edit $OPENNMS_HOME/etc/log4j2.xml (log4j.properties prior OpenNMS 14) and set the logging level for the eventd to DEBUG. Then check the eventd.log and you will see the parameters and their values for each incoming event like the following lines (date and time cut off for readability):

353 DEBUG [Event TCP Receiver[5817][]] TcpStreamHandler: Event record converted
353 DEBUG [Event TCP Receiver[5817][]] TcpStreamHandler: handling event, uei = uei.opennms.org/internal/rtc/subscribe
404 DEBUG [Event TCP Server[5817]] TcpServer: New connection accepted from
404 DEBUG [Event TCP Receiver[5817][]] RunnableConsumerThreadPool$SizingFifoQueue: adjust: started fiber EventHandlerPool-fiber0 ratio = 1.0, alive = 0
404 DEBUG [Event TCP Receiver[5817][]] TcpStreamHandler: stopping record handler
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl: Event {
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:   uuid  = <not-set>
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:   uei   = uei.opennms.org/internal/rtc/subscribe
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:   src   = RTCPostSubscriber
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:   iface = null
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:   time  = Monday, February 22, 2010 4:26:29 PM GMT
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:   parms {
404 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:     (url, http://localhost:8980/opennms/rtc/post/Infrastructure+CentralSide)
405 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:     (user, rtc)
405 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:     (passwd, rtc)
405 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:     (catlabel, Infrastructure CentralSide)
405 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl:   }
405 DEBUG [EventHandlerPool-fiber0] DefaultEventHandlerImpl: }
405 DEBUG [EventHandlerPool-fiber0] EventConfData: Match found using key: EventKey


The event management system in OpenNMS is pretty straightforward once it is understood. The ability to filter and specify severity based on varbind values makes OpenNMS into a highly capable and customizable SNMP trap manager.