Add autogenerated README
This commit is contained in:
Pim van Pelt
241
README.md
Normal file
241
README.md
Normal file
@ -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
|
||||
Reference in New Issue
Block a user