../_images/logo.png

yp-snmp Introduction

yp-snmp enables the Simple Network Management Protocol (SNMP) to join the other netconfd-pro Northbound interfaces. It does this by linking to the Open Source project Net-SNMP library.

This document describes:

  • how the SNMP agent is used

  • how to convert MIB modules to YANG modules

  • how to instrument MIB modules

  • how to install MIB modules in the netconfd-pro server, and then access them with SNMP client tools (agents).

../_images/SNMP_for_web_082517.png

yp-snmp Features

The yp-snmp subsystem has the following features:

  • SNMP packet processing within the netconfd-pro server by integrating the 'libnetsnmp' packet processing within the netconfd-pro server (agent library).

  • SNMP GET request processing

  • SNMP GETNEXT request processing

  • SNMP GETBULK request processing

  • SNMP SET request processing for writable configuration objects

  • Asynchronous Notifications – traps & informs

  • Support for SNMPv3

  • SNMPv3 TSM requests over Net-SNMP-enabled TLS/TCP and DTLS/UDP transports

  • The netconfd-pro SNMP server only fully supports YANG modules that were converted from MIB using the 'smidump' tool

SNMP SET uses the existing datastore edit processor. See SNMP SET Operations for configuration and instrumentation requirements.

Building SNMP support

In order to link Net-SNMP to netconfd-pro the Net-SNMP header files have to be installed on the system to build the server.

To run the netconfd-pro server with SNMP support both the 'snmpd' and 'snmptrapd' programs must be available. To test the SNMP support, use the client tools provided by Net-SNMP.

The following instructions will install Net-SNMP and its client tools.

Note

There are many parameters for building Net-SNMP.
For other options please refer to NET-SNMP

First download the version of Net-SNMP you wish to use. The following instructions use net-snmp-5.7.3 as an example. This will install the binaries and .h header files needed:

tar -zxvf net-snmp-5.7.3.tar.gz
cd net-snmp-5.7.3
./configure --with-defaults --disable-embedded-perl --without-perl-modules
make
sudo make install

Net-SNMP is required to build the server. Use the WITH_SNMP=1 and WITH_RESTCONF=1 make flags to build netconfd-pro with SNMP SET support from the source code:

sudo make EVERYTHING=1 WITH_SNMP=1 WITH_RESTCONF=1 uninstall
make EVERYTHING=1 WITH_SNMP=1 WITH_RESTCONF=1 distclean
make EVERYTHING=1 WITH_SNMP=1 WITH_RESTCONF=1
sudo make EVERYTHING=1 WITH_SNMP=1 WITH_RESTCONF=1 install

To test the SNMP client features, GET, WALK, etc., use the built-in IF-MIB module.

cd libif-mib
make
sudo make install

To run the netconfd-pro server, launch it with the parameters below to see the debug messages as the examples are running. The load-module command loads the IF-MIB SIL described previously:

sudo netconfd-pro with-snmp=true module=IF-MIB

Note

The server needs to be run at the root level as it uses restricted ports as part of the SNMP standard.

snmpget example

To run snmpget against the loaded IF-MIB SIL:

snmpget -v 2c -c public localhost 1.3.6.1.2.1.2.1.0

Example output:

IF-MIB::ifNumber.0 = INTEGER: 32

snmpwalk example

To run snmpwalk against the loaded IF-MIB SIL:

snmpwalk -v 2c -c public localhost 1.3.6.1.2.1.2.2

Example output:

