How it Works

BigPanda features the ability to ingest all SNMP Traps and convert them into BigPanda Alerts for correlation and aggregation in the platform. This is accomplished via a 2-pronged approach by utilizing the BigPanda SNMP Daemon and BigPanda Agent.

📘

Trap Messages

Note that only SNMP TRAP messages are consumed. Other types of SNMP messages like GET and SET are not in scope.

Installing the Integration

Administrators can install the integration by following the on-screen instructions in BigPanda. For more information, see Installing an Integration.

BigPanda SNMP Daemon

The BigPanda SNMP Daemon runs as a daemon on a Linux server that is in the local datacenter and on the same network as the devices being monitored. The following sections cover the high-level functions that the SNMP Daemon performs.

1. Consume SNMP Traps

The SNMP Daemon listens to traps on a port specified in the configuration. To safeguard against data loss or congestion, its consumption module does not share threads with the event-saving module.

SNMP communities up to v2 are supported, v3 is not available at this time.

Both UDP and TCP are supported.

2. Translate SNMP Object ID names

SNMP traps in their original form are similar to key-value pairs. Field names are represented using number tuples called Object IDs, for example, 1.3.6.1.6.3.1.1.4.3.0. These tuples are then translated into human-readable file names via configuration files called Management Information Base (MIB) files.

📘

MIB files are typically provided by the vendors of systems and devices emitting the SNMP traps.

SNMP Daemon Configuration File

The snmp-daemon.json configuration file is the primary configuration file for the BigPanda SNMP agent.

By default, its location is /etc/bigpanda/snmpd/snmp-daemon.json

The following are a few important properties to note:

📘

All logs can be found in /var/log/bigpanda/

Event Configuration Files

Event Configuration files are how the BigPanda SNMP agent knows how to process each trap. Each trap will have a configuration object. Multiple trap configurations can reside in one event configuration file, and multiple event configuration files can be used at the same time via the snmp-daemon.json configuration file.

In order for an incoming trap to be processed, it needs to have a corresponding trap configuration defined in an event configuration file.

Below are the properties used to capture the trap:

📘

Validation

If there are any integrity issues with an event config file, the agent will not load it at runtime.

The event config file will be skipped with a log entry stating as much:

ERROR: failed to load event config, skipping. path: /etc/bigpanda/snmpd/event_configs/file_name.json

🚧

Auto-Generated Event Config

If no matching trap is found within the loaded event configs, the agent is designed to auto-generate a config file for the trap. The alert will not be sent to the BigPanda console.

More details on the auto-generate feature below.

No MIB Support

The BigPanda SNMP agent can consume traps for which there is not a corresponding MIB file. As described above, the following properties in the Event Configuration file are required when using this feature:

• "type": "NO_MIB" - Use this declaration when using the no MIB feature
• trap - A friendly name for the trap. This will be used to easily identify the trap used.
• trap-oid - The trap's Object Identifier
• trap-var-binds - An object of key / value pairs where the key is the trap property name and the value is its position received in the trap

For example, here is an example Event Configuration snippet showing how to declare no MIB for a MIBless trap:

[
  {
    "type": "NO_MIB",
    "trap": "eatBamboo",
    "trap-oid": "2.9.7.16.1.14.4.1",
    "trap-var-binds": {
      "host": 2,
      "check": 4,
      "status": 7,
      "description": 5,
      "cluster": 9
    }
    ...
  }
]

📘

Notice that in the trap-var-binds object, the host property would be the second property received in the trap, check is in the fourth position, status is in the seventh spot, and so on.

Auto Generate Event Config

The BigPanda SNMP agent can generate a basic event config file for a trap that is not found. This will work both for MIB and NO_MIB types.

There are two templates that are leveraged when creating an event config file. Both can be found in /etc/bigpanda/snmpd/event_configs/.

• mib_template.json - Used when generating a MIB type config
• no_mib_template.json - Used when generating a NO_MIB type config

📘

New auto-generated event configs can be found in /etc/bigpanda/snmpd/auto-generated-event-configs/

Here is an example of an auto-generated event config file:

[
  {
    "type": "NO_MIB",
    "trap": "2.9.7.16.1.14.4.1",
    "trap-oid": "2.9.7.16.1.14.4.1",
    "trap-var-binds": {
      "varbind1": 1,
      "varbind": 2,
      "varbind3": 3
    },
    "copy": {
      "severity": "status"
    },
    "rename": {
    },
    "set": {
    },
    "map-status": {
      "Fatal": "critical",
      "Critical": "critical"
    },
    "primary": "<PRIMARY_VARBIND>",
    "secondary": "<SECONDARY_VARBIND>"
  }
]

👍

In new auto-generated event config files, you'll want to be sure to:

• Change the trap value to something more descriptive
• Map the Primary and Secondary properties to the proper trap-var-bind keys
• Ensure that the correct status-based field is mapped to the "status" property
• Ensure that the incoming status values are properly mapped to expected BigPanda values. See Map Severity
  

Once you've made the necessary changes to the file, rename it to something more descriptive and move it to /etc/bigpanda/snmpd/event_configs/.
 
Then add the event config file name to the list of event configs in the snmp-daemon.json file.
 
Finally, restart the bigpanda-snmpd service to put the changes into effect.

❗️

Primary and Secondary Properties

There are certain tags within the payload that are reserved words for BigPanda and cannot be used as the Primary or Secondary properties.

Please refer to the glossary for a list of reserved words.

3. Manipulate the Payload

The SNMP trap payload is manipulated in order to prepare it for consumption by the BigPanda Agent, and ultimately BigPanda. There are several supported types of manipulation actions. All manipulations are optional.

🚧

Please note that the copy, rename, set, drop, map-status, and resolve-mapping manipulations are processed in this order.

Copy, Rename, Set, & Drop Fields

The SNMP trap key-value pairs employ key names defined by the vendor of the system or device emitting the SNMP trap. Some of these keys might need to be copied, renamed or dropped before they can be sent to BigPanda. Other keys might need to be set.

Case sensitivity is not enforced on string matches. Below is an excerpt of drop, rename, and set examples.

{
  "mib": "xyz-platform-mib",
  "trap": "generic-problem-trap",
  ...
  "copy": {
    "eventOccurences": "event_occurrences"  
  },
  "rename": {
    "notification": "description",
    "clientName": "host",
    "checkName": "check",
    "checkSeverity": "status"
  },
  "set": {
    "team": "billing",
    "runbook": "http://docs.acme.com/af432"
  },
  "drop": [
    "eventID", 
    "eventOccurences", 
  ]
  ...
}

The Set field can also accept variable substitution as the value. Available variables are fields returned by the MIB, or if renaming fields, use the new name.

For example:

{
  "mib": "xyz-platform-mib",
  "trap": "generic-problem-trap",
  ...
  "set": {
    "team": "billing",
    "runbook": "http://docs.acme.com/af432",
    "interesting_field": "${host}_${check}" 
  }
  ...
}

Conditions

The BigPanda SNMP agent can perform actions against trap data if certain conditions are met. If the conditions are met, the agent can either suppress the trap - meaning that the trap is processed no further and will not be sent to BigPanda - or the agent can set additional fields that will be included in the trap data sent to BigPanda.

In the example Event Configuration below, you can see both the suppress and set conditions in action.

{
  "mib": "xyz-platform-mib",
  "trap": "generic-problem-trap",
  ...
  "conditions": [
    {
      "bp-name": "suppress-these",
      "bp-action": "suppress",
      "host": ".*moo.*"
    },
    {
      "bp-name": "set-these",
      "bp-action": "set-the-region",
      "host": ".*-mtnview-.*"
    }
  ],
  "custom-actions": {
    "set-the-region": {
      "type": "set",
      "region": "mountain_view"
    }
  }
  ...
}

