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:
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:
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-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 featuretrap- A friendly name for the trap. This will be used to easily identify the trap used.trap-oid- The trap's Object Identifiertrap-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 aMIBtype configno_mib_template.json- Used when generating aNO_MIBtype 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
trapvalue 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.
copy
object
For each 'from' / 'to' pair, copy the value from key 'from' to a new key with the name 'to'. 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...
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)
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 thebp-actionvalue in theconditionsobject."type": "set"tells the BigPanda SNMP agent which action to perform- Following the
setdeclaration, 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
animaland looking for the string literal"chicken"to match in thedescriptiontag.- Next, the
set-messageaction is of typesetwhich in this case is creating a new tagmessage. - The value for this new tag is a string using the defined capture group name as a variable.
- Next, the
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.pidps -ef | grep bigpanda-snmpdsudo 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-utilssudo apt-get install snmpThe 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_PATHBy default, bp-snmp-replay.py is located in /opt/bigpanda/bigpanda-snmpd/bp_snmpd
