Tailscale VPN¶

Tailscale ACL policy, peer relay, and connection troubleshooting.

ACL Policy¶

{
  "tagOwners": {
    "tag:relay": ["autogroup:admin"],
    "tag:clients": ["autogroup:admin"]
  },
  "acls": [
    { "action": "accept", "src": ["*"], "dst": ["*:*"] }
  ],
  "grants": [
    {
      "src": ["tag:clients"],
      "dst": ["tag:relay"],
      "app": { "tailscale.com/cap/relay": [] }
    },
    {
      "src": ["tag:clients"],
      "dst": ["tag:relay"],
      "ip": ["*"]
    }
  ]
}

The grants section must be set via the Tailscale API directly -- the MCP ACL tool (manage_acl) silently drops it:

curl -X POST -H "Authorization: Bearer $TAILSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.tailscale.com/api/v2/tailnet/mordasiewicz.com/acl" \
  -d '{ ... full ACL with grants ... }'

Peer Relay¶

When direct connections fail (school NAT, mobile hotspot symmetric NAT), devices route through tsrelay instead of Tailscale's DERP servers. No bandwidth throttling unlike DERP.

The Toronto Bell PPPoE address is dynamic, and automatic discovery does not reliably advertise the forwarded relay port. The relay therefore advertises the current public IP:40000 explicitly. A systemd timer refreshes it every five minutes when the public address changes:

Check the updater and advertised endpoint with:

systemctl status tailscale-relay-endpoint.timer
sudo systemctl start tailscale-relay-endpoint.service
tailscale debug prefs | grep -A3 RelayServer

On 2026-05-24, tsrelay had a stale static endpoint (142.114.208.227:40000). Peer-relay sessions were allocated but stuck at <no handshake>. The timer now prevents this. To clear static endpoint config while troubleshooting:

sudo tailscale set --relay-server-static-endpoints=

Do not leave the endpoint empty afterward. Run the updater service to restore the current public endpoint.

On 2026-07-21, Mac-to-workstation traffic was verified through peer-relay <public-ip>:40000; both clients reported the same VNI and the relay session counters increased in both directions.

Workstation needed Tailscale 1.98.3; with 1.96.4, relay candidates were visible but traffic still preferred DERP in cases where peer relay should have been available.

Connection priority (automatic)¶

flowchart TD
    A["Client connects"] --> B{"Direct UDP<br/>hole-punch?"}
    B -- "Yes" --> C["Direct connection<br/>~15ms"]
    B -- "No" --> D{"Peer relay<br/>available?"}
    D -- "Yes" --> E["Peer relay<br/>~15-45ms"]
    D -- "No" --> F["DERP relay<br/>~14ms, throttled"]

Grant mechanics¶

• src = who can use the relay (tag:clients)
• dst = the relay device (tag:relay)
• Only the initiating device needs the tag, not both sides
• Tags can't be removed without tailscale up --force-reauth
• To test without relay, remove grants from ACL instead of changing device tags

Connection Results by Location¶

Tailscale Ports¶