ipng/govpp-snmp-agentx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor README into a terse synopsis and a larger DETAILS.md doc

Browse Source
This commit is contained in:
Pim van Pelt
2025-06-17 01:06:37 +02:00
parent a73c7cbf91
commit 1cbca296c4
2 changed files with 285 additions and 297 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
README.md
View File

@ -1,324 +1,46 @@
# 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
for SNMP monitoring.
SNMP AgentX daemon that exposes VPP interface statistics via standard IF-MIB.
## 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 → SNMPd
```
The application consists of four main components:
1. **VPP Stats Client** (`src/vppstats/`): Connects to VPP stats socket and retrieves interface counters
2. **Interface MIB** (`src/ifmib/`): Maps VPP statistics to SNMP IF-MIB structure
3. **AgentX Client** (`src/agentx/`): Handles AgentX protocol connection and MIB registration
4. **Main Application** (`src/main.go`): Orchestrates the components and handles configuration
## Build Instructions
### Development Build
## Quick Start
```bash
# Build the binary
# Build
make build
# Run tests
# Test
make test
```
### Manual Build
If you prefer to use Go directly:
```bash
cd src && go build -o ../govpp-snmp-agentx .
```
### Debian Package
Build a Debian package for easy installation and deployment:
```bash
# Build the Debian package
# Create Debian package
make pkg-deb
# Install the package
# Install package
sudo dpkg -i ../govpp-snmp-agentx_*.deb
```
The Debian package includes:
- Binary installed to `/usr/sbin/govpp-snmp-agentx`
- Systemd service file
- Configuration file at `/etc/default/govpp-snmp-agentx`
- Manual page
## Configuration
## Usage
### Basic Usage
The Debian package installs a systemd service that reads configuration from `/etc/default/govpp-snmp-agentx`:
```bash
# Run with default settings
./govpp-snmp-agentx
# Edit service configuration
sudo nano /etc/default/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
# Start service
sudo systemctl start govpp-snmp-agentx
```
### 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
```bash
# 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
Default configuration:
```
GOVPP_SNMP_AGENTX_FLAGS="-agentx.addr /var/agentx/master -vppcfg /etc/vpp/vppcfg.yaml -vppstats.period 10"
```
## VPP Configuration File
## Documentation
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
```yaml
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
```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 Descriptions
```bash
# 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
```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 `-vppstats.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
```
- **Manual page**: `man govpp-snmp-agentx` (after package installation)
- **Detailed documentation**: [docs/DETAILS.md](docs/DETAILS.md)
## License
This project uses the LGPL 3.0 licensed go-agentx library. It has been modified due to a bug,
see details in [[GitHub PR#7](https://github.com/posteo/go-agentx/pull/11)], and as such is
licensed also LGPL 3.0. The go-agentx source code in this project will be removed once the
upstream PR is merged.
## 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
LGPL 3.0 (due to modified go-agentx dependency)