289 lines
9.5 KiB
Markdown
289 lines
9.5 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.10 | AA:BB:CC:DD:EE:FF | Primary NAS |
|
|
| Calypso | 192.168.0.11 | AA:BB:CC:DD:EE:FF | Secondary NAS |
|
|
| Concord NUC | 192.168.0.20 | AA:BB:CC:DD:EE:FF | Home Assistant |
|
|
| Homelab VM | 192.168.0.210 | - | Monitoring |
|
|
| RPi5 | 192.168.0.50 | - | Edge |
|
|
| Pi-hole | 192.168.0.53 | - | DNS Primary |
|
|
| AdGuard | 192.168.0.54 | - | DNS Secondary |
|
|
|
|
---
|
|
|
|
## Port Forwarding
|
|
|
|
### External Access
|
|
|
|
| Service | External Port | Internal IP | Internal Port | Protocol |
|
|
|---------|---------------|-------------|----------------|----------|
|
|
| NPM HTTP | 80 | 192.168.0.11 | 80 | HTTP |
|
|
| NPM HTTPS | 443 | 192.168.0.11 | 443 | HTTPS |
|
|
| WireGuard | 51820 | 192.168.0.11 | 51820 | UDP |
|
|
| Plex | 32400 | 192.168.0.10 | 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.0.20 | 8123 | VPN only |
|
|
| Authentik | 192.168.0.11 | 9000 | VPN only |
|
|
| Vaultwarden | 192.168.0.10 | 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.10 | Primary NAS |
|
|
| calypso | 192.168.0.11 | Secondary NAS |
|
|
| concord-nuc | 192.168.0.20 | Intel NUC |
|
|
| homelab | 192.168.0.210 | Proxmox VM |
|
|
| rpi5 | 192.168.0.50 | Raspberry Pi |
|
|
| pihole | 192.168.0.53 | Pi-hole |
|
|
| adguard | 192.168.0.54 | AdGuard |
|
|
|
|
---
|
|
|
|
## 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.11: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
|
|
|
|
### WireGuard (Primary)
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| Server | calypso.vish.local:51820 |
|
|
| Interface | 10.0.0.1/24 |
|
|
| Clients | Dynamic (pre-shared key) |
|
|
| Persistent Keepalive | 25 seconds |
|
|
|
|
### Headscale (Mesh)
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| Control Server | headscale.vish.local |
|
|
| Namespace | homelab |
|
|
| DERP Servers | Enabled |
|
|
| Exit Node | Enabled |
|
|
|
|
### Tailscale (Backup)
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| Control | tailscale.io |
|
|
| ACL | Defined in headscale |
|
|
| Subnet Router | Enabled |
|
|
|
|
---
|
|
|
|
## 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)
|