Archived - Configuring Event Forwarding

To install Event Forwarding

Event Forwarding integration architecture

Event Forwarding configuration file

Running ForkEvent

To run Event Forwarding

 

Event Forwarding allows Entuity to forward events to third party software. You can determine which events to forward, based on one or more of the following:

• event type.
• event source.
• event destination. Event Forwarding allows forwarding of events to more than third party software, and more than one instance of that software.

The details that Entuity forwards for each event are configurable, and may include the event's source, impact details and priority level.

Event Forwarding is a general application that is suitable fo ruse with a number of different products.

 

To install Event Forwarding:

Event Forwarding functionality is included with the standard Entuity installation, and is installed (but not activated) on the Entuity server. Event Forwarding requires Entuity and the receiving third party software to be installed and running, with permitted communication between the two.

ForkEvent is the main Event Forwarding executable, and is installed to:

entuity_home/integ/ForkEvent/

forkevent.cfg is the event forwarding configuration file, installed to:

entuity_home/etc/

 

Event Forwarding integration architecture

1. Entuity collects event data.
2. ForkEvent is configured to run in either Fork or Pipe mode. Configuration is through a combination of command line and configuration file parameters.
3. When Entuity recognizes an applicable event:
   • when Entuity recognizes an applicable event and ForkEvent is running in Fork mode, ForkEvent starts a Fork process. This process sends the data to the third party software, and then terminates. Each event results in a new Fork process.
   • when Entuity recognizes an applicable event and ForkEvent is running in Pipe mode, ForkEvent sends the event data to the stdin of the Pipe process. The Pipe process starts runningwhen ForkEvent is started and continues until ForkEvent is stopped.
4. Both Fork mode and Pipe mode forward event data to the integrated software. This software must be configured to receive the Entuity event data.
5. The integrated software can now handle the event data and, for example, display it through a console.

 

Event Forwarding configuration file

The Event Forwarding configuration file, forkevent.cfg, contains details used to:

• access the Entuity database.
• determine whether the Event Forwarding uses the Fork or Pipe processes.
• determine the format and order in which that event data is passed to the integrated product.

There are a number of sections. Each starts with its section name, enclosed within square brackets, e.g. [connection] and [data]. All variable definitions are held within sections. These sections can be divided into three types:

• Connection section contains details required to access the Entuity database.
• Process section determines whether the Fork or Pipe process is used, also which parameters are passed. You can specify one or more process sections, which one is used is passed as an argument when running ForkEvent.
• Data section details the events passed to the Pipe process.

 

Connection section

This section details the information required to access Entuity, so as to collect event data. The following is an example section:

[connection]
username=admin
view=All Objects
extendedEvents=0

where:

• [connection] is the name of the section that contains the details required to access Entuity event data.
• username is the Entuity login name.
• view is the Entuity View from which events are collected. Only when an event occurs on a device within the defined View is it forwarded by ForkEvent.
• extendedEvents sets the maximum number of characters that forkevent forwards for the event description. Event descriptions greater than this setting are truncated. When set to:
  
  • 0 (default), forwards event descriptions to a maximum of 127 characters.
  • 1, forwards event descriptions to a maximum of 4095 characters. Extended event descriptions are not currently stored in the Entuity database.

 

Process section

The process sections define the following:

• which ForkEvent process (Fork or Pipe) is used.
• the arguments passed to the process.

A configuration file can have more than one process definition, although only one is used at any one time. This is passed as an argument when ForkEvent is run.

The following is an example section:

[pipe_nt]
start=H:\master\src\integration\bins\ForkEvent\ForkEventNT
args=pipe ${connection.username}
EmptyVariable=MISSING_VALUE
type=pipe
directory=H:\master\src\integration\bins\ForkEvent
loglevel=all

where:

• [pipe_nt] is the section name. This is passed as a parameter with the ForkEvent
  command.
• start runs the specified executable. When type is:
  
  • fork, start runs when ForkEvent receives an event.
  • pipe, start runs as soon as ForkEvent runs, creating the Pipe process.
    As well as running Pipe and Fork directly, they can be run through a script or executable.
    For example a shell script that calls the ForkEvent process, passes arguments, or any
    other legitimate script instruction.
• type is the type of process, i.e fork or pipe.

