Tailscale

This guide is an independent, paraphrased technical tutorial based on public Tailscale concepts. Always consult official docs for authoritative details and current limits.

1. Overview

Tailscale builds a user‑space, identity‑aware, WireGuard®‑based mesh overlay that connects devices (a "tailnet") securely without managing traditional VPN concentrators. It focuses on:

• Zero‑config peer mesh (NAT traversal, relays only as fallback)
• Device & user identity (SSO / IdP integration)
• Fine‑grained policy (legacy ACLs + next‑gen Grants)
• Built‑in service discovery (MagicDNS, tags, autogroups)
• Application‑level access (Tailscale SSH, Funnel/Serve)
• Operational simplicity (ephemeral keys, GitOps policy, audit logs)

Use cases span homelab, multi‑cloud/service segmentation, developer remote access, site‑to‑site bridging, and incremental zero trust migration.

2. Core Architecture

Plane	Component	Responsibility
Control / Coordination	Coordination server	Auth handshake, key distribution metadata, NAT traversal assistance (STUN/DERP); never terminates user payload.
Data	WireGuard peer tunnels	Direct encrypted device‑to‑device UDP (or TCP encapsulated via DERP fallback).
Identity	SSO / IdP	Issues user principal (OIDC/SAML) feeding into tailnet policy.
Policy	Tailnet policy file (huJSON)	Access rules: legacy ACLs + Grants, tags, groups, device attributes, posture.
DNS / Discovery	MagicDNS / built‑in resolver	Human names, split DNS, internal cert issuance (HTTPS feature).
Enhanced Access	Tailscale SSH	Host-keyless, identity‑based SSH authorization with policy gating.
Ingress / Egress	Funnel / Serve / Exit Nodes	Controlled inbound publishing or routing outbound traffic via a node.

2.1 Flow Summary

1. Device authenticates via browser SSO → obtains node key (possibly ephemeral) signed into tailnet.
2. Coordination service pushes peer endpoint metadata + policies.
3. Peers attempt direct WireGuard handshake (NAT traversal); fallback to DERP relay only if hole‑punching fails.
4. Each device locally enforces policy—control plane is out of data path once sessions established.

2.2 Security Principles

• End‑to‑end encryption (WireGuard noise handshake → ChaCha20‑Poly1305) per peer pair.
• Default allow‑all initial sample policy for convenience; recommended shift to deny‑by‑default.
• Policy enforcement at edge (no central decrypt). Tailnet Lock (optional) adds signing root of trust.

3. Key Concepts

Concept	Description
Tailnet	Logical private mesh network for an org/user.
Node key / Auth key	Device key (short‑lived / renewable); Auth keys can auto‑provision unattended or ephemeral nodes.
Tags	Metadata labeling devices for scoping policy.
Groups	Logical sets of users (from IdP).
Autogroups	Built‑in sets like autogroup:members.
ACLs	First‑gen directional allow rules (still supported).
Grants	Next‑gen syntax unifying access control with richer semantics.
MagicDNS	Internal naming + automatic discovery.
Subnet router	Node advertising non‑Tailscale CIDRs into tailnet.
Exit node	Node chosen to route full Internet egress (like a split‑tunnel pivot).
Funnel / Serve	Publish services on a node to the Internet (Funnel) or local reverse‑proxy within tailnet (Serve).
Tailscale SSH	SSH sessions authenticated via identity & policy (no manual authorized_keys).

4. Installation Matrix

