jazzymc/infrastructure
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Phase 8: NetDisco Integration with NetBox
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
Details

Browse Source 
- Created 12-PHASE8-NETDISCO-INTEGRATION.md with full deployment plan
- Added NetDisco as planned service in CURRENT-STATE.md
- Documented MikroTik SNMP support (hAP ax3, CSS326, cAP ac)
- Added changelog entry for planning phase
- Decision: Keep NetAlertX running during transition
This commit is contained in:
XTRM Admin
2026-01-19 19:03:18 +02:00
parent c8ea001e25
commit 08b5258aa2
3 changed files with 359 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/00-CURRENT-STATE.md
View File

@@ -111,6 +111,7 @@
| Woodpecker Agent | woodpecker-agent | - | dockerproxy | - |
| RustDesk ID | rustdesk-hbbs | 21115-21116, 21118-21119 | bridge | rustdesk.xtrm-lab.org |
| RustDesk Relay | rustdesk-hbbr | 21117 | bridge | rustdesk.xtrm-lab.org |
| NetDisco | netdisco | 5000 | dockerproxy | netdisco.xtrm-lab.org (PLANNED) |
---
@@ -269,6 +270,7 @@ Proceed to individual phase documents:
5. [Phase 5: RustDesk Setup](./05-PHASE5-RUSTDESK.md)
6. [Phase 6: Portainer Management](./06-PHASE6-PORTAINER-MANAGEMENT.md)
7. [Phase 7: Gitea GitOps](./08-PHASE7-GITEA-GITOPS.md)
8. [Phase 8: NetDisco Integration](./12-PHASE8-NETDISCO-INTEGRATION.md)
**Reference Documents:**
- [MikroTik WiFi & CAPsMAN Configuration](./09-MIKROTIK-WIFI-CAPSMAN.md)

20
docs/07-CHANGELOG.md
View File