IF-MIB::ifIndex.20 = INTEGER: 20
IF-MIB::ifIndex.25 = INTEGER: 25
IF-MIB::ifIndex.30 = INTEGER: 30
IF-MIB::ifDescr.25 = STRING: Description string
IF-MIB::ifDescr.30 = STRING: Test string
IF-MIB::ifType.20 = INTEGER: softwareLoopback(24)
IF-MIB::ifType.25 = INTEGER: softwareLoopback(24)
IF-MIB::ifType.30 = INTEGER: softwareLoopback(24)
IF-MIB::ifMtu.20 = INTEGER: 1111
IF-MIB::ifMtu.25 = INTEGER: 2222
IF-MIB::ifMtu.30 = INTEGER: 1111
IF-MIB::ifSpeed.20 = Gauge32: 2030
IF-MIB::ifSpeed.25 = Gauge32: 10
IF-MIB::ifSpeed.30 = Gauge32: 2030
IF-MIB::ifPhysAddress.20 = STRING: aa:bb:cc:dd:0:ff
IF-MIB::ifPhysAddress.25 = STRING: aa:bb:cc:dd:0:ff
IF-MIB::ifPhysAddress.30 = STRING: aa:bb:cc:dd:0:ff
IF-MIB::ifAdminStatus.20 = INTEGER: testing(3)
IF-MIB::ifAdminStatus.25 = INTEGER: testing(3)
IF-MIB::ifAdminStatus.30 = INTEGER: testing(3)
IF-MIB::ifOperStatus.20 = INTEGER: testing(3)
IF-MIB::ifOperStatus.25 = INTEGER: testing(3)
IF-MIB::ifOperStatus.30 = INTEGER: testing(3)
IF-MIB::ifLastChange.20 = Timeticks: (33) 0:00:00.33
IF-MIB::ifLastChange.25 = Timeticks: (33) 0:00:00.33
IF-MIB::ifLastChange.30 = Timeticks: (33) 0:00:00.33
IF-MIB::ifInOctets.20 = Counter32: 2
IF-MIB::ifInOctets.25 = Counter32: 2
IF-MIB::ifInOctets.30 = Counter32: 2
IF-MIB::ifInUcastPkts.20 = Counter32: 3
IF-MIB::ifInUcastPkts.25 = Counter32: 3
IF-MIB::ifInUcastPkts.30 = Counter32: 3
IF-MIB::ifInDiscards.20 = Counter32: 5
IF-MIB::ifInDiscards.25 = Counter32: 5
IF-MIB::ifInDiscards.30 = Counter32: 5
IF-MIB::ifInErrors.20 = Counter32: 6
IF-MIB::ifInErrors.25 = Counter32: 6
IF-MIB::ifInErrors.30 = Counter32: 6
IF-MIB::ifInUnknownProtos.20 = Counter32: 7
IF-MIB::ifInUnknownProtos.25 = Counter32: 7
IF-MIB::ifInUnknownProtos.30 = Counter32: 7
IF-MIB::ifOutDiscards.20 = Counter32: 9
IF-MIB::ifOutDiscards.25 = Counter32: 9
IF-MIB::ifOutDiscards.30 = Counter32: 9
IF-MIB::ifOutErrors.20 = Counter32: 10
IF-MIB::ifOutErrors.25 = Counter32: 10
IF-MIB::ifOutErrors.30 = Counter32: 10

snmpbulkget example

To run snmpbulkget against the loaded IF-MIB SIL:

snmpbulkget -v 2c -Cn1 -Cr24 -c public localhost IF-MIB::ifDescr.2 IF-MIB::ifAdminStatus.2

Example output:

IF-MIB::ifAdminStatus.20 = INTEGER: testing(3)
IF-MIB::ifAdminStatus.25 = INTEGER: testing(3)
IF-MIB::ifAdminStatus.30 = INTEGER: testing(3)
IF-MIB::ifOperStatus.20 = INTEGER: testing(3)
IF-MIB::ifOperStatus.25 = INTEGER: testing(3)
IF-MIB::ifOperStatus.30 = INTEGER: testing(3)
IF-MIB::ifLastChange.20 = Timeticks: (33) 0:00:00.33
IF-MIB::ifLastChange.25 = Timeticks: (33) 0:00:00.33
IF-MIB::ifLastChange.30 = Timeticks: (33) 0:00:00.33
IF-MIB::ifInOctets.20 = Counter32: 2
IF-MIB::ifInOctets.25 = Counter32: 2
IF-MIB::ifInOctets.30 = Counter32: 2
IF-MIB::ifInUcastPkts.20 = Counter32: 3
IF-MIB::ifInUcastPkts.25 = Counter32: 3
IF-MIB::ifInUcastPkts.30 = Counter32: 3
IF-MIB::ifInDiscards.20 = Counter32: 5
IF-MIB::ifInDiscards.25 = Counter32: 5
IF-MIB::ifInDiscards.30 = Counter32: 5
IF-MIB::ifInErrors.20 = Counter32: 6
IF-MIB::ifInErrors.25 = Counter32: 6
IF-MIB::ifInErrors.30 = Counter32: 6
IF-MIB::ifInUnknownProtos.20 = Counter32: 7
IF-MIB::ifInUnknownProtos.25 = Counter32: 7
IF-MIB::ifInUnknownProtos.30 = Counter32: 7

SNMP SET Operations

