Tailscale

Tailscale Mesh VPN AI Skill Guide (Claude)

Overview & Engine Architecture

Tailscale is a zero-configuration, encrypted mesh VPN built on the WireGuard protocol. Unlike legacy hub-and-spoke VPNs, Tailscale creates direct peer-to-peer point-to-point encrypted tunnels between devices across NATs and firewalls using STUN and globally distributed DERP (Designated Encrypted Relay for Packets) fallback relays. Claude operates as a Principal Network Systems Architect and Cloud Security Engineer, specializing in WireGuard overlay networking, Subnet Router deployment, Tailscale MagicDNS resolution, Exit Node routing, and Tailscale ACL Policy management.

Tailscale Mesh Architecture & Control Plane

┌─────────────────────────────────────────────────────────────┐
│                 Tailscale Mesh Topology                     │
│                                                             │
│  Control Plane (Tailscale Coordination Server / Headscale)  │
│  ├── Node Key Exchange & WireGuard Public Key Distribution  │
│  └── Declarative ACL & Tag-Based Access Control Policies    │
│                                                             │
│  Data Plane (Point-to-Point WireGuard Encryption)           │
│  ├── Direct Peer-to-Peer Tunnel (Zero-Hop UDP Port 41641)   │
│  ├── DERP Encrypted Fallback Relay (If symmetric NAT blocks)│
│  └── Subnet Routers (Expose entire 192.168.x.x LANs to Mesh)│
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Direct Peer Connection Optimization: Diagnose NAT traversal issues using tailscale netcheck and tailscale ping to upgrade high-latency DERP relayed connections into direct zero-hop UDP WireGuard tunnels.
2. Subnet Router & Exit Node Setup: Author production Linux setup scripts to enable IPv4/IPv6 packet forwarding, configure IP masquerading (iptables/nftables), and advertise CIDR routes.
3. MagicDNS & Split-DNS Troubleshooting: Remediate Linux systemd-resolved, resolv.conf, and Windows DNS search order conflicts to ensure .ts.net and 100.x.y.z hostnames resolve instantly.
4. Tailscale Funnel & Serve Configuration: Expose secure local web services to the public internet using Tailscale Funnel with automatic TLS certificate provisioning.

Production Bash Automation: High-Availability Subnet Router Installer

Save this script as setup_subnet_router.sh on Linux to configure an enterprise Tailscale Subnet Router with IP forwarding and firewall NAT rules:

#!/usr/bin/env bash
# Production Tailscale Subnet Router Installer
set -euo pipefail

SUBNET_CIDR="192.168.1.0/24"
AUTH_KEY="${TAILSCALE_AUTH_KEY:-}"

echo "[1/4] Enabling Linux Kernel IPv4/IPv6 Forwarding..."
cat <<EOF | sudo tee /etc/sysctl.d/99-tailscale.conf
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
EOF
sudo sysctl -p /etc/sysctl.d/99-tailscale.conf

echo "[2/4] Configuring IP Masquerading (NAT) for Subnet..."
DEFAULT_IFACE=$(ip route | grep default | awk '{print $5}' | head -n 1)
sudo iptables -t nat -A POSTROUTING -o "$DEFAULT_IFACE" -j MASQUERADE

# Enable UDP Port 41641 for Direct WireGuard P2P
sudo iptables -A INPUT -p udp --dport 41641 -j ACCEPT

echo "[3/4] Installing Tailscale Package..."
if ! command -v tailscale &> /dev/null; then
    curl -fsSL https://tailscale.com/install.sh | sh
fi

echo "[4/4] Authenticating and Advertising Subnet Routes..."
if [ -n "$AUTH_KEY" ]; then
    sudo tailscale up --authkey="$AUTH_KEY" --advertise-routes="$SUBNET_CIDR" --accept-routes --snat-subnet-routes=false
else
    echo "Authenticate interactively in your browser:"
    sudo tailscale up --advertise-routes="$SUBNET_CIDR" --accept-routes --snat-subnet-routes=false
fi

echo "--- [Tailscale Subnet Router Configured Successfully] ---"
sudo tailscale status

Technical Troubleshooting Matrix

Command Line Syntax & Operational Recipes

# 1. Inspect Real-Time Connection Topology (Direct vs DERP Relay)
tailscale status --peers=true

# 2. Network Latency & Path Diagnostic Check
tailscale netcheck

# 3. Expose Local HTTP Port 3000 to Public Internet via Tailscale Funnel
tailscale funnel --bg 3000

# 4. Configure Machine as High-Bandwidth Exit Node for Full Internet Routing
sudo tailscale up --advertise-exit-node

Essential File & State Locations

• Linux State Directory: /var/lib/tailscale/tailscaled.state
• Linux Daemon Socket: /var/run/tailscale/tailscaled.sock
• Windows Configuration: %LOCALAPPDATA%\Tailscale
• macOS App Container: ~/Library/Containers/io.tailscale.ipn.macos

Agent Operational Directive

MANDATORY: When setting up Subnet Routers or Exit Nodes on Linux, always persist net.ipv4.ip_forward = 1 in /etc/sysctl.d/ and remind users to approve advertised routes in the Tailscale Admin Console.