283 lines
9.6 KiB
Markdown
283 lines
9.6 KiB
Markdown
# Network Architecture
|
|
|
|
*Homelab network topology and configuration*
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The homelab uses a multi-layered network architecture with external access via Cloudflare, internal services through Nginx Proxy Manager, and mesh VPN for secure remote access.
|
|
|
|
---
|
|
|
|
## Network Topology
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────┐
|
|
│ INTERNET │
|
|
│ (Public IP via ISP) │
|
|
└────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────────────────┐
|
|
│ CLOUDFLARE │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ DNS │ │ Proxy │ │ Tunnels │ │
|
|
│ │ vish.gg │ │ vish.gg │ │ (if used) │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────────────────┐
|
|
│ HOME NETWORK │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ Router │ │ Switch │ │ WiFi AP │ │
|
|
│ │ (Gateway) │ │ (Managed) │ │ (Ubiquiti) │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
│ │ │ │
|
|
│ └──────────────────┬────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────┴──────┐ │
|
|
│ │ VLANs │ │
|
|
│ │ 10 (MGMT) │ │
|
|
│ │ 20 (IOT) │ │
|
|
│ │ 30 (MAIN) │ │
|
|
│ └─────────────┘ │
|
|
└────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
┌───────────────┼───────────────┐
|
|
▼ ▼ ▼
|
|
┌───────────┐ ┌───────────┐ ┌───────────┐
|
|
│ ATLANTIS │ │ CALYPSO │ │ NUC │
|
|
│ (NAS) │ │ (NAS) │ │ (HA) │
|
|
└───────────┘ └───────────┘ └───────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## IP Address Scheme
|
|
|
|
### Subnet Configuration
|
|
|
|
| VLAN | Network | Gateway | DHCP Range | Purpose |
|
|
|------|---------|---------|------------|---------|
|
|
| 10 (MGMT) | 192.168.0.0/24 | .1 | .100-.150 | Infrastructure |
|
|
| 20 (IOT) | 192.168.1.0/24 | .1 | .100-.200 | Smart home |
|
|
| 30 (GUEST) | 192.168.2.0/24 | .1 | .100-.150 | Guest access |
|
|
|
|
### Static Assignments
|
|
|
|
| Host | IP | MAC | Purpose |
|
|
|------|-----|-----|---------|
|
|
| Atlantis | 192.168.0.200 | - | Primary NAS (DS1823xs+) |
|
|
| Calypso | 192.168.0.250 | - | Secondary NAS (DS723+), runs NPM |
|
|
| Guava | 192.168.0.100 | - | TrueNAS Scale workstation |
|
|
| PVE | 192.168.0.205 | - | Proxmox hypervisor |
|
|
| Pi-5 | 192.168.0.66 | - | Raspberry Pi 5 |
|
|
| Homelab VM | 192.168.0.210 | - | Proxmox VM, monitoring |
|
|
|
|
---
|
|
|
|
## Port Forwarding
|
|
|
|
### External Access
|
|
|
|
| Service | External Port | Internal IP | Internal Port | Protocol |
|
|
|---------|---------------|-------------|----------------|----------|
|
|
| NPM HTTP | 80 | 192.168.0.250 | 80 | HTTP |
|
|
| NPM HTTPS | 443 | 192.168.0.250 | 443 | HTTPS |
|
|
| Headscale | 8443 | 192.168.0.250 | 8085 | TCP (control server) |
|
|
| Plex | 32400 | 192.168.0.200 | 32400 | TCP |
|
|
|
|
### Internal Only (No Port Forward)
|
|
|
|
| Service | Internal IP | Port | Access Method |
|
|
|---------|-------------|------|----------------|
|
|
| Grafana | 192.168.0.210 | 3000 | VPN only |
|
|
| Prometheus | 192.168.0.210 | 9090 | VPN only |
|
|
| Home Assistant | 192.168.12.202 | 8123 | VPN only (via GL-MT3000 subnet) |
|
|
| Authentik | 192.168.0.250 | 9000 | VPN only |
|
|
| Vaultwarden | 192.168.0.200 | 8080 | VPN only |
|
|
|
|
---
|
|
|
|
## DNS Configuration
|
|
|
|
### Primary: Pi-hole / AdGuard
|
|
|
|
```
|
|
Upstream DNS:
|
|
- 1.1.1.1 (Cloudflare)
|
|
- 8.8.8.8 (Google)
|
|
|
|
Local Domains:
|
|
- vish.local
|
|
- vish.gg
|
|
```
|
|
|
|
### Local DNS Entries
|
|
|
|
| Hostname | IP | Description |
|
|
|----------|-----|-------------|
|
|
| atlantis | 192.168.0.200 | Primary NAS (DS1823xs+) |
|
|
| calypso | 192.168.0.250 | Secondary NAS (DS723+) |
|
|
| guava | 192.168.0.100 | TrueNAS Scale |
|
|
| pve | 192.168.0.205 | Proxmox host |
|
|
| homelab | 192.168.0.210 | Proxmox VM |
|
|
| pi-5 | 192.168.0.66 | Raspberry Pi 5 |
|
|
|
|
---
|
|
|
|
## Reverse Proxy Flow
|
|
|
|
### External Request (vish.gg)
|
|
|
|
```
|
|
1. User → https://service.vish.gg
|
|
2. Cloudflare DNS → resolves to home IP
|
|
3. Home Router → forwards to 192.168.0.250:443
|
|
4. NPM (Calypso) → terminates SSL
|
|
5. Authentik (if SSO) → authenticates
|
|
6. Backend service → responds
|
|
7. NPM → returns to user
|
|
```
|
|
|
|
### Internal Request
|
|
|
|
```
|
|
1. User → http://service.local (or IP)
|
|
2. Pi-hole/AdGuard → resolves to internal IP
|
|
3. NPM (optional) or direct → service
|
|
4. Response → user
|
|
```
|
|
|
|
---
|
|
|
|
## VPN Configuration
|
|
|
|
### Headscale (Primary Mesh VPN)
|
|
|
|
All nodes use the Tailscale client pointed at the self-hosted Headscale control server.
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| Control Server | `headscale.vish.gg:8443` |
|
|
| Host | Calypso (192.168.0.250) |
|
|
| Admin UI | Headplane (via NPM at :8443/admin) |
|
|
| DERP Servers | Tailscale public DERP map |
|
|
| MagicDNS suffix | `tail.vish.gg` |
|
|
| IP Range | 100.64.0.0/10 |
|
|
| Exit Nodes | atlantis, calypso, setillo, vish-concord-nuc, seattle, homeassistant |
|
|
|
|
### WireGuard (Point-to-Point, Secondary)
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| Server | Concord NUC (wg-easy, port 51820) |
|
|
| Interface | Dynamic |
|
|
| Use Case | Clients that can't run Tailscale |
|
|
|
|
---
|
|
|
|
## VLAN Configuration
|
|
|
|
### Management VLAN (10)
|
|
- Devices: NAS, switches, APs
|
|
- Access: Admin only
|
|
- Internet: Full
|
|
|
|
### IoT VLAN (20)
|
|
- Devices: Smart home, cameras
|
|
- Access: Restricted
|
|
- Internet: Filtered (Pi-hole)
|
|
- Isolation: Yes
|
|
|
|
### Main VLAN (30)
|
|
- Devices: Personal devices
|
|
- Access: Full
|
|
- Internet: Full
|
|
|
|
---
|
|
|
|
## Firewall Rules
|
|
|
|
### Router (UFW/iptables)
|
|
|
|
```bash
|
|
# Allow established connections
|
|
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
|
|
|
|
# Allow SSH
|
|
iptables -A INPUT -p tcp --dport 22 -j ACCEPT
|
|
|
|
# Allow HTTP/HTTPS
|
|
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
|
|
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
|
|
|
|
# Allow WireGuard
|
|
iptables -A INPUT -p udp --dport 51820 -j ACCEPT
|
|
|
|
# Drop everything else
|
|
iptables -A INPUT -j DROP
|
|
```
|
|
|
|
### Docker Network
|
|
|
|
```yaml
|
|
# docker-compose.yml
|
|
networks:
|
|
default:
|
|
driver: bridge
|
|
ipam:
|
|
config:
|
|
- subnet: 172.20.0.0/24
|
|
```
|
|
|
|
---
|
|
|
|
## Monitoring
|
|
|
|
### Network Metrics
|
|
|
|
| Metric | Source | Dashboard |
|
|
|--------|--------|-----------|
|
|
| Bandwidth | Node Exporter | Network |
|
|
| Packet loss | Prometheus | Network |
|
|
| DNS queries | Pi-hole | DNS |
|
|
| VPN connections | WireGuard | VPN |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Cannot Access Service
|
|
|
|
1. **Check DNS:** `nslookup service.vish.local`
|
|
2. **Check connectivity:** `ping 192.168.0.x`
|
|
3. **Check port:** `nc -zv 192.168.0.x 443`
|
|
4. **Check service:** `curl -I http://localhost:PORT`
|
|
5. **Check firewall:** `sudo iptables -L`
|
|
|
|
### Slow Network
|
|
|
|
1. Check bandwidth: `iperf3 -c 192.168.0.x`
|
|
2. Check for interference (WiFi)
|
|
3. Check switch port speed
|
|
4. Check for broadcast storms
|
|
|
|
### VPN Issues
|
|
|
|
1. Check WireGuard status: `wg show`
|
|
2. Check Headscale nodes: `headscale nodes list`
|
|
3. Verify firewall allows UDP 51820
|
|
4. Check NAT traversal
|
|
|
|
---
|
|
|
|
## Links
|
|
|
|
- [Cloudflare Setup](../infrastructure/cloudflare-dns.md)
|
|
- [WireGuard Guide](../services/individual/wg-easy.md)
|
|
- [Headscale Setup](../infrastructure/tailscale-setup-guide.md)
|
|
- [Port Forwarding](../infrastructure/port-forwarding-configuration.md)
|