The native SNMP endpoint accepts SET requests using SNMPv1, SNMPv2c, and SNMPv3. All varbinds in a request are converted into one merge payload and submitted together to the existing patch/edit processor. Normal validation, NACM authorization, SIL callbacks, and transaction rollback apply. SET does not bypass instrumentation or write operational data directly.

The target leaf and its ancestors must be configuration data. Read-only objects and list keys cannot be assigned directly by SET. Keys are supplied in the instance OID. The smiv2:max-access or smi:max-access extension, when present, must allow read-write or read-create access. A read-write table column requires an existing row in running; SET returns noCreation if that row is absent. A read-create column may create a row, subject to normal schema validation and SIL callbacks.

A SET requires a write-enabled Net-SNMP user or community and a matching write view. The SNMPv3 security name, or the security name associated with a community, is used as the NACM username. Existing read-only user examples must not be used for SET. Configure NACM permissions for that username and the target configuration objects.

For example, with an existing instrumented interface entry and suitable SNMPv3 user configuration, a manager can set ifAdminStatus using its numeric enumeration value:

snmpset -v 3 -l authPriv -u operator localhost 1.3.6.1.2.1.2.2.1.7.2 i 1

This example assumes the manager's Net-SNMP configuration supplies its security credentials. The final OID component selects interface index 2.

SET rejects a request while another client's candidate edits or a confirmed commit are pending. This prevents SET from committing or discarding unrelated configuration changes. Startup persistence follows the existing edit processor and the server's separate-startup configuration.

Integer and enumeration values, TruthValue booleans, Unsigned32/Gauge32, TimeTicks, Counter32/Counter64, object identifiers, strings, binary values, and physical addresses are decoded according to their YANG types. Invalid wire types, lengths, and values produce SNMP errors. Unsupported value or index encodings are rejected. Index handling uses the existing SNMP OID mapping; numeric, enumeration, and length-prefixed string indexes are supported. AgentX SET phases are not supported by this implementation.

The converted MIB models need configuration-aware instrumentation. After regenerating the models as described in Creating MIB Instrumentation, regenerate and implement the SIL edit callbacks for writable objects. Existing GET2-only instrumentation does not implement writes merely because the schema now marks an object as writable. RowStatus and other MIB-specific behavior must be implemented by the instrumentation.

Traps and Informs

NOTE: currently only SNMP Traps Version 2 are supported by the server.

To demonstrate SNMP traps make sure the following line exists in the 'snmpd.conf' file:

# send v2 traps
trap2sink localhost public 162

In order to collect and display the traps the following application can be used. 'snmptrapd' is an SNMP application that receives and logs SNMP TRAP and INFORM messages.

sudo snmptrapd -d -f -Lo:

To test that the setup is correct and that notifications are being received correctly, send a "linkDown" SNMP trap from a second terminal session using the following command:

snmptrap -v 2c -c public localhost '' 1.3.6.1.6.3.1.1.5.3 ifIndex i 2 ifAdminStatus i 1 ifOperStatus i 1

Example output:

sudo snmptrapd -d -f -Lo:
NET-SNMP version 5.7.3

Received 119 byte packet from UDP: [127.0.0.1]:47154->[127.0.0.1]:162
0000: 30 75 02 01  01 04 06 70  75 62 6C 69  63 A7 68 02    0u.....public.h.
0016: 04 31 08 5C  A0 02 01 00  02 01 00 30  5A 30 0F 06    .1.\.......0Z0..
0032: 08 2B 06 01  02 01 01 03  00 43 03 45  C2 E2 30 17    .+.......C.E..0.
0048: 06 0A 2B 06  01 06 03 01  01 04 01 00  06 09 2B 06    ..+...........+.
0064: 01 06 03 01  01 05 03 30  0E 06 09 2B  06 01 02 01    .......0...+....
0080: 02 02 01 01  02 01 02 30  0E 06 09 2B  06 01 02 01    .......0...+....
0096: 02 02 01 07  02 01 01 30  0E 06 09 2B  06 01 02 01    .......0...+....
0112: 02 02 01 08  02 01 01                                 .......
                   .......

2017-07-22 10:40:21 localhost [UDP: [127.0.0.1]:47154->[127.0.0.1]:162]:
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (4571874) 12:41:58.74  SNMPv2- MIB::snmpTrapOID.0 = OID: IF-MIB::linkDown
IF-MIB::ifIndex = INTEGER: 2 IF-MIB::ifAdminStatus = INTEGER: up(1) IF-MIB::ifOperStatus = INTEGER: up(1)