Administrator Handbook Table of contents version française

Trap filter creation


Introduction

Filters are used to trigger action when an event or a trap is received by LoriotPro. For each Event or Trap, multiple filters can be defined and thus multiple actions can be generated. Action can be used to send an E-mail, play a sound , start another program...

To create a filter you have the choice between three methods:

  1. Invoke the wizard from a received trap. This is the easiest method because the filter will be created automatically and you will only have to choose the action. You can use the TRAP simulator service plugin to create a fake Trap that will help use to set filter.
  2. Invoke the wizard from the filter tree. This method need to know the trap name that you want to filter.
  3. Open the Filter file and edit the file. This method is recommended of you want to create a lot of filter that are similar.

All filters are defined in the trapfilter.txt file located in the /bin directory of the LoriotPpro software. This file is a standard text file that you could edit with the Notepad program of Windows. The file creation could be made manually or extract from the documentation or by using the included tools.

The file is structured in two parts.

  1. The first one defines the Trap filters and their associated actions
  2. The second one defines the local or remote event filters, respecting the LoriotPro format, and their associated actions.


About snmp trap and notification

LoriotPro includes a ‘Trap server’ listening on UDP port 162. The software decodes different version of SNMP trap but the filter syntax remains the same for all of these versions.

To filter a trap you should know its name (snmp object ID), the software will use the SNMP ObjectID received in the Trap to match the correct filter. If you want to filter a received Trap you could use the « Trap filter Wizard » of the trap window contextual menu.

Trap (snmp v1) and Notification (snmp v2c and snmp v3) are initially defined in MIB files. If MIB files are compiled (added to LoriotPro) the exact name of the Trap will be recognized and you’ll have to use it in the filter. Otherwise, the name will be under its OID format and you will have to use it in the filter.

Example of snmp v1 trap

objet trap snmp v1

Example of snmp v2c notification in the MIB tree.

oid de trap

Example of snmp v1 trap recognized by LoriotPro (in the database)

trap snmp v1

Example of snmp trap (notification v3) not recognized by LoriotPro.0

trap v3

Warning: If you compile MIB files with the trap definitions of already declared filters using the OID format you’ll have to modify it with their real name to get them work.

How to find a Trap name

A simple way of finding a Trap name that you want to filter is to look at the ObjID column in the Trap window and to use the exact displayed name in the filter.

Trap oid
ObjID
column in the Trap window

In the example above, two traps have been received, if you want to filter the SNMP V3 notification, use the name ciscoconfigmanmibnotifications.1.

The same Trap in SNMP v1 has another name.

SNMP v1 trap

In this example the SNMP v1 Trap has the name : 

ciscoconfigmanmibnotificationprefix .

This Trap is defined in the Cisco MIB  :

Fichier : CISCO-CONFIG-MAN-MIB.my (extract)

 

ciscoConfigManEvent TRAP-TYPE
-- Reverse mappable trap
    ENTERPRISE ciscoConfigManMIBNotificationPrefix
    VARIABLES {
        ccmHistoryEventCommandSource, ccmHistoryEventConfigSource,
   ccmHistoryEventConfigDestination }
--  Status
--    mandatory
    DESCRIPTION
        "Notification of a configuration management event as
        recorded in ccmHistoryEventTable."
    ::= 1


Invoking the wizard from a received Trap 

Some Traps are never sent until that a real default occurs, a power supply failure for example. With LoriotPro it is possible to create a forged Trap by using the Trap Simulator service Plugin.

When the trap i s arrive in the Trap log you can select the wizard. trap filtre wizard

trap filter wizard
Traps Filter wizard option in the Trap contextual menu

If a Trap filter already exists, the program offers you to add an action to this Trap.

filter popup

If the Trap is not yet defined in the filter tree, the Wizard offers you to create a new entry.

filter popup 2

If the Trap is already filter by a wildcard filter, you are notified. You should check in the Filter Tree where is the wilcard filter and discard it eventually.

trap filter tree

The Trap action creation window appears with the known parameter of the agent. Select the actions that you want to realize at the next incoming trap of this type, coming from this agent.

