From 3623c05f6e87cc7469d921bb1ebb85d1ac1a50ad Mon Sep 17 00:00:00 2001 From: Pim van Pelt Date: Mon, 9 Jun 2025 17:40:34 +0200 Subject: [PATCH] Add autogenerated README --- README.md | 241 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..011ea79 --- /dev/null +++ b/README.md @@ -0,0 +1,241 @@ +# 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 three 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**: Registers with SNMP master agent to serve the MIB data + +## Build Instructions + +### Development Build + +```bash +go build -o vpp-snmp-agent . +``` + +### Static Binary Build + +For deployment without Go runtime dependencies: + +```bash +# Linux static binary +CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-extldflags "-static"' -o vpp-snmp-agent . + +# Cross-compile for different architectures +CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -ldflags '-extldflags "-static"' -o vpp-snmp-agent-linux-amd64 . +CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -a -ldflags '-extldflags "-static"' -o vpp-snmp-agent-linux-arm64 . +``` + +### Release Build with Version Info + +```bash +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 vpp-snmp-agent . +``` + +## Usage + +### Basic Usage + +```bash +# Run with default settings +./vpp-snmp-agent + +# Run with custom AgentX address +./vpp-snmp-agent -agentx-addr 127.0.0.1:705 + +# Run with Unix socket AgentX connection +./vpp-snmp-agent -agentx-addr /var/agentx/master +``` + +### Command Line Flags + +| Flag | Default | Description | +|------|---------|-------------| +| `-agentx-addr` | `localhost:705` | AgentX master agent address (hostname:port or Unix socket path) | +| `-vpp-stats-addr` | `/var/run/vpp/stats.sock` | VPP statistics socket path | +| `-period` | `10.0` | Interval in seconds for querying VPP interface stats | +| `-vpp-ifindex-offset` | `1000` | Offset to add to VPP interface indices for SNMP | + +### Examples + +```bash +# Custom polling interval (5 seconds) +./vpp-snmp-agent -period 5.0 + +# Custom VPP stats socket +./vpp-snmp-agent -vpp-stats-addr /custom/path/stats.sock + +# Custom interface index offset (start at 2000) +./vpp-snmp-agent -vpp-ifindex-offset 2000 + +# Full configuration +./vpp-snmp-agent \ + -agentx-addr /var/agentx/master \ + -vpp-stats-addr /var/run/vpp/stats.sock \ + -period 5.0 \ + -vpp-ifindex-offset 1000 +``` + +## 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) | + +## SNMP Query Examples + +### Query Interface Names + +```bash +# 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 Counters + +```bash +# 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 `-vpp-ifindex-offset 2000`: + +```bash +# 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 + +```bash +# 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 \ No newline at end of file