How to Provision RoadRunner to Support SNMP

Overview

In this article, we'll be discussing how to provision RoadRunner to support Simple Network Management Protocol (SNMP). Skylight Analytics currently supports SNMPv2 as a mechanism for delivering alert notifications to northbound systems.

Prerequisites:

Following articles are prerequisites to before setting up the SNMP trap receiver.

Alerting
Alert Policies

SNMP Connector Configuration

The connector config REST API can generate a MQTT token and provide a MQTT to SNMP client. The following example uses Postman to execute the API requests.

1. Authenticate with Skylight Analytics using your username and password. Record the cookie in the response; this will be used in subsequent requests.

{{protocol}}://{{host}}/api/v1/auth/login

2. POST a payload to {{protocol}}://{{host}}/api/v2/connector-configs

{
    "data": {
        "type": "connectorConfigs",
        "attributes": {
            "name": "<CONNECTOR NAME>",
            "tenantId": "<Tenant Name>",
            "datatype": "connectorConfig",
            "pollingFrequency": 60,
            "type": "FileWatcher",
            "zone": "<ZONE NAME>",
            "username": "<USER NAME>",
            "url": "/var/lib/data/snmp",
            "SNMPTrapSenderConfig": {
                "trapTargetHost": "<SNMP Trap Target HOST/IP>",
                "trapTargetPort": "162",
                "community": "public"
            }
        }
    }
}

• You may see the below error while sending the above post call.

{
    "code": 415,
    "message": "unsupported media type \"application/json\", only [application/vnd.api+json] are allowed"
}

• To fix this error, add a header called Content-Type application/vnd.api+json, as seen below

• After fixing the error code, execute Step 2. You will see that snmp connector will be created with response code 201.

• Replace with your tenant ID (this is not the tenant name).

• To get your Tenant ID, you can CURL the following URL or go to this page in your web browser.

curl 'https://<your tenant URL>/api/v1/onboarding/tenant-info' 
{ 
"data": {
 "attributes": {
 "tenantId": "<< TENANT ID >>",
 "tenantName": "<< TENANT NAME >>" }, "id": "<< TENANT NAME >>",
 "type": "tenant-info"
 }
 }

• Replace < ZONE NAME > with a unique zone identifier (anything unique, such as 1234).

