# Collect data using SNMP

{% hint style="info" %}
See the changelog of this Listener type [here](https://app.gitbook.com/s/1OZWDcmMPrhfCtF1rMJP/snmp-trapd-listener).
{% endhint %}

## Overview

Onum supports integration with [SNMP](https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol).

**SNMP (Simple Network Management Protocol)** is a standard protocol for monitoring and managing network devices. It operates on a client-server model where:

* **SNMP Agents** (devices) send **traps** (asynchronous notifications) to **SNMP Managers**.
* **Traps** contain information about events like system failures, security alerts, or performance issues.
* **OIDs (Object Identifiers)** uniquely identify each piece of information in the trap.

The **SNMP Trapd** Listener is a powerful and intelligent Listener that receives SNMP traps from network devices, parses them using embedded MIB (Management Information Base) files, and converts them into structured Onum events. It supports all major SNMP versions (v1, v2c, v3) with comprehensive authentication and privacy options.

### What are MIBs?

**MIBs (Management Information Bases)** are hierarchical databases that define:

* **OID structure** and relationships
* **Data types** for each OID
* **Human-readable names** for OIDs
* **Units** and **ranges** for values

**Example OID**: `1.3.6.1.2.1.1.1.0` → **sysDescr** (System Description)

### Architecture & MIB Strategy

The **SNMP Trapd** Listener includes essential MIBs for comprehensive SNMP support:

<table><thead><tr><th width="219.71484375">MIB</th><th>Purpose</th><th>Dependencies</th></tr></thead><tbody><tr><td><strong>SNMPv2-SMI</strong></td><td>Base SMI definitions</td><td>None</td></tr><tr><td><strong>SNMPv2-TC</strong></td><td>Base TC definitions</td><td>SNMPv2-SMI</td></tr><tr><td><strong>SNMPv2-MIB</strong></td><td>Core SNMP MIB</td><td>SNMPv2-SMI, SNMPv2-TC</td></tr><tr><td><strong>IF-MIB</strong></td><td>Interface monitoring</td><td>SNMPv2-SMI</td></tr><tr><td><strong>IP-MIB</strong></td><td>IP protocol</td><td>SNMPv2-SMI, IF-MIB</td></tr><tr><td><strong>TCP-MIB</strong></td><td>TCP protocol</td><td>SNMPv2-SMI, IP-MIB</td></tr><tr><td><strong>UDP-MIB</strong></td><td>UDP protocol</td><td>SNMPv2-SMI, IP-MIB</td></tr><tr><td><strong>HOST-RESOURCES-MIB</strong></td><td>Host resources</td><td>SNMPv2-SMI</td></tr><tr><td><strong>ENTITY-MIB</strong></td><td>Entity monitoring</td><td>SNMPv2-SMI</td></tr></tbody></table>

## Prerequisites

In order to use this Listener, you must

* Enable SNMP on the device itself.&#x20;
* Specifically enable the sending of SNMP traps.&#x20;
* Configure the device to send traps to the IP address and port of the receiving SNMP management system.&#x20;
* For SNMPv3, configure the correct authentication and/or privacy settings to be used when sending traps.&#x20;

## Onum Setup

{% stepper %}
{% step %}
Log in to your Onum tenant and click **Listeners > New listener**.
{% endstep %}

{% step %}
Double-click the **SNMP Trapd** Listener.
{% endstep %}

{% step %}
Enter a **Name** for the new Listener. Optionally, add a **Description** and some **Tags** to identify the Listener.
{% endstep %}

{% step %}
In the **Version**<mark style="color:red;">**\***</mark> section, select the required SNMP protocol version between **v1**, **v2c**, and **v3**.

For **v1** and **v2c**, you'll be prompted to enter the required **Community**<mark style="color:red;">**\***</mark>. The community string acts like a simple password to authenticate communication between the SNMP manager and the SNMP agent.

For **v3**, you must choose a security level between:

* **noAuthNoPriv** - Choose this option if no authentication is required:
  * Enter your username in the **User**<mark style="color:red;">**\***</mark> field that appears.
* **authNoPriv** - Choose this option to set basic authentication:
  * Enter your username in the **User**<mark style="color:red;">**\***</mark> field
  * Select the required authentication protocol (**MD5** or **SHA**). Then, choose your **Authentication Password**<mark style="color:red;">**\***</mark> from your [Secrets](https://docs.onum.com/administration/global-settings/organization-settings/secrets-management) or click **New secret** to create a new one.
* **authPriv** - Choose this option to set authentication + encryption:
  * Enter your username in the **User**<mark style="color:red;">**\***</mark> field.
  * Select the required authentication protocol (**MD5** or **SHA**). Then, choose your **Authentication Password**<mark style="color:red;">**\***</mark> from your [Secrets](https://docs.onum.com/administration/global-settings/organization-settings/secrets-management) or click **New secret** to create a new one.
  * Select the required privacy protocol (**DES** or **AES**). Then, choose your **Privacy Password**<mark style="color:red;">**\***</mark> from your [Secrets](https://docs.onum.com/administration/global-settings/organization-settings/secrets-management) or click **New secret** to create a new one.
    {% endstep %}

{% step %}
To create a new secret:

* Give the secret a **Name**.
* Turn off the **Expiration date** option.
* Click **Add new value** and paste the secret corresponding to the user/password.
* Click **Save**.

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FlUo7CuVpPgIVm5VNjLw6%2Fnenenew.png?alt=media&#x26;token=eb7a7231-0ac2-4099-93f9-18f9ead5add1" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FTSD53FxGQOjijA3W3DhE%2Fimage.png?alt=media&#x26;token=9941a3c0-100a-4759-b603-30079fbc90de" alt=""></picture><figcaption></figcaption></figure>

{% hint style="info" %}
Learn more about secrets in Onum in [this article](https://docs.onum.com/administration/global-settings/organization-settings/secrets-management).
{% endhint %}
{% endstep %}

{% step %}
Enter the UDP port to listen for traps.
{% endstep %}

{% step %}
Finally, click **Create labels**. Optionally, you can set labels to be used for internal Onum routing of data. By default, data will be set as **Unlabeled**. Click **Create listener** when you're done.

{% hint style="info" %}
Learn more about labels in [this article](https://docs.onum.com/the-workspace/listeners/labels).
{% endhint %}
{% endstep %}
{% endstepper %}

Click **Create listener** when you're done.

## Output data

The listener converts SNMP traps into structured Onum events with the following generated fields:

<table><thead><tr><th width="170.02734375">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>_raw</code></strong></td><td>Complete trap data as JSON</td></tr><tr><td><strong><code>sourceIp</code></strong></td><td>Source IP address</td></tr><tr><td><strong><code>sourcePort</code></strong></td><td>Source port number</td></tr><tr><td><strong><code>version</code></strong></td><td>SNMP version used</td></tr><tr><td><strong><code>mibName</code></strong></td><td>MIB name if parsing is successful, <em><strong>none</strong></em> otherwise</td></tr></tbody></table>

This is an output event example:

{% code overflow="wrap" %}

```
{
  "_raw": "{\"agent_addr\":\"10.123.54.210\",\"generic_trap\":6,\"specific_trap\":1,\"enterprise\":\"1.3.6.1.4.1.18494.2\",\"variable_bindings\":{\"1.3.6.1.4.1.18494.2.1.1\":\"ACCESS\"}}",
  "sourceIp": "10.123.54.210",
  "sourcePort": 12345,
  "version": "v1",
  "mibName": "SWIFT-MIB"
}
```

{% endcode %}