Northbound Trap Integration Example

This section shows you how Unified Assurance can send Northbound SNMP Trap messages to another system within the network. In this case, we are sending all threshold events to a northbound system. The specific type or number of events is easily customizable within the rules.

Dependencies

Unified Assurance Threshold engine running and checking for threshold violations against metric data.
Unified Assurance Syslog Aggregator running to receive notifications from the thresholding engine.
Unified Assurance Trap Aggregator running to receive notifications from the syslog aggregator.

Send to Northbound System Example

Sending SNMP Traps to a northbound system in Unified Assurance can be done within the rules files. The first step is to determine what events should be forwarded to the northbound system. Any type of event can be sent, but in this example, for every threshold event received by the syslog aggregator, a trap will be created and sent to the Northbound system. With additional Perl rules, the code could be modified to exclude certain event types or a set of devices, if required.

Navigate to Rules

Configuration -> Rules
Open the base.load file used by the Syslog Aggregator.
1. The path to the default file is Event Rules (event) -> Default read-write branch (default) -> eventStdAggregator -> syslog -> base.load.
Add the code below to the load file. This section of code brings in the library needed to send an SNMP trap. This change is made in base.load to avoid excessive unshifting within the application, which may cause slowness issues, especially on systems processing a large number of events:
```
use Net::SNMP;
```
Save the changes.
Navigate to Rules.

Configuration -> Rules
Open the metric_manager.rules file used by the Syslog Aggregator.
1. The path to the default file is Event Rules (event) -> Default read-write branch (default) -> eventStdAggregator -> syslog -> metric_manager.rules.

Add the code below to the rules file. This section of code creates an SNMP session and sends a SNMP Trap to the designated system. Replace the \<NORTH-BOUND-SYSTEM-HERE> section with the FQDN or IP address of the northbound system:

$Log->Message("DEBUG", "Sending Trap Event For Threshold Event");
my ($session, $error) = Net::SNMP->session(
    -hostname  => '<NORTH-BOUND-SYSTEM-HERE>',
    -community => 'public',
    -port      => 162,
);

if (!defined($session)) {
    printf("ERROR: %s.\n", $error);
    exit 1;
}
else {
    my $result = $session->trap(
        -enterprise   => '1.3.6.1.4.1.40127',
        -generictrap  => 6,
        -specifictrap => 1,
        -varbindlist  => [
            '1.3.6.1.4.1.40127.2.1.1', OCTET_STRING, "$colons[0]",
            '1.3.6.1.4.1.40127.2.1.2', OCTET_STRING, "MMM|$colons[2]|$colons[3]|$colons[4]",
            '1.3.6.1.4.1.40127.2.1.3', OCTET_STRING, "$colons[5]",
            '1.3.6.1.4.1.40127.2.1.4', OCTET_STRING, "$colons[6]",
            '1.3.6.1.4.1.40127.2.1.5', OCTET_STRING, "$colons[7]",
            '1.3.6.1.4.1.40127.2.1.6', OCTET_STRING, "$colons[8]",
            '1.3.6.1.4.1.40127.2.1.7', OCTET_STRING, "$colons[9]",
            '1.3.6.1.4.1.40127.2.1.8', OCTET_STRING, "$colons[10]",
            '1.3.6.1.4.1.40127.2.1.9', OCTET_STRING, "$colons[11]",
            '1.3.6.1.4.1.40127.2.1.10', OCTET_STRING, "$colons[12]",
            '1.3.6.1.4.1.40127.2.1.11', OCTET_STRING, "$colons[13]",
            '1.3.6.1.4.1.40127.2.1.12', OCTET_STRING, "$colons[14]",
            '1.3.6.1.4.1.40127.2.1.13', OCTET_STRING, "$colons[15]",
            '1.3.6.1.4.1.40127.2.1.14', OCTET_STRING, "$colons[16]"
        ]
    );

    $session->close();
}

Save the changes.
Restart the Syslog Aggregator service.
Verify the Syslog Aggregator is sending the traps.

Send to Unified Assurance

This is an example of how Unified Assurance uses the above information to receive SNMP Traps from another Unified Assurance system.

Navigate to Rules.

Configuration -> Rules
Open the trap vendor directory used by the Trap Aggregator.
1. The path to the default directory is Event Rules (event) -> Default read-write branch (default) -> eventStdAggregator -> trap -> vendor.
Click Add -> Add File.
Create a rules file entitled monolith-trap.rules.

Enter the following code for the new file rules file.

# MODULE-IDENTITY #
#    monolithEventMIB MODULE-IDENTITY ::= { monolithEvents 1 } -- { 'monolithEventMIB' => '1.3.6.1.4.1.40127.2.1' }

# NOTIFICATION-TYPEs #
#    monolithEventAssocTrap   NOTIFICATION-TYPE ::= { monolithEventTraps 1 } -- { 'monolithEventAssocTrap' => '1.3.6.1.4.1.40127.2.1.1.1' }
#    monolithThresholdDate    NOTIFICATION-TYPE ::= { monolithEventObjects 1 } -- { 'monolithThresholdDate'  => '1.3.6.1.4.1.40127.2.1.2.1'  }

