# 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

```yaml
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:**
```yaml
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

```yaml
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:**
```sql
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":
```sql
-- 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
1. Test SNMP from netdisco container:
   ```bash
   docker exec netdisco-backend snmpwalk -v2c -c netdisco 192.168.31.1 system
   ```
2. Check logs: `tail -f /mnt/user/appdata/netdisco/logs/netdisco-daemon.log`
3. Verify community and IP restrictions on MikroTik devices

---

## References

- [NetDisco Documentation](https://netdisco.org/)
- [NetDisco GitHub Issues](https://github.com/netdisco/netdisco-docker/issues)
- [MikroTik SNMP Documentation](https://help.mikrotik.com/docs/spaces/ROS/pages/8978519/SNMP)
- [NetBox Plugin for NetDisco](https://github.com/mksoska/netbox-plugin-netdisco)