---
name: tailscale
description: "Configure Tailscale connectivity, subnet routing, and MagicDNS; troubleshoot WireGuard paths and DERP relay behavior."
category: cross-platform
risk: safe
source: self
source_type: self
date_added: "2026-08-26"
tags: ["tailscale", "wireguard", "mesh-vpn", "derp-relay", "magicdns", "subnet-router", "claude"]
tools: ["claude", "cursor", "gemini", "codex"]
---

# 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:

```bash
#!/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

| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **High Latency (>150ms) / Slow Speed on Local Network** | Traffic is routing through a distant DERP relay due to symmetric NAT or firewall blocking direct UDP packets. | 1. Run `tailscale netcheck` to diagnose NAT mapping.<br>2. Run `tailscale ping <target-node>` to inspect if connection is `direct` or `via DERP(...)`.<br>3. Open UDP port **41641** on your router/firewall. |
| **Subnet Router Advertises Route but Devices Cannot Ping LAN IPs** | Linux host has `net.ipv4.ip_forward` disabled, or route approval is pending in Tailscale Admin Console. | 1. Check `sysctl net.ipv4.ip_forward` (must equal 1).<br>2. In **Tailscale Admin Console** $\rightarrow$ *Machines*, click the router node $\rightarrow$ *Edit Route Settings* $\rightarrow$ **Approve Route**.<br>3. On client nodes, ensure `tailscale up --accept-routes` is enabled. |
| **MagicDNS Fails to Resolve Hostnames on Linux** | Conflict between Tailscale DNS and local `systemd-resolved` or network manager. | 1. Check `/etc/resolv.conf` (should link to `/run/systemd/resolve/stub-resolv.conf`).<br>2. Run `systemctl restart systemd-resolved`.<br>3. Set `tailscale up --accept-dns=true`. |
| **Windows TUN Adapter Fails: `Wintun error`** | Conflicting VPN drivers (OpenVPN, NordVPN) locked the Wintun network adapter. | 1. Open Device Manager $\rightarrow$ Network Adapters $\rightarrow$ Uninstall **Tailscale Tunnel / Wintun**.<br>2. Restart Tailscale Windows Service (`net stop Tailscale && net start Tailscale`). |

---

## Command Line Syntax & Operational Recipes

```bash
# 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.