# Tailscale — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Tailscale Knowledge Base — Index" type: index updated: 2026-07-07 --- # Tailscale — Knowledge Base Tailscale is a zero-config mesh VPN built on WireGuard: devices form a private network (a tailnet) with a central coordination server for key exchange and NAT traversal, while traffic flows peer-to-peer and end-to-end encrypted. This wiki covers how it works, connectivity (subnet routers, exit nodes, app connectors), MagicDNS, access control (ACLs and grants), identity/SSO, device and user management, the CLI and API, and the security model. Master catalog - every page appears here. ## Concepts ### Fundamentals - [[concepts/what-is-tailscale]] - what Tailscale is and the mesh model - [[concepts/how-tailscale-works]] - control vs data plane, WireGuard, STUN/DERP, NAT traversal - [[concepts/tailnet-and-addressing]] - the tailnet, 100.x CGNAT range, names, IPv6 - [[concepts/install-and-first-use]] - install per platform and first login - [[concepts/cli-reference]] - the `tailscale` CLI and `tailscale up` flags ### Connectivity & routing - [[concepts/subnet-routers]] - reach non-tailnet subnets (advertise-routes) - [[concepts/exit-nodes]] - route all traffic through a chosen node - [[concepts/magicdns-and-dns]] - MagicDNS, split DNS, nameservers - [[concepts/app-connectors]] - route to external SaaS by domain ### Access, identity & management - [[concepts/access-controls]] - the tailnet policy file: ACLs and grants - [[concepts/device-management]] - tags, key expiry, Tailnet Lock - [[concepts/identity-and-sso]] - identity model, SSO providers, roles, approval - [[concepts/users-and-organization]] - inviting/removing users, org settings ### Security & automation - [[concepts/security-model]] - zero-trust model, firewall ports, what Tailscale can/can't see - [[concepts/api-and-automation]] - the Tailscale API, auth keys, logging ## Syntheses - [[syntheses/tailscale-vs-vpn]] - Tailscale vs a traditional hub-and-spoke VPN - [[syntheses/routing-mechanisms-compared]] - subnet routers vs exit nodes vs app connectors - [[syntheses/acls-vs-grants]] - the classic ACL model vs the newer grants model ## Statistics - **Total pages**: 18 - **Concepts**: 15 - **Entities**: 0 - **Summaries**: 0 - **Syntheses**: 3 --- title: "Access Controls (Tailnet Policy File, ACLs, and Grants)" type: concept tags: [access-control, acls, grants, policy-file, hujson, tags, zero-trust, advanced] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-access-control-tailscale-docs.md", "raw/docs_page-manage-permissions-using-acls-tailscale-docs.md", "raw/docs_page-grants-tailscale-docs.md", "raw/docs_page-acl-policy-examples-tailscale-docs.md", "raw/docs_page-syntax-reference-for-the-tailnet-policy-file-tailscale-docs.md", "raw/docs_page-visual-policy-editor-tailscale-docs.md", "raw/docs_page-visual-policy-editor-reference-tailscale-docs.md", "raw/docs_page-manage-access-tailscale-docs.md"] confidence: high --- # Access Controls (Tailnet Policy File, ACLs, and Grants) ## Definition Tailscale access control embodies least privilege and zero trust: by default, all connections between devices in your [[concepts/tailnet-and-addressing|tailnet]] are denied unless explicitly permitted through your **tailnet policy file**. The policy file is expressed in human JSON (HuJSON), a JSON variant that allows comments and trailing commas. There are two ways to define access: **grants** (the recommended, next-generation syntax) and **access control lists (ACLs)** (the original, first-generation syntax). Grants provide all original ACL functionality plus application-layer permissions and route filtering. ACLs will continue to work indefinitely, but receive no new features, so Tailscale recommends grants for all new configurations. Both are deny-by-default and both live in the same policy file, where they can coexist. ## How It Works ACLs are deny-by-default, directional, and locally enforced, and don't affect local network traffic. "Directional" means allowing a source to connect to a destination does not let the destination connect back unless a rule explicitly permits it. "Locally enforced" means each device enforces incoming connections based on rules distributed to all devices, without further involvement from the coordination server. Tailscale automatically translates all ACLs to lower-level rules that allow traffic from a source IP to a destination IP and port. An ACL rule has an `action`, `src`, optional `proto`, and `dst`: ```hujson { "action": "accept", "src": [ ], "proto": "tcp", // optional "dst": [ ], } ``` Because Tailscale denies by default, the only possible `action` is `accept`. A grant is even simpler: each grant requires only a source (`src`) and a destination (`dst`), plus at least one of network permissions (`ip`) or application permissions (`app`); the `accept` action is implied. This grant gives a synced group full network access to logging servers, and makes that group the tag owner: ```hujson { "grants": [ { "src": ["group:security-team@example.com"], "dst": ["tag:logging"], "ip": ["*"] } ], "tagOwners": { "tag:logging": ["group:security-team@example.com"] } } ``` The `ip` field sets network-layer capabilities: `"ip": ["tcp:443", "udp:53"]` grants TCP 443 and UDP 53 on the destination. The `app` field sets application-layer capabilities in the format `"domainName/capabilityName"` (for example `"tailscale.com/cap/tailsql"`); the policy engine treats app capability parameters as opaque JSON and validates only that they are valid JSON. Device posture checks (`srcPosture`) apply only to the source of a grant, never the destination. ## Key Parameters The tailnet policy file has these top-level sections: `grants` and `acls` (access control); `ssh` (Tailscale SSH); `autoApprovers` (auto-approve subnet routers, exit nodes, app connectors); `nodeAttrs` (device/user attributes); `postures` (device posture rules); `tagOwners`, `groups`, `hosts`, `ipsets` (targets); and `tests` / `sshTests` (assertions). - **src selectors**: `*` (any Tailscale device), a user (`shreya@example.com`), a group (`group:`), a Tailscale IP, a subnet CIDR, a host, a tag (`tag:production`), or an autogroup (`autogroup:`). - **dst format** is `:`. Ports can be `*` (any), a single port (`22`), a comma list (`80,443`), or a range (`1000-2000`). - **proto**: an IANA protocol number `1-255` or a named alias (`tcp`, `udp`, `icmp`, `sctp`, and others). Requires Tailscale v1.18.2 or later. Only TCP, UDP, and SCTP support ports. - **Autogroups** include `autogroup:internet` (exit-node internet access), `autogroup:self` (a user's own devices), `autogroup:member`, `autogroup:admin`, `autogroup:tagged`, and `autogroup:shared`. - **groups** map a `group:` name to a list of full user emails; groups cannot contain other groups. - **hosts** map a friendly name to an IP or CIDR (the name cannot contain `@`). - **tests** assert `accept`/`deny` destinations so a policy change cannot silently revoke or grant critical access; failing tests reject the updated policy file. The **default policy** allows all devices to reach all others: ```hujson { "acls": [ { "action": "accept", "src": [ "*" ], "dst": [ "*:*" ] } ] } ``` Omitting the `acls` field is equivalent to this default allow-all. To deny all connections, use an empty `acls` array: `{ "acls": [] }`. You can edit the policy file from the **Access controls** page of the admin console, via GitOps, or via the Tailscale API. The **visual policy editor** offers three modes: **Visual editor** (interactive GUI, synced to JSON on save), **JSON editor** (direct HuJSON with a **Convert to grants** button), and **GitOps** (read-only preview; version control is the source of truth). When you use the visual editor, it automatically converts ACL syntax to grants on the backend. ## When To Use Use grants for all new policies and to fold network- and application-layer permissions into one rule; use `via` for routing-aware policies and `srcPosture` for context-aware access. Keep legacy ACLs only where they already exist, or migrate them with the Convert to grants button. Use `tests` and `sshTests` in CI/GitOps to guard critical permissions on every policy change. See [[syntheses/acls-vs-grants|ACLs vs Grants]] for a decision framework. ## Risks & Pitfalls - ACLs do not limit route discovery; restrict access to [[concepts/subnet-routers|subnet routers]] and [[concepts/exit-nodes|exit nodes]] with explicit rules and guard them with tests. - Only devices with `autogroup:internet` access can use exit nodes; you cannot restrict the use of specific exit nodes via ACLs. - App capability parameters are defined by the application, not Tailscale, and are not validated beyond being valid JSON. - Removing `autogroup:nonroot` from an SSH rule's `users` while broadening `dst` can let anyone SSH in as any non-root user. - For 4via6 subnet routers, target the IPv6 CIDR (from `tailscale debug via`), not the IPv4 address. ## Related Concepts - [[concepts/device-management|Device Management]] - [[concepts/identity-and-sso|Identity and SSO]] - [[concepts/security-model|Security Model]] - [[concepts/app-connectors|App Connectors]] - [[concepts/api-and-automation|API and Automation]] - [[syntheses/acls-vs-grants|ACLs vs Grants]] ## Sources - raw/docs_page-access-control-tailscale-docs.md - raw/docs_page-manage-permissions-using-acls-tailscale-docs.md - raw/docs_page-grants-tailscale-docs.md - raw/docs_page-acl-policy-examples-tailscale-docs.md - raw/docs_page-syntax-reference-for-the-tailnet-policy-file-tailscale-docs.md - raw/docs_page-visual-policy-editor-tailscale-docs.md - raw/docs_page-visual-policy-editor-reference-tailscale-docs.md - raw/docs_page-manage-access-tailscale-docs.md --- title: "Tailscale API, automation, and logging" type: concept tags: [api, automation, integrations, logging, iac] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-tailscale-api-tailscale-docs.md", "raw/docs_page-automations-tailscale-docs.md", "raw/docs_page-integrations-tailscale-docs.md", "raw/docs_page-logging-overview-tailscale-docs.md"] confidence: high --- ## Definition Tailscale exposes an application programming interface (API) plus a set of automation, integration, and logging surfaces that let you manage a tailnet programmatically rather than only through the admin console. **The Tailscale API is available for all plans.** ## How It Works **API authentication.** Requests are authenticated with an **access token** (sometimes called an **API key**). You must be an **Owner, Admin, IT admin, or Network admin** of a tailnet to generate one. Access tokens are generated from the **Keys** page of the admin console. Key properties: - You choose the expiry as a number of days, **between 1 and 90 inclusive**. - Tailscale-generated API access tokens are **case-sensitive**. - Tokens automatically expire after the chosen number of days; to keep using the API afterward you must generate a new token. Tokens can also be revoked before expiration. Recently expired and revoked tokens are shown on the Keys page. As an alternative to an access token with full API permission, use **trust credentials** to provide delegated, fine-grained control to the Tailscale API. **Device provisioning with OAuth.** When you create an OAuth app for device provisioning, the request body accepts an optional **`allowedNodeAttributes`** field -- an array of custom node attributes automatically assigned to every device provisioned through that OAuth app. Each value must use the **`custom:`** prefix (for example, `custom:provisioned`); only custom attributes can be allowlisted. Because they are assigned at provision time, they can be referenced in device-posture conditions (`srcPosture`) and in grants. ## Key Parameters **Automation surfaces:** - **Infrastructure as code (IaC):** official **Terraform** and **Pulumi** providers interact with the Tailscale API to manage resources such as access-control policies, devices, and nameservers. - **API:** automate aspects of your network. - **Webhooks:** subscribe to events on your network and process notifications through an integration or app. - **GitOps:** an alternative to managing access-control policies and the tailnet policy file via the admin console -- supported with **Bitbucket CI, GitLab CI, and GitHub Actions**. - **Tailscale Shortcuts for macOS and iOS:** built-in Shortcuts actions to connect to a tailnet, use an exit node, or switch user accounts. **Integration targets** (from the integrations catalog): cloud server; containers or virtualized environments; serverless app; database; remote code environment; access or share resources from a development environment; firewall; web server; network attached storage (NAS); and MDM solution. **Logging.** Each Tailscale agent streams its logs to a central log server at **`log.tailscale.com`**, including real-time open/close events for every inter-machine TCP or UDP connection. Because both endpoints log every connection, lost or tampered logs can be detected by comparing the double entries. - **Client logs** are accessible locally on some desktop platforms; on Windows they are stored in `C:\ProgramData\Tailscale` (more generally `$env:ALLUSERSPROFILE\Tailscale`). - **Opt out of client logging** per device with the **`--no-logs-no-support`** flag for the `tailscaled` daemon or the equivalent **`TS_NO_LOGS_NO_SUPPORT`** environment variable (for example, set `TS_NO_LOGS_NO_SUPPORT=true` in `%ProgramData%\Tailscale\tailscaled-env.txt` on Windows). On Windows only the environment variable is available. Blocking client logging may prevent Tailscale from providing technical support. - **Network flow logs** are available for the **Premium and Enterprise plans**, must be enabled, and show which devices connect to one another over time. They "strictly do not contain any information about client operations or contents of network traffic" and can be streamed to a SIEM. - **Configuration audit logs** (server logs) record actions that modify a tailnet's configuration -- action type, actor, target resource, and time. They are **enabled by default for all tailnets**, available for the **most recent 90 days**, inspectable on the Logs page by anyone with admin-console access, and can be streamed to a SIEM. - **Kubernetes Operator** reconciliation logs are centrally collected; opt out by adding `TS_NO_LOGS_NO_SUPPORT` to `operatorConfig.extraEnv` (Helm) or the Operator Deployment (static manifests). - Local SSH session logs are not supported as of version 1.48.0; use Tailscale SSH session recording instead. ## When To Use Use the API and IaC providers to manage tailnets at scale (bulk device, ACL, and DNS management); webhooks and GitOps to drive event- and code-based workflows; and the logging surfaces for auditing, incident forensics, and SIEM integration. ## Risks & Pitfalls - Access tokens are case-sensitive and expire in at most 90 days -- automation must rotate them or use OAuth/trust credentials. - Blocking client logging (`--no-logs-no-support` / `TS_NO_LOGS_NO_SUPPORT`) disables telemetry and may make technical support impossible. - If you manage the tailnet policy file with an external provider (Terraform/GitOps), console edits are overwritten on the next sync. ## Related Concepts - [[concepts/access-controls]] - [[concepts/security-model]] - [[concepts/device-management]] - [[concepts/exit-nodes]] ## Sources - raw/docs_page-tailscale-api-tailscale-docs.md - raw/docs_page-automations-tailscale-docs.md - raw/docs_page-integrations-tailscale-docs.md - raw/docs_page-logging-overview-tailscale-docs.md --- title: "App connectors" type: concept tags: [routing, app-connector, saas, ip-blocklist, doh, route-injection, networking] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-how-app-connectors-work-tailscale-docs.md", "raw/docs_page-infrastructure-access-tailscale-docs.md", "raw/docs_page-connect-to-external-services-with-ip-block-lists-tailscale-d.md", "raw/docs_page-route-injection-tailscale-docs.md"] source_url: "https://tailscale.com/docs/features/app-connectors" confidence: high --- # App connectors ## Definition An app connector lets you route traffic to self-hosted and software-as-a-service (SaaS) applications through dedicated devices in your tailnet, addressing applications by domain name instead of IP address. An app connector works like a [[concepts/subnet-routers|subnet router]] with the added benefit of routing users and devices to applications by domain names, providing more reliable connectivity. It is the right tool when an external service (e.g. Amplitude, Confluence, GitHub, Looker, Office 365, Salesforce, Stripe, Mongo Atlas, Amazon RDS, Planetscale) needs to see your traffic arriving from a small, stable set of IP addresses. App connectors are available for all plans. ## How app connectors differ from subnet routers and exit nodes All three inject routes into client routing tables, but they serve different purposes. A [[concepts/subnet-routers|subnet router]] provides access to specific private subnets by IP/CIDR. An [[concepts/exit-nodes|exit node]] routes all outbound internet traffic (`0.0.0.0/0`, `::/0`). An app connector is a subnet router specialized for reaching applications by domain name: it resolves configured domains to IP addresses and advertises those discovered IPs as routes automatically. By default, exit nodes capture all traffic that isn't already directed to a subnet router or app connector. See [[syntheses/routing-mechanisms-compared|Routing mechanisms compared]]. ## How It Works Key terms: - App connector -- the overall feature and the admin console settings to add/remove connectors. - App connector device -- the Linux device designated to route traffic to your application. It must have a public IP address, and IP forwarding must be enabled. - Application -- the self-hosted, cloud-based, or SaaS application the device routes traffic to. Setup, at a high level: 1. Configure your tailnet policy file to define device permissions for the connector, including tags. 2. Assign the configured tag to the tailnet devices that should access the connector. 3. Configure a Linux device (public IP, IP forwarding enabled) to act as the app connector. 4. Configure the app connector in the admin console to specify the tag and the domain names for the applications. 5. Configure the application for additional access/security needs, including optional IP allowlisting to only permit requests from the app connector device IP addresses. At runtime: a tagged device accesses an application; the request passes to the app connector device; the connector routes traffic to the application by egressing to the IP addresses advertised by the application domains; optionally the application verifies the request comes from the connector's public IP; and return traffic flows back through the connector to the user device. ### DNS discovery mechanism App connectors use the PeerAPI to perform DNS discovery through DoH (DNS over HTTPS): - Access requirement: client devices must have access to the app connector tag for it to appear as a peer. - DNS resolution: app connectors use DoH to resolve configured domains to IP addresses. - Route advertisement: discovered IP addresses are automatically advertised as routes to the tailnet. Minimal access (such as ICMP) is sufficient to enable peer discovery -- full application access is not required. ## Improving IP block lists Third-party or internal services (for example on serverless providers like Heroku) may use an IP block list (sometimes called an IP allowlist) that expects all user traffic to originate from one or a few IP addresses. Because Tailscale doesn't send all traffic through a central concentrator, your traffic otherwise arrives from all over the internet and hits those protections. IP block lists are essentially security by obscurity, grow unwieldy as users spread across locations, and are worsened by cloud VPCs using NAT gateways and elastic IPs. To improve them, set up an app connector to route traffic for a specific application through a single IP address -- that IP is the only one that needs to be on the block list. The app connector acts as a subnet router, providing access to the external service from your tailnet, and lets users access the service from anywhere. You can also manage a small collection of IP addresses in your tailnet policy file with an IP set. ## Infrastructure access App connectors fit Tailscale's broader infrastructure-access story: secure, least-privilege access to production infrastructure without exposing services to the public internet. Common workflows include replacing SSH bastion hosts with direct encrypted connections, recording SSH sessions for compliance, enforcing least-privilege and just-in-time access using tags, grants, and ephemeral nodes, and managing access across multi-cloud or multi-region environments (AWS, GCP, Azure, and on-premises). ## Routing vs access control (route injection) Routes and access controls operate at different layers. Routes (Layer 3) determine which IP ranges are reachable through the tunnel; access controls (ACLs/grants) determine which connections are permitted. A common misconception is that grants or ACLs control route injection -- they do not. Grants control packet filtering; routes are injected based on what connectors advertise and what the control plane approves. For traffic to flow you need both a route (to direct packets into the tunnel) and an access control rule (to permit the packets). A grant allowing a broad CIDR like `0.0.0.0/0` does not cause additional routes to be injected. See [[syntheses/acls-vs-grants|ACLs vs grants]]. ## Risks & Pitfalls - Linux devices do not accept routes by default. Run `tailscale set --accept-routes=true` on all Linux devices that need the connectors. Use the `UseTailscaleSubnets` system policy to prevent users from disabling accept-routes. - If a user is not connected to the tailnet, they still have access to the application unless IP allowlisting is configured; enforce `AlwaysOn.Enabled` to keep devices connected. - Providers often use multiple domains -- you must add all of them to the connector configuration (the GitHub V2Fly project lists known applications and their domains). - Shared IPs: if multiple FQDNs share an IP and one is an app connector target, connections to all FQDNs sharing that IP route through the connector, because once an app connector resolves an IP it routes all traffic to that IP through the connector. - Availability: run multiple app connector devices for reliability. If a connector becomes unavailable and no others exist, resolution to the domain fails until it is back online. Configure [[concepts/subnet-routers|high availability]] failover/regional routing. - Expired connector keys keep advertised routes configured but unreachable ("fail close"); disable key expiry or configure high availability. - If you manage the tailnet policy file with an external provider (Terraform, GitOps), changes made to app connectors in the admin console are overwritten on the next sync -- manage them through the external provider. ## Related Concepts - [[concepts/subnet-routers|Subnet routers]] -- the routing primitive app connectors build on - [[concepts/exit-nodes|Exit nodes]] -- route all internet traffic instead of by domain - [[concepts/access-controls|Access controls]] -- grants that permit connector traffic - [[concepts/magicdns-and-dns|MagicDNS and DNS]] -- DoH resolution underlies connector discovery - [[syntheses/routing-mechanisms-compared|Routing mechanisms compared]] ## Sources Based on Tailscale's official documentation for how app connectors work, infrastructure access, connecting to external services with IP block lists, and route injection. --- title: "CLI Reference" type: concept tags: [tailscale, cli, commands, tailscale-up, reference, operational] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-tailscale-cli-tailscale-docs.md", "raw/docs_page-tailscale-up-command-tailscale-docs.md"] confidence: high --- # CLI Reference ## Definition The Tailscale client includes a built-in command-line interface (CLI), available on all plans, to manage and troubleshoot your device within your [[concepts/tailnet-and-addressing|tailnet]]. The CLI is installed automatically on Linux, macOS, and Windows; there is **no CLI support for iOS and Android**. On Linux the `tailscale` binary is typically already in `$PATH`, and commands take the form `tailscale `. A common flag applies to all commands: `--socket=` (path to the tailscaled socket). ## How It Works The most-used lifecycle commands: - `tailscale up [flags]` - connect your device to Tailscale and authenticate if needed. Running it with no flags connects. - `tailscale down` - disconnect from Tailscale. Reconnect by re-running `tailscale up` with no flags. - `tailscale login [flags]` - log in and add this device to your network. - `tailscale logout` - disconnect and expire the current login; you must reauthenticate next `tailscale up`. On an ephemeral node, logout removes the node immediately. - `tailscale set [flags]` - change specific preferences without re-specifying everything (unlike `up`, it only updates flags you pass). - `tailscale status` - condensed table of your connections; `tailscale status --json` gives machine-readable output for automation. - `tailscale switch ` - switch accounts (fast user switching). **Important behavior of `tailscale up`:** flags are **not persisted between runs; you must specify all flags each time.** To clear a previously set flag, pass it with an empty argument, for example `tailscale up --advertise-tags=` clears any tags. In v1.8 or later, if you omit a previously set flag the CLI warns you and prints a copyable command including all existing flags. ## Key Parameters **Key `tailscale up` flags (verbatim):** - `--accept-dns` - Accept DNS configuration from the admin console. Defaults to accepting DNS settings. - `--accept-routes` - Accept subnet routes that other nodes advertise. Default depends on OS: Windows, iOS, Android, the macOS App Store variant, and the macOS standalone variant default to accepting routes; all other platforms default to not accepting. - `--advertise-connector` - Advertise this node as an app connector. - `--advertise-exit-node` - Offer to be an exit node for outbound internet traffic. Defaults to not offering. - `--advertise-routes=` - Expose physical subnet routes to your entire Tailscale network. - `--advertise-tags=` - Give tagged permissions to this device; you must be listed in "TagOwners". - `--auth-key=` - Provide an auth key to automatically authenticate the node; if it begins with `file:` it is a path to a file containing the key. - `--exit-node=` - Use a Tailscale IP or machine name as an exit node. `--exit-node=auto:any` tracks the suggested exit node; `--exit-node=` disables use of an exit node. - `--exit-node-allow-lan-access` - Allow the client node access to its own LAN while connected to an exit node. Defaults to not allowing. - `--force-reauth` - Force re-authentication. - `--hostname=` - Use a hostname instead of the OS one; changes the MagicDNS machine name. - `--login-server=` - Use a control server other than `https://controlplane.tailscale.com` (for example a Headscale instance). - `--netfilter-mode` - (Linux only) `off`, `nodivert`, or `on`. Defaults to `on`, except Synology defaults to `off`. - `--operator=` - A Unix username other than `root` to operate `tailscaled`. - `--reset` - Reset unspecified settings to default values. - `--shields-up` - Block incoming connections from other devices. Useful for personal devices that only make outgoing connections. - `--snat-subnet-routes` - (Linux only) Source NAT traffic to local routes advertised with `--advertise-routes`. - `--stateful-filtering` - (Linux only) Enable stateful filtering for subnet routers and exit nodes. Defaults to disabled. - `--ssh` - Run a Tailscale SSH server. Defaults to false. - `--timeout=` - Max time to wait for the service to initialize; parseable by `time.ParseDuration()`. Defaults to `0s` (blocks forever). - `--unattended` - (Windows only) Keep Tailscale running after the current user logs out. **Other notable subcommands:** - `tailscale ip [flags] []` - get a device's Tailscale IP; `-4`/`-6` return only IPv4/IPv6, `--1` returns one (preferring IPv4). - `tailscale ping ` - ping exclusively over Tailscale; `--until-direct` stops once a direct path is established (defaults true). - `tailscale netcheck` - report physical network conditions (UDP support, nearest DERP, DERP latency) to debug connectivity. - `tailscale cert hostname..ts.net` - generate Let's Encrypt cert/key files (90-day expiry; you must renew certs made this way). - `tailscale serve ` - serve content to your tailnet; `tailscale funnel ` - serve publicly to the internet. - `tailscale ssh ` - establish a Tailscale SSH session. - `tailscale whois ip[:port]` - get the machine and user for a Tailscale IP. - `tailscale update [flags]` - update the client (`--track`, `--version`, `--yes`, `--dry-run`). - `tailscale version [flags]`, `tailscale bugreport`, `tailscale lock `, `tailscale exit-node list|suggest`, `tailscale dns status|query`, `tailscale drive`, `tailscale file cp|get`, `tailscale metrics`, `tailscale completion `. ## When To Use Use the CLI for anything a GUI cannot do: scripting/automation (`tailscale status --json | jq ...`), CI/CD provisioning (`--auth-key`), server setup (`--advertise-routes`, `--advertise-exit-node`, `--ssh`), and connectivity debugging (`netcheck`, `ping`, `bugreport`). For services that must wait for Tailscale to be ready, use `tailscale wait && /path/to/service`. ## Risks & Pitfalls - **`tailscale up` does not remember flags** - re-running it without a previously set flag drops that setting. Prefer `tailscale set` for incremental changes. - `--netfilter-mode=off` or `nodivert` makes you responsible for configuring the firewall securely for Tailscale traffic. - Do not run `tailscale systray` as superuser (`sudo tailscale systray`) - it is not designed for that and will fail. - Certificates made with `tailscale cert` do not auto-renew; you own renewal. ## Related Concepts - [[concepts/install-and-first-use|Install and First Use]] - [[concepts/how-tailscale-works|How Tailscale Works]] - [[concepts/tailnet-and-addressing|Tailnet and Addressing]] - [[concepts/what-is-tailscale|What is Tailscale?]] ## Sources - raw/docs_page-tailscale-cli-tailscale-docs.md - raw/docs_page-tailscale-up-command-tailscale-docs.md --- title: "Device Management (Tags, Key Expiry, Tailnet Lock)" type: concept tags: [device-management, tags, key-expiry, tailnet-lock, node-key, security, advanced] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-manage-devices-tailscale-docs.md", "raw/docs_page-group-devices-with-tags-tailscale-docs.md", "raw/docs_page-key-expiry-tailscale-docs.md", "raw/docs_page-tailnet-lock-tailscale-docs.md"] confidence: high --- # Device Management (Tags, Key Expiry, Tailnet Lock) ## Definition Device management covers the controls Tailscale gives you over which devices are allowed on your [[concepts/tailnet-and-addressing|tailnet]] and how their identity and keys are maintained over time. Three features anchor it: **tags** (identity for non-user devices, used to drive access control by purpose), **key expiry** (periodic device reauthentication), and **Tailnet Lock** (a trust-on-first-use scheme where trusted nodes must sign new nodes before they can join). Devices are reviewed and managed from the **Machines** page of the admin console, and additional controls include device approval, the web interface, and device posture management. ## How It Works **Tags** authenticate and identify non-user devices such as servers, subnet routers, and ephemeral nodes. Tags are essentially service accounts with more flexibility: a device can have multiple tags, and access policies can target each tag individually. Applying a tag removes any user-based authentication (a device can have tags or a user account, not both), and re-authenticating a device with a user account removes all its tags. There is no "tags" section; you define tags by their owners in the `tagOwners` section of the policy file. Only tag owners can apply a tag, though Owner, Admin, and Network admin can apply any tag even if they don't own it. A tagged device's identity is the combination of all its tags (not the intersection), and tags are not "joined" for access rules -- use a composite tag like `tag:prod-database` for segmented access. **Key expiry** requires users to periodically reauthenticate on each device. The default expiration period depends on your domain setting; new domains default to 180 days. If reauthentication doesn't occur, keys expire and connections to and from that endpoint stop working. Renewing keys on a device with the CLI uses `tailscale up --force-reauth` (which can drop the tailnet connection, so avoid running it remotely over SSH/RDP without a backup login). **Tailnet Lock** lets trusted nodes sign and verify other nodes so you don't need to trust the coordination server for distributing public node keys. Each node has a node key and a **Tailnet Lock key (TLK)**; every node generates a TLK even when the feature is off. Trusted public TLKs are stored in the **tailnet key authority (TKA)**, a cryptographic chain that verifies node-key signatures before adding peers, and verifies signature changes to the trusted-key set. With Tailnet Lock enabled, a new node's public node key requires a signature from a Tailnet Lock key before peers accept connections. ## Key Parameters Define a tag by listing its owners (only `dave@example.com` can apply `tag:server`): ```hujson { "tagOwners": { "tag:server": ["dave@example.com"], // dave@example.com can authenticate devices with the tag:server tag } } ``` A tag can also have an empty owner list (`"tag:infrastructure": []`), which means it is implicitly owned by Owners, Admins, and Network admins. - **Apply tags with the CLI**: `sudo tailscale login --advertise-tags=tag:server` (comma-separate for multiple: `tag:server,tag:development`). `--advertise-tags=` with no value removes all tags. You cannot remove tags via `--advertise-tags` if the device uses an auth key -- generate a new auth key instead. Add `--force-reauth` to re-authenticate as the current user. - **Apply tags with the API**: send a `POST` to `/api/v2/device//tags` with body `{"tags": ["tag:foo", "tag:bar"]}`. - **Tag limits**: 50 tagged devices on all plans; a tagged device must keep at least one tag; IP sets do not support tags; tagged devices can only SSH into other tagged devices. - **Key expiry actions** (Machines page): **Disable Key Expiry**, **Enable Key Expiry**, and **Temporarily extend key** (extends 30 minutes, only shown for expired keys). Set a custom authentication period of 1 to 180 days on the **Device management** page; the change applies to devices logged in after the change. When a tag is first applied and authenticated, the tagged device has key expiry disabled by default. - **Tailnet Lock CLI**: `tailscale lock init` (enable; needs at least two signing nodes and generates ten disablement secrets), `tailscale lock status`, `tailscale lock sign nodekey: tlpub:`, `tailscale lock add tlpub:`, `tailscale lock remove tlpub:` (add `--re-sign=false` to skip re-signing), `tailscale lock revoke-keys` (multi-step co-signed revocation), `tailscale lock disable` (needs a disablement secret), and `tailscale lock local-disable`. Tailnet Lock requires Tailscale v1.46.1 or later, is available on Personal and Enterprise plans, and needs Owner, Admin, or IT admin to enable or disable. You verify each node's provisioned state with `tailscale lock status` and confirm all nodes report the same trusted signing keys. ## When To Use Use tags for any non-human device (web servers, subnet routers, app connectors) and for devices multiple users must manage, so removing a user does not remove the device. Use auth keys with pre-assigned tags to streamline onboarding. Disable key expiry on trusted, hard-to-reach devices such as servers, subnet routers, or remote IoT nodes. Adopt Tailnet Lock when you want to keep the center of trust in your own network while still using Tailscale's managed control plane. ## Risks & Pitfalls - Never use tags to annotate user devices (laptops, phones): applying a tag removes the user, and the device would stay on the network even after the user is removed -- a security risk. - Disabling key expiry weakens the periodic-reauthentication safeguard; scope it to trusted devices only. - Tailnet Lock disablement secrets display only at initialization. If you lose them and gave none to Tailscale support, the tailnet cannot be recovered. - Tailnet Lock and **device approval** are mutually exclusive. Limits: max 20 signing nodes; rotate lock keys at most once per year; Android cannot be a signing node. - For OAuth clients and auth keys, requested tags must exactly match the authenticating tags or be owned per `tagOwners`; applying a subset requires explicit ownership (add the tag as its own owner). ## Related Concepts - [[concepts/access-controls|Access Controls]] - [[concepts/identity-and-sso|Identity and SSO]] - [[concepts/security-model|Security Model]] - [[concepts/subnet-routers|Subnet Routers]] - [[concepts/api-and-automation|API and Automation]] ## Sources - raw/docs_page-manage-devices-tailscale-docs.md - raw/docs_page-group-devices-with-tags-tailscale-docs.md - raw/docs_page-key-expiry-tailscale-docs.md - raw/docs_page-tailnet-lock-tailscale-docs.md --- title: "Exit nodes" type: concept tags: [routing, exit-node, vpn, mullvad, mdm, networking] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-use-exit-nodes-tailscale-docs.md", "raw/docs_page-exit-nodes-route-all-traffic-tailscale-docs.md", "raw/docs_page-recommended-exit-nodes-tailscale-docs.md", "raw/docs_page-mandatory-exit-nodes-tailscale-docs.md"] source_url: "https://tailscale.com/docs/features/exit-nodes" confidence: high --- # Exit nodes ## Definition An exit node is a device on your tailnet that routes all of another device's public internet traffic, effectively functioning as a VPN server. By default Tailscale is an overlay network: it only routes traffic between Tailscale devices and doesn't touch your public internet traffic. An exit node changes that -- when you route all traffic through it, you use default routes (`0.0.0.0/0`, `::/0`), so your internet traffic appears to come from the exit node's location. This is useful on untrusted Wi-Fi, for reaching services only available in your home country, or to meet compliance needs. Exit nodes are available for all plans. Both the exit node and the devices using it must run Tailscale v1.20 or later. ## How It Works For security, exit node functionality is opt-in at every step: a device must advertise itself as an exit node; an Owner, Admin, or Network admin must allow it for the tailnet; and every device must explicitly opt in to using it. By default, exit nodes capture all network traffic that isn't already directed to a subnet router or app connector. You can still route specific traffic through [[concepts/subnet-routers|subnet routers]] or [[concepts/app-connectors|app connectors]]. Setup on Linux requires IP forwarding (same `net.ipv4.ip_forward` / `net.ipv6.conf.all.forwarding` sysctl steps as subnet routers), then advertising the device: ``` sudo tailscale set --advertise-exit-node ``` In the admin console, open the Machines page, find the device by the `Exit Node` badge or `property:exit-node` filter, open Edit route settings, and check `Use as exit node`. If the authenticating user can approve exit nodes in `autoApprovers`, approval is automatic. Each client enables the exit node separately (per operating system). You can verify your traffic is routed by checking your public IP -- the exit node's address should display. Turn it off by selecting `None` in the Exit Node section. ## Key Parameters / Flags - `--advertise-exit-node` -- advertises the device as an exit node. Run as `sudo tailscale set --advertise-exit-node`. - `--exit-node=` -- selects a specific exit node to route through. Run as `tailscale set --exit-node=`. - `--exit-node-allow-lan-access` -- lets the connecting device still reach its local network while routing through the exit node. Pass to `tailscale up` or `tailscale set`. (By default a device connecting to an exit node loses access to its local network; you can also enable `Allow Local Network Access` in the client's Exit Nodes section.) ## Grant access to use an exit node By default, any user in your tailnet can use a configured exit node -- no grants or ACLs needed. This changes once you customize the access control policy. To permit exit node use, add a grant or ACL whose `dst` is `autogroup:internet`. This grants permission to route internet traffic through any configured exit node -- it is NOT the same as adding the exit node device itself as the destination, which only permits connecting to the device (such as SSH), not using it as an internet gateway. If a policy never grants access to `autogroup:internet`, Tailscale has no permission to route internet traffic through the exit node. ## Recommended (suggested) exit nodes A recommended exit node (also called a suggested exit node) is an exit node or Mullvad exit node that Tailscale selects automatically based on client information such as location and latency. Available for Standard, Premium, and Enterprise plans, or customers with the Mullvad add-on. Tailscale prefers non-Mullvad exit nodes: if any standard exit nodes are available it recommends them first, using latency and performance data; for Mullvad exit nodes (no performance data) it selects based on location. From the CLI, view the suggestion and then apply it: ``` tailscale exit-node suggest ``` The command returns the suggested exit node's ID. Accept it with: ``` tailscale set --exit-node= ``` ## Mandatory exit nodes Mandatory exit nodes let you require an always-on exit node via mobile device management (MDM) system policies. Available for Premium and Enterprise plans, or customers with the Mullvad add-on. Requires Tailscale client v1.69.3 or later. Useful in hybrid/remote environments where employees must route traffic through corporate or branch offices. - To require a single always-on exit node, configure the `ExitNodeID` policy to that node's ID. - To require a fleet of regionally-routed exit nodes, set `ExitNodeID` to `auto:any` and optionally list permitted nodes in the `AllowedSuggestedExitNodes` policy. If `AllowedSuggestedExitNodes` is unset, all exit nodes are allowed; if set but empty, no exit nodes are allowed. ## Risks & Pitfalls - A common point of confusion is adding the exit node device as the grant `dst` -- that permits connecting to the device, not using it as an internet gateway. Use `autogroup:internet`. - Mandating always-on exit nodes can cause service disruptions when exit nodes lose connectivity or during captive portal workflows; use caution combining with a policy that prevents disconnecting the client. - Running an exit node on Android is not performant (userspace routing only) and may be too slow for most cases; keep the device powered. - Expired connector keys keep advertised routes configured but unreachable ("fail close"); disable key expiry or configure high availability. - Destination logging is disabled by default for privacy; Enterprise tailnets can enable it (requires log streaming) for visibility in Network flow logs. ## Related Concepts - [[concepts/subnet-routers|Subnet routers]] -- route to specific private subnets instead of all internet traffic - [[concepts/app-connectors|App connectors]] -- route to applications by domain - [[concepts/magicdns-and-dns|MagicDNS and DNS]] -- by default a device using an exit node also uses it as a DNS resolver - [[syntheses/tailscale-vs-vpn|Tailscale vs VPN]] - [[syntheses/routing-mechanisms-compared|Routing mechanisms compared]] ## Sources Based on Tailscale's official documentation for using exit nodes, exit nodes (route all traffic), recommended exit nodes, and mandatory exit nodes. --- title: "How Tailscale Works" type: concept tags: [tailscale, wireguard, encryption, nat-traversal, derp, stun, foundational] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-tailscale-encryption-tailscale-docs.md", "raw/docs_page-what-is-stun-tailscale-docs.md", "raw/docs_page-what-happens-if-the-coordination-server-is-down-tailscale-do.md", "raw/docs_page-is-my-traffic-routed-through-your-servers-tailscale-docs.md", "raw/docs_page-can-tailscale-decrypt-my-traffic-tailscale-docs.md"] confidence: high --- # How Tailscale Works ## Definition Tailscale connects devices with end-to-end encrypted, direct (peer-to-peer) WireGuard tunnels, coordinated by a central control plane but never routed through it. The architecture separates a **control plane** (which makes decisions: authentication, key exchange, access-policy interpretation, packet-filter computation) from a **data plane** (which executes them: packet forwarding and processing). This split minimizes the blast radius of a breach and lets each plane scale independently. Tailscale can never decrypt your traffic: devices only exchange public keys, private keys never leave the device, and all traffic is end-to-end encrypted, always. ## How It Works **Control plane.** Control-plane communication (key exchange and coordinating device connections) uses a custom Noise IK-based protocol with X25519 (RFC7748). It can run directly over plain TCP where allowed, or be wrapped in TLS when needed. The coordination server distributes public keys and firewall rules to all devices; it is part of the control plane, not the data plane, and avoids being a bottleneck by not relaying traffic. **Data plane.** The data plane uses WireGuard to encrypt communication between devices. A pair of devices starts by using a DERP server to establish a connection, then transitions to a direct connection if possible. If a direct connection is not possible, they fall back to a relayed connection through DERP. DERP servers never access unencrypted data - they only handle WireGuard packets that are already encrypted. Device-to-DERP connections are authenticated with a NaCl box construction on top of TLS to verify clients own their claimed WireGuard keys. **NAT traversal and STUN.** Most devices cannot talk directly because of firewalls and Network Address Translation (NAT). Tailscale's NAT-traversal engine uses a custom UDP protocol for path discovery (authenticated with NaCl box), separate from the WireGuard data plane. To do this it uses STUN (Session Traversal Utilities for NAT): the Tailscale client acts as the STUN client and the DERP relay servers act as STUN servers. The client sends a STUN request to all DERP servers, which report back the public IP and port they saw; Tailscale uses that to work out how to traverse the NAT. You can inspect this with `tailscale netcheck`. **DERP relays.** DERP stands for Designated Encrypted Relay for Packets - globally distributed relay servers that act as a fallback when NAT traversal fails. Traffic bounced through DERP is encrypted and "no different security-wise than the other dozen hops your internet packets already make." Tailscale routes over the shortest path possible, which in most cases is a direct peer-to-peer connection. ## Key Parameters - **Cryptography.** WireGuard for the data plane; Noise IK + X25519 for the control plane; ED25519 signatures for Tailnet Lock. - **TLS.** Built on Go's `crypto/tls`, minimum TLS 1.2 with TLS 1.3 support; ECDHE for forward secrecy; AEAD dynamically chooses between AES-128-GCM and ChaCha20-Poly1305 based on hardware AES acceleration. - **Not FIPS compliant.** Primitives including Curve25519, XSalsa20, ChaCha20-Poly1305, and the Noise and WireGuard protocols cannot be made FIPS compliant under current standards. - **Connection types** (as shown by `tailscale status`): `direct`, `relay`, and `peer-relay`. - **Log data** is sent over TLS without additional authentication or encryption. ## When To Use Understanding this model matters when you need to reason about latency (direct vs relayed paths), privacy guarantees (end-to-end encryption, no server-side decryption), compliance (non-FIPS crypto), or resilience. If the **coordination server goes down**, the network mostly keeps working: traffic is never routed through it, device keys are stored locally, and cached firewall rules stay enforced - so existing devices keep communicating until a key expires. However, while it is down you cannot add new users/devices, refresh or exchange keys, update firewall rules, or revoke existing keys, so devices will gradually lose access as keys expire. ## Risks & Pitfalls - **Key expiry is device-dependent**, based on each device's last authentication time, so different devices in the same tailnet expire at different moments. - If UDP is blocked on your network, direct connections are unlikely and traffic falls back to slower DERP relays (check with `tailscale netcheck`). - A "difficult" NAT that varies the mapped IP by destination (`MappingVariesByDestIP: true`) hampers direct connections. - The documented cryptographic mechanisms reflect implementation as of December 2024 and may change; they are not a permanent commitment. ## Related Concepts - [[concepts/what-is-tailscale|What is Tailscale?]] - [[concepts/tailnet-and-addressing|Tailnet and Addressing]] - [[concepts/cli-reference|CLI Reference]] - [[syntheses/routing-mechanisms-compared|Routing Mechanisms Compared]] ## Sources - raw/docs_page-tailscale-encryption-tailscale-docs.md - raw/docs_page-what-is-stun-tailscale-docs.md - raw/docs_page-what-happens-if-the-coordination-server-is-down-tailscale-do.md - raw/docs_page-is-my-traffic-routed-through-your-servers-tailscale-docs.md - raw/docs_page-can-tailscale-decrypt-my-traffic-tailscale-docs.md --- title: "Identity and SSO" type: concept tags: [identity, sso, oidc, user-approval, user-roles, authentication, foundational] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-tailscale-identity-tailscale-docs.md", "raw/docs_page-supported-sso-identity-providers-tailscale-docs.md", "raw/docs_page-user-approval-tailscale-docs.md", "raw/docs_page-user-roles-tailscale-docs.md"] confidence: high --- # Identity and SSO ## Definition Identity is core to Tailscale: it ties users, devices, and traffic together so access can be enforced based on *who* and *what* is connecting. Tailscale distinguishes **user identity** from **node identity**. A user identity is a digital identity that an external identity provider (IdP) authenticates -- Tailscale is not an IdP and has no passwords of its own, instead delegating user authentication to native or custom OpenID Connect (OIDC) providers. A **node identity** binds a user's identity to a specific device using a cryptographic key pair, and Tailscale uses it when creating a tunnel between two nodes so each side knows exactly who it is connecting to. This concept also covers who is allowed to join a tailnet (**user approval**) and what they can do in the admin console (**user roles**). ## How It Works When a user logs in to a new device, the IdP authenticates them (including any MFA configured on the IdP) via an OAuth 2.0 flow over TLS. Tailscale then creates a node that ties the authenticated user identity to the device's machine key. Two key pairs underpin this: a **machine key** (created when the client is installed; identifies the device to the control plane) and a **node key** (created on first authentication; used by WireGuard to authenticate nodes and establish end-to-end encryption). Private keys never leave the device; the control plane collects and distributes only public keys. Because IP addresses are ephemeral on the modern internet, Tailscale's security model is based on user identity, tags, and node identity rather than IP address -- though it still provides stable IP addresses. Because Tailscale delegates to an IdP, it can automatically rotate connection encryption keys and inherit team security policies such as MFA. Tailscale requests the minimum OIDC scopes needed: it reads users' emails and names (and, if provided, a photo URL, not the photo itself). With the GitHub IdP it requests the minimum permissions to read team membership; it does not use repository or project-board content. ## Key Parameters **Supported native identity providers**: Apple; Google (including Gmail and Google Workspace); GitHub; Microsoft (Microsoft Accounts, Office365, Active Directory, Microsoft Entra ID); Okta; and OneLogin. Tailscale also supports **custom OIDC providers**, **passkeys** for any tailnet you are authorized to join, and two-factor / multifactor authentication (enabled in your IdP, applied to all apps including Tailscale). You must be an Owner to set up an identity provider. You cannot migrate a tailnet to or from GitHub or Apple as the IdP. **User approval** lets network administrators review and approve new users before they can join. It is available on all plans. When enabled, a new user's first login sets their status to *needs approval*: they can connect to the coordination server but cannot connect to other devices until approved. An Owner, Admin, or IT admin approves the user (and can change the role assigned at approval time) or removes them; find pending users with the `status:needsapproval` filter. For tailnets created May 22, 2025 or later, user approval is enabled by default; for older tailnets it was disabled by default. User approval and **User & group provisioning** are mutually exclusive -- enabling provisioning disables user approval. **User roles** are IAM roles that restrict access to the admin console. Basic roles (all plans) are **Owner**, **Admin**, and **Member**; Advanced roles (Standard, Premium, and Enterprise) are **Billing admin**, **IT admin**, **Network admin**, and **Auditor**. - **Owner** -- owns the Tailscale account; can see billing and plan; exactly one per organization; must transfer ownership before the Owner account can be deleted. - **Admin** -- can perform any admin console action, including inviting/removing users, modifying policies, approving machines, and changing billing. - **Network admin** -- manages network configuration only: can write the tailnet policy file and DNS/subnet settings; reads (not writes) user and device info. - **IT admin** -- manages users and machines only: remove users, approve/remove devices, modify general settings; can grant all roles (separation of duties); cannot write the policy file or accept subnet routes. - **Billing admin** -- modifies plan and billing only; reads everything else. - **Auditor** -- reads all configuration but cannot modify anything. - **Member** -- cannot access the admin console; connects to nodes as permitted by policy. New users are Members by default. A user cannot modify their own role, except to transfer the Owner role. Writing the tailnet policy file is limited to Owner, Admin, and Network admin; generating auth keys, API access tokens, and OAuth clients is limited to Owner, Admin, Network admin, and IT admin. ## When To Use Use the IdP you already have; Tailscale layers on top of it. In larger organizations, map advanced roles to teams: Network admin for networking, IT admin for onboarding/offboarding, Billing admin for finance, and Auditor for compliance. Enable user approval to gate who can join, especially when inviting external users. Note that some permissions -- access to a machine, tag ownership, and route/exit-node self-approval -- are governed by the tailnet policy file, not by user roles. ## Risks & Pitfalls - Tailscale is not an IdP: your IdP's security posture (including MFA) is your login security. There are no Tailscale passwords. - You cannot migrate to or from GitHub or Apple as an IdP, which can strand a tailnet on the wrong provider. - User approval cannot coexist with User & group provisioning; enabling provisioning silently disables approval and leaves pending users needing manual action. - Removing an unapproved user does not stop them from logging in again to an unapproved state. ## Related Concepts - [[concepts/users-and-organization|Users and Organization]] - [[concepts/access-controls|Access Controls]] - [[concepts/device-management|Device Management]] - [[concepts/security-model|Security Model]] - [[concepts/what-is-tailscale|What is Tailscale?]] ## Sources - raw/docs_page-tailscale-identity-tailscale-docs.md - raw/docs_page-supported-sso-identity-providers-tailscale-docs.md - raw/docs_page-user-approval-tailscale-docs.md - raw/docs_page-user-roles-tailscale-docs.md --- title: "Install and First Use" type: concept tags: [tailscale, install, quickstart, setup, onboarding, foundational] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-install-tailscale-tailscale-docs.md", "raw/docs_page-start-using-tailscale-tailscale-docs.md", "raw/docs_page-tailscale-quickstart-tailscale-docs.md", "raw/docs_page-connecting-without-installing-tailscale-tailscale-docs.md"] confidence: high --- # Install and First Use ## Definition Getting started with Tailscale takes three steps: create an account, install the Tailscale client, and log in on two or more devices. Authenticating your devices automatically creates a [[concepts/tailnet-and-addressing|tailnet]] with sensible default access policies. The client is cross-platform (Linux, macOS, Windows, iOS, Android, Chromebook, Apple TV, Amazon Fire), and on Linux/macOS/Windows the [[concepts/cli-reference|Tailscale CLI]] is installed automatically. ## How It Works **Create a tailnet (quickstart).** 1. Go to `tailscale.com` and select **Get Started** (or download and install the client first, then sign up). 2. On the "Sign up with your identity provider" page, log in using a single sign-on (SSO) identity provider account. Signing up with a custom-owned domain enrolls you in the Enterprise plan for a 14-day trial; signing up with a public-domain email (such as `@gmail.com`) enrolls you in the Personal plan (six free users and many Enterprise features). You can change plans later. 3. On "Welcome to Tailscale", select **Business use** or **Personal use**. 4. On "Let's add your first device", select the OS for the device you are on, download/install the client, and authenticate with the same credentials. 5. On "Next, add a second device", select the OS for another machine, copy the link, and send it to the second device. After it authenticates, both devices display. 6. Select **Take me home** to reach the admin console, which controls users, devices, DNS, permissions, authentication keys, and more. **First login on a device.** After installing, connect and authenticate with: ``` tailscale up ``` Running `tailscale up` without any flags connects to Tailscale and authenticates if needed. To disconnect, run `tailscale down`; to reconnect, re-run `tailscale up` without any flags. (Full flag list in [[concepts/cli-reference|CLI Reference]].) **Add more devices** by (a) logging in from other devices with an existing user account, (b) adding servers using a tag as the server's identity plus an authentication key, or (c) using MDM/system policies. Tailscale automatically assigns each device a unique `100.x.y.z` IP. ## Key Parameters **Install and update methods:** - **Download page** - install/update from the Tailscale Download page. - **Client UI** - update from an installed client's UI (Windows and macOS). - **Tailscale CLI** - update with `tailscale update` (available on Linux, Windows, macOS). - **App stores** - Apple App Store, Google Play, Amazon Appstore. - **Packages site** - choose the stable, release candidate, or unstable build track. **Auto-update** can be configured from the admin console, from client/app-store settings, or via an MDM solution (Google Workspace, Jamf, Iru [formerly Kandji], Microsoft Intune). **macOS note:** there are three ways to run Tailscale on macOS (App Store, standalone, and others); Windows can be installed via the standard installer, MSI, or inside WSL 2. ## When To Use Install Tailscale directly on any device you want to connect - "it just works, and requires no configuration as devices move between networks." **When you cannot install the client**, run a [[concepts/subnet-routers|subnet router]] and relay traffic between your tailnet and those devices instead. Documented reasons: - Incrementally migrating from a large number of existing networks. - Incrementally migrating from a cloud provider's own VPC offering. - Connecting to appliances you cannot install software on (gaming consoles, smart appliances, IoT devices, printers). - Connecting to devices running an unsupported operating system. ## Risks & Pitfalls - There is **no CLI support on iOS and Android**; manage those clients through the app UI. - The plan you land on depends on your sign-up email domain (custom domain -> Enterprise trial; public domain -> Personal), which can surprise new users. - Renaming a device changes its MagicDNS name; keep machine names organized from the start via the Machines page. - For servers, prefer tag-based identity plus an authentication key rather than a human user account, so the device is not tied to one person's login. ## Related Concepts - [[concepts/what-is-tailscale|What is Tailscale?]] - [[concepts/cli-reference|CLI Reference]] - [[concepts/tailnet-and-addressing|Tailnet and Addressing]] - [[concepts/subnet-routers|Subnet Routers]] - [[concepts/magicdns-and-dns|MagicDNS and DNS]] ## Sources - raw/docs_page-install-tailscale-tailscale-docs.md - raw/docs_page-start-using-tailscale-tailscale-docs.md - raw/docs_page-tailscale-quickstart-tailscale-docs.md - raw/docs_page-connecting-without-installing-tailscale-tailscale-docs.md --- title: "MagicDNS and DNS" type: concept tags: [dns, magicdns, split-dns, doh, nameservers, networking] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-dns-in-tailscale-tailscale-docs.md", "raw/docs_page-why-is-magicdns-fetching-records-on-port-443-tailscale-docs.md"] source_url: "https://tailscale.com/docs/reference/dns-in-tailscale" confidence: high --- # MagicDNS and DNS ## Definition Tailscale gives each device a unique, stable [[concepts/tailnet-and-addressing|Tailscale IP address]], but IP addresses aren't memorable. DNS in Tailscale maps those IPs to human-readable names. You manage DNS for your tailnet using MagicDNS, your tailnet DNS settings (nameservers and search domains), or public DNS records, and via the `tailscale dns` command. Clients must be configured to use Tailscale DNS settings for these to take effect. Managing DNS is available for all plans. ## MagicDNS MagicDNS, enabled by default, automatically assigns DNS names to devices in your tailnet so you can address them by name instead of IP. It is optional and not required to use other DNS settings. You cannot add arbitrary records to MagicDNS. Applications make DNS lookups to the local MagicDNS server at the virtual IP address `100.100.100.100` instead of the OS-level DNS servers; MagicDNS then upgrades queries to DNS over HTTPS (DoH) transparently where possible. ## How It Works DNS settings are managed from the DNS page of the admin console. This covers MagicDNS, nameservers, and search domains. ### Nameservers Nameservers are the IPv4 or IPv6 addresses of DNS servers devices use when connected to the tailnet. There are two types: - Restricted nameservers -- apply only to DNS queries matching a specific search domain. This is also known as split DNS. Example: configure `1.1.1.1` as a nameserver for `example.com`, and devices only use `1.1.1.1` for queries matching `*.example.com` (such as `foo.example.com`). - Global nameservers -- handle queries for any domain. When you use a public global nameserver (Cloudflare, Google, etc.), Tailscale automatically uses DNS-over-HTTPS (DoH) so queries are encrypted before traversing the internet. Some public global DNS nameservers: - Quad9: `9.9.9.9`, `149.112.112.112`, `2620:fe::fe`, and `2620:fe::9`. - Google: `8.8.8.8`, `8.8.4.4`, `2001:4860:4860::8888`, and `2001:4860:4860::8844`. - Cloudflare: `1.1.1.1`, `1.0.0.1`, `2606:4700:4700::1111`, and `2606:4700:4700::1001`. Tailscale treats each global nameserver's list of addresses as one entity -- adding one Google address includes all of Google's. Best practice is to use more than one global nameserver for redundancy, but note that multiple nameservers can bypass content restrictions if they differ. Unless your nameservers are public or use Tailscale IP addresses, you probably need to configure [[concepts/subnet-routers|subnet routing]] so devices can reach private DNS servers. ### Nameservers and exit nodes By default, when a device uses an [[concepts/exit-nodes|exit node]], it also uses the exit node as a DNS resolver for all domains, regardless of global and restricted (split DNS) nameserver configuration. You can override this per nameserver in the admin console by enabling the `Use with exit node` setting (Edit nameserver options), which includes that nameserver in DNS resolution for devices using an exit node. ### Search domains Search domains are domain suffixes automatically appended to any name that is not a fully qualified domain name (FQDN). Only devices running Tailscale v1.34 or later can use search domains. Example: with `example.com` and `test.com` configured, entering `server` searches `server.example.com` first, and if no match, `server.test.com`. When MagicDNS is enabled, it is always the first domain in the Search Domains list and this is not configurable. ### Public DNS records Instead of the admin console, you can publish records on your public-facing DNS server. Because Tailscale IP addresses are only accessible to users of your network, publishing these names is relatively harmless. Tailscale does not offer a DNS server, so you run your own or use one from your cloud, domain host, or DNS provider. Public DNS names might take a while to propagate. ### Override DNS servers By default, devices prefer their local DNS settings and only use the tailnet's DNS servers when needed. Enable `Override DNS servers` (under Global nameservers on the DNS page) to force devices to ignore local DNS and always use the tailnet's global nameservers -- useful to ensure access to private records, prevent untrusted nameservers, or force traffic through a filtering DNS server. Make sure all devices can reach your global nameservers first: if an ACL or grant blocks access to the global nameserver, that device can't resolve DNS. ## The port-443 behavior A common surprise is MagicDNS "fetching records on port 443." When you use popular DNS providers, Tailscale transparently upgrades you to DNS over HTTPS (DoH) to make lookups end-to-end encrypted with the DNS server. Traditional DNS is clear text over UDP port 53, which lets attackers on the same network sniff your DNS traffic. DoH sends DNS requests over HTTPS (TLS) instead. Applications query the local MagicDNS server at `100.100.100.100`, and MagicDNS upgrades queries to DoH -- this may manifest as an unexpected TCP connection to port 443 (the standard HTTPS port). Outbound connection monitoring software may need to be adjusted to account for this. NextDNS only allows connections over DoH, so all lookups are end-to-end encrypted. ## Risks & Pitfalls - `nslookup` may return incorrect results on some platforms because it doesn't use OS-provided DNS info; this shows up with split DNS or MagicDNS. Test instead with `dscacheutil` (macOS), the OS-native tools (Windows), or platform-appropriate commands on Linux. - Resolver order is not guaranteed: modern operating systems reorder, parallelize, and load-balance nameservers, so Tailscale cannot guarantee resolvers are queried in the order you specify. If you need a specific resolver to answer differently, use split DNS or conditional forwarding. - Enabling `Override DNS servers` before all devices can reach the global nameservers will break DNS resolution for blocked devices. ## Related Concepts - [[concepts/tailnet-and-addressing|Tailnet and addressing]] -- the IPs MagicDNS maps names to - [[concepts/subnet-routers|Subnet routers]] -- reach private DNS servers on advertised subnets - [[concepts/exit-nodes|Exit nodes]] -- exit node as default DNS resolver - [[concepts/app-connectors|App connectors]] -- also use DoH for DNS discovery ## Sources Based on Tailscale's official documentation for DNS in Tailscale and the FAQ on why MagicDNS fetches records on port 443. --- title: "Tailscale security and trust model" type: concept tags: [security, zero-trust, encryption, firewall, privacy] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-zero-trust-networking-definition-tailscale-docs.md", "raw/docs_page-can-tailscale-decrypt-my-traffic-tailscale-docs.md", "raw/docs_page-is-my-traffic-routed-through-your-servers-tailscale-docs.md", "raw/docs_page-what-devices-can-connect-to-or-know-mine-tailscale-docs.md", "raw/docs_page-what-firewall-ports-should-i-open-to-use-tailscale-tailscale.md", "raw/docs_page-tailscale-encryption-tailscale-docs.md"] confidence: high --- ## Definition Tailscale is built on a **zero-trust** model: the core premise is that "you can't trust the physical network anymore." Zero Trust Networking (ZTN) is an architecture descended from Google's BeyondCorp design. Instead of a "hard crunchy outside, soft chewy inside" perimeter firewall, Tailscale puts a firewall around every device and service and keeps every session encrypted between each pair of endpoints, so an attacker with physical network access sees only "meaningless encrypted packets" and cannot easily perform "lateral motion" between devices. ## How It Works **Tailscale cannot decrypt your traffic.** Devices running Tailscale only exchange their public keys; private keys never leave the device. All traffic is end-to-end encrypted, always. **Traffic is not routed through Tailscale's servers by default.** Tailscale routes traffic over the shortest path possible -- in most cases a direct, peer-to-peer connection. When a direct connection cannot be established, devices bounce traffic off geographically distributed relay servers called **DERPs**. Relayed traffic is already encrypted and is "no different security-wise than the other dozen hops your internet packets already make." **Encryption layers** span the control plane and data plane: - **Control plane** (key exchange, coordinating connections): a custom Noise IK-based protocol with X25519 (RFC7748). It can run over plain TCP or be wrapped in TLS. - **Data plane** (device-to-device traffic): WireGuard. DERP servers "never access your unencrypted data; they only handle WireGuard packets that are already encrypted." Device-to-DERP connections are authenticated using a NaCl box construction on top of TLS. - **NAT traversal**: a custom UDP protocol using NaCl box; it can only influence connection efficiency, "not the security of the data they carry." - **TLS**: builds on Go crypto/tls, requiring a minimum of TLS 1.2 and supporting TLS 1.3, with ECDHE forward secrecy and AEAD (AES-128-GCM or ChaCha20-Poly1305). - Tailnet Lock uses ED25519 signatures. Device TLS certificates come from Let's Encrypt for MagicDNS hostnames. **Device visibility** is organized into tailnets by identity-provider domain. Devices in different tailnets cannot know about or connect to each other by default; cross-tailnet access requires explicit sharing. Within a tailnet the model is deny-by-default, but the **default access-control policy lets all devices connect to and know about each other**. Tailscale uses **netmap trimming** so a client sees only relevant devices. If a grant lets device-a connect to device-b, each can know about the other; with no such rule, neither can know about the other. ## Key Parameters **Firewall ports.** Most of the time you **don't need to open any firewall ports** -- Tailscale uses NAT traversal so it "just works." When both devices are on difficult networks, you may open ports to help peer-to-peer connections: - Let internal devices start **TCP connections to `*:443`** -- coordination server and DERP relays use HTTPS on port 443. - Let internal devices start **UDP from `:41641` to `*:*`** -- direct WireGuard tunnels use UDP with a source port that defaults to `41641` (reconfigurable per device). - Let internal devices start **UDP to `*:3478`** -- the STUN protocol, used only toward DERP servers. - Let internal devices start **HTTP (TCP) connections to `*:80`** -- coordination server prefers HTTP on port 80 (falls back to 443), also used for captive-portal detection via a `/generate_204` endpoint returning a `204` status. Static IP ranges (if IP-based rules are required): - `login.tailscale.com` / `controlplane.tailscale.com` -- IPv4 `192.200.0.0/24`, IPv6 `2606:B740:49::/48`. - `log.tailscale.com` -- IPv4 `199.165.136.0/24`, IPv6 `2606:B740:1::/48`. DERP servers are named `derpN` where `1 <= N <= 28` (as of August 2025) and are reached at TCP port `443`. ## When To Use The zero-trust model applies to every Tailscale deployment. Tailscale recommends an **incremental** rollout: first secure user devices with encrypted connections to [[concepts/subnet-routers|subnet routers]], then add end-to-end encryption to your most valuable servers one by one, lock down non-encrypted traffic, and finally retire the subnet routers for a fully migrated subnet. ## Risks & Pitfalls - Tailscale's cryptographic implementations are **not FIPS compliant**, and primitives such as Curve25519, XSalsa20, ChaCha20-Poly1305, and the Noise and WireGuard protocols cannot be made FIPS compliant. This may matter for organizations with FIPS requirements. - The default "allow all within a tailnet" policy is permissive -- restrict visibility with more prescriptive [[concepts/access-controls|access-control policies]] when needed. - Hardcoding DERP IP addresses is discouraged; the set of relays grows over time, so use `*:443` and domain-based rules. - All Tailscale log data is sent over TLS "without additional authentication or encryption." ## Related Concepts - [[concepts/how-tailscale-works]] - [[concepts/access-controls]] - [[concepts/exit-nodes]] - [[concepts/api-and-automation]] - [[syntheses/tailscale-vs-vpn]] ## Sources - raw/docs_page-zero-trust-networking-definition-tailscale-docs.md - raw/docs_page-can-tailscale-decrypt-my-traffic-tailscale-docs.md - raw/docs_page-is-my-traffic-routed-through-your-servers-tailscale-docs.md - raw/docs_page-what-devices-can-connect-to-or-know-mine-tailscale-docs.md - raw/docs_page-what-firewall-ports-should-i-open-to-use-tailscale-tailscale.md - raw/docs_page-tailscale-encryption-tailscale-docs.md --- title: "Subnet routers" type: concept tags: [routing, subnet-router, snat, high-availability, site-to-site, networking] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-subnet-routers-tailscale-docs.md", "raw/docs_page-configure-a-subnet-router-tailscale-docs.md", "raw/docs_page-disable-subnet-route-masquerading-tailscale-docs.md", "raw/docs_page-site-to-site-networking-tailscale-docs.md", "raw/docs_page-set-up-high-availability-tailscale-docs.md", "raw/docs_page-troubleshoot-overlapping-subnet-route-failover-tailscale-doc.md", "raw/docs_page-connect-to-an-aws-vpc-using-subnet-routes-tailscale-docs.md"] source_url: "https://tailscale.com/docs/features/subnet-routers" confidence: high --- # Subnet routers ## Definition A subnet router is a device in your tailnet that acts as a gateway, advertising routes so other tailnet devices can reach non-Tailscale devices on a physical subnet. This lets you extend the tailnet to include devices that don't or can't run the Tailscale client (printers, cameras, legacy hosts, entire cloud VPCs) without installing Tailscale everywhere. Any device using the subnet router as a gateway is considered "behind" the subnet router. Devices behind subnet routers don't count toward your pricing plan's device limit. Subnet routers respect Tailscale's [[concepts/access-controls|access control policies]], maintaining the security model while bridging to conventional subnet-based networks. Subnet routers are available for all plans. ## How It Works A subnet router relays traffic between the tailnet and a traditional subnet. By default it uses Source Network Address Translation (SNAT), so traffic from a device behind the router appears to come from the router itself rather than the original device. You can disable SNAT to preserve original source IPs (Linux only). Setup on Linux requires two things: enabling IP forwarding and advertising routes. If your Linux system has a `/etc/sysctl.d` directory: ``` 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 ``` Otherwise use `/etc/sysctl.conf` in place of the file above. If your Linux node uses `firewalld`, a known issue may require allowing masquerading as a workaround: `firewall-cmd --permanent --add-masquerade`. Advertise routes with a comma-separated CIDR list (works with `tailscale set` or `tailscale up`): ``` sudo tailscale set --advertise-routes=192.0.2.0/24,198.51.100.0/24 ``` All platforms except Apple TV support both IPv4 and IPv6 subnets; Apple TV only supports IPv4. After advertising, enable the routes in the admin console: open the Machines page, find the device by the `Subnets` badge or `property:subnet` filter, select Edit route settings, check the routes, and Save. You can skip this step if you use `autoApprovers`. Route approval and access rules are separate mechanisms -- see [[concepts/app-connectors|route injection]] and [[syntheses/routing-mechanisms-compared|the routing comparison]]. Verify with `tailscale ip -4` and a ping. Most platforms auto-discover new routes; Linux devices need `sudo tailscale set --accept-routes`. ## Key Parameters - `--advertise-routes=` -- comma-separated list of subnet routes to expose to the tailnet. Requires IP forwarding enabled. - `--accept-routes` -- makes a client (notably Linux) accept advertised routes from other subnet routers. - `--snat-subnet-routes=false` (Linux only) -- disables SNAT/masquerading so the end device sees the originating device's IP. Run as `tailscale up --snat-subnet-routes=false`. When disabled you must add a return route (Network `100.64.0.0/10`, next hop = the LAN IP of your subnet router) on the device OS, in VPC settings, or via DHCP. Disabling masquerading can also be expressed as `tailscale up --snat-subnet-routes=false`. If SNAT is disabled, NAT traffic to local routes advertised with `--advertise-routes` needs routing configured manually. ## Site-to-site networking Site-to-site (layer 3 / L3 routing) connects two or more distinct networks using subnet routers, so devices in different subnets communicate without either installing Tailscale. Requirements: the subnets must NOT have identical CIDR ranges (use HA or 4via6 if they must), and both subnet routers must run Linux. A typical per-router command combines the flags: ``` tailscale up --advertise-routes=192.0.2.0/24 --snat-subnet-routes=false --accept-routes ``` You should also clamp the maximum segment size (MSS) to the MTU using iptables on the `tailscale0` interface: ``` iptables -t mangle -A FORWARD -o tailscale0 -p tcp -m tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu ``` Grant traffic between subnets with two `grants` rules (one per direction). Configure non-router subnet devices to route via the subnet router with `ip route add via ` (these do not persist across reboot). In cloud environments like AWS you can update the provider's routing tables instead. ## High availability and overlapping routes For redundancy, run 2+ subnet routers advertising the exact same route prefix, for example: ``` sudo tailscale set --advertise-routes=10.0.0.0/24,10.1.0.0/24 ``` Failover is the default (all plans): the oldest connector is primary; if it disconnects from the control plane for more than ~15 seconds, traffic moves to another. Regional routing (Premium/Enterprise) groups overlapping connectors into DERP regions and assigns clients to the closest. Tailscale uses longest prefix matching (LPM) across overlapping routes with different prefix lengths. Failover only works between routers advertising the EXACT same prefix -- a broader route is not a fallback for a more-specific one. If the router for `10.0.0.0/24` goes offline, Tailscale drops traffic to that prefix rather than falling back to a `/16`. To avoid black holes, have the broader-prefix router also advertise the more-specific prefix (e.g. router A advertises both `10.0.0.0/16` and `10.0.0.0/24`). ## Risks & Pitfalls - Be careful with `--accept-routes` on HA routers sharing the same route in the same region: the standby accepts its own advertised route from the primary, creating an inefficient path. For most HA setups, use `--advertise-routes` alone. - Setting `--snat-subnet-routes=false` on a node acting as both subnet router and exit node can cause upstream drops; separate the roles onto two nodes. - Expired connector keys: advertised routes remain configured but unreachable ("fail close" policy). Disable key expiry or configure HA to prevent disruption. - Tailscale does not currently support designating a preferred subnet router for a route. ## Related Concepts - [[concepts/exit-nodes|Exit nodes]] -- route outbound internet traffic (use exit nodes for `0.0.0.0/0` and `::/0`) - [[concepts/app-connectors|App connectors]] -- route to applications by domain name - [[concepts/magicdns-and-dns|MagicDNS and DNS]] -- split DNS to internal DNS servers on advertised subnets - [[concepts/access-controls|Access controls]] -- grants that permit traffic across routes - [[syntheses/routing-mechanisms-compared|Routing mechanisms compared]] ## Sources Based on Tailscale's official documentation for subnet routers, subnet router configuration, disabling subnet route masquerading, site-to-site networking, high availability, overlapping subnet route failover, and connecting to an AWS VPC using subnet routes. --- title: "Tailnet and Addressing" type: concept tags: [tailscale, tailnet, addressing, cgnat, ipv6, dns, foundational] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-what-is-a-tailnet-tailscale-docs.md", "raw/docs_page-tailnet-names-and-types-tailscale-docs.md", "raw/docs_page-what-are-these-100-x-y-z-addresses-tailscale-docs.md", "raw/docs_page-reserved-ip-addresses-tailscale-docs.md", "raw/docs_page-tailscale-ipv6-support-tailscale-docs.md"] confidence: high --- # Tailnet and Addressing ## Definition A **tailnet** is a Tailscale network: a secure, interconnected collection of users, devices, and resources, inaccessible from the public internet. Tailscale creates a tailnet the first time you log in on any device, and each authenticated device is added to it. Every device receives a stable, unique **Tailscale IP address** in the `100.x.y.z` (CGNAT) range that stays the same regardless of physical location or network. There are two tailnet types: a **personal tailnet** (shared-domain single-user, like `gmail.com`) and an **organization tailnet** (custom domain, like `example.com`). ## How It Works **Tailnet names.** A tailnet uses three primary name types: - **Tailnet DNS name** - the fully qualified domain used for name resolution throughout your tailnet, assigned as `tail.ts.net` where `` is a random hex string (for example `tailnet-fe8c.ts.net` or the default form `tailfe8c.ts.net`). You can generate a more memorable randomized name (for example `cat-crocodile.ts.net` or `yak-bebop.ts.net`) from the DNS page of the admin console via "Rename tailnet". It underpins MagicDNS, HTTPS certificates, and sharing. - **Machine name** - the name of a device/node, generated from the OS hostname when the device joins; changeable from the admin console or CLI. - **Tailnet ID** - the string used with the Tailscale API, found on the General page of the admin console. There is also a **Display name** (the private domain or email shown in the client/admin console; up to 65 characters; letters, numbers, spaces, apostrophes, hyphens; no periods or underscores; viewing it in the client requires version 1.88 or later) and a **Legacy ID** (renamed from "Organization" in October 2025; only shown on tailnets created before that change). **The 100.x.y.z addresses.** Tailscale IP addresses come from the CGNAT (Carrier-Grade NAT) shared address space defined in RFC 6598: the `100.64.0.0/10` subnet (`100.64.0.0` through `100.127.255.255`). Tailscale uses this range because it does not conflict with common private ranges (`10.0.0.0/8`, `192.168.0.0/16`), it is designed for intermediate traffic needing additional NAT before reaching the public internet, and it is philosophically an ISP-style range (Tailscale acts as a service provider building a shared overlay on the regular internet). These addresses are never exposed to the public internet. **IPv6.** Tailscale supports both IPv4 and IPv6, and DERP servers can even bridge IPv4-only and IPv6-only devices. Every device gets a private IPv6 address from the `fd7a:115c:a1e0::/48` unique local prefix, so IPv6 connectivity always works inside the tailnet even if your ISP lacks IPv6. Public IPv6 is used for direct connections only when both devices have public IPv6 addresses; otherwise Tailscale defaults to IPv4. Exit nodes fully support IPv6. ## Key Parameters Reserved IP addresses (from RFC 6598 range; not assignable to devices): - `100.64.0.0/10` - the CGNAT range Tailscale uses for device IP addresses. - `100.100.0.0/24` - Tailscale internal use; unavailable for IP pools. - `100.100.100.0/24` - Tailscale internal use; unavailable for IP pools. - `100.100.100.100` - **Quad100**, a device-local service address providing a DNS resolver on port `53` and a device management interface on port `80`. - `100.115.92.0/23` - Tailscale internal use; unavailable for IP pools. - `fd7a:115c:a1e0::/48` - the IPv6 unique local address prefix for device IPv6 addresses. - `fd7a:115c:a1e0::53` - IPv6 equivalent of Quad100 (same DNS resolver and device management services). - `100.101.102.103` - reserved for the `tshello` example service. IPv4 interoperability (direct vs relayed): two IPv4+IPv6 devices use the protocol they share; an IPv6-only and an IPv4-only device use a **relayed** connection. ## When To Use You reference these ranges when writing access control policies (you can specify a device by its `100.x.y.z` address in `src`/`dst` fields), configuring IP pools, or troubleshooting connectivity. Quad100 (`100.100.100.100:53`) is where MagicDNS resolution happens; verifying a device can reach it is a standard DNS troubleshooting step. ## Risks & Pitfalls - **CGNAT conflicts.** If your ISP or another VPN also uses `100.64.0.0/10`, you can hit routing conflicts; the fix involves disabling IPv4 selectively or tailnet-wide. - **Reserved ranges are not assignable** and IP pools must not overlap them (`100.100.0.0/24`, `100.100.100.0/24`, `100.115.92.0/23`). - **Quad100 is device-local**: traffic to `100.100.100.100` stays on the local device and cannot be targeted in access control policies. - **Duplicate IPs** can occur if you restore a device from backup or clone a filesystem. - **Renaming the tailnet DNS name** can break existing links to devices, because MagicDNS, HTTPS certificates, and sharing all rely on it; after a randomized name is used for HTTPS certs you cannot re-generate it (you can only switch between it and the default). ## Related Concepts - [[concepts/what-is-tailscale|What is Tailscale?]] - [[concepts/how-tailscale-works|How Tailscale Works]] - [[concepts/magicdns-and-dns|MagicDNS and DNS]] - [[concepts/cli-reference|CLI Reference]] ## Sources - raw/docs_page-what-is-a-tailnet-tailscale-docs.md - raw/docs_page-tailnet-names-and-types-tailscale-docs.md - raw/docs_page-what-are-these-100-x-y-z-addresses-tailscale-docs.md - raw/docs_page-reserved-ip-addresses-tailscale-docs.md - raw/docs_page-tailscale-ipv6-support-tailscale-docs.md --- title: "Users and Organization" type: concept tags: [users, invitations, organization, billing, fast-user-switching, administration, foundational] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-manage-users-tailscale-docs.md", "raw/docs_page-inviting-users-tailscale-docs.md", "raw/docs_page-invite-any-user-to-your-tailnet-tailscale-docs.md", "raw/docs_page-deleting-and-suspending-users-tailscale-docs.md", "raw/docs_page-manage-your-organization-tailscale-docs.md", "raw/docs_page-fast-user-switching-tailscale-docs.md"] confidence: high --- # Users and Organization ## Definition Managing users is an essential part of maintaining a [[concepts/tailnet-and-addressing|tailnet]]: controlling who is invited, what access they have, when they are removed, and how the organization's contact, billing, and domain information is maintained. It also includes **fast user switching**, which lets a single device move between two or more logged-in accounts without re-authenticating. This concept covers the operational lifecycle of a user -- invite, approve, suspend, restore, delete -- plus org-level account settings. Access-console permissions themselves come from [[concepts/identity-and-sso|user roles]]. ## How It Works Users are managed from the **Users** page of the admin console. You invite team members or any external user, control their access (approval, roles, deletion/suspension), and switch the active client account on a device. Tailscale bills for every active user on every tailnet, including invited users who are paid users on other tailnets; a Tailscale account may not be shared by multiple individuals. **Inviting any user** sends a one-time-use invitation as a generated URL, for friends, family, contractors, or org members. Unused invites expire after 30 days. You need Owner, Admin, or IT admin to invite. From the Users page, select **Invite external users**, then either add email addresses and **Invite** (choosing one role for all addresses in that invite), or use **Copy invite link** to generate and copy an invite URL. Recipients paste the URL into a browser, sign in with their IdP or passkey, and download the client. By default, tailnets only allow Admin users to accept invitations to join external tailnets; you can change which roles may join under **Join external tailnets** (or select **Deny** to disable it). **Deleting, suspending, or deprovisioning** a user vacates their seat for reuse; a restored user consumes an available seat again. Owner, Admin, or IT admin can delete or suspend. Deleting a user deletes their devices (device keys are removed from the coordination server, blocking further connection requests) and stops their API access tokens and auth keys, usually within seconds. To delete an Owner, first transfer the Owner role to another user. Suspending a user (without deleting devices) blocks their devices from exchanging traffic, blocks adding devices, blocks admin-console access, and stops their tokens and auth keys; **Restore user** returns access to the devices they owned at restore time. ## Key Parameters - **Invite management**: **Resend user invite** and **Copy invite link** (Owner/Admin/IT admin); **Delete invite** to revoke (Owner/Admin/IT admin); review pending invites with the `status:invited` filter (Owner, Admin, IT admin, Network admin, or Billing admin); track invite activity in the **Configuration logs** page. - **Approval and provisioning**: if [[concepts/identity-and-sso|user approval]] is enabled, invited users must be approved before they can join. If **User & group provisioning** (SCIM) is enabled, deprovision users through the IdP -- deactivating in Okta or deleting in Microsoft Entra ID automatically suspends the user in Tailscale. - **User states**: **Suspended** (restricted, restorable), deleted (permanent), **Needs approval** (`status:needsapproval`), and **Idle** (a non-Owner not signed in or using Tailscale for more than 7 days). Machines and API/auth keys for suspended users are suspended; for deleted users they are deleted or revoked and cannot be reassigned. - **Leaving**: users who joined multiple external tailnets can use **Leave tailnet** to leave subsequently joined organizational tailnets. You cannot delete yourself from a tailnet -- ask an admin to remove your account (or contact support to delete your account). - **Organization settings** (Manage your organization): **Contact preferences** (account, configuration, security, and billing contacts); **Manage billing** and **Manage your plan**; and tailnet name / domain management (Tailnet DNS, machine, Tailnet ID, and Legacy ID names, plus domain ownership). **Fast user switching** (all plans) lets a device hold multiple logged-in accounts but keep only one active at a time; a device cannot transmit packets on multiple tailnets simultaneously. The active client account is independent of the account used for the admin console. Add and switch accounts via the client app (macOS, iOS, Windows) or the CLI (Linux, macOS, Windows): - `tailscale login` -- add an account (opens a browser to authenticate). - `tailscale switch alice@example.com` -- switch accounts; you won't be asked to re-authenticate unless the device's node key for that tailnet has expired or the account has never been used on the device. - `tailscale switch --list` -- list accounts (an asterisk marks the active one). - `tailscale set --nickname=work` -- set a nickname for the active account, usable in `tailscale switch work`. - `tailscale logout` -- log out the active account. ## When To Use Invite team members for ongoing access and use one-time external invites for contractors, friends, or family. Suspend (rather than delete) when a user should be temporarily blocked but may return, preserving their devices. Use fast user switching to move between a personal and a work tailnet on one device without re-authenticating. Restrict **Join external tailnets** to limit which roles can accept outside invitations. ## Risks & Pitfalls - Every active user is billed on every tailnet, including invited users who pay on other tailnets -- track invites to control cost. - Deleting a user permanently deletes their devices and revokes their keys; those keys cannot be reassigned, so plan replacements. - You cannot delete an Owner without first transferring the Owner role. - Removing or deleting an unapproved user does not prevent them from logging in again to an unapproved state. - Enabling User & group provisioning changes how users must be deprovisioned (through the IdP), and it disables user approval. ## Related Concepts - [[concepts/identity-and-sso|Identity and SSO]] - [[concepts/access-controls|Access Controls]] - [[concepts/device-management|Device Management]] - [[concepts/cli-reference|CLI Reference]] - [[concepts/api-and-automation|API and Automation]] ## Sources - raw/docs_page-manage-users-tailscale-docs.md - raw/docs_page-inviting-users-tailscale-docs.md - raw/docs_page-invite-any-user-to-your-tailnet-tailscale-docs.md - raw/docs_page-deleting-and-suspending-users-tailscale-docs.md - raw/docs_page-manage-your-organization-tailscale-docs.md - raw/docs_page-fast-user-switching-tailscale-docs.md --- title: "What is Tailscale?" type: concept tags: [tailscale, vpn, wireguard, mesh, zero-trust, foundational] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-what-is-tailscale-tailscale-docs.md", "raw/docs_page-terminology-and-concepts-tailscale-docs.md", "raw/docs_page-technical-overviews-tailscale-docs.md"] confidence: high --- # What is Tailscale? ## Definition Tailscale is a Zero Trust, identity-based connectivity platform that creates a secure, peer-to-peer mesh network (called a [[concepts/tailnet-and-addressing|tailnet]]) between your devices. It replaces legacy VPN, SASE, and PAM tooling to connect remote teams, multi-cloud environments, CI/CD pipelines, edge and IoT devices, and AI workloads. Under the hood it builds encrypted point-to-point connections using the open-source WireGuard protocol, so only devices on your private network can communicate with each other. Setup is "zero config": after you create an account, authenticating two or more devices automatically creates a tailnet with a sensible set of default access policies, and connections work across firewalls and NAT without port forwarding or complex firewall rules. ## How It Works Traditional VPNs use a hub-and-spoke topology: every device sends all traffic through a central gateway, which adds latency and becomes a bottleneck and single point of failure. Tailscale instead operates as a mesh topology where each device talks directly to others using NAT traversal, giving higher throughput, lower latency, and improved reliability. You can still use Tailscale like a traditional full-tunnel VPN by routing all traffic through an [[concepts/how-tailscale-works|exit node]]. The system has two planes that work in unison (see [[concepts/how-tailscale-works|How Tailscale Works]]): - The **control plane**, centered on the coordination server, manages authentication, encryption keys, access policies, and device coordination. It never relays your traffic. - The **data plane** carries the actual encrypted packets directly between devices (peer-to-peer), falling back to DERP relay servers only when a direct connection is impossible. Because the architecture avoids centralization where possible, adding new devices or users does not create the bottlenecks that plague traditional VPNs. ## Key Parameters Core terms every Tailscale user should know (full glossary in [[concepts/tailnet-and-addressing|Tailnet and Addressing]] and [[concepts/how-tailscale-works|How Tailscale Works]]): - **Tailnet** - a Tailscale network: an interconnected collection of users, devices, and resources. There are personal tailnets (shared-domain single-user, like `gmail.com`) and organization tailnets (custom domain, like `example.com`). - **Node** - a combination of a user and a device. - **Device** - anything other than a user (physical or virtual) that sends, receives, or processes data on the network. - **Peer** - another node your device is trying to reach. - **Coordination server** - the central control-plane server that maintains a connection to all devices; it manages keys and policy but does not relay traffic. - **Client** - the software application that runs on a device so it can join a tailnet; uses WireGuard for encrypted peer-to-peer connections. - **Tailscale IP address** - a unique `100.x.y.z` address assigned to each device that stays stable across networks. - **Identity provider (IdP)** - Tailscale is not an IdP; it relies on external providers (Google, Okta, Microsoft) for authentication. ## When To Use Tailscale scales from personal use to enterprise deployments. Documented use cases include: - **Business VPN** - replace a legacy VPN and enable secure remote access to infrastructure. - **Privileged Access Management (PAM)** - Zero Trust with just-in-time access and session recording. - **Workload connectivity** - connect pipelines, apps, and Kubernetes workloads. - **CI/CD** - granular secure access to every runner and workload. - **Edge and IoT** - access, manage, and monitor thousands of devices. - **Securing AI** - unified governance for AI agents and users. - **Homelab / personal** - remotely access a media server, share a service with friends, etc. It is described as ideal for DevOps, IT, and Security teams because of its low setup barrier, cross-platform reach, and configurability. ## Risks & Pitfalls - Tailscale depends on an external identity provider; it does not authenticate users itself, so your IdP's security posture matters. - Its cryptographic implementations are **not FIPS compliant** and several primitives cannot be made compliant, which matters for regulated organizations (see [[concepts/how-tailscale-works|How Tailscale Works]]). - The `100.x.y.z` CGNAT range can conflict with ISPs or other VPNs that use the same space (see [[concepts/tailnet-and-addressing|Tailnet and Addressing]]). - "Zero config" reduces effort but you should still define access control policies; the defaults are sensible but not tailored to your environment. ## Related Concepts - [[concepts/how-tailscale-works|How Tailscale Works]] - [[concepts/tailnet-and-addressing|Tailnet and Addressing]] - [[concepts/install-and-first-use|Install and First Use]] - [[concepts/cli-reference|CLI Reference]] - [[syntheses/tailscale-vs-vpn|Tailscale vs Traditional VPN]] ## Sources - raw/docs_page-what-is-tailscale-tailscale-docs.md - raw/docs_page-terminology-and-concepts-tailscale-docs.md - raw/docs_page-technical-overviews-tailscale-docs.md --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion --- title: "ACLs vs. grants in the tailnet policy file" type: synthesis tags: [access-control, acls, grants, policy-file, migration] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-access-control-tailscale-docs.md", "raw/docs_page-grants-tailscale-docs.md", "raw/docs_page-syntax-reference-for-the-tailnet-policy-file-tailscale-docs.md"] confidence: high --- ## Comparison Tailscale has two ways to write access-control rules in the **tailnet policy file** (expressed in human JSON, HuJSON). Both follow the deny-by-default model: all connections between devices are denied unless explicitly permitted. | | ACLs (`acls`) | Grants (`grants`) | | --- | --- | --- | | Generation | Original / first-generation syntax | Modern, recommended, next-generation syntax | | Layers covered | Network layer only | Network layer (`ip`) **and** application layer (`app`), unified | | Core fields | `action` (only `accept`), `src`, `proto` (optional), `dst` as `:` | `src`, `dst`, and at least one of `ip` or `app`; implied `accept` action | | Route filtering / routing awareness | Not supported (cannot restrict specific exit nodes) | Adds route filtering and routing awareness with `via` | | Device posture | `srcPosture` on rules | `srcPosture` (applies to `src` only, not `dst`) | | Future features | Will keep working indefinitely, but receives **no new features** | Where all new capability lands | ## Analysis **ACLs** are "Tailscale's original approach to network layer security." Each ACL rule grants access from a set of sources to a set of destinations. Because access is deny-by-default, the only possible `action` is `accept`. A rule uses `src`, an optional `proto` (an IANA protocol number `1-255` or a named alias such as `tcp`, `udp`, `icmp`), and `dst` entries in `:` form. The `acls` section still supports the legacy fields `users` and `ports`, but best practice is `src` (instead of `users`) and `dst` (instead of `ports`). Tailscale automatically translates all ACLs to lower-level source-IP-to-destination-IP-and-port rules. A notable ACL limitation: "You cannot restrict the use of specific exit nodes using ACLs." **Grants** are "Tailscale's enhanced access control system that combines network layer and application layer permissions into a unified framework." A grant has three components: **Source** (`src`), **Destination** (`dst`), and **Capabilities** grouped as network capabilities (the `ip` field) and application capabilities (the `app` field). Example: `"ip": ["tcp:443", "udp:53"]` grants TCP 443 (HTTPS) and UDP 53 (DNS); the `app` field uses the format `"domainName/capabilityName"` (for example `"tailscale.com/cap/tailsql"`). "Grants can do everything ACLs can, plus they facilitate application-level permissions and route filtering." Application capabilities are defined by the applications themselves, and the policy engine treats their parameters as opaque JSON. **Selectors are shared.** Both mechanisms draw on the same targets and selectors defined in the policy file -- autogroups, custom groups, tags, IP addresses, and individual users. Notable selectors: `autogroup:internet` (internet access through an exit node), `autogroup:self`, `autogroup:member`, `autogroup:admin`, and role autogroups; groups (`group:engineering`), tags (`tag:production`), and hosts. Tags must be declared in `tagOwners` before use. **Coexistence and migration.** Grants and legacy ACLs "can coexist in the same tailnet policy file." Tailscale recommends migrating to grants and using grants for all new configurations, while promising ACLs "will always be supported" / "will continue to work indefinitely." A dedicated migration guide exists. The same policy file also holds shared sections used by both: `ssh` (Tailscale SSH), `autoApprovers` (bypass approval for advertising subnet routers, exit nodes, and app connectors), `nodeAttrs`, `postures`, `tagOwners`, `groups`, `hosts`, `ipsets`, `tests`, and `sshTests`. ## Recommendations - **For all new tailnet policy configurations, use grants** -- they are the recommended, actively developed syntax and cover everything ACLs do plus application-layer permissions and route filtering. - **Choose grants when you need** application-layer capabilities (`app`), fine-grained permissions by user role or device posture, per-exit-node restriction, or routing awareness with `via`. - **Keep or write ACLs** only where you already have a working ACL base and no need for the new capabilities; ACLs remain supported indefinitely but will not gain new features. - **Migrate incrementally** -- grants and ACLs coexist in the same file, so you can move rules over gradually and use the `tests` / `sshTests` sections to assert that permissions do not change during migration. ## Pages Compared - [[concepts/access-controls]] - [[concepts/security-model]] - [[concepts/device-management]] - [[concepts/exit-nodes]] - [[syntheses/routing-mechanisms-compared]] --- title: "Routing mechanisms compared: subnet routers vs. exit nodes vs. app connectors" type: synthesis tags: [routing, subnet-routers, exit-nodes, app-connectors, comparison] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-subnet-routers-tailscale-docs.md", "raw/docs_page-exit-nodes-route-all-traffic-tailscale-docs.md", "raw/docs_page-how-app-connectors-work-tailscale-docs.md"] confidence: high --- ## Comparison Tailscale offers three ways to reach resources that are not themselves running the Tailscale client. All three are available on all plans. | | Subnet router | Exit node | App connector | | --- | --- | --- | --- | | What it routes | Access to specific private subnets (LANs, VPCs) | All outbound public internet traffic | Traffic to specific self-hosted or SaaS applications | | Addressed by | IP ranges / CIDR routes | Default routes (`0.0.0.0/0`, `::/0`) | **Domain names** (not IP addresses) | | Key flag / config | `tailscale set --advertise-routes=...` | Advertise device as exit node; `autogroup:internet` in policy | Tailnet policy `app` capability + tag; DoH DNS discovery | | Affects internet traffic? | No | Yes -- functions like a VPN server | Only for the configured application domains | | Device host requirement | Almost any device running Tailscale | Linux, macOS, Windows, Android, iOS, or tvOS; Tailscale v1.20+ | A Linux device with a public IP and IP forwarding | | Counts toward device limit? | Devices behind it do **not** count | n/a | n/a | ## Analysis **Subnet routers** extend a tailnet to devices that "don't or can't run the Tailscale client," acting as gateways that relay traffic between the tailnet and conventional subnet-based networks (printers, cameras, AWS VPCs, Amazon RDS / Google Cloud SQL). You enable IP forwarding and run `sudo tailscale set --advertise-routes=192.0.2.0/24,198.51.100.0/24`. By default they perform Source Network Address Translation (**SNAT**, masquerading), so traffic appears to come from the router; you can disable this with `--snat-subnet-routes=false` (Linux only) to preserve the original source IP. Devices behind a subnet router do not count toward your pricing plan's device limit. **Exit nodes** route *all* public internet traffic through one device, effectively using default routes (`0.0.0.0/0`, `::/0`), "similar to how you would if you were using a typical VPN" -- useful on untrusted Wi-Fi or for accessing services only available in your home country. Exit node use requires explicit opt-in on every device, the device must advertise itself as an exit node, and an Owner/Admin/Network admin must allow it. To permit exit-node use, a grant or ACL must have `dst` of **`autogroup:internet`** -- adding the exit node device itself as the destination only permits connections *to* it (such as SSH), not using it as an internet gateway. **App connectors** work "like a subnet router with the added benefit of routing your users and devices to applications by domain names instead of IP addresses." They target internally hosted resources, cloud/VPC infrastructure, and SaaS apps (Amplitude, Confluence, GitHub, Looker, Office 365, Salesforce, Stripe) and managed platforms (Mongo Atlas, Amazon RDS, Planetscale). An app connector uses the PeerAPI to perform DNS discovery over DoH (DNS over HTTPS), resolves configured domains to IP addresses, and automatically advertises those as routes. The connector device must be Linux with a public IP and IP forwarding enabled. **Shared behavior.** All three are "connectors." When a connector's key expires, its advertised routes remain configured on other devices but become unreachable ("fail close" policy) -- Tailscale keeps them intentionally so removing them cannot leak traffic to untrusted networks. Mitigate by disabling key expiry on the connector or configuring high availability. Exit nodes capture all traffic "that isn't already directed to a subnet router or app connector," so the three compose. ## Recommendations - **Reach a private network / LAN / VPC** (office LAN, cloud VPC, printers, databases by IP) -> use a **subnet router**. - **Route all internet traffic** (privacy on untrusted Wi-Fi, geo-access, compliance requiring a VPN) -> use an **exit node**, and grant `autogroup:internet`. - **Reach specific apps addressed by domain**, especially SaaS with IP allowlisting -> use an **app connector**, which gives reliable domain-based routing and centralized per-app access management. - For any connector role in production, **disable key expiry or set up high availability** to avoid fail-close outages. ## Pages Compared - [[concepts/subnet-routers]] - [[concepts/exit-nodes]] - [[concepts/app-connectors]] - [[concepts/access-controls]] - [[syntheses/tailscale-vs-vpn]] --- title: "Tailscale vs. a traditional VPN" type: synthesis tags: [vpn, comparison, mesh, wireguard, coexistence] created: 2026-07-07 updated: 2026-07-07 sources: ["raw/docs_page-vpn-replacement-tailscale-docs.md", "raw/docs_page-can-i-use-tailscale-alongside-other-vpns-tailscale-docs.md"] confidence: high --- ## Comparison | Dimension | Traditional corporate VPN | Tailscale | | --- | --- | --- | | Topology | Hub-and-spoke through a central VPN concentrator | Mesh -- direct peer-to-peer connections between devices ([[concepts/how-tailscale-works]]) | | Transport | Varies by product | WireGuard data plane, end-to-end encrypted | | Traffic captured (default) | Typically all traffic routed through the concentrator | Only a small subset -- traffic to Tailscale IP addresses; the rest of your internet traffic is left alone | | Setup | Legacy VPN infrastructure, manual provisioning | Zero-config; simplified provisioning and granular access control | | Access model | Network-level tunnel | Per-device, identity-based, deny-by-default ([[concepts/access-controls]]) | | Firewall rules | Often aggressive ("all traffic through me") | None required by default; NAT traversal "just works" | ## Analysis **As a replacement.** Tailscale "replaces traditional corporate VPNs with a modern, zero-config networking solution." Employees get fast, secure access to internal apps and resources without legacy VPN complexity, while IT benefits from simplified provisioning and granular access control. Popular replacement workflows include secure remote access to internal corporate applications and data, secure remote access for work-from-home or remote employees, and automating employee onboarding/offboarding with SCIM. **As a coexisting overlay.** It is "theoretically possible" to run Tailscale alongside other VPNs because, by default, Tailscale only routes a small subset of your traffic (using Tailscale IP addresses). However, "in most cases, you can't use Tailscale alongside other VPNs without a workaround," usually due to: - **Aggressive firewall rules** -- most VPNs force all traffic through themselves and drop Tailscale traffic that only Tailscale knows how to route. - **Device limitations** -- iOS and Android enforce a limit of only one active VPN at a time. - **IP address conflicts** -- if the other VPN uses the Carrier-Grade NAT (CGNAT) range (`100.64.0.0` through `100.127.255.255`) that Tailscale uses, it conflicts with `100.x.y.z` Tailscale IP addresses. **Workarounds** (consider Mullvad exit nodes (beta) first): - **Userspace networking mode** -- instead of the default kernel mode (which creates a network interface, changes firewall rules, and assigns a Tailscale IP), Tailscale exposes a SOCKS5 proxy and proxies incoming connections to the same port on localhost (`127.0.0.1`). Note: the standard `ping` command does not work for tailnet destinations in userspace mode; use `tailscale ping` instead. - **Split tunnels** -- a DNS configuration that resolves queries differently by destination. If the other VPN supports split-tunnel DNS, add the Tailscale IP subnets `100.64.0.0/10` and `fd7a:115c:a1e0::/48` (and any [[concepts/subnet-routers|subnet routes]] you use). The split-tunnel workaround does **not** work for devices using [[concepts/exit-nodes|exit nodes]], because an exit node makes Tailscale behave like a traditional VPN, setting aggressive firewall rules to route all traffic through the exit node; exit nodes only support one VPN at a time. ## Recommendations - **Prefer Tailscale as a full replacement** for a hub-and-spoke VPN concentrator when you want zero-config mesh connectivity, per-device identity-based access, and simplified onboarding/offboarding. - **Keep Tailscale as an overlay alongside another VPN** only when the other VPN avoids aggressive firewall rules and does not use the CGNAT range; otherwise apply userspace networking or split tunnels. - **When using exit nodes**, treat Tailscale as your single VPN -- do not expect another VPN or split tunneling to coexist. - On iOS/Android, remember only one VPN can be active at a time -- coexistence is not possible there. ## Pages Compared - [[concepts/how-tailscale-works]] - [[concepts/subnet-routers]] - [[concepts/exit-nodes]] - [[concepts/access-controls]] - [[concepts/security-model]] - [[syntheses/routing-mechanisms-compared]]