govpp-snmp-agentx/README.md

VPP SNMP AgentX Bridge

A Go application that bridges VPP (Vector Packet Processing) interface statistics to SNMP using the AgentX protocol. It queries VPP interface counters and exposes them via the standard IF-MIB (1.3.6.1.2.1.31.1.1.1) for SNMP monitoring.

Features

• Real-time VPP interface statistics via SNMP
• Standard IF-MIB compliance (ifXTable)
• AgentX protocol support (TCP and Unix sockets)
• Configurable interface index offset to avoid conflicts
• Configurable polling intervals
• Thread-safe operation with proper synchronization

Architecture

VPP Stats Socket → VPP Stats Client → Interface MIB → AgentX → SNMP Master Agent

The application consists of four main components:

1. VPP Stats Client (vppstats/): Connects to VPP stats socket and retrieves interface counters
2. Interface MIB (ifmib/): Maps VPP statistics to SNMP IF-MIB structure
3. AgentX Client (agentx/): Handles AgentX protocol connection and MIB registration
4. Main Application: Orchestrates the components and handles configuration

Build Instructions

Development Build

go build -o govpp-snmp-agentx .

Static Binary Build

For deployment without Go runtime dependencies:

# Linux static binary
CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-extldflags "-static"' -o govpp-snmp-agentx .

# Cross-compile for different architectures
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -ldflags '-extldflags "-static"' -o govpp-snmp-agentx-linux-amd64 .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -a -ldflags '-extldflags "-static"' -o govpp-snmp-agentx-linux-arm64 .

Release Build with Version Info

VERSION=$(git describe --tags --always --dirty)
BUILD_TIME=$(date -u '+%Y-%m-%d_%H:%M:%S')
CGO_ENABLED=0 go build -ldflags "-X main.version=${VERSION} -X main.buildTime=${BUILD_TIME}" -o govpp-snmp-agentx .

Usage

Basic Usage

# Run with default settings
./govpp-snmp-agentx

# Run with custom AgentX address
./govpp-snmp-agentx -agentx.addr 127.0.0.1:705

# Run with Unix socket AgentX connection
./govpp-snmp-agentx -agentx.addr /var/agentx/master

Command Line Flags

General Application Flags

Flag	Default	Description
-debug	false	Enable debug logging
-vppcfg	""	VPP configuration YAML file to read interface descriptions from

AgentX Module Flags

Flag	Default	Description
-agentx.addr	localhost:705	AgentX master agent address (hostname:port or Unix socket path)

VPP Statistics Module Flags

Flag	Default	Description
-vppstats.api.addr	/var/run/vpp/api.sock	VPP API socket path
-vppstats.stats.addr	/var/run/vpp/stats.sock	VPP statistics socket path
-vppstats.period	10	Interval in seconds for querying VPP interface stats
-vppstats.ifindex-offset	1000	Offset to add to VPP interface indices for SNMP

Examples

# Enable debug logging
./govpp-snmp-agentx -debug

# Custom polling interval (5 seconds)
./govpp-snmp-agentx -vppstats.period 5

# Custom VPP stats socket
./govpp-snmp-agentx -vppstats.stats.addr /custom/path/stats.sock

# Custom VPP API socket
./govpp-snmp-agentx -vppstats.api.addr /custom/path/api.sock

# Custom interface index offset (start at 2000)
./govpp-snmp-agentx -vppstats.ifindex-offset 2000

# With VPP configuration file for interface descriptions
./govpp-snmp-agentx -vppcfg /etc/vpp/vppcfg.yaml

# Full configuration
./govpp-snmp-agentx \
  -agentx.addr /var/agentx/master \
  -debug \
  -vppcfg /etc/vpp/vppcfg.yaml \
  -vppstats.api.addr /var/run/vpp/api.sock \
  -vppstats.stats.addr /var/run/vpp/stats.sock \
  -vppstats.period 5 \
  -vppstats.ifindex-offset 1000

VPP Configuration File

The -vppcfg flag accepts a YAML configuration file that describes VPP interfaces and their descriptions. This file is used to populate the ifAlias (.18) field in the ifXTable with meaningful interface descriptions.

YAML Format Example

interfaces:
  GigabitEthernet82/0/0:
    description: 'Infra: Management interface'
  TenGigabitEthernet1/0/2:
    description: 'Infra: Core uplink'
    sub-interfaces:
      100:
        description: 'Cust: Customer VLAN 100'
      200:
        description: 'Transit: Provider VLAN 200'
loopbacks:
  loop0:
    description: 'Core: Router loopback'

