Configuring the Collection Agents

NetworkLens may be configured to use several different collection agents. New events are automatically inserted into the LENS_EVENT table:

Table 1. LENS_EVENT table sample data

1000032001-12-12 13:51:072001-12-13 15:00:37192.168.23.7NULLSYSLOGLOG_LOCAL7 from 1231: Dec 12 13:51:07 MST: %LINK-3-UPDOWN: Interface Serial3/1:0, changed state to down
1001032001-12-12 19:13:11NULL192.168.9.115053System MeltdownKandahar POP site unavailable
1002012001-12-13 14:06:232001-12-13 15:01:00192.168.0.1NULLInterface LinkLink DOWN: 2 (Serial2/0) propPointToPointSerial


The SYSLOG Collection Agent opens UDP port 514 and listens for SYSLOG messages. By default, SYSLOG messages have the format:

The integer is composed of a "facility" and "priority". The facility is mapped to a descriptive name such as "LOG_USER", and the priority is directly mapped to the severity of the generated event in the LENS_EVENT table.

For more information, refer to the SYSLOG Collection Agent Source Code included in the appendix.

TCP Socket

Currently, the TCP socket collection agent listens for TCP connections on port 9002. Arguments are passed in a similar manner as HTTP GET requests:

  1. Everything is sent as one string of characters (arbitrary length). The valid character set is [0-9], [a-z], [A-Z], '=', '&', '+', '%', and '_'.

  2. Name/value pairs are separated by a & (ampersand) character.

  3. For each name/value pair, the name and value and separated by a = (equal sign) character.

  4. Every non-alphanumeric character not in [0-9a-zA-Z=&+%_] (including the space) must be escaped with the %XX notation, where "XX" is the hexadecimal equivalent (using either A-F or a-f) of the character being substituted. See RFC2396 for further information. Other characters (in the set above) can be escaped, but don't have to be.

  5. To be compatible with CGI scripts, spaces may be translated to the + (plus) character or encoded with the %20 hex equivalent.

The following names will be recognized:

Table 2. TCP Socket Collection Agent Allowed Names

NameAllowed Values
severityunknown, alert, critical, error, warning, notification, informational, debugging
ref_idan integer of 11 digits or less
categoryany arbitrary text value
summaryany arbitrary text value

Example 1. TCP Socket Interface

categorySystem Meltdown
summaryKandahar POP site unavailable

would be sent as (all on one line):

Example 2. TCP Socket Interface

categorythis has spaces
summarySystem Exception: you must restart Windows.

would be sent as (all on one line):

For more information, refer to the TCP Socket Collection Agent Source Code included in the appendix.


SNMP traps are handled in a two step process. First, the "snmptrapd" program must be running with the "-On" option. This makes the trap handler (part of the UCD SNMP package) output all of the OIDs in numeric format.

To start capturing SNMP traps, you must run the trap collector as follows:

$ su -
# vi /etc/snmp/snmptrapd.conf
# snmptrapd -On

The contents of the /etc/snmp/snmptrapd.conf file should be:

traphandle default /usr/sbin/lens-traphandler
or whereever you have unpacked the NetworkLens tools.

The traphandler will populate the LENS_TRAP and LENS_TRAP_ARGS tables. The "lens-trap" script will parse the raw data in these two tables; and, using the "LENS_SEVERITY", "LENS_CATEGORY", and "LENS_SUMMARY" tables, will create and/or modify events in the master LENS_EVENT table.