trap filter action
Trap action Wizard window

To define a filter and its action,

The Wizard opens a Trap creation window with the selected Trap parameters.

trap filter string
Trap Filter creation Wizard window

If you refuse the automatic creation, at least you can use the proposed syntax to put in the trapfilter.txt file.

Finally you can call the Advanced dialog box

advanced trap filter

The advanced Trap Filter Parameters give you a higher control on the action trigger. The threshold use the Trap Filter Counter. The Trap Filter Counter is inncresead each time a filter match.

You can select the following options

Match All

All the times the Filter will match the action will be triggered

Match only First

Given a Trap Filter Counter initially at 0, only the first time the filter will match the action will be triggered.

Match only X

Given a Trap Filter Counter initially at 0, only the first X filter matches will triggered the action.

Match after X

Given a Trap Filter Counter initially at 0,  after X filter matches, each new Filter match will trigger an action. 

Match if supposed burst for time interval <=

Evaluate the number of Filter matched during a specific time interval and trigger the action if the value is superior to the threshold

Match Every X

Trigger the action each X filter match


Invoking the wizard from the Filter tree window

A new Trap could be directly created from the Trap window. You should first create a new trap entry and then you will be able to attach filters to this Trap.

Select the Traps Filters node object in the tree and call the contextual menu « New Trap Filter/Action ».

trap menu

The Trap filter creation window is displayed.

trap filter setting

The first task consists of defining a name for the Trap filter. If the Trap is a standard Trap, select it from the combo box. If the Trap is of Enterprise type select it from the Enterprise type combo box, this will unlock the « Trap name » field.

If you do not not exactly what is the Trap you want to filter, you can browse the Trap that are available in the LoriotPro Mib DataBase.

trap picker details

Remark : If are looking for Enterprise V1 Trap or Private SNMP V2 notification in the list and you do not see them you should get the Mib file containing the Trap definition by contacting the hardware manufacturer or the sofwtare editor.

By default when a Trap filter is defined a LoriotPro Event is automatically attached as an action to this Trap. Each time the defined Trap will be received an Event will be generated.

trap to event action

Remark : If you choose the Event number 0 nothing will be displayed in the Event window.

Use all received information in the Trap window and the documentation syntax table to complete the fields. The Wizard button calls the help window that guides you for creating the character string including the variables.

trap string message
Trap filter string (Wizard)

When the new Trap Filter is defined we can start to attach filter rules to it.

trap filter define

The Trap action creation window appears with the known parameter of the agent. Select the actions that you want to realize at the next incoming trap of this type, coming from this agent.

trap actions
Trap action Wizard window

To define a filter and its action,

The Wizard opens a Trap creation window with the selected Trap parameters.

message string
Trap Filter creation Wizard window

If you refuse the automatic creation, at least you can use the proposed syntax to put in the trapfilter.txt file.

Finally you can call the Advanced dialog box

The advanced Trap Filter Parameters give you a higher control on the action trigger. The threshold use the Trap Filter Counter. The Trap Filter Counter is inncresead each time a filter match.

You can select the following options

Match All

All the times the Filter will match the action will be triggered

Match only First

Given a Trap Filter Counter initially at 0, only the first time the filter will match the action will be triggered.

Match only X

Given a Trap Filter Counter initially at 0, only the first X filter matches will triggered the action.

Match after X

Given a Trap Filter Counter initially at 0,  after X filter matches, each new Filter match will trigger an action. 

Match if supposed burst for time interval <=

Evaluate the number of Filter matched during a specific time interval and trigger the action if the value is superior to the threshold

Match Every X

Trigger the action each X filter match


Traps filter syntax

Once the Trap filter name known, you should define all associated parameters. A filter is defined by only one line without carriage return. A filter contains 6 to 7 parameter in a specific order.

traps action list

Example
trap  ciscoConfigManMIBNotificationPrefix 6 1 3 "%n (%N) for agent %i from proxy [%p] %0 %1 %2 %3 %4 %5"

Table of Trap filter syntax

Options

Examples