• Replace < USER NAME > with the Skylight tenant admin user that is creating the connector configuration (the same username that an admin would log in to Skylight as (e.g. admin@tenant.com).

Optional: If you will be using this connector for ingesting CSV files, replace < Data Ingestion URI > with the path to your ingestion files (e.g. /var/lib/data/pocs/jyu/cybetron/rr/ ).

Configure the SNMPTrapSenderConfig with your SNMP Trap Receiver. All alerts from Skylight Analytics will be sent to the trap receiver configured here.

• Replace <SNMP Trap Target HOST/IP> with the Hostname/IP of the SNMP Trap Receiver
• Replace trapTargetPort with the SNMP Trap Receiver's port (usually 162)
• Replace community with the SNMP Trap Receiver's community string

3. Log in to Skylight Analytics and find your Connector Configuration in the Settings.

4. Download the connector.

5. Follow the guide below to run your connector.

Deploying Roadrunner in Docker

• Once the RR has successfully connected and has been configured, you will see SNMP RoadRunner logs as below:

$ sudo docker logs -tf <'container id or container name'>

6. You can download your connector config using the API call below:

GET {{protocol}}://{{host}}/api/v2/connector-configs

Setting up the SNMP Trap Receiver to See Alerts

You can create an SNMP trap receiver with a docker-snmp tool to see whether or not snmp trap is being triggered.

To create an SNMP trap receiver with a docker container**

1. Download the SNMP trap receiver from docker hub repository

https://hub.docker.com/r/lidaheemc/docker-snmp

2. Install the SNMP trap receiver.

sudo docker pull lidaheemc/docker-snmp

3. Run and Test the SNMP trap receiver.

sudo docker run -d -p 162:162/udp --name snmptrap-receiver -v $PWD/snmp:/var/log/snmp lidaheemc/docker-snmp

4. Check docker SNMP trap container status.
   

• Once the server is running you can view the log by using the below command:

docker logs -tf --tail 100 <container id or container name>

You can see the trap logs as below:

5. Check the snmp-trap receiver log i.e. below:

6. Now your connector will forward alerts from MQTT to the configured SNMP trap receiver.

ACCEDIAN-SMI.mib

For quick reference, the following mapping are used:

SNMPID:                 ".1.3.6.1.4.1.22420.3.1", 
ObjectIDOID:            ".1.3.6.1.4.1.22420.3.2", 
ObjectNameOID:          ".1.3.6.1.4.1.22420.3.3", 
ObjectTypeOID:          ".1.3.6.1.4.1.22420.3.4", 
DirectionOID:           ".1.3.6.1.4.1.22420.3.5", 
PolicyIDOID:            ".1.3.6.1.4.1.22420.3.6", 
MetricOID:              ".1.3.6.1.4.1.22420.3.7", 
AlertTypeOID:           ".1.3.6.1.4.1.22420.3.8", 
SourceOID:              ".1.3.6.1.4.1.22420.3.9", 
ProcessedTimestampOID:  ".1.3.6.1.4.1.22420.3.10", 
StartTimestampOID:      ".1.3.6.1.4.1.22420.3.11", 
TimestampOID:           ".1.3.6.1.4.1.22420.3.12", 
PolicyNameOID:          ".1.3.6.1.4.1.22420.3.13", 
AlertStateOID:          ".1.3.6.1.4.1.22420.3.14",

SNMP Trap MIB for alerts on capture based metrics

The trap definition is in the file PERFORMANCEVISION-MIB.txt

PERFORMANCEVISION-MIB.txt

For quick reference, the following mapping are used:

SNMPID:                           ".1.3.6.1.4.1.36773.3.1", 
CaptureMetaNameOID:               ".1.3.6.1.4.1.36773.3.1.1",
CaptureMetaFiringOID:             ".1.3.6.1.4.1.36773.3.1.2", 
CaptureMetaCertaintyPercentOID:   ".1.3.6.1.4.1.36773.3.1.3", 
CaptureMetaDescOID:               ".1.3.6.1.4.1.36773.3.1.4",

Sending Alert Metadata in SNMP Trap

SNMP Traps can retrieve metadata defined on the object. The maximum configuration is set to five for defining the alertMetaDataKey(x) to be returned. When this feature is enabled in the Roadrunner configuration it will search for the specified metadata key and retrieve the value if found. A blank string will be returned if the key is not located or if the key was not defined in one of the alertMetaDataKey attributes.

To configure the connector

1. Create the new connector configuration in the UI by going to Settings → Connectors → New

2. Select FileWatcher type and fill in the rest of the fields.

3. Once the connector is created, retrieve the current configuration via the connector-configs API.
   Note: The connector config ID will be required to do the update, you can retireve this in one of the following two ways:

   • Searching for it in the UI once it is created and select it. Once selected the URL in the browser will display the UID for this connector as shown below selection=c22f0050-7070-45cd-a830-d6e1cdacb2d7

Or:

• Using a tool such as postman all of the connector configs can be retrieved by using the following api: {{serverAddress}}/api/v2/connector-configs (replace {{serverAddress}} with the address of the system). This will return all of the connector configs which can be searched for the one in question.

Once the connector configuration UID has been obtained, the configuration must be changed to allow for the connection to the MQTT service.

To change the configuration to allow connection to MQTT service:

1. Retrieve the connector configuration using the following GET:{{serverAddress}}/api/v2/connector-configs/{{connectorConfigId}}
   (replace {{connectorConfigId}} with the value retrieved above)
2. Modify the body of the connector config to include both the SNMPTrapSenderConfig and the MQTTConfig.
   Both of these sections need the variable keys replaced represented by the double curly brace:

{
    "data": {
        "attributes": {
            "SNMPTrapSenderConfig": {
                "trapTargetHost": "192.168.1.6",
                "trapTargetPort": "162",
                "community": "public",
                "alertMetaDataEnabled": {{true/false}},
                "alertMetaDataKey1": "{{metaDataKey1}}",
                "alertMetaDataKey2": "{{metaDataKey2}}",
                "alertMetaDataKey3": "{{metaDataKey3}}",
                "alertMetaDataKey4": "{{metaDataKey4}}",
                "alertMetaDataKey5": "{{metaDataKey5}}"
            },
            "MQTTConfig": {
                "brokerURI": "wss://{{serverAddress}}:443/mqtt",
                "clientID": "{{connectorConfigName}}",
                "notificationTopic": "{{tenantName}}/v1/notifications/alert/public/#",
                "user": "{{userName}}"
            }
            .... additional information returned when the configuration was retrieved ....
     }
}

3. Once the payload has been modified perform a PATCH to send the required updates to the system: {{serverAddress}}/api/v2/connector-configs/{{connectorConfigId}} (replace {{connectorConfigId}} with the value retrieved above)

4. Download and install the new connector.

SNMP Trap Reference

		SNMPID:                ".1.3.6.1.4.1.22420.3.50.1",
		ObjectIDOID:           ".1.3.6.1.4.1.22420.3.2",
		ObjectNameOID:         ".1.3.6.1.4.1.22420.3.3",
		ObjectTypeOID:         ".1.3.6.1.4.1.22420.3.4",
		DirectionOID:          ".1.3.6.1.4.1.22420.3.5",
		PolicyIDOID:           ".1.3.6.1.4.1.22420.3.6",
		MetricOID:             ".1.3.6.1.4.1.22420.3.7",
		AlertTypeOID:          ".1.3.6.1.4.1.22420.3.8",
		SourceOID:             ".1.3.6.1.4.1.22420.3.9",
		ProcessedTimestampOID: ".1.3.6.1.4.1.22420.3.10",
		StartTimestampOID:     ".1.3.6.1.4.1.22420.3.11",
		TimestampOID:          ".1.3.6.1.4.1.22420.3.12",
		PolicyNameOID:         ".1.3.6.1.4.1.22420.3.13",
		AlertStateOID:         ".1.3.6.1.4.1.22420.3.14",
		ThresholdValueOID:     ".1.3.6.1.4.1.22420.3.15",
		MetaDataKey1OID:       ".1.3.6.1.4.1.22420.3.16",
		MetaDataKey2OID:       ".1.3.6.1.4.1.22420.3.17",
		MetaDataKey3OID:       ".1.3.6.1.4.1.22420.3.18",
		MetaDataKey4OID:       ".1.3.6.1.4.1.22420.3.19",
		MetaDataKey5OID:       ".1.3.6.1.4.1.22420.3.20",
		MetaDataVal1OID:       ".1.3.6.1.4.1.22420.3.21",
		MetaDataVal2OID:       ".1.3.6.1.4.1.22420.3.22",
		MetaDataVal3OID:       ".1.3.6.1.4.1.22420.3.23",
		MetaDataVal4OID:       ".1.3.6.1.4.1.22420.3.24",
		MetaDataVal5OID:       ".1.3.6.1.4.1.22420.3.25",
		TriggeredValueOID:     ".1.3.6.1.4.1.22420.3.26",

SNMP Trap Example Payload

If alertMetaDataEnabled in the connectorConfig is set to true, the following values will be returned:

[{Name:.1.3.6.1.6.3.1.1.4.1.0 Type:ObjectIdentifier Value:.1.3.6.1.4.1.22420.3.50.1 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.2 Type:OctetString Value:33761-F648E24B-AB01-4B95-8CC6-1AB6611FCCC0 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.3 Type:OctetString Value:E21600_ABC_2_ENB_AF22 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.4 Type:OctetString Value:twamp-sf Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.5 Type:OctetString Value:0 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.6 Type:OctetString Value:c79123a7-27d4-472e-a541-789a334f0a94 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.7 Type:OctetString Value:delayP95 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.8 Type:OctetString Value:twamp-sf Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.9 Type:OctetString Value:skylight-spark Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.10 Type:OctetString Value:1688834954653 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.11 Type:OctetString Value:1688834954653 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.12 Type:OctetString Value:1688834954653 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.13 Type:OctetString Value:Test Name SQA_TWAMP_1686775324645909 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.14 Type:OctetString Value:raised Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.15 Type:OctetString Value:15000.0 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.16 Type:OctetString Value:region Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.17 Type:OctetString Value:target_city Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.18 Type:OctetString Value:source_city Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.19 Type:OctetString Value:service_class Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.20 Type:OctetString Value:uplink_route Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.21 Type:OctetString Value:north east Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.22 Type:OctetString Value:ottawa Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.23 Type:OctetString Value:montreal Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.24 Type:OctetString Value:af22 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.25 Type:OctetString Value:rtr0121-rtr1447-rtr1847-rtr1848-rtr1849-rtr1851 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.26 Type:OctetString Value:16000.0 Logger:<nil>}]

If alertMetaDataEnabled is not set or set to false the following values will be returned, you will notice that 16 to 25 are no longer present in the returned payload. This is due to a new parameter being added after the metaData and to ensure backwards compatibility and the numbering was not reordered.

[{Name:.1.3.6.1.6.3.1.1.4.1.0 Type:ObjectIdentifier Value:.1.3.6.1.4.1.22420.3.50.1 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.2 Type:OctetString Value:33761-F648E24B-AB01-4B95-8CC6-1AB6611FCCC0 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.3 Type:OctetString Value:E21600_ABC_2_ENB_AF22 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.4 Type:OctetString Value:twamp-sf Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.5 Type:OctetString Value:0 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.6 Type:OctetString Value:c79123a7-27d4-472e-a541-789a334f0a94 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.7 Type:OctetString Value:delayP95 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.8 Type:OctetString Value:twamp-sf Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.9 Type:OctetString Value:skylight-spark Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.10 Type:OctetString Value:1688834954653 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.11 Type:OctetString Value:1688834954653 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.12 Type:OctetString Value:1688834954653 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.13 Type:OctetString Value:Test Name SQA_TWAMP_1686775324645909 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.14 Type:OctetString Value:raised Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.15 Type:OctetString Value:15000.0 Logger:<nil>}
{Name:.1.3.6.1.4.1.22420.3.26 Type:OctetString Value:16000.0 Logger:<nil>}]