Windows Event Log Traps

From OpenNMS
Jump to: navigation, search


Windows can be configured to send SNMP traps when certain messages appear in the Windows Event Log. This article will walk the reader through the process of configuring these traps to be sent and up to the point of configuring OpenNMS to turn them into events.

Tools on the Windows side

There is a pair of utilities that ship with Windows that are used to define and export the mappings and to import the exported mappings and configure the actual sending of traps:

GUI tool for defining mappings of event log messages to SNMP traps
CLI tool for importing the definitions created by evntwin and configuring the actual sending of traps

Documentation about these tools is almost nonexistent on Microsoft's sites, but they seem to be supported.

Tools on the OpenNMS side

Normally, when you are creating these traps on a Windows box, the traps won't be defined in an existing MIB, meaning you need to manually define them. When you first generate an undefined trap, OpenNMS will log an "Enterprise Default" trap event against the node. These "Enterprise Default" traps provide all the information you need to generate a definition.

While you can create a new events xml file, you might find it easier to add these definitions to an existing file. If you do go down the route of creating your own file, remember that it needs to appear at the bottom of the eventconf.xml file, but ABOVE the line - otherwise you will only ever get "Enterprise Default" traps displayed, and not your own customized ones!

Configuring the Windows side

Defining and exporting mappings with evntwin

Start the evntwin utility from the Start -> Run menu or from a DOS prompt. In the initial window, click the radio button for Custom under Configuration type. Then click the Edit >> button to expand the list of event sources. The window will now look like this:

Evntwin Edit Mode Starting.png

Browse the list of event sources, or use the Find button, to track down the event source that you're interested in. It helps at this stage to have the Windows Event Viewer open and displaying details on the event log entry for which you want to configure trap mappings. The Event ID will line up between the Event Viewer and evntwin. As an example, we will configure a trap mapping for an event in the Security log whose source is Security and whose event ID is 520; this event is a success audit event informing us that the system time was changed. Here this event is highlighted in the evntwin utility:

Evntwin Edit Mode Event Selected.png

Click the Add... button and a dialog pops up identifying the enterprise OID and trap specific ID of the mapped trap. Here you can tweak the conditions under which traps should be sent if you want. This dialog also shows the message body as it would appear in the Event Log, only with the dynamic information tokenized in the form of %1, %2, and so on. These tokens will be helpful in identifying the information contained in the varbinds of the resulting trap:

Evntwin Trap Properties Dialog.png

Note that the value in the enterprise OID text field will very likely overflow the width of the field, so you'll need to use Ctrl+A or right-click and Select All to get the whole thing onto the clipboard. The OID will be of the form:

The part will be familiar to some people as Microsoft's private enterprise MIB branch. The 1 after this prefix is for software, and the 13 doesn't seem to be defined anywhere, but we'll presume it to be the root OID where Event Log mapped trap OIDs live. The remainder of this OID is an encoding of the Event Log source name; the 8 encodes the length in octets, and the following eight octets are the ASCII (or presumably Unicode) character codes for the characters comprising the source name. See [1] for a quick reference to ASCII character codes.

Note on Windows 2000
On Windows 2000 without Service Pack, the enterprise OIDs that evntwin generates are not properly nested under the Microsoft private enterprise MIB branch. Instead they use a truncated prefix of 1.3. plus the encoded source name. These OIDs are not canonically valid as SNMP object identifiers, but OpenNMS should handle them. See KB article 296672 at Microsoft for a description and workaround.

Click OK and your first mapping will appear in the main evntwin window. Once you're done adding mappings, click the Apply button in the main evntwin window. Then highlight all the mappings (this is important!) and click the Export... button. Choose a location and filename to save the event-to-trap mapping definitions:

Evntwin Exporting Mappings.png

The exported event-to-trap mappings will be a text file whose contents look like this:

#pragma add Security "Security" 520 1 0

This would appear to map as follows:

#pragma add <LogName> "<SourceName>" <EventID> <EventCount> <TimeInterval>

Importing exported definitions with evntcmd

Now open an elevated command prompt and change to the directory where you exported the event-to-trap mappings. Run the evntcmd utility, giving it the name of your exported mappings file as its only argument. The output should look like this:

C:\Documents and Settings\admin\My Documents>evntcmd events.cnf
Microsoft (R) Event To Trap Translator; Configuration Tool v2.00
Copyright (c) Microsoft Corporation 1998.  All rights reserved.

[Wrn05] Command line parsed successfully.
[Wrn05] Configuration file 'events.cnf' parsed successfully.
[Wrn05] Registry connected to 'localhost'.
[Wrn05] Commands processed successfully.
Note on distributed use of evntcmd

It appears it's possible to give this utility -s sysname on its command line to have it connect to remote systems and configure them in the same manner, but I have not tested this.

Set the trap sink

At this point, you're done configuring the Windows side, unless you haven't yet configured the SNMP service to send traps to your OpenNMS server. This is done from the Services MMC snap-in, SNMP service properties, Traps tab.

Generate a test trap

For this example, we can simply change the system time to generate a trap. We'll switch over to the OpenNMS side to continue.

Configuring the OpenNMS side

Now that we've generated a test trap by changing the system time, we should see a Microsoft "enterprise default" event of indeterminate severity in the OpenNMS event browser:

Evntwin Generated Trap Default Time Changed.png

Remainder left as an exercise to the reader

There is plenty of existing documentation on creating event definitions for OpenNMS. All the information needed to build a definition for this trap is available by looking at the enterprise-default event depicted above.

Common Issues and Answers

We identify any issues that arises when setting up a trap using evntwin

Negative Trap Specific ID

There are times, when the specific trap ID given by evntwin is not the same as the trap that OpenNMS sees. This is not a bug in OpenNMS, as this is the same ID that Windows sends out. It's difficult to say why, at this point, but it seems to only happen when the specific trap ID is greater than 2^31 (2147483648).

If the trap ID is greater than 2^31, then there is a simple formula you can use. Just subtract 2^32 from the specific trap ID.

PYTHON (assuming specific ID = 3221234964, the received ID = -1073732332):

>>> 32221234964-(2**32)

JAVA (assuming specific ID = 3221234964, the received ID = -1073732332):

System.out.printf("%f\n",3221234964L-(Math.pow(2, 32)));

How does Windows auto-create the OID? I want to map all traps from a certain application

Windows uses the Application Name as the OID. All OID's for Microsoft, begins with After that, 13.1 shows the evntwin definition traps (i.e.

After that, the application definition begins. The next digit defines the number of characters in the application name. So, if we are talking about the application (source) MSExchangeIS, the number of characters would be 12 for XX. Thus we would have:

After that, Microsoft then spells out the Application Name using ASCII character numbers (
                         M  S  E  x  c   h  a   n   g   e   I  S