Description Mapping

• Main interfaces: Use the description field directly
• Sub-interfaces: Use the description field from the sub-interfaces section
• Loopbacks: Use the description field from the loopbacks section
• Fallback: If no description is found, the interface name is used as the alias

SNMP Interface Mapping

VPP interfaces are mapped to SNMP indices with a configurable offset (default 1000):

• VPP Interface 0 → SNMP Index 1000
• VPP Interface 1 → SNMP Index 1001
• VPP Interface N → SNMP Index (N + offset)

Supported MIB Objects

The application implements the ifXTable (1.3.6.1.2.1.31.1.1.1) with the following objects:

OID	Object	Type	Description
.1.{index}	ifName	DisplayString	Interface name
.2.{index}	ifInMulticastPkts	Counter32	RX multicast packets
.3.{index}	ifInBroadcastPkts	Counter32	RX broadcast packets
.4.{index}	ifOutMulticastPkts	Counter32	TX multicast packets
.5.{index}	ifOutBroadcastPkts	Counter32	TX broadcast packets
.6.{index}	ifHCInOctets	Counter64	RX bytes (high capacity)
.7.{index}	ifHCInUcastPkts	Counter64	RX unicast packets (high capacity)
.8.{index}	ifHCInMulticastPkts	Counter64	RX multicast packets (high capacity)
.9.{index}	ifHCInBroadcastPkts	Counter64	RX broadcast packets (high capacity)
.10.{index}	ifHCOutOctets	Counter64	TX bytes (high capacity)
.11.{index}	ifHCOutUcastPkts	Counter64	TX unicast packets (high capacity)
.12.{index}	ifHCOutMulticastPkts	Counter64	TX multicast packets (high capacity)
.13.{index}	ifHCOutBroadcastPkts	Counter64	TX broadcast packets (high capacity)
.18.{index}	ifAlias	DisplayString	Interface description/alias (from VPP config or interface name)

SNMP Query Examples

Query Interface Names

# Get all interface names
snmpwalk -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1.1

# Get specific interface name (interface 0 with default offset)
snmpget -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1.1.1000

Query Interface Descriptions

# Get all interface descriptions/aliases
snmpwalk -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1.18

# Get specific interface description (interface 0 with default offset)
snmpget -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1.18.1000

Query Interface Counters

# Get RX bytes for interface 0
snmpget -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1.6.1000

# Get TX bytes for interface 1
snmpget -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1.10.1001

# Walk all interface counters
snmpwalk -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1

Query with Custom Offset

If running with -vppstats.ifindex-offset 2000:

# Interface 0 counters at index 2000
snmpget -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1.6.2000

Prerequisites

VPP Requirements

• VPP must be running with stats socket enabled
• Stats socket accessible at /var/run/vpp/stats.sock (or custom path)
• Application must have read permissions on the stats socket

SNMP Requirements

• SNMP master agent running (net-snmp's snmpd)
• AgentX protocol enabled in snmpd configuration
• AgentX socket accessible (TCP port 705 or Unix socket)

SNMP Agent Configuration

Add to /etc/snmp/snmpd.conf:

# Enable AgentX
master agentx
agentXSocket tcp:localhost:705
# or for Unix socket:
# agentXSocket /var/agentx/master

Troubleshooting

Common Issues

1. "Failed to connect to VPP stats"

   • Check VPP is running: vppctl show version
   • Verify stats socket exists: ls -la /var/run/vpp/stats.sock
   • Check permissions on stats socket

2. "Failed to dial AgentX"

   • Verify SNMP agent is running: systemctl status snmpd
   • Check AgentX is enabled in snmpd.conf
   • Test AgentX socket: netstat -ln | grep 705

3. "Failed to register IF-MIB: ErrorDuplicateRegistration"

   • Another agent is already serving the IF-MIB
   • Check with: snmpwalk -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1

4. "Retrieved stats for 0 interfaces"

   • VPP may have no interfaces configured
   • Check VPP interfaces: vppctl show interface

Debug Commands

# Check VPP interfaces
vppctl show interface

# Check VPP stats
vppctl show stats

# Test SNMP master agent
snmpwalk -v2c -c public localhost 1.3.6.1.2.1.1

# Check AgentX registration
snmpwalk -v2c -c public localhost 1.3.6.1.2.1.31.1.1.1

License

This project uses the LGPL 3.0 licensed go-agentx library.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Version History

• v1.0.0: Initial release with IF-MIB support
• v1.1.0: Added configurable interface index offset
• v1.2.0: Added Unix socket support for AgentX