Example Path: examples/snmp/TableWrite

Warning: SNMP DYNAMIC TABLE WRITES ARE BETA AND NOT RELEASED

SNMP Table Write Example

Overview

This example demonstrates a writable SNMP table MIB on a NetBurner device. It is the tabular complement to the scalar example in ../CustomMIB: where that example shows how to wire up a handful of individual SNMPREADFUNC / SNMPWRITEFUNC scalars, this one shows how to register N rows of M columns at runtime, sharing a single read dispatcher and one write dispatcher per column type.

Use the table pattern when you have repeating data (e.g. one row per sensor). Use scalars when each value is a true singleton (community strings, trap destination, etc.).

Features

SNMP agent listening on UDP port 161 for queries
Custom read/write scalar MIB variables under 1.3.6.1.4.1.8174.1.* covering every supported type (String, Integer, Gauge, MAC, TimeTicks, Counter, OID, IpAddress)
A dynamic SNMP table under 1.3.6.1.4.1.8174.10.1.* with the same nine column types, indexed by TestIndex
A read-only scalar testTableNumber (1.3.6.1.4.1.8174.9.0) reporting the current row count
Runtime row addition (A command and AddTables(5) at startup)
SNMP enterprise trap with custom variable bindings
Interactive command processor over Telnet (port 23) and serial
HTTP web server on port 80
User authentication for command sessions

Network Ports

Port 23  (TCP)  - Telnet command interface
Port 80  (TCP)  - HTTP web server
Port 161 (UDP)  - SNMP agent (inbound queries)
Port 162 (UDP)  - SNMP trap destination (outbound)

MIB Structure

Defined in mib/NburnTableTest_Mib.txt and implemented in src/test.cpp.

Scalars (under netba = 1.3.6.1.4.1.8174.1):

OID                       Name              Type        Access
3.6.1.4.1.8174.1.2.0   ATestString       String      Read-Write
3.6.1.4.1.8174.1.3.0   ATestInteger      INTEGER     Read-Write
3.6.1.4.1.8174.1.4.0   ATestGauge        Gauge       Read-Write
3.6.1.4.1.8174.1.5.0   ATestMacAddr      PhysAddress Read-Write
3.6.1.4.1.8174.1.6.0   ATestTimeTick     TimeTicks   Read-Write
3.6.1.4.1.8174.1.7.0   ATestCounter      Counter     Read-Write
3.6.1.4.1.8174.1.8.0   ATestOid          OBJECT ID   Read-Write
3.6.1.4.1.8174.1.9.0   ATTestIP          IpAddress   Read-Write
3.6.1.4.1.8174.9.0     testTableNumber   INTEGER     Read-Only

Table (under 1.3.6.1.4.1.8174.10):

TestTable . testEntry . column . index

1.3.6.1.4.1.8174.10 . 1 . 1..9 . <TestIndex>

Columns within testEntry:

TestIndex (INTEGER, index)        6 TestTimeTick  (TimeTicks)
TestString    (DisplayString)     7 TestCounter   (Counter)
TestInteger   (INTEGER)           8 TestOid       (OBJECT ID)
TestGauge     (Gauge)             9 TTestIP       (IpAddress)
TestMacAddr   (PhysAddress)

Build Instructions

SNMP support is enabled by the predef-overload.h file located at:

overload/nbrtos/include/predef-overload.h

which contains:

#define ENABLE_SNMP (1)

Project Files

makefile                            - Build configuration
src/main.cpp                        - Globals (AppName, SYSDESC,
                                      SYSOID, TheSnmpServer) plus a
                                      UserMain that brings up the
                                      stack, calls InitVars() and
                                      AddTables(5), then runs
                                      StartCommandLine() and idles
src/commands.h
src/commands.cpp                    - Telnet/serial CLI -- five
                                      file-scope Process* callbacks
                                      plus the public
                                      StartCommandLine().  The 'A'
                                      command calls AddTables() from
                                      test.h
src/trap.h
src/trap.cpp                        - SNMP trap PDU builder +
                                      SendTestTrap().  Called from
                                      the 'T' command in commands.cpp
src/test.h
src/test.cpp                        - Scalar read/write callbacks,
                                      table read dispatcher,
                                      per-column write handlers,
                                      plus public InitVars() and
                                      AddTables()
mib/NburnTableTest_Mib.txt          - SMI MIB definition
overload/nbrtos/include/
  predef-overload.h                 - Build flag to enable SNMP

How the Table Code Works

The table is built around three pieces in src/test.cpp, exposed via src/test.h:

AddTableElementtestEntry(void *data_el, snmp_typeINTEGER index) For one row, calls AddSnmpEntry(...) for each column (read) and AddSnmpWriteEntry(...) for each writable column. The same opaque data_el pointer is handed to the dispatchers on every callback.
PutTableElementstestEntry(SNMP_Request &req, void *data_el, int subid) The single read dispatcher. data_el identifies the row; subid (1..9) identifies the column. It writes the right ASN.1 type into req.put_asn for that field.
WrtTEtestEntry<Column>(value, bTest, void *pElement) One write handler per column type. bTest is the SNMP two-pass set protocol – validate on the first pass, commit on the second.

AddTables(int na) is the public startup loop: allocate a row, populate the struct fields, then call AddTableElementtestEntry to register it. The interactive A command does the same thing at runtime by calling AddTables(5) from commands.cpp.

The CLI ('A' to add rows, 'D' to dump the SNMP tree, 'T' to send a trap, logout to end the session) lives in src/commands.cpp, exposed through a single public function StartCommandLine() in src/commands.h. The trap PDU itself is built in src/trap.cpp; commands.cpp includes trap.h for SendTestTrap() and test.h for AddTables().

