Tailscale Network Management

Trigger Keywords: tailscale, tailnet, wireguard vpn, mesh vpn, tailscale ssh, exit node, subnet router, tailscale acl, magicDNS, tailscale serve, tailscale funnel

What is Tailscale? A mesh VPN service built on WireGuard that creates secure, encrypted peer-to-peer connections between devices without complex configuration. Unlike traditional VPNs with central gateways, Tailscale creates direct connections between devices (or uses relay servers when needed).

Key Benefits:

Zero-config networking: Works seamlessly across NAT and firewalls Direct connections: Peer-to-peer mesh reduces latency vs traditional hub-and-spoke VPNs WireGuard encryption: State-of-the-art cryptographic security Identity-based access: Integrates with SSO providers (Google, Okta, GitHub, etc.) Cross-platform: Works on Linux, macOS, Windows, iOS, Android, and more Quick Start Installation

Linux (one-liner):

curl -fsSL https://tailscale.com/install.sh | sh

macOS:

brew install tailscale

Windows/Other platforms: Download from https://tailscale.com/download

Initial Setup

Start Tailscale and authenticate

sudo tailscale up

Check status

tailscale status

Get your Tailscale IP

tailscale ip -4

Connect via MagicDNS hostname

ssh user@machine-name

Common Operations Basic Connection Management

Connect to your tailnet

tailscale up

Disconnect but keep daemon running

tailscale down

Check connection status and peers

tailscale status

View detailed network map

tailscale status --json | jq

Ping another tailnet device (TSMP ping)

tailscale ping machine-name

Test connectivity including ACLs (ICMP ping)

tailscale ping --icmp machine-name

Subnet Router Setup

What it does: Allows devices without Tailscale to be accessible via a gateway device that does have Tailscale installed.

On the router device:

Enable IP forwarding (Linux)

echo 'net.ipv4.ip_forward = 1' | sudo tee -a /etc/sysctl.d/99-tailscale.conf echo 'net.ipv6.conf.all.forwarding = 1' | sudo tee -a /etc/sysctl.d/99-tailscale.conf sudo sysctl -p /etc/sysctl.d/99-tailscale.conf

Advertise routes to your local network

sudo tailscale up --advertise-routes=192.168.1.0/24,10.0.0.0/24

In the admin console:

Go to Machines → find your subnet router Click menu → "Edit route settings" Enable the advertised routes

On client devices:

Linux needs explicit flag to accept routes

sudo tailscale up --accept-routes

Other platforms accept routes automatically

Exit Node Configuration

What it does: Routes ALL internet traffic through a specific device on your tailnet (like a traditional VPN).

Setup exit node:

Enable IP forwarding (same as subnet router)

echo 'net.ipv4.ip_forward = 1' | sudo tee -a /etc/sysctl.d/99-tailscale.conf echo 'net.ipv6.conf.all.forwarding = 1' | sudo tee -a /etc/sysctl.d/99-tailscale.conf sudo sysctl -p /etc/sysctl.d/99-tailscale.conf

Advertise as exit node

sudo tailscale up --advertise-exit-node

In admin console:

Go to Machines → find exit node Click menu → "Edit route settings" Enable "Use as exit node"

Use exit node from another device:

Use specific exit node

tailscale set --exit-node=exit-node-name

Use suggested exit node (auto-selects best)

tailscale set --exit-node=auto:any

Allow LAN access while using exit node

tailscale set --exit-node=exit-node-name --exit-node-allow-lan-access

Stop using exit node

tailscale set --exit-node=

Tailscale SSH Setup

What it does: SSH without managing keys, using your Tailscale identity for authentication.

Enable SSH on server:

Enable Tailscale SSH server

sudo tailscale set --ssh

Configure access in admin console: Go to Access Controls and add to the policy file:

{ "grants": [ { "src": ["user@example.com"], "dst": ["tag:servers"], "ip": ["22"] } ], "ssh": [ { "action": "accept", "src": ["user@example.com"], "dst": ["tag:servers"], "users": ["root", "ubuntu", "autogroup:nonroot"] } ] }

Connect from client:

No special setup needed on client!

ssh machine-name

Or use specific user

ssh ubuntu@machine-name

Works with SCP and SFTP too

scp file.txt machine-name:/tmp/

Check mode (for high-security connections):