Note, only type and start are mandatory parameters.

• args allow you to pass command line arguments with the Pipe and Fork processes. You can pass values taken from the:
  
  • Event data, e.g. ${event.PAPIID}.
  • Configuration file itself, e.g. ${connection.username}, where connection is the section name and username the variable name.
• EmptyVariable is used to enter a value in an event variable passed from Entuity that does not contain any data, i.e. to make it easier to identify in the integrated package. By default EMPTY_VARIABLE is entered, using EmptyVariable you can replace that with one of your choice, e.g. MISSING_VALUE.
• directory is the directory from which the process is run and log files are written to.
• loglevel is the level of logging information recorded, i.e. errors, warning, info, debug
  and all.

Running a Script

These example section illustrate the format for invoking a script that handles the fork process. The structure for Linux (fork_unix) and Windows (fork_win) is similar:

[fork_unix]
start=/bin/sh
args=/Entuity/scripts/evchild.sh
= ${event.PAPIId}
= ${event.PAPIEventStr}
= ${event.PAPIEventGroup}
= ${event.PAPIDescr}
# Can include a few words from your sponsor if you like
= Entuity Events
= ${event.PAPIImpact}
= ${event.PAPIImpactDescr}
= ${event.PAPIDetails}

[fork_win]
type=fork
directory=${logdir}
start=c:\Cygwin\bin\bash
args=c:\scripts\evchild.bash
= ${event.PAPIId}
= ${event.PAPIEventStr}
= ${event.PAPIEventGroup}
= ${event.PAPIDescr}
# Can include a few words from your sponsor if you like
= Entuity Events
= ${event.PAPIImpact}
= ${event.PAPIImpactDescr}
= ${event.PAPIDetails}

where:

• start sets the executable that executes the script.
• args includes the:
  • script file, e.g. evchild.bash
  • event data, e.g. ${event.PAPIID}.

Note, in Windows, the full path must be specified for both start and args.

 

Data section

This section holds the associations between labels and Entuity event variables. These labels can be used by the Pipe process to identify and manipulate event data. There must only be one data section in an Event Forward configuration file.

The data section is only used with the Pipe process. The Pipe process runs continually and it is only through the data section that arguments can be passed for each event. The Fork process is started for each event, and so arguments are passed each time an event occurs.

The following is an example section:

[data]
ID=${event.PAPIID}
EventGroup=${event.PAPIEventGroup}
EventId=${event.PAPIEventId}
EventString=${event.PAPIEventStr}
timeStamp=${event.PAPItimeStamp}
ID1=${event.PAPIObjectID_1}
ID2=${event.PAPIObjectID_2}
ID3=${event.PAPIObjectID_3}
ID4=${event.PAPIObjectID_4}
PRI=${event.PAPISeverity}
Attr=${event.PAPIAttr}
DESCR=${event.PAPIDescr}
Impact=${event.PAPIImpact}
ImpactDescr=${event.PAPIImpactDescr}
DETAILS=${event.PAPIDetails}

where:

• [data] is the mandatory name of the data section.
• ${event.PAPIID} is a numeric value specifying the current instance of the event.
• ${event.PAPIEventGroup} is a numeric value specifying the event's group.
• ${event.PAPIEventID} is the event identifier within the context of the event group.

The combination of event group and event ID uniquely identify all Entuity event types.

• ${event.PAPIEventStr} is the description of the event associated with the event identifier.
• ${event.PAPIObjectID_1}, ${event.PAPIObjectID_2} and ${event.PAPIObjectID_3} and ${event.PAPIObjectID_4} are internal values that indicate the origin of the event.
• ${event.PAPItimestamp} is the time the event occurred, represented as UTC (Coordinated Universal Time, i.e. the number of seconds since 1970-01-01 00:00:00 GMT).
• ${event.PAPISeverity} is the internal value of the event severity. The Entuity event severity levels are:
  
  • 2, Information.
  • 4, Minor.
  • 6, Severe.
  • 8, Major.
  • 10, Critical.
• ${event.PAPIDescr} is a textual description of the managed object on which the event occurred, e.g. VLAN, device, module or port.
• ${event.PAPIDetails} is supplemental information on the particular event, e.g. actual values of network statistics which caused a threshold event.
• ${event.PAPIImpactDescr} is entities likely to be affected by the event, e.g. hosts, VLANs and monitored applications.

