Skip to content
slopscale
Esc
↑↓navigate↵open⌘Jpreview
On this page

Apps

Route traffic for chosen domains through tagged app connector nodes: define apps, how learned and static routes and split DNS work, and manage them.

An app is a set of domains reached through app connectors, following Tailscale’s app connectors. Instead of routing all Internet traffic through an exit node or advertising broad subnets, an app connector lets devices on your tailnet reach specific applications and SaaS domains (such as example.com or *.example.com) through designated connector nodes in your network.

How it works

  1. Connector node. A machine runs the app connector service and advertises itself as a connector.
  2. App definition. An operator defines the app with its domains, static routes, and connector selectors.
  3. Route learning and approval. The connector resolves the app’s domains, advertises single-address host routes for the learned IPs, and the server approves them automatically.
  4. DNS. The server sends each machine the policy lets through a connector split DNS for the app’s domains that points at that connector, so queries reach it and it learns the addresses.

Setting up a connector node

A connector node must be a tagged machine because connectors act as shared network infrastructure; user-owned machines cannot serve as connectors.

On the machine, advertise the connector service:

tailscale set --advertise-connector

When registering a new node, pass --advertise-connector to tailscale up along with the node’s tags:

sudo tailscale up --login-server <YOUR_SLOPSCALE_URL> --auth-key <KEY> \
  --advertise-connector

The node reports to the server that it runs the app connector service. The server sends app definitions to matching connector nodes using the tailscale.com/app-connectors node capability.

Defining apps

An app has:

  • Name: 1 to 63 characters.
  • Description: an optional summary.
  • Domains: domain names or wildcard domains the connectors watch and resolve, such as example.com or *.example.com.
  • Connectors: node tag selectors (such as tag:connector) that specify which connector nodes serve the app, or * to select every tagged machine running the connector. If omitted, * is the default.
  • Routes: optional static CIDR prefixes (such as 198.51.100.0/24) that connectors always advertise. Full internet routes (0.0.0.0/0 and ::/0) are refused.

Learned and static routes

Connector nodes watch the app’s configured domains and resolve them. Whenever a connector learns an address for a domain, it advertises a host route (/32 for IPv4 or /128 for IPv6).

The server approves learned single-address routes automatically. If an app defines static routes, any prefix within those routes is also approved automatically for the app’s connectors. Any other advertised routes, such as broader subnets (10.0.0.0/16) or exit routes, are not covered by the app and require manual approval by an operator (or policy autoApprovers.routes).

When a domain leaves an app, or the app is deleted, the connector withdraws the routes it learned for it and the server drops their approvals with them, so the connector’s route list only holds what it advertises. Exit routes are left alone, and a plain subnet router keeps its approvals when it stops advertising a route, as before.

DNS

The server sends machines split DNS for the app’s domains, pointing at the connectors’ DNS endpoints over the tailnet, the way Tailscale’s control plane does. A query for example.com goes to a connector, and the connector answers it and learns the addresses in the answer. A connector is never sent its own apps. A wildcard domain (*.example.com) routes the base domain too. Nothing has to be configured under DNS; a split DNS rule for the same domain, if one exists, comes first.

A connector answers a peer’s query only when the policy lets that peer send traffic to the internet through it. That is the access the peer needs for the addresses the connector learns: a rule with the peer as the source and autogroup:internet, or the addresses themselves, as the destination. The connector refuses every other peer with a 403, and a machine whose only resolver for a name refuses it gets no answer at all.

So a machine gets the split DNS toward a connector only when that connector will answer it. The server reads this from the packet filter it sends the connector, which is where the connector’s client looks. Seeing a connector as a peer is not enough. A gateway that reaches a connector through a rule from one node to the other, with nothing through it, gets no split DNS for the app, and the app’s names go to its global nameservers like any other name. Among the connectors that answer a machine, online ones come first.

The client checks TCP port 53, so:

  • A rule to autogroup:internet limited to tcp:53 is enough for the app’s DNS. The machine then resolves the app’s names through the connector, and the connector drops the machine’s traffic on other ports.
  • A rule limited to udp:53, or to any other UDP port, is not enough.
  • A rule to the internet on another TCP port, tcp:443 for instance, is enough: the server adds the DNS rule to the connector’s filter for every source the policy lets reach a public address through it.

A machine with only an IPv6 tailnet address gets the split DNS toward a connector only when that connector is also an approved exit node. Over IPv6 the client checks an address that a connector on its own does not answer for.

Machines at the connector’s site

A machine that reaches the internet from the same public address as one of an app’s connectors skips that app. The app already sees the address it allows, so going through a connector would only add a hop. Say the connector sits in the office: a laptop in the office goes out directly, while the same laptop at home still goes through the office connector.

The server compares the public IPv4 address each client reports among its endpoints, the address its NAT shows the internet, so nothing has to be configured. When a machine or a connector moves, its peers get a new netmap. A machine that skips an app does not get these:

  • the split DNS for the app’s domains, toward any connector
  • the public prefixes inside the app’s static routes, from any connector
  • the host routes the connector behind its address learned

The app is skipped on every connector, not only the one behind the machine’s address. With a second connector abroad for failover, the office laptop resolves the app’s names itself and goes out from the office address, instead of sending them abroad. A connector at another site keeps its learned host routes in the laptop’s view, because they cannot be told apart from those of the other apps it serves; with the names resolved locally the laptop rarely meets them.

Private prefixes such as 10.0.0.0/8 in an app’s static routes stay routed through the connector, since sharing a public address says nothing about reaching a private network.

Connectors at several sites

An app can list connectors at several sites, for example tag:office-gateway and tag:eu-gateway. The client sends each DNS query for the app’s domains to every connector it can reach at once, so each connector learns the addresses and advertises them. Each machine then goes through the connector nearest it by the round trips it measured, and machines equally near several connectors are spread over them; see regional routing. A machine without measurements goes through the tailnet-wide primary.

Two things follow from routing by address:

  • A service that only lets in the address of one site, an office IP on an allowlist for instance, refuses machines steered to the other site. Keep such a service in an app whose connectors share that address.
  • Hosts behind a CDN often share addresses: every proxied hostname in one Cloudflare zone may resolve to the same two. A connector that learned them for one app routes every hostname on them, including hosts in no app. List the CDN’s hostnames in an app whose connectors suit all of them, or keep them out of apps.

Console and API

The admin console has an Apps page under Connectivity (Connectivity › Apps), listing configured apps, their domains, connector selectors, static routes, and the connector nodes assigned to each app with counts of learned and pending routes.

From the CLI:

slopscale apps list
slopscale apps show --id 1
slopscale apps create --name "Internal Tools" \
  --domain tools.corp.example.com --domain "*.tools.corp.example.com" \
  --connector tag:connector \
  --route 192.0.2.0/24
slopscale apps update --id 1 --route 198.51.100.0/24
slopscale apps delete --id 1

Through the API:

  • GET /api/v1/apps: list all apps (requires policy_file:read).
  • POST /api/v1/apps: create an app (requires policy_file).
  • GET /api/v1/app/{id}: retrieve an app (requires policy_file:read).
  • PUT /api/v1/app/{id}: update an app definition (requires policy_file).
  • DELETE /api/v1/app/{id}: delete an app (requires policy_file).

Creating, updating and deleting an app are audited as app.create, app.update and app.delete.

Last updated on

Was this page helpful?