SNMP (Simple Network Management Protocol)

SNMP is an Internet Standard protocol and way for servers and network devices to share information on their current state. The protocol allows for the standardization of messages from a diverse array of systems.

Supported Versions:

Type:

v1, v2, v2c

Daemon and Agent

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:

Property
Type
Description

snmp.community

list

A list of community strings that are used by your SNMP trap emitters.

processing.mibs-dir

string

The location where the compiled Python MIB files reside. You likely won't need to change this.

processing.event-configs

list

A list of locations to find the event configuration files. The location path is relative to the directory in which the snmp-daemon.json file resides (by default /etc/bigpanda/snmpd).

processing.generate_event_configs

boolean

The agent can auto generate a skeleton config file for traps that are not found. (default: true)

logging.raw_capture_level

string

The BigPanda SNMP agent can log received SNMP alerts. It can log ones that failed to be sent to BigPanda, all received alerts, or none of them.

Possible values are none, error, all (default: error).

logging.log_level

string

The verboseness of which to log. Possible values are INFO and DEBUG (default: INFO).

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:

Setting
Type
Description

mib

string

(optional) The name of the MIB file to look for traps. The MIB should reside in the directory defined in the snmp-daemon.json configuration file.

File extensions should be omitted.

Required when using a MIB.

type

string

(optional) Declare and set this value to "NO_MIB" when using the no MIB feature.

Required when using no MIB.

trap

string

The name of the incoming trap.

trap-oid

string

(optional) The incoming trap's Object Identifier.

Required when using no MIB.

trap-var-binds

object

(optional) An object of key / value pairs where the key is the trap property name and the value is its position received in the trap.

Required when using no MIB.

primary

string

(required) sets the key that the BigPanda console would leverage for incident identification.

secondary

string

(required) sets the key that the BigPanda console would leverage for incident identification.

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,
    "varbind1": 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 Key

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

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.

Manipulation
Type
Description

copy

object

For each 'from' / 'to' pair, copy the value from key 'from' to a new key with the name 'to'. More...

rename

object

For each key / value pair, rename the key to the corresponding value. More...

set

object

For each key / value pair, set the key to the corresponding value in the trap payload Value could be a template (ex. "my name is {name}"). More...

drop

list

List of fields to drop from the trap payload. More...

map-status

object

Translates a trap's statuses to corresponding BigPanda supported event severities (critical, warning, unknown, and ok)

resolve-mapping

object

Change the status field value to "ok" if one of the key value pairs are found in the trap payload.

set-time

boolean

Whether or not to set unix time in the trap payload.

add_system_fields

boolean

Whether or not to add system fields on each trap (ex. community, daemon port). (default true)

primary

string

Set the primary property to the specified value. More...

secondary

string

Set the secondary property to the specified value. More...

conditions

object array

An array of objects that can perform conditional set or suppress manipulations. More...

custom-actions

object

An object containing the key / value pairs to add to the alert if a condition is met. More...

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_key and secondary_key. 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

SNMP (Simple Network Management Protocol)


SNMP is an Internet Standard protocol and way for servers and network devices to share information on their current state. The protocol allows for the standardization of messages from a diverse array of systems.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.