@@ -1,4 +1,24 @@
# Infrastructure Changelog
## 2026-01-19 - NetDisco Integration Planning
### Phase 8: NetDisco + NetBox Integration
- [DOCS] Created 12-PHASE8-NETDISCO-INTEGRATION.md
- [PLANNING] NetDisco deployment for SNMP-based network discovery
- [PLANNING] MikroTik SNMP configuration (hAP ax³, CSS326, cAP ac)
- [PLANNING] NetBox integration via plugin or custom API sync
- [DECISION] Keep NetAlertX running in parallel during transition
### MikroTik SNMP Support Confirmed
- hAP ax³ (RouterOS 7.x): Full SNMPv1/v2c/v3 support
- CSS326 (SwOS): SNMPv1/v2c read-only support
- cAP ac (RouterOS 7.x): Full SNMPv1/v2c/v3 support
### Resources
- [NetDisco](https://netdisco.org/)
- [NetBox Plugin for NetDisco](https://github.com/mksoska/netbox-plugin-netdisco)
---
## 2026-01-19 - NetBox IPAM/DCIM Deployment

337
docs/12-PHASE8-NETDISCO-INTEGRATION.md Normal file
View File

@@ -0,0 +1,337 @@
# Phase 8: NetDisco Integration with NetBox
**Status:** PLANNED
**Priority:** Medium
**Created:** 2026-01-19
---
## Overview
Deploy NetDisco for enterprise-grade network discovery using SNMP, and integrate it with NetBox for a unified "Fing-like" network management experience.
**Goal:** Automatic device discovery, switch port mapping, and L2/L3 topology tracking synchronized to NetBox IPAM/DCIM.
---
## Current State
| Tool | Status | Purpose |
|------|--------|---------|
| NetAlertX | Running | ARP/ICMP-based device discovery |
| NetBox | Running | IPAM/DCIM (manual data entry) |
| NetDisco | Not deployed | SNMP-based discovery |
**Decision:** Keep NetAlertX running in parallel during transition.
---
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ SNMP-Enabled Devices │
├─────────────────┬─────────────────┬─────────────────────────┤
│ hAP ax³ │ CSS326 │ cAP ac │
│ 192.168.31.1 │ 192.168.31.9 │ 192.168.31.6 │
│ RouterOS 7.x │ SwOS │ RouterOS 7.x │
│ SNMPv2c/v3 │ SNMPv1/v2c │ SNMPv2c/v3 │
└────────┬────────┴────────┬────────┴────────┬────────────────┘
│ │ │
└─────────────────┼─────────────────┘
│ SNMP Polling
▼
┌─────────────────────┐
│ NetDisco │
│ 192.168.31.2:5000 │
│ (Unraid Docker) │
└──────────┬──────────┘
│ API Sync
▼
┌─────────────────────┐
│ NetBox │
│ 192.168.31.2:8090 │
│ netbox-plugin │
└─────────────────────┘
```
---
## Tasks
### Task 8.1: Enable SNMP on MikroTik Devices
#### 8.1.1 hAP ax³ (RouterOS)
```routeros
# SSH to router
ssh -p 2222 xtrm@192.168.31.1
# Enable SNMP
/snmp set enabled=yes contact="admin@xtrm-lab.org" location="XTRM Home Lab"
# Create community (restrict to Unraid only)
/snmp community add name=netdisco addresses=192.168.31.2/32 read-access=yes write-access=no
# Verify
/snmp print
/snmp community print
```
**Status:** [ ] Not started
#### 8.1.2 CSS326 (SwOS)
1. Access SwOS web UI: http://192.168.31.9/index.html
2. Navigate to **SNMP** tab
3. Configure:
- Enable: Yes
- Community: netdisco
- IP Address Filter: 192.168.31.2
**Note:** SwOS only supports SNMPv1/v2c read-only.
**Status:** [ ] Not started
#### 8.1.3 cAP ac (RouterOS)
```routeros
# SSH to cAP
ssh -p 2222 xtrm@192.168.31.6
# Enable SNMP (same config as hAP ax³)
/snmp set enabled=yes contact="admin@xtrm-lab.org" location="XTRM Home Lab"
/snmp community add name=netdisco addresses=192.168.31.2/32 read-access=yes write-access=no
```
**Status:** [ ] Not started
---
### Task 8.2: Deploy NetDisco on Unraid
#### Docker Compose
```yaml
version: '3'
services:
netdisco:
image: netdisco/netdisco:latest
container_name: netdisco
restart: unless-stopped
ports:
- "5000:5000"
environment:
- NETDISCO_DOMAIN=netdisco.xtrm-lab.org
- NETDISCO_DB_HOST=postgresql17
- NETDISCO_DB_NAME=netdisco
- NETDISCO_DB_USER=netdisco
- NETDISCO_DB_PASS=<secure_password>
- NETDISCO_ADMIN_USER=admin
- NETDISCO_ADMIN_PASS=<secure_password>
volumes:
- /mnt/user/appdata/netdisco/config:/home/netdisco/environments
- /mnt/user/appdata/netdisco/logs:/home/netdisco/logs
- /mnt/user/appdata/netdisco/nd-site-local:/home/netdisco/nd-site-local
networks:
- dockerproxy
depends_on:
- postgresql17
networks:
dockerproxy:
external: true
```
#### Database Setup
```bash
# Create NetDisco database in existing PostgreSQL
docker exec -it postgresql17 psql -U postgres -c "CREATE USER netdisco WITH PASSWORD 'secure_password';"
docker exec -it postgresql17 psql -U postgres -c "CREATE DATABASE netdisco OWNER netdisco;"
```
**Status:** [ ] Not started
---
### Task 8.3: Configure NetDisco Discovery
#### deployment.yml Configuration
```yaml
# /mnt/user/appdata/netdisco/config/deployment.yml
snmp_community:
- community: netdisco
read: true
write: false
device_auth:
- tag: mikrotik
community: netdisco
snmp_version: 2
discover_only:
- 192.168.31.1 # hAP ax³
- 192.168.31.6 # cAP ac
- 192.168.31.9 # CSS326
schedule:
discover: '0 * * * *' # Hourly discovery
macsuck: '15 * * * *' # MAC address table poll
arpnip: '30 * * * *' # ARP table poll
nbtstat: '45 * * * *' # NetBIOS name poll
```
**Status:** [ ] Not started
---
### Task 8.4: Traefik Ingress for NetDisco
Add to Traefik dynamic configuration:
```yaml
http:
routers:
netdisco:
rule: "Host(`netdisco.xtrm-lab.org`)"
entryPoints:
- websecure
service: netdisco
tls:
certResolver: cloudflare
services:
netdisco:
loadBalancer:
servers:
- url: "http://netdisco:5000"
```
**DNS:** Add netdisco.xtrm-lab.org to Cloudflare
**Status:** [ ] Not started
---
### Task 8.5: NetBox Integration
#### Option A: NetBox Plugin (Prototype)
Repository: https://github.com/mksoska/netbox-plugin-netdisco
```bash
# Install in NetBox container
docker exec -it netbox pip install netbox-plugin-netdisco
# Add to NetBox configuration.py
PLUGINS = ['netbox_netdisco']
PLUGINS_CONFIG = {
'netbox_netdisco': {
'NETDISCO_HOST': 'http://netdisco:5000',
'NETDISCO_USERNAME': 'admin',
'NETDISCO_PASSWORD': '<password>',
}
}
```
**Note:** Plugin is prototype-stage. Test thoroughly.
#### Option B: Custom API Sync Script
Create a sync script using NetDisco API + pynetbox:
```python
#!/usr/bin/env python3
# /mnt/user/appdata/netbox/scripts/netdisco_sync.py
import requests
import pynetbox
NETDISCO_URL = "http://192.168.31.2:5000"
NETBOX_URL = "http://192.168.31.2:8090"
NETBOX_TOKEN = "<api_token>"
nb = pynetbox.api(NETBOX_URL, token=NETBOX_TOKEN)
# Fetch devices from NetDisco
devices = requests.get(f"{NETDISCO_URL}/api/v1/device").json()
for device in devices:
# Check if device exists in NetBox
existing = nb.dcim.devices.get(primary_ip=device['ip'])
if not existing:
print(f"New device found: {device['ip']} ({device['name']})")
# Create or flag for review
```
**Status:** [ ] Not started
---
### Task 8.6: Testing & Validation
#### Checklist
- [ ] SNMP reachable from Unraid to all MikroTik devices
- [ ] NetDisco discovers hAP ax³, CSS326, cAP ac
- [ ] Switch port mapping shows connected devices
- [ ] MAC address tracking working
- [ ] NetBox sync shows discovered devices
- [ ] Traefik proxy working (netdisco.xtrm-lab.org)
#### SNMP Test Commands
```bash
# Test SNMP from Unraid
docker run --rm --network dockerproxy netdisco/netdisco snmpwalk -v2c -c netdisco 192.168.31.1 system
docker run --rm --network dockerproxy netdisco/netdisco snmpwalk -v2c -c netdisco 192.168.31.9 system
docker run --rm --network dockerproxy netdisco/netdisco snmpwalk -v2c -c netdisco 192.168.31.6 system
```
**Status:** [ ] Not started
---
## Expected Outcomes
| Metric | Before | After |
|--------|--------|-------|
| Device discovery | ARP scan only | SNMP + ARP |
| Switch port visibility | None | Full mapping |
| MAC tracking | Basic | Full history |
| NetBox data source | Manual | Auto-sync |
| L2 topology | Unknown | Mapped |
---
## Resource Requirements
| Resource | Estimate |
|----------|----------|
| Memory | ~200-400 MiB |
| CPU | Low (polling-based) |
| Disk | ~500 MiB (logs + DB) |
| Database | Reuse postgresql17 |
---
## Rollback Plan
If issues occur:
1. Stop NetDisco container
2. SNMP can remain enabled (read-only, no risk)
3. NetAlertX continues to function
4. Remove Traefik route
---
## References
- [NetDisco Documentation](https://netdisco.org/)
- [NetDisco API Wiki](https://github.com/netdisco/netdisco/wiki/API)
- [MikroTik SNMP Documentation](https://help.mikrotik.com/docs/spaces/ROS/pages/8978519/SNMP)
- [CSS326 SwOS SNMP](https://help.mikrotik.com/docs/spaces/SWOS/pages/76415036/CRS3xx+and+CSS326-24G-2S+series+Manual)
- [NetBox Plugin for NetDisco](https://github.com/mksoska/netbox-plugin-netdisco)
- [pynetbox Library](https://github.com/netbox-community/pynetbox)