if ($specific == 0) {
    $Log->Message('ERROR', "Found Specific 0");
}
elsif ($specific == 1) {
    #----------------------------------#
    # monolithEventAssocTrap - Enterprise [1.3.6.1.4.1.40127.2.1.1] Specific [1] 
    #----------------------------------#
    # monolithEventAssocTrap NOTIFICATION-TYPE
    #  OBJECTS { monolithThresholdDate, monolithThresholdMessage, monolithThresholdDNS, monolithThresholdIP, monolithThresholdInstance,
    #  monolithThresholdValue, monolithThresholdUtil, monolithThresholdType, monolithThresholdPoller, monolithThresholdSampleRate,
    #  monolithThresholdCompare, monolithThresholdMetricID, monolithThresholdState }
    #  STATUS current
    #  DESCRIPTION
    #  "Trigger when there is an client association event.
    #  The client's MAC address is enclosed."
    #  ::= { monolithEventTraps 1 }
    #----------------------------------#

    my $monolithThresholdDate       = $vars->{'1.3.6.1.4.1.40127.2.1.1'};
    my $monolithThresholdMessage    = $vars->{'1.3.6.1.4.1.40127.2.1.2'};
    my $monolithThresholdDNS        = $vars->{'1.3.6.1.4.1.40127.2.1.3'};
    my $monolithThresholdIP         = $vars->{'1.3.6.1.4.1.40127.2.1.4'};
    my $monolithThresholdInstance   = $vars->{'1.3.6.1.4.1.40127.2.1.5'};
    my $monolithThresholdValue      = $vars->{'1.3.6.1.4.1.40127.2.1.6'};
    my $monolithThresholdUtil       = $vars->{'1.3.6.1.4.1.40127.2.1.7'};
    my $monolithThresholdType       = $vars->{'1.3.6.1.4.1.40127.2.1.8'};
    my $monolithThresholdPoller     = $vars->{'1.3.6.1.4.1.40127.2.1.9'};
    my $monolithThresholdSampleRate = $vars->{'1.3.6.1.4.1.40127.2.1.10'};
    my $monolithThresholdCompare    = $vars->{'1.3.6.1.4.1.40127.2.1.11'};
    my $monolithThresholdMetricID   = $vars->{'1.3.6.1.4.1.40127.2.1.12'};
    my $monolithThresholdState      = $vars->{'1.3.6.1.4.1.40127.2.1.13'};

    my @colons                = split(/\|/,$monolithThresholdMessage);
    $Event->{'AlarmGroup'}    = $colons[3];
    $Event->{'Summary'}       = "Monolith Threshold Event - $monolithThresholdType/$monolithThresholdInstance - Value/Compare/Rate - $monolithThresholdValue/$monolithThresholdCompare/$monolithThresholdSampleRate";
    $Event->{'Severity'}      = $colons[2];
    $Event->{'SubAlarmGroup'} = $monolithThresholdInstance;
    $Event->{'AlarmType'}     = 300;
    $Event->{'Node'}          = $monolithThresholdDNS;
    $Event->{'IPAddress'}     = $monolithThresholdIP;
    $Event->{'SubMethod'}     = "Unified Assurance Event Forwarding";
}
else {
    $Event->{'AlarmGroup'}    = 'Unknown Trap';
    $Event->{'SubAlarmGroup'} = 'Unknown';
    $Event->{'Summary'}       = 'Unknown ' . $Event->{'SubMethod'} . ' Trap - ' . $enterprise . '-' . $specific . '.  Please notify your system administrator';
    $Event->{'Severity'}      = 4;
    $Event->{'AlarmType'}     = 0;
}

$Event->{'AlarmKey'} = $Event->{'SubMethod'} . '-' . $Event->{'Node'} . '-' . $Event->{'AlarmGroup'} . '-' . $Event->{'SubAlarmGroup'} . '-' . $Event->{'Summary'};

Save the changes.
Open the base.includes file used by the Trap Aggregator in the Rules UI.
1. The path to the default file is Event Rules (event) -> Default read-write branch (default) -> eventStdAggregator -> trap -> base.includes.

Add the code below to the includes file:

MonolithTrap,eventStdAggregator/trap/vendor/monolith-trap.rules

Save the changes.
Open the base.rules file used by the Trap Aggregator using the Rules UI.
1. The path to the default file is Event Rules (event) -> Default read-write branch (default) -> eventStdAggregator -> trap -> base.rules.
The next step is to add a call to the new rules file based on the Unified Assurance enterprise OID. This should go in the Generic = 6 section along with any other custom traps you expect to receive:
```
if ($enterprise =~ /^1\.3\.6\.1\.4\.1\.40127\b/) {
    $Log->Message("DEBUG", "Using Monolith Trap Rules - $specific - $generic");
    MonolithTrap();
}
```
Save the changes.
Restart the Trap Aggregator service.
Verify the Trap Aggregator is receiving the traps.

Title and Copyright Information

Developer’s Guide

F88951-01