Suppress

When "bp-action": "suppress" is declared, it will suppress any alerts that match the key / value trap properties.

In the example above, any trap with a host property containing moo will be suppressed.

📘

Suppressed traps are written to the bp-suppress log

Set

When bp-action is not suppress, it is treated as an alias for a custom action. The value must therefore exist as an object within the custom-actions object.

Within the custom-actions object is a list of aliased action objects. The aliased action object is structured as such:

{
  ...
  "custom-actions": {
    "<ALIASED_ACTION_NAME>": {
      "type": "set",
      "key1": "value1",
      "key2": "value2",
      ...
    }
  }
  ...
}

• "<ALIASED_ACTION_NAME>" is the value set from the bp-action value in the conditions object.
• "type": "set" tells the BigPanda SNMP agent which action to perform
• Following the set declaration, all other key / value pairs are the properties that are dynamically added to the alert.

From the example above:

{
  "mib": "xyz-platform-mib",
  "trap": "generic-problem-trap",
  ...
  "conditions": [
    {
      "bp-name": "suppress-these",
      "bp-action": "suppress",
      "host": ".*moo.*"
    },
    {
      "bp-name": "set-these",
      "bp-action": "set-the-region",
      "host": ".*-mtnview-.*"
    }
  ],
  "custom-actions": {
    "set-the-region": {
      "type": "set",
      "region": "mountain_view"
    }
  }
  ...
}

Any trap with a host property with a value containing -mtnview- will have a new tag added to the alert called region with a value of mountain_view.

Regex Capture Capability

The agent allows for a more flexible approach to manipulating your trap using Python Regex to match an expression and extract any relevant information.

Take, for example, the following event-config file

[
   {
       "type": "NO_MIB",
       "trap": "SAMPLE_TRAP",
       "trap-oid": "1.3.6.1.4.1.1234",
       "trap-var-binds": {
           "host": 1,
           "check": 2,
           "description": 3
       },
       "set": {
         ...
       },
       "conditions": [
           {
               // Tag to use a python regex on
               "description": ".*(?P<animal>chicken).*",
               "bp-action": "set-message",
               "bp-name": "Setting Message"
           }
       ],
       "custom-actions": {
           "set-message": {
               "type": "set"
               // Using the defined capture group names
               // a custom value can be created
               "message": "Yes, the {cap_group1} did cross!"
           }
       },
       "primary": "host",
       "secondary": "check"
   }
]

The conditions array has an object which will look at the description tag and perform the set-message action that is defined in the custom-actions property.

The above sample is performing the following actions:

• Creating a capture group called animal and looking for the string literal "chicken" to match in the description tag.
• Next, the set-message action is of type set which in this case is creating a new tag message.
• The value for this new tag is a string using the defined capture group name as a variable.

The python syntax to create a capture group and label it is as follows:
(?P<capture_name>{{regex expression}})

🚧

Escape Characters

If a more complex Python Regex is required that includes the need to escape characters.

For Example.
(?P<name>.*) \( .* \) (?P<check>.*).*

You need to account that this is a string within your JSON file and the escape character needs its own escape character.

A properly formatted string to the above example would be
"(?P<name>.*) \\( .* \\) (?P<check>.*).*"

Map Severities

SNMP traps may contain a wide variety of status codes or severities. These may be represented as a string or an integer. The map-status function translates a trap's statuses to corresponding BigPanda supported event severities (critical, warning, unknown, and ok).

📘

map-status requires a status property. If the trap does not natively send one, then you will need to either rename the trap's status field or copy its status field to a new status field

{
  "mib": "xyz-platform-mib",
  "trap": "generic-problem-trap",
  ...
  "map-status": {
    "Major": "critical",
    "Minor": "warning",
    "Resolved": "Ok"
  }
  ...
}

🚧

Once the map severities logic has been executed, future events without a valid status will be logged and then dropped.

Define Primary & Secondary Properties

