214 lines
6.8 KiB
Markdown
214 lines
6.8 KiB
Markdown
# NetBox — DCIM / IPAM
|
|
|
|
**Data Center Infrastructure Management & IP Address Management**
|
|
|
|
## Service Overview
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| **Host** | homelab-vm (192.168.0.210) |
|
|
| **Port** | 8443 (-> 8000 internal) |
|
|
| **URL** | https://nb.vish.gg |
|
|
| **Local URL** | http://192.168.0.210:8443 |
|
|
| **Image** | `linuxserver/netbox:latest` |
|
|
| **Stack** | `hosts/vms/homelab-vm/netbox.yaml` |
|
|
| **Data** | `/home/homelab/docker/netbox/{config,db,redis}` |
|
|
|
|
## Credentials
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| **Superuser Email** | your-email@example.com |
|
|
| **Superuser Password** | Set via env var `SUPERUSER_PASSWORD` at deploy time |
|
|
| **DB Password** | Set via env var `DB_PASSWORD` |
|
|
| **Redis Password** | Set via env var `REDIS_PASSWORD` |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Internet
|
|
|
|
|
Cloudflare (proxied)
|
|
|
|
|
nb.vish.gg
|
|
|
|
|
NPM (matrix-ubuntu:443) --- SSL: *.vish.gg LE wildcard cert
|
|
|
|
|
http://192.168.0.210:8443 (LAN)
|
|
|
|
|
+-------+-------+
|
|
| | |
|
|
netbox-db redis netbox
|
|
(pg:16) (redis:7) (uwsgi)
|
|
```
|
|
|
|
NPM on matrix-ubuntu reaches homelab-vm via its **LAN IP** (192.168.0.210).
|
|
|
|
## Components
|
|
|
|
| Container | Image | Purpose |
|
|
|-----------|-------|---------|
|
|
| `netbox` | linuxserver/netbox:latest | Web UI + API + background worker |
|
|
| `netbox-db` | postgres:16-alpine | PostgreSQL database |
|
|
| `netbox-redis` | redis:7-alpine | Caching and task queue |
|
|
|
|
## DNS & Reverse Proxy
|
|
|
|
- **Cloudflare**: `nb.vish.gg` A record (proxied), auto-updated by DDNS
|
|
- **DDNS**: Listed in `ddns-vish-proxied` service (`hosts/synology/atlantis/dynamicdnsupdater.yaml`)
|
|
- **NPM** (matrix-ubuntu): Proxy host ID 46 -- `nb.vish.gg` -> `http://192.168.0.210:8443`
|
|
- SSL: Let's Encrypt wildcard certificate (`*.vish.gg`)
|
|
- Force SSL: yes
|
|
- Block exploits: yes
|
|
|
|
## Deployment
|
|
|
|
Deployed via `docker compose` with env vars for secrets:
|
|
|
|
```bash
|
|
cd /home/homelab/organized/repos/homelab/hosts/vms/homelab-vm
|
|
|
|
SUPERUSER_EMAIL=your-email@example.com \
|
|
SUPERUSER_PASSWORD="REDACTED_PASSWORD" \
|
|
DB_PASSWORD="REDACTED_PASSWORD" \
|
|
REDIS_PASSWORD="REDACTED_PASSWORD" \
|
|
docker compose -f netbox.yaml -p netbox up -d
|
|
```
|
|
|
|
First startup takes several minutes (DB migrations + static file collection).
|
|
|
|
## Configuration
|
|
|
|
Main config persisted at: `/home/homelab/docker/netbox/config/configuration.py`
|
|
|
|
Key settings:
|
|
- `ALLOWED_HOSTS = ['*']` -- NPM handles domain routing
|
|
- `TIME_ZONE = 'UTC'`
|
|
- `LOGIN_REQUIRED = False` (change to `True` to require auth for read access)
|
|
- `SECRET_KEY` -- auto-generated on first run, do not change
|
|
|
|
To edit:
|
|
```bash
|
|
sudo nano /home/homelab/docker/netbox/config/configuration.py
|
|
docker restart netbox
|
|
```
|
|
|
|
## Authentication (Authentik OIDC)
|
|
|
|
NetBox uses Authentik SSO via OpenID Connect.
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| **Provider** | NetBox (PK: 23, OAuth2/OIDC) |
|
|
| **Application slug** | `netbox` |
|
|
| **Discovery URL** | `https://sso.vish.gg/application/o/netbox/` |
|
|
| **Client ID** | `BB7PiOu8xFOl58H2MUfl9IHISVLuJ4UwwMGvmJ9N` |
|
|
| **Redirect URI** | `https://nb.vish.gg/oauth/complete/oidc/` |
|
|
| **Scopes** | openid, profile, email |
|
|
| **User mapping** | `associate_by_email` pipeline -- matches Authentik email to NetBox user |
|
|
|
|
Login page shows "OpenID Connect" button. The `vish` Authentik user is mapped to a superuser account.
|
|
|
|
Configuration in `/home/homelab/docker/netbox/config/configuration.py`:
|
|
```python
|
|
REMOTE_AUTH_ENABLED = True
|
|
REMOTE_AUTH_BACKEND = 'social_core.backends.open_id_connect.OpenIdConnectAuth'
|
|
REMOTE_AUTH_AUTO_CREATE_USER = True
|
|
SOCIAL_AUTH_OIDC_OIDC_ENDPOINT = 'https://sso.vish.gg/application/o/netbox/'
|
|
SOCIAL_AUTH_OIDC_KEY = '<client-id>'
|
|
SOCIAL_AUTH_OIDC_SECRET = '<client-secret>'
|
|
```
|
|
|
|
## Inventory Data
|
|
|
|
NetBox is pre-populated with the full homelab inventory:
|
|
|
|
| Category | Count |
|
|
|----------|-------|
|
|
| Sites | 3 (Home, Seattle, Contabo VPS) |
|
|
| Devices | 19 (NAS, VMs, switches, workstations, RPis) |
|
|
| Services | 110 (all Docker containers with ports) |
|
|
| IP Addresses | 28 (LAN + Tailscale for all hosts) |
|
|
| IP Prefixes | 5 (LAN, Tailscale, Docker, K8s) |
|
|
| Interfaces | 39 (10GbE, 1GbE, virtual, Tailscale, switch ports) |
|
|
| MAC Addresses | 17 (all physical NICs with SSH access) |
|
|
| Cables | 4 (10GbE switch connections) |
|
|
| Clusters | 3 (Portainer Docker, Olares K8s, Headscale) |
|
|
| Virtual Machines | 3 (homelab-vm, matrix-ubuntu, tdarr-node) |
|
|
| Tags | 17 (media, monitoring, devops, ai-ml, etc.) |
|
|
|
|
## MAC Addresses
|
|
|
|
NetBox v4.2+ stores MAC addresses as separate objects (`/api/dcim/mac-addresses/`), not as
|
|
fields on interfaces. Each MAC is linked to an interface via `assigned_object_type` +
|
|
`assigned_object_id`.
|
|
|
|
Populated MACs (2026-03-30):
|
|
|
|
| Device | Interface | MAC Address |
|
|
|--------|-----------|-------------|
|
|
| atlantis | eth0 | 90:09:D0:8B:0C:E9 |
|
|
| atlantis | eth1 | 90:09:D0:8B:0C:EA |
|
|
| atlantis | ovs_eth2 | 90:09:D0:8B:0C:EB |
|
|
| calypso | eth0 | 90:09:D0:5D:DD:DE |
|
|
| calypso | ovs_eth2 | 90:09:D0:5B:DC:70 |
|
|
| concord-nuc | eno1 | F4:4D:30:65:52:56 |
|
|
| guava | enp1s0f0np0 | E8:EB:D3:C1:11:D8 |
|
|
| guava | enp1s0f1np1 | E8:EB:D3:C1:11:D9 |
|
|
| homelab-vm | eth0 | 3A:E3:15:F8:B3:90 |
|
|
| olares | enp129s0 | 84:F7:58:3F:DB:2A |
|
|
| pi-5 | eth0 | 88:A2:9E:00:1A:C5 |
|
|
| setillo | eth0 | 90:09:D0:76:97:3E |
|
|
| seattle | eth0 | 00:50:56:54:38:A2 |
|
|
| pve | eno1 | 94:C6:91:A4:F4:63 |
|
|
| matrix-ubuntu | ens3 | 02:11:32:20:04:FE |
|
|
| jellyfish | eth0 | 2C:CF:67:24:39:D6 |
|
|
| homeassistant | end0 | 20:F8:3B:02:29:A1 |
|
|
|
|
Devices without MACs (no SSH access): archer-be800, msi-prestige, pi-5-kevin, shield-tv, shinku-ryuu (offline).
|
|
|
|
## API
|
|
|
|
REST API at `/api/`, GraphQL at `/graphql/`.
|
|
|
|
NetBox v4 uses v2 API tokens with the `Bearer` keyword:
|
|
```bash
|
|
# Create a token via Django shell (plaintext only shown once):
|
|
docker exec netbox python3 /app/netbox/netbox/manage.py shell -c "
|
|
from users.models import Token, User
|
|
admin = User.objects.get(username='admin')
|
|
t = Token(user=admin, description='my-token', write_enabled=True)
|
|
t.save()
|
|
print(f'nbt_{t.key}.{t._token}')
|
|
"
|
|
|
|
# Use the token:
|
|
curl -H "Authorization: Bearer nbt_<key>.<plaintext>" https://nb.vish.gg/api/dcim/devices/
|
|
```
|
|
|
|
Note: `API_TOKEN_PEPPERS` must be configured in `configuration.py` for v2 tokens to work.
|
|
|
|
Key API endpoints:
|
|
- `/api/dcim/devices/` -- devices
|
|
- `/api/dcim/interfaces/` -- network interfaces
|
|
- `/api/dcim/mac-addresses/` -- MAC addresses (v4.2+ separate model)
|
|
- `/api/ipam/ip-addresses/` -- IP addresses
|
|
- `/api/dcim/cables/` -- physical cabling
|
|
|
|
## Maintenance
|
|
|
|
```bash
|
|
# Logs
|
|
docker logs netbox --tail 50
|
|
|
|
# Restart
|
|
docker restart netbox
|
|
|
|
# Upgrade
|
|
docker compose -f netbox.yaml -p netbox pull && \
|
|
docker compose -f netbox.yaml -p netbox up -d
|
|
|
|
# Backup database
|
|
docker exec netbox-db pg_dump -U netbox netbox > /home/homelab/docker/netbox/backup-$(date +%Y%m%d).sql
|
|
```
|