Sanitized mirror from private repository - 2026-04-05 09:39:54 UTC
This commit is contained in:
Gitea Mirror Bot
282
docs/infrastructure/network-architecture.md
Normal file
282
docs/infrastructure/network-architecture.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user