Commands

Connect via serial console or Telnet to port 23. Log in with any username and password that are not identical (e.g., user: "hello", pass: "world").

A        - Add 5 more rows to the test table
D        - Dump the full SNMP MIB tree to the console
T        - Send a test SNMP enterprise trap
logout   - Close the current session
(other)  - Display command help

Testing with the net-snmp Command-Line Tools

Warning: Dynamic table writes are BETA in this SDK. The command lines below show the syntax; behavior may not be fully working in all cases.

The NetBurner SDK ships a portable net-snmp 5.9.1 distribution at:

C:\nburn\snmp\net-snmp\

containing snmpget.exe, snmpset.exe, snmpwalk.exe, snmptable.exe, snmptranslate.exe, etc. The standard MIBs (RFC1155-SMI, RFC1213-MIB, SNMPv2-SMI, SNMPv2-TC, ...) live alongside the per-example MIBs at:

C:\nburn\snmp\mibs\

If you copy this example's mib\NburnTableTest_Mib.txt into that mibs folder, the tools will resolve symbolic names like ATestString.0, testTableNumber.0, TestInteger.0, etc. from the example's MIB. Without the copy you can still use full numeric OIDs and everything works.

All examples below use the example IP address 192.168.1.100. Substitute your NetBurner's actual IP (run nbdiscovery if you do not know it).

One-time setup so you can copy/paste cleanly

Windows cmd:

set PATH=C:\nburn\snmp\net-snmp;PATH% set MIBDIRS=C:\nburn\snmp\mibs set MIBS=ALL

PowerShell:

$env:PATH = "C:\nburn\snmp\net-snmp;$env:PATH" $env:MIBDIRS = "C:\nburn\snmp\mibs" $env:MIBS = "ALL"

Bash (Git Bash / MSYS):

export PATH="/c/nburn/snmp/net-snmp:$PATH" export MIBDIRS="/c/nburn/snmp/mibs" export MIBS="ALL"

After that the -M / -m flags below can be omitted. All examples include them explicitly so they work even without the env vars.

snmpget – read scalars and the row count

snmpget -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 testTableNumber.0 snmpget -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 ATestString.0 ATestInteger.0 snmpget -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 ATTestIP.0 ATestMacAddr.0

Numeric form (no MIB needed):

snmpget -v2c -c public 192.168.1.100 .1.3.6.1.4.1.8174.9.0 snmpget -v2c -c public 192.168.1.100 .1.3.6.1.4.1.8174.1.3.0

snmpwalk – enumerate scalars and the table

Walk the scalars subtree:

snmpwalk -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 .1.3.6.1.4.1.8174.1

Walk the entire test table (9 columns x N rows):

snmpwalk -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 .1.3.6.1.4.1.8174.10

Show the table as a grid:

snmptable -v2c -c public -M C:\nburn\snmp\mibs -m ALL -Cb 192.168.1.100 .1.3.6.1.4.1.8174.10

snmpset – write scalars and table cells

Type letter goes between the OID and the value: s = string, i = integer, a = IpAddress, u = unsigned, c = counter, t = TimeTicks, o = OID, x = hex string

Set a string scalar:

snmpset -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 ATestString.0 s "hello"

Set an integer scalar:

snmpset -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 ATestInteger.0 i 42

Set an IpAddress scalar:

snmpset -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 ATTestIP.0 a 192.168.1.7

Set a single table cell (TestString of row 0):

snmpset -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 .1.3.6.1.4.1.8174.10.1.2.0 s "row0string"

Set multiple cells in one PDU (one set call, two varbinds):

snmpset -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 .1.3.6.1.4.1.8174.10.1.3.0 i 100 .1.3.6.1.4.1.8174.10.1.4.0 u 250

Always confirm with a follow-up snmpget:

snmpget -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 .1.3.6.1.4.1.8174.10.1.2.0

Adding rows at runtime

Press A on the Telnet (port 23) or serial command processor to add 5 more rows. Re-walk the table to see the new entries appear:

snmpwalk -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 .1.3.6.1.4.1.8174.10 snmpget -v2c -c public -M C:\nburn\snmp\mibs -m ALL 192.168.1.100 testTableNumber.0

snmptranslate – offline OID name/number lookup

snmptranslate -M C:\nburn\snmp\mibs -m ALL -On testTableNumber.0 snmptranslate -M C:\nburn\snmp\mibs -m ALL .1.3.6.1.4.1.8174.10.1.2.0

Troubleshooting

Cannot find module (NBURNSAMPLE-MIB) Copy this example's mib\NburnTableTest_Mib.txt to C:\nburn\snmp\mibs\ and retry.

Timeout Verify with ping 192.168.1.100 and confirm the device is on the same subnet. SNMP listens on UDP/161; check Windows Firewall.

Error in packet, Reason: (readOnly) You used the read community on a write operation. Use the write community in -c for snmpset.

Error in packet, Reason: notWritable / wrongType / wrongValue The agent rejected the SET. notWritable means the column has no AddSnmpWriteEntry() registration; wrongType means the type letter did not match the column's MIB SYNTAX; wrongValue means the value failed validation in the WrtTE_xxx() handler's bTest pass.

IpAddress reads back byte-reversed Known issue in older SDKs in nbrtos\source\snmp\asn1.cpp ASN::GetIPAddr. See CustomMIB ReadMe for context.

SNMP System Identifiers

sysDescr.0 : "NetBurner SNMP Test application" sysObjectID.0 : 1.3.6.1.4.1.8174.2.40