XTRM Admin
1ddfc68192
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
6.9 KiB
6.9 KiB
Phase 8: NetDisco Integration with NetBox
Status: IN PROGRESS (Tasks 8.1-8.4 Complete) 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 | ⏳ PENDING |
| 8.6 | Testing & Validation | ⏳ PENDING |
Current State
| Tool | Status | Purpose |
|---|---|---|
| NetAlertX | Running | ARP/ICMP-based device discovery |
| NetBox | Running | IPAM/DCIM (manual data entry) |
| NetDisco | ✅ Running | SNMP-based discovery |
Decision: Keep NetAlertX running in parallel during transition.
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 |
Access URLs
| URL | Purpose |
|---|---|
| https://netdisco.xtrm-lab.org | External access (Authentik SSO) |
| http://192.168.31.2:5000 | Internal direct access |
Configuration
- Config Path: /mnt/user/appdata/netdisco/environments/deployment.yml
- Logs: /mnt/user/appdata/netdisco/logs/
Completed Tasks
Task 8.1: SNMP Configuration (COMPLETED)
| Device | IP | Communities | Access Restriction |
|---|---|---|---|
| hAP ax³ | 192.168.31.1 | netdisco, public |
192.168.31.2/32 |
| cAP ac | 192.168.31.6 | netdisco, public |
192.168.31.2/32 |
| CSS326 | 192.168.31.9 | public |
None (SwOS limitation) |
SNMP Settings:
- Contact: admin@xtrm-lab.org
- Location: XTRM Home Lab
- Version: SNMPv2c
- Write Access: Disabled
Task 8.2: NetDisco Deployment (COMPLETED)
Docker Compose: /mnt/user/appdata/netdisco/docker-compose.yml
services:
netdisco-backend:
container_name: netdisco-backend
image: netdisco/netdisco:latest-backend
hostname: netdisco-backend
restart: unless-stopped
volumes:
- /mnt/user/appdata/netdisco/nd-site-local:/home/netdisco/nd-site-local
- /mnt/user/appdata/netdisco/environments:/home/netdisco/environments
- /mnt/user/appdata/netdisco/logs:/home/netdisco/logs
environment:
NETDISCO_DOMAIN: deployment
NETDISCO_DB_HOST: postgresql17
NETDISCO_DB_PORT: 5432
NETDISCO_DB_NAME: netdisco_db
NETDISCO_DB_USER: netdisco_user
NETDISCO_DB_PASS: NetD1sc0_M0stW4nt3d@db
networks:
- dockerproxy
netdisco-web:
container_name: netdisco-web
image: netdisco/netdisco:latest-web
hostname: netdisco-web
restart: unless-stopped
volumes:
- /mnt/user/appdata/netdisco/nd-site-local:/home/netdisco/nd-site-local
- /mnt/user/appdata/netdisco/environments:/home/netdisco/environments
- /mnt/user/appdata/netdisco/logs:/home/netdisco/logs
environment:
NETDISCO_DOMAIN: deployment
NETDISCO_DB_HOST: postgresql17
NETDISCO_DB_PORT: 5432
NETDISCO_DB_NAME: netdisco_db
NETDISCO_DB_USER: netdisco_user
NETDISCO_DB_PASS: NetD1sc0_M0stW4nt3d@db
PORT: 5000
networks:
- dockerproxy
networks:
dockerproxy:
external: true
Task 8.3: Discovery Configuration (COMPLETED)
deployment.yml:
database:
name: 'netdisco_db'
user: 'netdisco_user'
pass: 'NetD1sc0_M0stW4nt3d@db'
host: 'postgresql17'
community_rw:
- netdisco
- public
discover_only:
- 192.168.31.1 # hAP ax³
- 192.168.31.6 # cAP ac
- 192.168.31.9 # CSS326
site_local_files: true
no_auth: true
schedule:
discover: '0 */2 * * *' # Every 2 hours
macsuck: '15 * * * *' # MAC poll hourly
arpnip: '30 * * * *' # ARP poll hourly
nbtstat: '45 * * * *' # NetBIOS hourly
Discovery Results:
| Device | IP | Status |
|---|---|---|
| hAP ax³ | 192.168.31.1 | ✅ Discovered |
| cAP ac | 192.168.31.6 | ✅ Discovered |
| CSS326 | 192.168.31.9 | ✅ Discovered |
Task 8.4: Traefik Ingress (COMPLETED)
Traefik Dynamic Config: /mnt/user/appdata/traefik/dynamic.yml
http:
routers:
netdisco-secure:
rule: "Host(\`netdisco.xtrm-lab.org\`)"
entryPoints:
- https
middlewares:
- default-headers
- authentik-forward-auth
tls:
certResolver: cloudflare
service: netdisco
services:
netdisco:
loadBalancer:
servers:
- url: "http://netdisco-web:5000"
Important Fix Applied:
The web UI failed to start with error: The setting session_cookie_key must be defined
Root Cause: When using external PostgreSQL, the dancer_session_cookie_key record was missing from the sessions table.
Fix:
INSERT INTO sessions (id, a_session) VALUES ('dancer_session_cookie_key', md5(random()::text));
Pending Tasks
Task 8.5: NetBox Integration
Option A: NetBox Plugin (Prototype)
- Repository: https://github.com/mksoska/netbox-plugin-netdisco
- Status: Prototype stage - may have compatibility issues
Option B: Custom API Sync Script (Recommended)
- Use NetDisco API + pynetbox library
- More control over sync behavior
- Can be scheduled via cron
Task 8.6: Testing & Validation
- Verify all SNMP queries working
- Confirm switch port mapping
- Test MAC address tracking
- Validate NetBox sync (once implemented)
- Test external access via Traefik
Troubleshooting
session_cookie_key Error
If web UI shows "session_cookie_key must be defined":
-- Check if key exists
SELECT * FROM sessions WHERE id = 'dancer_session_cookie_key';
-- Insert if missing
INSERT INTO sessions (id, a_session) VALUES ('dancer_session_cookie_key', md5(random()::text));
Discovery Not Working
- Test SNMP from netdisco container:
docker exec netdisco-backend snmpwalk -v2c -c netdisco 192.168.31.1 system - Check logs:
tail -f /mnt/user/appdata/netdisco/logs/netdisco-daemon.log - Verify community and IP restrictions on MikroTik devices