Environment	Command / Notes
macOS	Install app (GUI) or brew install --cask tailscale; then tailscale up.
Linux (Debian/Ubuntu)	`curl -fsSL https://tailscale.com/install.sh
Docker container	Run sidecar or embed binary; start with tailscaled & plus tailscale up --authkey=....
Kubernetes	Sidecar per pod (for service mesh patterns) or node‑level DaemonSet; or use operator patterns.
Windows	Installer GUI / MSI; then authenticate.
iOS / Android	Mobile apps (on‑demand or persistent).

Minimal Linux quick start:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --accept-routes --ssh --authkey tskey-auth-ABC123 --hostname api-node-1

(Use ephemeral or pre‑authorized keys for automation; never hardcode reusable long‑lived keys in public repos.)

5. Quick Start Workflow

1. Create tailnet (sign in) & link IdP.
2. Install client on two devices; run tailscale up.
3. Confirm mutual connectivity: tailscale status and ping by magic name ping host2 or curl http://host2:8080.
4. Tighten policy: replace default allow with explicit accept rules or grants.
5. Optionally enable MagicDNS + HTTPS certs for internal hostnames.
6. Add SSH support: tailscale up --ssh and define ssh section (Grants) / ssh ACL block.

6. Policy: ACLs vs Grants

Tailscale is evolving from classic ACL JSON arrays to Grants (richer, composable, future‑extensible). Both live in the tailnet policy file (huJSON: JSON + comments/trailing commas). Grants unify access semantics (network, SSH, Funnel). Existing ACLs continue working; new builds should prefer Grants where available.

6.1 Sample Deny‑by‑Default (ACL style)

{ // tailnet policy file excerpt
  "acls": [
    { "action": "accept", "src": ["group:dev"], "dst": ["tag:api:443", "tag:db:5432"] },
    { "action": "accept", "src": ["tag:ci"], "dst": ["tag:api:443"] }
  ],
  "tagOwners": { "tag:api": ["group:platform"], "tag:db": ["group:platform"], "tag:ci": ["group:devops"] },
  "groups": { "group:dev": ["alice@example.com", "bob@example.com"], "group:platform": ["carol@example.com"], "group:devops": ["dana@example.com"] }
}

6.2 Equivalent (Illustrative Grants Style)

{ // illustrative only; verify final syntax in official docs
  "grants": [
    {
      "who": ["group:dev"],
      "can": ["connect"],
      "to": ["tag:api:443", "tag:db:5432"],
      "because": "Developers need API+DB"
    },
    {
      "who": ["tag:ci"],
      "can": ["connect"],
      "to": ["tag:api:443"],
      "because": "CI triggers integration tests"
    }
  ]
}

Add posture / time‑bounded / JIT constraints as features permit. Maintain policies via GitOps (API pull + PR review) for auditable change control.

7. Tags, Groups, Device Attributes

• Use minimal stable tags per service layer: tag:frontend, tag:api, tag:db.
• Enforce tagOwners to restrict who can claim tags.
• Device posture attributes (when available) can require OS patch level or disk encryption for access.

8. Subnet Routers (Layer 3 Expansion)

A subnet router advertises traditional LAN/IP ranges into the tailnet. Example enabling two ranges:

sudo tailscale up --advertise-routes=10.10.0.0/16,10.20.0.0/16 --authkey tskey-auth-subnet-XXX

Then approve routes (admin console or API). Security Tip: Limit which users/groups can use advertised routes with explicit ACL/Grant targets.

9. Exit Nodes

Exit nodes route general Internet traffic from a client through a chosen peer (privacy / geolocation / egress control). Enable on candidate:

sudo tailscale up --advertise-exit-node

Use from a client:

tailscale up --exit-node=node-exit-1 --exit-node-allow-lan-access=true

Mitigate risk by restricting who can select the exit node in policy.

10. MagicDNS & Internal HTTPS

Activate MagicDNS to avoid raw IP usage and to integrate internal certificate issuance for HTTPS (optional in plans). After enabling, hosts resolve like api-node-1.tailnet-name.ts.net. Combine with split DNS for on‑prem resolvers; audit names to avoid collisions.

11. Tailscale SSH

Enable host and define policy referencing ssh capability (ACL section or Grants). Connect without provisioning static host keys:

# From client
ssh root@api-node-1

Session enforcement occurs via identity + tailnet policy; optionally enable session recording.

12. Funnel & Serve

• Serve: Reverse proxy local service to tailnet (e.g., map HTTP to 443 internally).
• Funnel: Carefully expose a tailnet service to the public Internet via a Tailscale-managed endpoint (plan/feature gated). Example (illustrative):

tailscale serve https / myapp.local 3000
# For Funnel (public) – confirm feature availability
 tailscale funnel 443 3000

Validate least privilege: restrict which tagged nodes may use Funnel to mitigate inadvertent exposure.

13. Kubernetes Patterns

Pattern	Description	Pros	Cons
Node-level DaemonSet	Each node joins tailnet; cluster services reachable by node IPs.	Simpler ops	Less granular per-pod isolation
Sidecar per Pod	Pod gets its own tailnet identity; fine-grained policy.	Granular isolation	Higher resource overhead
Gateway Pod + Subnet Router	Single pod advertises internal Service CIDRs.	Minimal footprint	Single point of concentration
Operator / Automation	Declaratively manage keys, tags, and rotation.	GitOps alignment	Additional controller complexity

Example sidecar snippet (simplified):

apiVersion: v1
kind: Pod
metadata:
  name: api-with-mesh
  labels:
    app: api
spec:
  containers:
    - name: api
      image: ghcr.io/example/api:1.2.3
      ports:
        - containerPort: 8080
    - name: tailscaled
      image: tailscale/tailscale:stable
      securityContext:
        capabilities:
          add: ["NET_ADMIN", "SYS_MODULE"]
      env:
        - name: TS_AUTHKEY
          valueFrom:
            secretKeyRef:
              name: ts-auth
              key: authkey
      args: ["/bin/sh", "-c", "tailscaled & sleep 5; tailscale up --authkey $TS_AUTHKEY --hostname api-with-mesh --accept-routes --ssh; tail -f /dev/null"]

Use ephemeral auth keys with auto‑expiry to reduce credential blast radius.

14. Automation & CI/CD

Common patterns:

• Ephemeral build agents join tailnet only for artifact pulls.
• CI job uses short‑lived key (scoped to tags) then self‑destructs.
• GitOps for policy: pipeline validates policy file syntax (huJSON → strict JSON) & runs static rules (e.g., forbid wide *:*).

Example policy lint (pseudo make target):

validate-tailscale-policy:
	jq '.' tailnet-policy.hujson >/dev/null
	./scripts/check-wide-rules.py tailnet-policy.hujson

15. Security Hardening Checklist

Area	Recommendation
Key Lifecycle	Prefer ephemeral / auto‑expiring auth keys; rotate device keys periodically.
Principle of Least Privilege	Constrain Grants/ACL scopes; segment by tag layers.
Tag Ownership	Restrict tagOwners to platform/security groups.
Funnel / Exit	Limit to dedicated hardened nodes; monitor logs.
Logging	Stream flow logs & configuration audit logs to SIEM.
Posture	Enforce device posture (disk encryption, OS version) where supported.
Tailnet Lock	Enable for high assurance (tamper resistant root of trust).
Secrets	Never embed long‑lived keys in images; inject at runtime (K8s secrets, vault).

16. Performance & Reliability

• Direct path preference: ensure symmetric UDP allowed outbound; open minimal egress (no inbound listener requirement for most NAT types).
• Monitor tailscale status for relay indicators (DERP usage). Excess indicates traversal failures.
• On high‑connection servers, tune OS: increase UDP buffer sizes, avoid aggressive firewall conntrack expiry.
• Leverage multiple subnet routers for HA (advertise identical routes → any can serve). Avoid single exit node chokepoint.

17. Troubleshooting Flow

Symptom	Diagnostic	Action
Cannot reach peer	tailscale status (check relay vs direct)	Inspect firewalls; ensure recent client version
DNS resolution fails	tailscale netcheck; verify MagicDNS setting	Re-enable MagicDNS or push split DNS config
Route not applied	tailscale netcheck / admin routes page	Approve route; verify advertising flag
SSH denied	Policy log / check Grants ssh scope	Add explicit rule; ensure device tagged properly
High DERP usage	Status shows relay frequently	Allow UDP outbound; examine symmetric NAT constraints

Generate verbose logs:

sudo tailscale bugreport
# or
sudo tailscale up --verbose=1

18. Frequently Asked Questions

Question	Answer (Concise)
Does control plane see plaintext?	No; encryption end‑to‑end between peers. Control plane holds coordination metadata only.
Can I keep ACLs?	Yes, indefinitely; but new capabilities appear first in Grants.
Is DERP a bottleneck?	Only for flows that can't traverse NAT; optimize network to maximize direct paths.
How do I rotate keys?	Use key expiry automation + ephemeral keys + periodic device reauth (or Tailnet Lock).
Multi‑cloud connectivity?	Just install on instances; optionally add subnet routers for VPC CIDRs.
Replace traditional VPN?	Often; phased migration using subnet routers + gradually enforced policy.
Public service exposure?	Use Funnel selectively; otherwise prefer internal Serve or reverse proxy.

19. Best Practices Summary

• Start permissive for bootstrap, then transition to explicit deny‑by‑default.
• Normalize naming/tag taxonomy early.
• Automate policy validation (syntax + rule lint) in CI before merge.
• Use ephemeral auth keys for CI agents & short‑lived workloads.
• Limit exposure features (Funnel, exit nodes) to hardened, monitored nodes.
• Stream logs to centralized observability; alert on wide grants or new relay dependencies.
• Keep clients updated (benefits: traversal, performance, security patches).

20. Next Steps & Integrations

Consider layering:

• Monitoring: Flow logs → SIEM, metrics dashboards.
• Secret managers: Inject auth keys dynamically.
• Posture attestation: Gate higher‑sensitivity services behind strong device posture policies.
• Terraform / API: Codify tailnet policy & provisioning.

21. Attribution

WireGuard® is a registered trademark of Jason A. Donenfeld. This document paraphrases public Tailscale concepts; consult official docs for authoritative, evolving details.

---

End of guide.