TCPClientd

Overview

The Unified Assurance Event TCP Client Aggregator is a generic integration that connects to a device over a TCP socket, reads the available messages, parses the results with customizable rules and creates de-duplicated events within Unified Assurance.

By default, Unified Assurance has the Event TCP Client Aggregator and Event TL1 Aggregator event services that utilizes the TCP Client Aggregator to collect events.

TCP Client Aggregator Setup

1. Determine the host and port settings needed to establish a client connection.

2. Review the logic in the rules files referenced in the configuration to see the processing that will be done when messages are retrieved:

   • LoadRules will be run during application startup to load data that might be needed during processing.

   • IncludeRules will be read during application startup to load additional files that might be called during processing.

   • BaseRules will be run for each device that is selected based on the configuration.

   Update the logic as needed.

3. Create a clone of the default service, making changes to the configuration as needed.

4. Enable the Service.

   Configuration -> Broker Control -> Services

Default Service

Default Configuration

Event TL1 Aggregator Service

Event TL1 Aggregator Configuration

Best Practices

The following list shows the best practices for working with this application:

• To let the aggregator run more efficiently and connect to multiple endpoints, a Meta Tag specific to the devices that will be connected should be used and then specified in the Application Configuration. In addition, the Meta Tag TCPAggregatorPort should be added to the devices with the value set to the port to be used.

Rules

This aggregator uses the Unified Assurance standard rules architecture in Perl syntax. For information about creating rules, see the following in Unified Assurance Developer's Guide:

• Core for information about core rules functions.

• Events for information about Event rules functions.

• Application Logging

Tokens

The aggregator exposes the following tokens for rules processing.

$CustomHash->{SubObject} = &share({});

Example Integrations

Creating Custom Rules Files

The TCP Client Aggregator will split each message using the defined Delimiter, by default newline (\n). So if the message is:

This Device is Down\n
This Device is Up\n

That will create two events in Unified Assurance.

These two events will be used as an example of how the messages could be parsed in the rules file.

Steps

1. Go to the Rules UI:

   Configuration -> Rules

2. Expand the folder path: core -> default -> collection -> event -> tcpclient

3. Select the tcpclient folder, then click Add -> Add File. Enter the following:

   • File Name => newbase.rules

   • Logic

     $Log->Message('DEBUG', "Ran Base Rules");
     $Log->Message('DEBUG', [
         '#===============================================',
         '# Received New TCP Client Message',
         '# DNS     = ' . $Packet->{'DeviceName'},
         '# IP      = ' . $Packet->{'IP'},
         '# Message = ' . $Packet->{'Message'},
         '#==============================================='
     ]);
     
     $Event->{'Node'}       = $Packet->{'DeviceName'};
     $Event->{'IPAddress'}  = $Packet->{'IP'};
     $Event->{'Summary'}    = $Packet->{'Message'};
     $Event->{'Severity'}   = 0;
     $Event->{'AlarmGroup'} = 'Unknown';
     $Event->{'AlarmKey'}   = 'GenericTCP-->' . $Event->{'Node'} . ':' . $Event->{'Summary'};
     
     if ($Packet->{'Message'} eq '') {
         $Event->{'SubMethod'} = "Error";
         $Log->Message('ERROR', "Blank message in packet");
         $discard_flag = 1;
     }
     elsif ($Packet->{'Message'} =~ "Down") {
         $Event->{'AlarmGroup'} = "Down";
         $Event->{'Severity'}   = 5;
     }
     elsif ($Packet->{'Message'} =~ "Up") {
         $Event->{'AlarmGroup'} = "Up";
         $Event->{'Severity'}   = 0;
     }
     else {
         # NO Rules
         $Event->{'SubMethod'} = "Generic TCP";
         $Log->Message('ERROR', "!ERROR! No Rules Defined for TCP");
         $Log->Message('DEBUG', "No Rules for TCP Message [" . $Packet->{Message} . "]");
     }
     $Log->Message('DEBUG', "Finished Base Rules");
     

     When the event message is parsed, if the message contains Down, a Down Event is created with Severity set to 5 (Critical).

     If the message contains Up, an event is passed in which clears the previous alarm by parsing the message and setting Severity to 0 (Normal).

   • Click Submit, then enter a commit message, then click OK.

4. Create a clone of the default service, making changes to the configuration as needed for connectivity, and change the BaseRules configuration to use the newbase.rules.

5. Verify the aggregator is processing the events correctly.

Administration Details

The following list shows the technical details you will need for advanced administration of the application:

• Package - coreCollection-app

• Synopsis - ./TCPClientd [OPTIONS]

• Options:

   -c, --AppConfigID N   Application Config ID (Service, Job, or Request ID)
   -?, -h, --Help        Print usage and exit
  

• Threaded - Multithreaded