# 🌐 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.*