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