{ "ssh": [ { "action": "check", // Requires recent SSO re-auth "src": ["user@example.com"], "dst": ["tag:servers"], "users": ["root"] } ] }

Serve and Funnel

Tailscale Serve (share within your tailnet):

Serve local web server to tailnet

tailscale serve 3000

Serve specific path

tailscale serve --https=443 --set-path=/app 8080

Serve static files

tailscale serve --https=443 /var/www/html

Serve with TLS-terminated TCP

tailscale serve --tls-terminated-tcp=5432 localhost:5432

Check status

tailscale serve status

Turn off

tailscale serve off

Tailscale Funnel (expose to public internet):

Share to entire internet (must be on ports 443, 8443, or 10000)

tailscale funnel 3000

Turn off

tailscale funnel off

Access Control Lists (ACLs)

Default policy (allows all):

{ "acls": [ { "action": "accept", "src": [""], "dst": [":*"] } ] }

Role-based access example:

{ "groups": { "group:engineering": ["user1@example.com", "user2@example.com"], "group:ops": ["ops@example.com"] }, "tagOwners": { "tag:dev": ["group:engineering"], "tag:prod": ["group:ops"] }, "acls": [ { "action": "accept", "src": ["group:engineering"], "dst": ["tag:dev:"] }, { "action": "accept", "src": ["group:ops"], "dst": ["tag:prod:"] } ] }

Modern Grants syntax (recommended):

{ "grants": [ { "src": ["group:engineering"], "dst": ["tag:dev"], "ip": ["*"] }, { "src": ["group:ops"], "dst": ["tag:prod"], "ip": ["22", "443", "80"] } ] }

Common Scenarios Home Lab Access

On home server

sudo tailscale up --advertise-routes=192.168.1.0/24

From anywhere

ssh homeserver

Access 192.168.1.* devices through homeserver

Secure Travel

Set home device as exit node before trip

tailscale set --exit-node=home-server

All traffic now routes through home

Multi-Site Connectivity

Site A router

sudo tailscale up --advertise-routes=10.0.0.0/24

Site B router

sudo tailscale up --advertise-routes=10.1.0.0/24 --accept-routes

Now Site B can reach Site A's 10.0.0.0/24 network

Troubleshooting Connection Issues

Check if devices can establish connection (ignores ACLs)

tailscale ping --tsmp peer-name

Check end-to-end including ACLs

tailscale ping --icmp peer-name

View network map and connection details

tailscale netcheck

Debug daemon logs

tailscale debug daemon-logs

Check DERP relay status

tailscale netcheck

If TSMP succeeds but ICMP fails: ACL policy is blocking the connection.

If both fail: Network connectivity issue (firewall, NAT, routing problem).

ACL Testing

Preview rules for specific user (in admin console)

Access Controls → Preview rules → select user

Test ACL in policy file

Add to policy:

"tests": [ { "src": "user@example.com", "accept": ["tag:server:22"], "deny": ["tag:prod:*"] } ]

Subnet Router Not Working

Verify IP forwarding enabled

cat /proc/sys/net/ipv4/ip_forward # Should be 1

Check firewall isn't blocking

sudo iptables -L -v -n sudo iptables -t nat -L -v -n

Verify routes advertised

tailscale status | grep "subnet router"

On client, ensure routes accepted

tailscale status | grep "routes accepted"

MagicDNS Not Resolving

Check MagicDNS enabled

tailscale status | grep MagicDNS

In admin console: DNS → Enable MagicDNS

Flush DNS cache

macOS

sudo dscacheutil -flushcache

Linux (systemd-resolved)

sudo systemd-resolve --flush-caches

Best Practices Security

✅ Use tags for servers: Never share with personal accounts

sudo tailscale up --advertise-tags=tag:server

✅ Disable key expiry for servers:

Admin console → Machines → menu → "Disable key expiry" Or use --auth-key with reusable key

✅ Use check mode for root access: Requires recent SSO re-authentication

✅ Principle of least privilege: Grant only necessary ports in ACLs

{ "grants": [{ "src": ["group:devs"], "dst": ["tag:dev"], "ip": ["22", "80", "443"] // Only SSH and HTTP(S) }] }

✅ Enable Tailnet Lock (enterprise): Cryptographically prevent unauthorized device additions

Operations

✅ Use auth keys for automation:

Generate in admin console → Settings → Keys

sudo tailscale up --auth-key=tskey-auth-...

✅ Tag infrastructure servers: Enables service accounts instead of personal ownership

✅ Set up high-availability:

Multiple subnet routers with same routes = automatic failover

Router 1

sudo tailscale up --advertise-routes=10.0.0.0/24

Router 2

sudo tailscale up --advertise-routes=10.0.0.0/24

✅ Use GitOps for ACLs: Version control your policy file with GitHub/GitLab

✅ Monitor with logging: Enable network flow logs (Enterprise feature)

Performance

✅ Enable UDP GRO forwarding (Linux subnet routers):

NETDEV=$(ip -o route get 8.8.8.8 | cut -f 5 -d " ") sudo ethtool -K $NETDEV rx-udp-gro-forwarding on rx-gro-list off

✅ Prefer direct connections: Check with tailscale status - look for "direct"

✅ Use appropriate MTU: Usually auto-detected correctly, but can tune if needed

Reference Files references/cli-reference.md - Complete CLI command reference with all flags references/acl-examples.md - Detailed ACL and grants configuration examples references/api-usage.md - Tailscale API integration and automation references/troubleshooting.md - Comprehensive troubleshooting guide references/production-setup.md - Best practices for production deployments scripts/setup_subnet_router.sh - Automated subnet router setup script scripts/setup_exit_node.sh - Automated exit node setup script