infrastructure/docs/archive/12-PHASE8-NETDISCO-INTEGRATION.md

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:

/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

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:

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)

# 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":

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:

docker logs netbox 2>&1 | grep -i plugin

Verify plugins.py is mounted:

docker exec netbox cat /etc/netbox/config/plugins.py

SNMP Not Responding

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────────────┘