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:**
```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────────────┘
```