Each variable name is prefaced by event, which identifies it as a value generated by Entuity.

 

Running ForkEvent

ForkEvent must be run after the Entuity server starts or is restarted. ForkEvent accesses the Entuity database using the specified event forwarding configuration file and the specified process section within it.

When ForkEvent is run, the configuration file and the required process section are passed to it:

1. ForkEvent then uses details in the [connection] section to access the Entuity database.
2. ForkEvent then uses details in the process section to determine whether it is running in fork or pipe mode. When running in pipe mode, ForkEvent starts the Pipe process.
3. When an event occurs, ForkEvent can:
   • send the event data to the stdin of the pipe process.
   • run a new fork process.

When there are a large number of events, Fork mode can cause a significant processing overhead. A more efficient method is using ForkEvent in Pipe mode, which only uses one process.

You can also run more than one ForkEvent process at one time, although they must use different configuration files. If an event occurs when running multiple ForkEvent processes, the event is handled by all the processes.

 

Fork process

When running in Fork mode, each time ForkEvent recognizes an event it will generate a new Fork process. As the process is created, arguments detailing the event will be passed to it. You can pass these arguments through start or args.

 

Pipe process

When running in Pipe mode, each time a ForkEvent recognizes an event it sends the event data to the stdin of the Pipe process. The format and structure of the event data is taken from the [data] section in the configuration file.

The Pipe continues to run until it is explicitly stopped or the Entuity server is stopped. Each time a new event occurs, the same ForkEvent process is used.

In Pipe mode, ForkEvent sends event data in the format:

VariableLabel VariableValue <CR>
BlankLine <CR>

where:

• VariableLabel is the label assigned to the event data in the [data] section, e.g. Descr in Descr=${event.PAPIDescr}.
• VariableValue is the event data value, extracted from the [data] section, e.g. ${event.PAPIDescr} in Descr=${event.PAPIDescr}.
• <CR> is the end of line marker. Each value is passed on its own line.
• BlankLine is automatically sent at the end of the event data to signal the end of that event.

Although the Pipe command requires more time to set up, it provides for a more efficient use of machine resources. I.e., in fork mode each new event generates a new child process, but in pipe mode the existing pipe process is used.

 

Using scripts

You can use scripts when ForkEvent is in both Pipe and Fork mode. For example, the following extract from an event forward configuration file passes three arguments to the script, command.sh:

[pipe_nt]
start=H:\master\src\integration\bins\command.sh
args=pipe ${connection.username} ${event.PAPIImpactDescr}

This is the command.sh script:

#!/bin/sh
FILE=/tmp/com.$$
echo "1="$1>>$FILE
echo "2="$2>>SFILE
echo "3="$3>>$FILE
while read line;do
echo "line:" $line>>$FILE
done

This script takes three arguments and prints them to a file. The $ variables access the sequential attributes passed with, in this integration, event data. These variables have the format $n, where n is the positional attribute. In this example, the output file could be:

1=pipe
2=admin
3=HOST: 00-50-8b-af-39-67

 

To run Event Forwarding:

You can only run ForkEvent when the Entuity server is running. To run ForkEvent, enter:

forkevent ConfigurationFile SectionName

where:

• forkevent is the process command.
• ConfigurationFile is the ForkEvent configuration file, e.g. ForkEvent.cfg.
• SectionName is the section within the ForkEvent configuration file that details the method
  and arguments for forwarding the event data, e.g. fork_nt.

Each time you stop and start the Entuity server, you must run ForkEvent. You can run more than one ForkEvent process at one time, although they must use different configuration files. When running multiple ForkEvent processes and an event occurs, the event details are forwarded by all processes.

 

Automatic ForkEvent startup and shutdown

You can automate starting and stopping of ForkEvent by adding it to the start up file, e.g. startup_UNIX_site_specific, startup_WIN32_site_specific:

[forkevent]
state=normal
type=command
start=${ ENTUITY_HOME}${FPS}integ${FPS}FORKEVENT${FPS}
forkevent${ ENTUITY_HOME}{FPS}etc${FPS}forkevent.cfg fork-unix