Vish/homelab-optimized
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sanitized mirror from private repository - 2026-03-27 11:53:55 UTC
Some checks failed
Documentation / Build Docusaurus (push) Failing after 5m8s
Details
Documentation / Deploy to GitHub Pages (push) Has been skipped
Details

Browse Source
This commit is contained in:
Gitea Mirror Bot
2026-03-27 11:53:55 +00:00
commit 06d6e3e3af
1278 changed files with 331159 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

415
docs/infrastructure/networking.md Normal file
View File

@@ -0,0 +1,415 @@
# 🌐 Network Infrastructure Guide
**🟡 Intermediate Guide**
This guide covers the complete network infrastructure of the homelab, including the blazing-fast **25Gbps symmetric internet connection**, 10 Gigabit Ethernet backbone, Tailscale overlay network, and DNS architecture.
---
## ⚡ Internet Connection
### **ISP Specifications**
| Specification | Value |
|---------------|-------|
| **Download Speed** | 25 Gbps |
| **Upload Speed** | 25 Gbps |
| **Type** | Symmetric Fiber |
| **Latency** | <5ms to major CDNs |
> **Note**: This enterprise-grade connection supports the entire infrastructure with bandwidth to spare, enabling true 10GbE LAN-to-WAN performance.
---
## 🚀 10 Gigabit Ethernet Infrastructure
### **TP-Link TL-SX1008 - Core 10GbE Switch**
#### **Hardware Specifications**
- **Model**: TP-Link TL-SX1008
- **Type**: 8-port 10 Gigabit Ethernet unmanaged switch
- **Ports**: 8x 10GBASE-T RJ45 ports
- **Switching Capacity**: 160 Gbps
- **Forwarding Rate**: 119.05 Mpps
- **Power**: External power adapter
- **Form Factor**: Desktop/rack-mountable
#### **Connected Systems**
| Host | Interface Type | Use Case | Performance |
|------|---------------|----------|-------------|
| **Atlantis** | Built-in 10GbE | Media streaming, backup operations | Full 10Gbps |
| **Calypso** | PCIe 10GbE card | Development, package caching | Full 10Gbps |
| **Shinku-Ryuu** | PCIe 10GbE card | Gaming, creative work, large transfers | Full 10Gbps |
| **Guava** | PCIe 10GbE card | AI/ML datasets, model training | Full 10Gbps |
---
## 🏗️ Network Topology
### **Physical Network Layout**
```
Internet (25Gbps Symmetric Fiber)
│
├── TP-Link Archer BE800 Router (WiFi 7)
│ │
│ ├── Main Network (192.168.0.0/24) ──── Trusted devices
│ │ │
│ │ └── Mesh Nodes (APs) ──── WiFi coverage
│ │
│ ├── IoT WiFi ──── Smart home devices (isolated)
│ │
│ └── Guest WiFi ──── Visitors (internet only)
│
└── TP-Link TL-SX1008 (10GbE Switch)
├── Atlantis (192.168.0.200) - 10GbE
├── Calypso (192.168.0.250) - 10GbE
├── Shinku-Ryuu - 10GbE
└── Guava - 10GbE
```
### **Router Details**
| Specification | Value |
|---------------|-------|
| **Model** | TP-Link Archer BE800 |
| **WiFi Standard** | WiFi 7 (802.11be) |
| **WAN Port** | 10GbE |
| **LAN Ports** | 4x 2.5GbE + 1x 10GbE |
| **Mesh Support** | Yes (EasyMesh) |
### **Wireless Coverage**
- **Primary Router**: TP-Link Archer BE800 (WiFi 7)
- **Mesh Nodes**: Additional APs for whole-home coverage
- **SSIDs**: Main, IoT, Guest (isolated networks)
### **Network Segments**
#### **Main Network (192.168.0.0/24)**
- **Purpose**: Primary homelab infrastructure
- **Speed**: 1GbE standard, 10GbE for high-performance systems
- **Access**: Full LAN access, Tailscale routing
- **Devices**: Servers, NAS, workstations, trusted devices
#### **IoT WiFi Network**
- **Purpose**: Smart home devices, sensors
- **Isolation**: Internet access only, no LAN access
- **Devices**: Smart bulbs, sensors, cameras, etc.
- **Note**: VLAN segmentation planned for future
#### **Guest Network**
- **Purpose**: Visitor internet access
- **Isolation**: Complete isolation from internal networks
- **Features**: Bandwidth limiting, time restrictions available
---
## 🔒 Headscale VPN Overlay
> **Self-Hosted Control Plane**: This homelab uses [Headscale](https://headscale.net/), a self-hosted Tailscale control server, rather than Tailscale cloud. The control server runs at `headscale.vish.gg:8443` on Calypso. All Tailscale clients are pointed to this server.
### **Headscale / Tailscale Network Architecture**
```
Headscale Mesh Network (100.x.x.x/10)
├── Atlantis (100.83.230.112) - Primary NAS
├── Calypso (100.103.48.78) - Secondary NAS, runs Headscale
├── Setillo (100.125.0.20) - Remote NAS, Tucson
├── Homelab VM (100.67.40.126) - Main monitoring/services VM
├── PVE (100.87.12.28) - Proxmox hypervisor
├── Guava (100.75.252.64) - TrueNAS Scale physical host
├── Concord NUC (100.72.55.21) - Intel NUC, exit node
├── Shinku-Ryuu (100.98.93.15) - Desktop workstation
├── Pi-5 (100.77.151.40) - Raspberry Pi 5
├── Pi-5-Kevin (100.123.246.75) - Raspberry Pi 5 (backup ISP)
├── Jellyfish (100.69.121.120) - Pi 5 media/NAS
├── GL-MT3000 (100.126.243.15) - GL.iNet router (Concord)
├── GL-BE3600 (100.105.59.123) - GL.iNet router (Concord)
├── Home Assistant (100.112.186.90) - HA Green via GL-MT3000
├── Seattle VPS (100.82.197.124) - Contabo VPS exit node
└── matrix-ubuntu (100.85.21.51) - Atlantis VM
```
### **Headscale Benefits**
- **Self-Hosted Control**: Full ownership of coordination server and private keys
- **Zero-Config Mesh**: Automatic peer-to-peer networking
- **MagicDNS**: Device hostnames via `tail.vish.gg` suffix
- **Mobile Access**: Secure remote access from anywhere
- **Cross-Platform**: Works on all devices and operating systems
- **NAT Traversal**: Works behind firewalls and NAT (via DERP relays)
- **Unlimited Devices**: No tier limits unlike Tailscale cloud free tier
---
## 🌐 DNS Architecture
### **Split-Horizon DNS with AdGuard Home**
```
┌─────────────────────────────────────────────────────────────────┐
│ DNS RESOLUTION FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Query: plex.vish.gg │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Device │───►│ AdGuard │───►│ Cloudflare │ │
│ │ (Client) │ │ Home │ │ DNS │ │
│ └─────────────┘ └──────┬──────┘ └─────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ Local Match? │ │
│ └──────┬──────┘ │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ │ YES │ │ NO │
│ ▼ │ ▼ │
│ Return Local IP │ Forward to Upstream │
│ (192.168.0.x) │ (Cloudflare) │
│ │ │
└─────────────────────────────────────────────────────────────────┘
```
### **AdGuard Home Instances**
| Host | Location | Purpose | Tailscale IP |
|------|----------|---------|--------------|
| **Concord NUC** | Home | Primary DNS for home network | 100.72.55.21 |
| **Calypso** | Home | Secondary DNS, local services | 100.103.48.78 |
### **DNS Features**
- **Ad Blocking**: Network-wide ad blocking for all devices
- **Split-Horizon**: Local services resolve to internal IPs when on Tailscale
- **Query Logging**: DNS query analytics and monitoring
- **Parental Controls**: Content filtering capabilities
- **Custom Rewrites**: *.vish.gg → local IPs when internal
### **Split-Horizon Example**
| Query | From Internet | From Tailscale/LAN |
|-------|--------------|-------------------|
| `plex.vish.gg` | → Cloudflare → Public IP | → AdGuard → 192.168.0.80 |
| `git.vish.gg` | → Cloudflare → Public IP | → AdGuard → 192.168.0.250 |
| `grafana.vish.gg` | → Cloudflare → Public IP | → AdGuard → Internal IP |
---
## ⚡ Network Performance
### **10GbE Performance Benefits**
#### **Media Streaming**
- **4K Content**: Smooth streaming without buffering
- **8K Content**: Future-proof for ultra-high resolution
- **Multiple Streams**: Concurrent 4K streams to multiple devices
- **Plex Performance**: Instant transcoding and delivery
#### **Backup Operations**
- **NAS-to-NAS**: Fast synchronization between Atlantis and Calypso
- **Incremental Backups**: Rapid delta transfers
- **Snapshot Replication**: Quick BTRFS/ZFS snapshot transfers
- **Disaster Recovery**: Fast restoration from backups
#### **Development Workflows**
- **Docker Images**: Rapid container image pulls/pushes
- **Package Caching**: Fast APT/NPM/PyPI cache access
- **Git Operations**: Large repository clones and pushes
- **Build Artifacts**: Quick distribution of compiled binaries
#### **AI/ML Workloads**
- **Dataset Transfers**: Multi-GB datasets in seconds
- **Model Training**: Fast data loading during training
- **Model Sharing**: Quick distribution of trained models
- **Jupyter Notebooks**: Responsive remote notebook access
#### **Creative Work**
- **Video Editing**: 4K/8K raw footage transfers
- **Photo Libraries**: RAW image synchronization
- ** 3D Rendering**: Asset and render file distribution
- **Audio Production**: Multi-track project sharing
---
## 🔧 Network Configuration
### **10GbE Interface Configuration**
#### **Atlantis (Built-in 10GbE)**
```bash
# Check interface status
ip addr show eth1
# Configure static IP (if needed)
sudo nmcli con mod "Wired connection 2" ipv4.addresses 10.0.0.112/24
sudo nmcli con mod "Wired connection 2" ipv4.gateway 10.0.0.1
sudo nmcli con mod "Wired connection 2" ipv4.dns 10.0.0.1
sudo nmcli con up "Wired connection 2"
```
#### **PCIe 10GbE Cards (Calypso, Shinku-Ryuu, Guava)**
```bash
# Install drivers (if needed)
sudo apt update
sudo apt install linux-headers-$(uname -r)
# Check PCI device
lspci | grep -i ethernet
# Configure interface
sudo nmcli con add type ethernet ifname eth1 con-name 10gbe
sudo nmcli con mod 10gbe ipv4.addresses 10.0.0.XXX/24
sudo nmcli con mod 10gbe ipv4.gateway 10.0.0.1
sudo nmcli con mod 10gbe ipv4.dns 10.0.0.1
sudo nmcli con mod 10gbe ipv4.method manual
sudo nmcli con up 10gbe
```
### **Performance Testing**
#### **Bandwidth Testing**
```bash
# Install iperf3
sudo apt install iperf3
# Server mode (on target system)
iperf3 -s
# Client mode (test from another system)
iperf3 -c 10.0.0.112 -t 30 -P 4
# Expected results: ~9.4 Gbps (accounting for overhead)
```
#### **Latency Testing**
```bash
# Ping test
ping -c 100 10.0.0.112
# Expected results: <1ms latency on local network
```
#### **Real-World Performance**
```bash
# Large file transfer test
scp large_file.bin user@10.0.0.112:/tmp/
# rsync performance test
rsync -avz --progress /large/dataset/ user@10.0.0.112:/storage/
```
---
## 🌍 Public Access & Cloudflare
### **Publicly Accessible Services**
All public services are accessed via `*.vish.gg` domain through Cloudflare:
```
Internet User
│
▼
┌─────────────────┐
│ Cloudflare │ ← DDoS protection, WAF, SSL
│ (Proxy) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Router :443 │ ← Only ports 80/443 forwarded
└────────┬────────┘
│
▼
┌─────────────────┐
│ Nginx Proxy │ ← SSL termination, routing
│ Manager │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Internal Service│ ← Plex, Gitea, Grafana, etc.
└─────────────────┘
```
### **Cloudflare Configuration**
| Setting | Value |
|---------|-------|
| **SSL Mode** | Full (Strict) |
| **Always HTTPS** | Enabled |
| **Minimum TLS** | 1.2 |
| **Proxy Status** | Proxied (orange cloud) |
| **DDoS Protection** | Always On |
### **Port Forwarding**
| External Port | Internal Destination | Purpose |
|---------------|---------------------|---------|
| 80 | Nginx Proxy Manager | HTTP → HTTPS redirect |
| 443 | Nginx Proxy Manager | HTTPS services |
> **Security Note**: All other ports are blocked. Internal services are accessed via Tailscale VPN.
### **Cloudflare Tunnels**
Some services use Cloudflare Tunnels as an alternative to port forwarding:
- Zero-config public access
- No ports exposed on router
- Additional DDoS protection
---
## 🛡️ Network Security
### **Firewall Configuration**
- **Router Firewall**: TP-Link Archer BE800 built-in firewall
- **Exposed Ports**: Only 80 and 443 for reverse proxy
- **Default Policy**: Deny all inbound except allowed
- **VPN Security**: Headscale/Tailscale encrypted mesh networking
### **Access Control**
- **SSH Keys**: Key-based authentication for all Linux systems
- **Port Security**: Non-standard SSH ports where applicable
- **Service Binding**: Services bound to specific interfaces
- **Headscale ACLs**: Network access control policies
---
## 📊 Network Monitoring
### **Monitoring Tools**
- **Grafana**: Network performance dashboards
- **Prometheus**: Metrics collection and alerting
- **SNMP Monitoring**: Switch and router monitoring
- **Uptime Kuma**: Service availability monitoring
### **Key Metrics**
- **Bandwidth Utilization**: 10GbE link usage
- **Latency**: Inter-host communication delays
- **Packet Loss**: Network reliability metrics
- **Connection Counts**: Active network connections
---
## 🔄 Network Maintenance
### **Regular Tasks**
- **Firmware Updates**: Router and switch firmware
- **Cable Management**: Organize and label cables
- **Performance Testing**: Regular bandwidth tests
- **Security Audits**: Network vulnerability scans
### **Troubleshooting**
- **Link Status**: Check physical connections
- **Speed Negotiation**: Verify 10GbE link speeds
- **DNS Resolution**: Test hostname resolution
- **Routing Tables**: Verify network routing
---
## 📋 Related Documentation
- **[Host Infrastructure](hosts.md)**: Detailed host specifications
- **[Headscale Setup](../services/individual/headscale.md)**: Self-hosted Tailscale control server
- **[Tailscale Mesh Diagram](../diagrams/tailscale-mesh.md)**: Full mesh network map
- **[Network Topology](../diagrams/network-topology.md)**: Physical network layout
---
*This network infrastructure provides enterprise-level performance and reliability for the homelab environment, supporting everything from basic web browsing to high-performance computing workloads.*