Tailscale Operations Manual

Tailscale is a mesh VPN based on WireGuard. Core concepts: tailnet (your private network), node (each device), DERP (relay server, used when direct connection is not possible), MagicDNS (automatic .ts.net domain names), ACL (access control).

Status Check

tailscale status                          # All nodes: IP/hostname/online status/exit node
tailscale status --json | jq '.'          # Machine-readable
tailscale status --self                   # View only the local machine

tailscale ip -4                           # Local Tailscale IPv4 (100.x.y.z)
tailscale ip -6                           # Local Tailscale IPv6

tailscale netcheck                        # Network connectivity: NAT type/latency/DERP reachability
tailscale ping <hostname>                 # End-to-end connectivity test (via tailnet)
tailscale ping --c 5 <hostname>           # 5 pings

tailscale version                         # Client version
tailscale debug derp-map                  # Currently used DERP map
tailscale debug local-creatures           # MagicDNS names registered on this machine
tailscale debug prefs                     # Current configuration (routes/exit nodes/accept-routes...)

Basic Operations

# Start/Stop
tailscale up                              # Start (using previous parameters)
tailscale down                            # Disconnect (does not delete the node)
tailscale logout                          # Logout and delete this node

# Common 'up' parameters
tailscale up --accept-routes              # Accept subnet routes advertised by other nodes
tailscale up --advertise-routes=192.168.1.0/24  # Advertise subnet (make this machine a subnet gateway)
tailscale up --exit-node=<hostname>       # Specify exit node (global traffic goes through it)
tailscale up --exit-node-allow-lan-access # In exit node mode, still allow access to local LAN
tailscale up --reset                      # Reset all configurations and run 'up' again
tailscale up --operator=lizzbit           # Allow non-root users to operate

# Switch accounts
tailscale login                           # Login (new device or re-login)
tailscale switch <account>                # Switch login account

# Re-authenticate (after key expiration)
tailscale up --force-reauth

Subnet Router

# On the node acting as the gateway:
tailscale up --advertise-routes=192.168.31.0/24,10.0.0.0/24

# Approve routes in the Admin Console (one-time):
# Machines → Find the node → Edit route settings → Check subnets and Approve

# Enable on client:
tailscale up --accept-routes              # Accept all approved routes
# View currently accepted routes
tailscale debug prefs | grep Route

Exit Node

# On the exit node (usually a VPS or host with public internet access):
tailscale up --advertise-exit-node

# After approval in the Admin Console, on the client:
tailscale up --exit-node=<hostname>       # Global traffic goes through the exit node
tailscale up --exit-node=                 # Restore direct connection (empty value)

# Temporarily switch exit node
tailscale set --exit-node=<hostname>
tailscale set --exit-node=                # Cancel

DERP Servers

# View current DERP usage
tailscale netcheck                        # Shows latency for each DERP + currently selected one
tailscale debug derp-map                  # DERP map URL (built-in + custom)

# Self-hosted DERP (derper)
# Start: derper -hostname derp.liz6.com -certmode manual -certdir /etc/ssl/
# Ports: 8443 (TLS, exposed to public internet), 3478 (STUN, UDP)
# Add custom DERP map in Tailscale Admin Console → Access Controls:
#   "derpMap": { "Regions": { "901": { ... } } }

# DERP debugging
tailscale debug --derp                     # Real-time DERP connection status
# If traffic goes through DERP (not direct), latency will be significantly higher

ACL Management (Admin Console)

# ACLs are managed in the Access Controls page of the admin console (JSON)
# Core concepts:
# - acls: who can access whom/what port
# - groups: user groups
# - hosts: restrict which sources a node accepts
# - derpMap: custom DERP servers

# Example ACL:
# "acls": [
#   {"action": "accept", "src": ["group:admin"], "dst": ["*:*"]},
#   {"action": "accept", "src": ["group:dev"], "dst": ["tag:server:22,443"]},
# ]

# Test when ACL is not taking effect:
tailscale ping <hostname>                 # End-to-end verification

Troubleshooting

# 1. Check service status
systemctl status tailscaled
journalctl -u tailscaled -f               # Real-time logs

# 2. Check connectivity
tailscale ping <hostname>                 # Direct connection success = low latency pong
# If it shows "via DERP(...)", it is using the relay, resulting in high latency

# 3. WireGuard level
wg show                                   # Tailscale's WireGuard interface (usually tailscale0)
ip addr show tailscale0                   # 100.x.y.z

# 4. Firewall
# Tailscale uses STUN (UDP 3478) and DERP (TCP 443/8443) for hole punching
# If direct connection fails, check if UDP is blocked

# 5. NAT issues
tailscale netcheck                        # Check NAT type: easy/random/hard
# "hard NAT" is the hardest to connect to directly; may require DERP or manual hole punching

# 6. Reset
tailscale down
systemctl restart tailscaled
tailscale up

# 7. MagicDNS not working
# Check if enabled: tailscale debug prefs | grep -i dns
# MagicDNS base domain: <hostname>.<tailnet>.ts.net
nslookup <hostname> 100.100.100.100       # Resolve using Tailscale DNS