Definitions

Trap

trap

This keyword informs the compiler that it is a Trap filter.

name

ciscoConfigManMIBNotificationPrefix

The Trap name.

Remark

If you use the name * then all received Trap no yet filtered will be filtered by this line. When using the Wizard, a message inform you that your filter line will be placed after such line with an *.

enterprise trap

The generic Trap type

6

This parameter is used by Trap SNMP v1 and define Standard Traps

In SNMP v1, six generic Traps are defined, one complementary is called “specific”

Numéro

Type standard

0

ColdStart

1

PowerOn

2

LinkDown

3

LinkUp

4

Authentication

5

EGP

6

Enterprise /Notification

The specific trap type

1

Use in SNMP v1 when the generic type of the Trap is 6 (previous parameter) else this value is 0.

Event level

3

Value from 0 to 10 are use to assign a level of severity to the Event. The level allows a display of Trap in different colors in the Global Event window.

The  message to display in the Global Events window

"%n (%N) for agent %i from proxy [%p] %0 %1 %2 %3 %4 %5"

This parameter is a character string delimited by quotations. The message body that should be display in the Global Events window.

Variable start by the % or $ character followed by a reference letter use by the compiler to replace them by their value. Customized variables could be used in the string.

Variables

Meaning

%r

Reference

%i

IP address of the SNMP agent

%p

Source IP address of the Trap packet

%t

Timestamp contain in the Trap,

%t display the Timestamp.

%T

Display the local Timestamp.

%0 à %9

Trap specific parameters values if they exist

$0 à $9

The SNMP name of the previous parameters

%n

The Trap SNMP  ObjID.

%l

The severity level

%N

The Trap name if it exists

Event number assigned

(optionnal)

Higher than  10000.

10002

By default, Trap forwarded to the Global Event window use the number 300. You could customize by selecting another number higher than 10000. That allows you to create dedicated Event filters.

.

Examples 

trap  ciscoMgmt.41.2 6 1 1 "%n for Agent %i proxy [%p] $0->%0 $1->%1 $2->%2 $3->%3"
trap  ciscoMgmt.43.2 6 1 1 "%n for Agent %i proxy [%p] $0->%0 $1->%1 $2->%2 $3->%3"
trap  cisco 6 1 3 "%n (%N) for agent %i from proxy [%p]  : %0 %1 $2/%2 ByteIn/%3 ByteOut/%4 $5/%5"
trap  loriotidsprobe 6 1 3 "%n (%N) for agent %i from proxy [%p]  : %0 %1 $2/%2 ByteIn/%3 ByteOut/%4 $5/%5"
trap  ciscoSyslogMIBNotificationPrefix 6 1 3 "%n (%N) for agent %i from proxy [%p] %0 %1 %2 %3 %4 %5"
trap  ciscoConfigManMIBNotificationPrefix 6 1 3 "%n (%N) for agent %i from proxy [%p] %0 %1 %2 %3 %4 %5"
trap  LinkDown 2 0 6 "%r for %n from %i  Interface %1 at %t Description %1 Type %2 Status %3" 10002


Filter Actions

The reception of a Trap could trigger an action. You could trigger action on filter conditions based on the packet source address or the SNMP community. Actions are located in the filter file after the Trap definition. The key work “action” followed by five parameters should be used on each line defining a new action.

 trigger action

Example
action 0.0.0.0 0.0.0.0  *  wave "wave/linedown.wav"

Table of syntaxes of Trap associated actions

Parameters

Examples

Definitions

IP

0.0.0.0

The two following parameters are used to trigger an action if the source address of the packet match the filter.

The rule below is applied :

IF IP_SOURCE_RECEIVED AND  IP_MASK = IP THEN action

Example :

With IP received = 10.33.10.121
If rule with IP = 0.0.0.0 IP_MASK =0.0.0.0 then all IP addresses trigger the action)
If rule with IP=10.33.0.0 IP_MASK=255.255.0.0 then the action is triggered because  10.33.10.121 pertains to network 10.33.0.0
If rule with IP=20.0.0.0 IP_MASK=255.0.0.0 then no action is triggered because 10.33.10.121 does not pertain to network 20.0.0.0)

