Sanitized mirror from private repository - 2026-04-05 11:58:57 UTC

2026-04-05 11:58:57 +00:00
commit 4622707153
1395 changed files with 358059 additions and 0 deletions
--- a/docs/services/individual/netbox.md
+++ b/docs/services/individual/netbox.md
@@ -0,0 +1,213 @@
+# 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
+```