Events propagated through the BigPanda platform contain two optional attributed called primary_property and secondary_property. These attributes are used to determine which fields should be used as a title and subtitle, respectively, in the UI.

As this is a proprietary concept to BigPanda and nonexistent in SNMP traps, users may configure these attributes on a per trap-type basis.

{
  "mib": "xyz-platform-mib",
  "trap": "generic-problem-trap",
  ...
  "primary": "host",
  "secondary": "check"
  ...
}

4. Capture Events to Local Disk

By this point, the SNMP traps have been consumed, translated, manipulated, and readied for saving to a local file storage. The target directory for saving is specified in the configuration file. The generated files should have Read/Write permissions assigned only to the bigpanda group for security reasons. All other users and groups should have denied read access.

Below are two examples of event files as they appear on disk.

{
  "timestamp": 1512923088,
  "mib": "xyz-platform-mib",
  "trap": "generic-problem-trap",
  "switch": "ny-switch-83", 
  "problem": "firmware update required",
  "status": "critical",
  "primary_property": "switch",
  "secondary_property": "problem"
}

{
  "timestamp": 1512923138,
  "mib": "bmc-mib",
  "trap": "system-resources-trap",
  "host": "server8",
  "check": "cpu load",
  "description": "RESOLVED - CPU Load < 80%",
  "status": "ok"
}

Once saved to disk, the event files are collected by the BigPanda Agent and forwarded to the BigPanda platform in the cloud.

Troubleshooting

The following Shell commands will help you perform various checks on the SNMP daemon.

cat /var/run/bigpanda-snmpd.pid

ps -ef | grep bigpanda-snmpd

sudo netstat -nltup | grep <PORT>

All logs can be found at /var/log/bigpanda

Simulating a Trap

Simulating an SNMP trap to the daemon may be useful for testing purposes. First, install snmptrap with these commands in your Shell.

sudo yum install net-snmp-utils

sudo apt-get install snmp

The SNMP Trap command structure follows this format:
snmptrap -v ${SNMP_VERSION} -c ${COMMUNITY} ${DESTINATION_HOST}:${DESTINATION_PORT} ${UPTIME} ${OID or MIB} ${OBJECT} ${VALUE_TYPE} ${VALUE}

Below is an example of this structure in use.

sudo snmptrap -v 2c -c public 127.0.0.1:5000 1 1.3.6.1.2.1.1 1.3.6.1.2.1.1.5 s "production-switch-1" 1.3.6.1.2.1.1.1 s "SNMP trap test"

Replaying Traps

The BigPanda SNMP package includes a python utility that can replay raw traps that were captured to the bp-snmp-raw-captures or bp-snmp-raw-captures-errors log files.

Within the capture log files, you will find raw trap data that looks like this:

SNMP_VERSION 1.3.6.1.2.1.1.1234 = v2
pysnmp.proto.rfc1902.TimeTicks 1.3.6.1.2.1.1.3.0 = 1
pyasn1.type.univ.ObjectIdentifier 1.3.6.1.6.3.1.1.4.1.0 = 1.3.6.1.2.1.1.1234
pysnmp.proto.rfc1902.OctetString 1.3.6.1.2.1.1.1234.1 = acme-mtvnview-01
pysnmp.proto.rfc1902.OctetString 1.3.6.1.2.1.1.1234.5 = some_check
pysnmp.proto.rfc1902.Integer 1.3.6.1.2.1.1.1234.6 = 1
--------------------------------------------------

Each raw trap entry begins with SNMP_VERSION and ends with --------------------------------------------------.

When replaying the raw traps, we recommend to copy the the raw trap(s) from the log to a dedicated replay file.

To replay the traps, you will want to run this command:

python bp-snmp-replay.py --capture_log_file_path CAPTURE_LOG_FILE_PATH

📘

By default, bp-snmp-replay.py is located in /opt/bigpanda/bigpanda-snmpd/bp_snmpd