To select a unique address

example : 192.168.10.1 code the action below

Action 192.168.10.1 255.255.255.255

IP Mask

0.0.0.0

Define above.

Community

*

The SNMP community that should be receive to trigger the action (Only in SNMP V1 et V2c).

The  * sign works has wildcard.

Warning: If you use SNMP v3, use the * and the advanced parameter of the host that should be defined for this object.

OID

 

The SNMP object name use in the parameter field of the Trap

Value

 

A value that will be used to filter the Trap on this particular parameter

Action types

Wave

The type of action to trigger if all the 3 previous conditions are satisfied.
See next table for action types

parameters

"wave/linedown.wav"

A character string that is used as line parameter by the executable program
See next table for action types

Tableau des actions associées aux Traps

Actions

Command

  wave

Play a wave file :

The string of command line parameters should contain the full path to a wave file. The string could contain variables.

Example:
Wave "wave/chord.wav"

 trap

Forward the v1 or v2c Traps  to another server.

Example:
Trap "10.33.10.126"

 winrun

Start a Windows type program :

The string of command line parameters should contain the full path to an Window executable file.  The string could contain variables

Example:
telnet "telnet %i"

 dosrun

Start a DOS type program :

The string of command line parameters should contain the full path to an Window executable file.  The string could contain variables identical to the Trap filter string

Example:
Dosrun "telnet %i"

 syslog

Send a Syslog message :

The string of command line parameters contains the IP address of the Syslog server and others variables.

Example:
syslog "10.33.10.126 %r for %n from %i from proxy [%p] Request from station [%0]"

 smtp

Create a Mail message in the Mail spooler

The string of command line parameters should contain The E-mail address and other variables.

Example 

smtp "unknow@domain.com  Authentication fail %i %m "

 custom

Display the Trap in the custom window 1 to 3 and their variables.

Example:
Custom  "1 %n for Agent %i proxy [%p] $0->%0 $1->%1 $2->%2 $3->%3"

nul

Do nothing

Forward Trap as Event to a LoriotPro

It is possible to create a LoriotPro Event and send it to any LoriotPro SNMP manager.

forward event

run scriptRun Script

Run a LUA script. The script is added to a queue and processed by the service plugin


The wizard dialog allows you to create your message string passed to the executable or sent as Event.

Table of variables

Variables

Meaning

%r

Reference

%i

IP address of the SNMP agent

%p

Source IP address of the Trap packet

%t

Timestamp contained in the Trap, %t display the Timestamp.

%T

Display the local Timestamp.

%0 à %9

Trap specific parameters values if they exist

$0 à $9

The SNMP oid name of the previous parameters

%n

The Trap SNMP  ObjID.

%l

The severity level

%N

The Trap name if it exists

Examples

trap  Authentication 4 0 3 "%n (%N) for agent %i from proxy [%p] %0 %1 %2 %3 %4 %5"
 action 10.33.10.121 255.255.255.255 public trap "10.33.10.129"
 action 10.33.10.121 255.255.255.255 public wave "wave/ding.wav"
 action 0.0.0.0 0.0.0.0  * syslog "10.33.10.126 %r for %n from %i from proxy [%p] Request from station [%0]"
trap  LinkUp 3 0 4 "%r for %n from %i  Interface %1 at %t Description %1 Type %2 Status %3" 10001
 action 0.0.0.0 0.0.0.0  *  wave "wave/lineup.wav"

The reception the ‘Authentication’ standard Trap will generate a message in the Global event window

If the source address of the sending agent satisfy the condition actions will be realized. If this address is  10.33.10.121, three actions will be realized.

1.     A Trap will be forwarded to server 10.33.10.129
2.     The ding.wav sound will be played.
3.     A Syslog message will be sent to the server 10.33.10.126.

Remark: The variable used in the string are the same as those used in the Trap filter.

Warning: It could no be several filter for the same Trap but a Trap could trigger several actions.

 


www.loriotpro.com