XTRM Admin
0e35142e10
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
- Added MikroTik DHCP to NetBox sync script - Installed Slurp'it plugin v1.2.7 in NetBox - Enhanced NetDisco to NetBox sync with ARP/MAC data - Enabled SNMP on Unraid server (4 devices now discoverable) - Updated Phase 8 documentation with all scripts and configs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
235 lines
6.4 KiB
Markdown
235 lines
6.4 KiB
Markdown
# Phase 8: NetDisco Integration with NetBox
|
|
|
|
**Status:** ✅ COMPLETED (Enhanced)
|
|
**Priority:** Medium
|
|
**Created:** 2026-01-19
|
|
**Last Updated:** 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.
|
|
|
|
---
|
|
|
|
## Task Status Summary
|
|
|
|
| Task | Description | Status |
|
|
|------|-------------|--------|
|
|
| 8.1 | Enable SNMP on MikroTik Devices | ✅ COMPLETED |
|
|
| 8.2 | Deploy NetDisco on Unraid | ✅ COMPLETED |
|
|
| 8.3 | Configure NetDisco Discovery | ✅ COMPLETED |
|
|
| 8.4 | Traefik Ingress for NetDisco | ✅ COMPLETED |
|
|
| 8.5 | NetBox Integration | ✅ COMPLETED |
|
|
| 8.6 | Testing & Validation | ✅ COMPLETED |
|
|
| 8.7 | Enhanced Network Mapping | ✅ COMPLETED |
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
| Tool | Status | Purpose |
|
|
|------|--------|---------|
|
|
| NetAlertX | Running | ARP/ICMP-based device discovery |
|
|
| NetBox | Running | IPAM/DCIM with Slurpit plugin |
|
|
| NetDisco | ✅ Running | SNMP-based discovery |
|
|
|
|
**Discovered Devices:** 4 (hAP ax³, cAP ac, CSS326, Unraid)
|
|
|
|
---
|
|
|
|
## Deployment Details
|
|
|
|
### Database
|
|
- **Host:** postgresql17
|
|
- **Database:** netdisco_db
|
|
- **User:** netdisco_user
|
|
- **Password:** NetD1sc0_M0stW4nt3d@db
|
|
|
|
### Containers
|
|
| Container | Image | Port | Status |
|
|
|-----------|-------|------|--------|
|
|
| netdisco-web | netdisco/netdisco:latest-web | 5000 | Running |
|
|
| netdisco-backend | netdisco/netdisco:latest-backend | - | Running |
|
|
| netbox | netbox-custom:latest (with slurpit) | 8090 | Running |
|
|
|
|
### Access URLs
|
|
| URL | Purpose |
|
|
|-----|---------|
|
|
| https://netdisco.xtrm-lab.org | External access (Authentik SSO) |
|
|
| http://192.168.31.2:5000 | Internal NetDisco access |
|
|
| https://netbox.xtrm-lab.org | External NetBox access |
|
|
| http://192.168.31.2:8090 | Internal NetBox access |
|
|
|
|
---
|
|
|
|
## Task 8.7: Enhanced Network Mapping (COMPLETED)
|
|
|
|
### 1. MikroTik DHCP → NetBox Sync
|
|
|
|
**Script:** `/mnt/user/appdata/netdisco/scripts/mikrotik_dhcp_to_netbox.sh`
|
|
|
|
Syncs DHCP leases from MikroTik router to NetBox IP addresses with:
|
|
- Hostname
|
|
- MAC address
|
|
- Comments/notes from DHCP
|
|
|
|
**Run Command:**
|
|
```bash
|
|
/mnt/user/appdata/netdisco/scripts/mikrotik_dhcp_to_netbox.sh
|
|
```
|
|
|
|
**Result:** 29 devices synced (26 created, 3 updated)
|
|
|
|
### 2. Slurp'it NetBox Plugin
|
|
|
|
**Plugin Version:** 1.2.7
|
|
**NetBox Version:** 4.5.0
|
|
|
|
**Custom Image:** `netbox-custom:latest`
|
|
|
|
**Plugin Configuration:** `/mnt/user/appdata/netbox/config/plugins.py`
|
|
```python
|
|
PLUGINS = ["slurpit_netbox"]
|
|
PLUGINS_CONFIG = {
|
|
"slurpit_netbox": {}
|
|
}
|
|
```
|
|
|
|
**Note:** Slurp'it requires a separate Slurp'it server for full network discovery. The plugin provides NetBox integration once the server is configured.
|
|
|
|
### 3. Enhanced NetDisco → NetBox Sync
|
|
|
|
**Script:** `/mnt/user/appdata/netdisco/scripts/sync_to_netbox.py`
|
|
|
|
Enhanced version syncs:
|
|
- Device info (serial, OS, model, vendor)
|
|
- IP addresses from device_ip table
|
|
- ARP table entries (MAC to IP mappings)
|
|
- System MAC addresses
|
|
- Uptime information
|
|
|
|
**Run Command:**
|
|
```bash
|
|
PG17_IP=$(docker inspect postgresql17 --format "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}")
|
|
|
|
docker run --rm \
|
|
--network dockerproxy \
|
|
-e NETDISCO_DB_HOST=$PG17_IP \
|
|
-e NETBOX_URL=http://192.168.31.2:8090 \
|
|
-v /mnt/user/appdata/netdisco/scripts:/scripts \
|
|
python:3.11-slim python /scripts/sync_to_netbox.py
|
|
```
|
|
|
|
---
|
|
|
|
## SNMP-Enabled Devices
|
|
|
|
| Device | IP | Type | Communities |
|
|
|--------|-----|------|-------------|
|
|
| hAP ax³ | 192.168.31.1 | Router | netdisco, public |
|
|
| cAP ac | 192.168.31.6 | AP | netdisco, public |
|
|
| CSS326 | 192.168.31.9 | Switch | public |
|
|
| XTRM-Unraid | 192.168.31.2 | Server | netdisco, public |
|
|
|
|
### Unraid SNMP Configuration
|
|
|
|
**Config File:** `/etc/snmp/snmpd.conf`
|
|
```
|
|
rocommunity netdisco
|
|
rocommunity public
|
|
syslocation XTRM Home Lab
|
|
syscontact admin@xtrm-lab.org
|
|
sysname XTRM-Unraid
|
|
disk /mnt/disk1
|
|
disk /mnt/cache
|
|
extend cpumhz /usr/local/emhttp/plugins/snmp/cpu_mhz.sh
|
|
extend diskfree /usr/local/emhttp/plugins/snmp/disk_free_space.sh
|
|
extend disktemp /usr/local/emhttp/plugins/snmp/disk_temps.sh
|
|
extend meminfo /usr/local/emhttp/plugins/snmp/mem_info.sh
|
|
extend sharefree /usr/local/emhttp/plugins/snmp/share_free_space.sh
|
|
```
|
|
|
|
**Plugin:** kubedzero/unraid-snmp
|
|
|
|
---
|
|
|
|
## Sync Scripts Summary
|
|
|
|
| Script | Purpose | Trigger |
|
|
|--------|---------|---------|
|
|
| sync_to_netbox.py | NetDisco → NetBox device sync | Manual / cron |
|
|
| mikrotik_dhcp_to_netbox.sh | MikroTik DHCP → NetBox IPs | Manual / cron |
|
|
|
|
### Scheduling (Cron Examples)
|
|
|
|
```bash
|
|
# NetDisco sync - hourly at :45
|
|
45 * * * * docker run --rm --network dockerproxy -e NETDISCO_DB_HOST=172.18.0.13 -e NETBOX_URL=http://192.168.31.2:8090 -v /mnt/user/appdata/netdisco/scripts:/scripts python:3.11-slim python /scripts/sync_to_netbox.py >> /mnt/user/appdata/netdisco/logs/sync.log 2>&1
|
|
|
|
# MikroTik DHCP sync - hourly at :50
|
|
50 * * * * /mnt/user/appdata/netdisco/scripts/mikrotik_dhcp_to_netbox.sh >> /mnt/user/appdata/netdisco/logs/dhcp-sync.log 2>&1
|
|
```
|
|
|
|
---
|
|
|
|
## NetBox Credentials
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| URL | http://192.168.31.2:8090 |
|
|
| Admin User | admin |
|
|
| Admin Password | M0stW4nt3d@xtrm |
|
|
| API Token (v1) | kI2HiUD8Bb53KfdkOTaiWYxZuERjhGU30CgGdYxm |
|
|
| Secret Key | 56537576d25051987077c7270c876099fe44ad83bc7695a7f4531904fce5678e |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### session_cookie_key Error
|
|
If NetDisco web UI shows "session_cookie_key must be defined":
|
|
```sql
|
|
SELECT * FROM sessions WHERE id = 'dancer_session_cookie_key';
|
|
INSERT INTO sessions (id, a_session) VALUES ('dancer_session_cookie_key', md5(random()::text));
|
|
```
|
|
|
|
### NetBox Plugin Not Loading
|
|
Check container logs:
|
|
```bash
|
|
docker logs netbox 2>&1 | grep -i plugin
|
|
```
|
|
|
|
Verify plugins.py is mounted:
|
|
```bash
|
|
docker exec netbox cat /etc/netbox/config/plugins.py
|
|
```
|
|
|
|
### SNMP Not Responding
|
|
```bash
|
|
snmpwalk -v2c -c netdisco 192.168.31.1 system
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 8 Summary
|
|
|
|
**Status: ✅ COMPLETED**
|
|
|
|
All tasks completed with enhanced capabilities:
|
|
- 4 devices discovered via SNMP (MikroTik + Unraid)
|
|
- NetDisco → NetBox sync with device details
|
|
- MikroTik DHCP → NetBox sync (29 devices/IPs)
|
|
- Slurp'it plugin installed for future discovery expansion
|
|
- ARP table sync for MAC-to-IP mapping
|
|
|
|
**Data Flow:**
|
|
```
|
|
MikroTik Devices ─SNMP─> NetDisco ─sync─> NetBox
|
|
│ │ ↑
|
|
└──────DHCP──────────sync────────────┘
|
|
```
|