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:

VPP Stats Client (vppstats/): Connects to VPP stats socket and retrieves interface counters
Interface MIB (ifmib/): Maps VPP statistics to SNMP IF-MIB structure
AgentX Client (agentx/): Handles AgentX protocol connection and MIB registration
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.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.addr /custom/path/stats.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.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

"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
"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
"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
"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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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