From 1cbca296c479b0c2d542cf12bec9a9be6bf30ec5 Mon Sep 17 00:00:00 2001 From: Pim van Pelt Date: Tue, 17 Jun 2025 01:06:37 +0200 Subject: [PATCH] Refactor README into a terse synopsis and a larger DETAILS.md doc --- README.md | 316 +++--------------------------------------------- docs/DETAILS.md | 266 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 285 insertions(+), 297 deletions(-) create mode 100644 docs/DETAILS.md diff --git a/README.md b/README.md index 4db3d7d..3cf2e9c 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/DETAILS.md b/docs/DETAILS.md new file mode 100644 index 0000000..73aee9b --- /dev/null +++ b/docs/DETAILS.md @@ -0,0 +1,266 @@ +# VPP SNMP AgentX Bridge - Detailed Documentation + +## 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 + +## 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 | + +## Usage 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 +``` + +## 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 + +```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 +``` + +## 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 \ No newline at end of file