🔐 WireGuard Split-Tunnel VPN

Complete Documentation for a Production-Ready Selective Routing VPN System

📊 System Overview

Clients Supported
Up to 254
IP Allocation
10.7.0.0/24
Direct Internet
10.7.0.0-127
VPN Routed
10.7.0.128-255
Listen Port
UDP 22119
VPN Provider
NordVPN

🚀 Quick Navigation

Architectural Guide Technical Reference Source Files

🏗️ Architectural Guide

A comprehensive high-level overview of the system architecture, design principles, and how all components interact together. Perfect for understanding the big picture without deep technical details.

  • System architecture diagrams
  • Component descriptions
  • IP allocation strategy
  • Data flow scenarios
  • DNS resolution architecture
  • Network namespace design
  • Policy routing concepts
  • Security model analysis
Read Architectural Guide →

⚙️ Technical Reference

Complete line-by-line documentation of every configuration file and script. Explains what each line does, why it's implemented that way, and how it interacts with the rest of the system. For developers and engineers.

Read Technical Reference →

📂 Project Files

This system consists of 4 essential files that work together to create the complete split-tunnel routing solution. Each file has a specific role in the network configuration.

📋 internal.conf

dnsmasq DNS server configuration with custom local domain records and upstream DNS servers

🔐 wg0.conf

WireGuard interface configuration with private key, IP address, port, and lifecycle hooks

🚀 wg0-up.sh

Startup script (217 lines) that creates namespaces, starts OpenVPN, and configures routing

🛑 wg0-down.sh

Teardown script that gracefully removes all networking and returns system to clean state

✨ Key Features & Capabilities

🎯 IP-Based Routing

Traffic routing decisions made automatically based on client IP assignment. No per-client configuration needed - just assign an IP and the system handles the rest.

🔀 Split Tunneling

Divide VPN network into two halves: direct internet (low latency) and VPN-routed (privacy). Both types of clients connected simultaneously.

🌐 DNS Privacy

DNS queries from VPN clients are routed through the VPN tunnel, preventing DNS leaks and providing true privacy for DNS resolution.

📦 Namespace Isolation

OpenVPN runs in an isolated network namespace, preventing routing conflicts and enabling completely different routing policies for VPN traffic.

🛣️ Policy Routing

Kernel-level routing decisions based on packet marks, source IPs, and destinations. Sophisticated routing without client awareness.

🔒 Transparent Operation

Clients require no special configuration. Simply connect to WireGuard and automatically get the routing determined by their IP assignment.

🚀 Scalable Design

Supports up to 254 simultaneous clients with no client-side complexity. Server-side routing handles all complexity transparently.

🔧 Production Ready

Idempotent operations, graceful shutdown, stateful filtering, and comprehensive error handling. Safe for production environments.

📖 Documentation Structure

This documentation suite consists of three carefully organized documents:

1. Architectural Guide

Comprehensive overview of the system at a conceptual level. Explains the design principles, architecture diagrams, how components fit together, and data flow through the system. Best for understanding the big picture.

2. Technical Reference

Complete line-by-line documentation of every file and script. Each line of code is explained with what it does, why it's implemented that way, and how it interacts with other parts. Best for implementation and debugging.

3. This Homepage

Navigation hub and quick reference with system overview, feature highlights, and links to detailed documentation. Use this to find the right documentation for your needs.

🎓 Getting Started

Start with the guide that matches your needs: