Tailscale

This document guides you through the different authentication and configuration options for Tailscale with TSDProxy. For a quick comparison of authentication methods, see Authentication Methods.

Authentication Methods

TSDProxy supports three authentication methods with Tailscale: OAuth, OAuth (manual), and AuthKey.

OAuth

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:example" # Optional if tags are defined in each proxy

OAuth (Manual)

tailscale:
  providers:
    default:
      authKey: ""
      authKeyFile: ""

AuthKey

tailscale:
  providers:
    default:
      authKey: "YOUR_GENERATED_KEY_HERE"
      authKeyFile: ""

Funnel

In addition to configuring TSDProxy to enable Funnel, you need to grant permissions in the Tailscale ACL. See Troubleshooting for more details. Also read Tailscale’s Funnel documentation for requirements and limitations.

Tags

• Tags are required for OAuth authentication.
• Tags only work with OAuth authentication.
• Tags can be configured in the provider or service.
• If tags are defined in the provider, they apply to all services.
• If tags are defined in the service, provider tags are ignored.

Prevent Duplicate Machines

When TSDProxy restarts and the data directory has been lost (e.g. non-persistent Docker volume), Tailscale creates a new machine instead of reconnecting the existing one. This results in duplicate machines in your tailnet, often with a -1 suffix.

The preventDuplicates option (default: false) tells TSDProxy to query the Tailscale API before creating a new node. If an existing device with the same hostname and matching tags is found and is offline, it is deleted first so the new node can take its place.

A boolean option:

Requirements

• OAuth authentication (clientId + clientSecret) — the Tailscale API is not available with auth keys alone.
• Tags must be configured on the provider.

Configuration

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:example"
      preventDuplicates: true

Safety checks

A device is only deleted when all of these conditions are true:

• It has the same hostname as the proxy being created
• It has matching tags
• It is currently offline (ConnectedToControl is false)
• The local tsnet state file is missing (no existing identity to reuse)

Online devices are never deleted.

Certificate Concurrency

When many ephemeral containers restart at once, TSDProxy requests TLS certificates for all of them simultaneously. The Tailscale local API cannot handle this thundering herd, resulting in context deadline exceeded errors and failed certificate generation.

The maxCertConcurrency option (default: 2) limits how many certificate generation requests run in parallel. Requests that exceed the limit wait for a slot and are logged at warn level if delayed by more than one second.

tailscale:
  providers:
    default:
      maxCertConcurrency: 3 # allow up to 3 parallel cert requests

Identity Headers

TSDProxy resolves the Tailscale identity of each incoming request and forwards it to your backend services via HTTP headers. All identity headers are stripped from the incoming request before being set, preventing header injection attacks.

Unauthenticated requests (e.g. via Funnel) will not receive identity headers.

TSDProxy Headers

Standard Auth Headers

These headers are recognized by common reverse-proxy-aware backends (Authelia, OAuth2 Proxy, Traefik, FileBrowser, etc.):

Standard Proxy Headers

Usage Example: FileBrowser

FileBrowser supports proxy authentication out of the box. Configure it to read the X-Forwarded-User header set by TSDProxy:

filebrowser --auth.method=proxy --auth.header=X-Forwarded-User

Users will be automatically logged in with their Tailscale login name.

Shared Tailscale

By default, each proxy gets its own Tailscale connection (tsnet.Server). When you enable shared mode, multiple proxies share a single Tailscale connection, which is useful when you want to conserve Tailscale machine quota or centralize DNS and TLS management.

How it works

• All shared proxies use one tsnet.Server with SNI (Server Name Indication) routing

• Incoming TLS connections are dispatched by domain name to the correct proxy

• Each proxy must have a custom domain set (tsdproxy.domain label or domain in list config) because SNI routing depends on unique domain names

• Only HTTPS ports are supported in shared mode — TCP and plain HTTP ports cannot be multiplexed by SNI and will be rejected at startup

  Note

  SNI routing inspects the TLS ClientHello to determine which domain the client is connecting to. Without TLS, there is no SNI to inspect, so multiple proxies cannot share a single listener on the same port. HTTP redirects (80/http->...) are also excluded because they would conflict when multiple proxies try to bind port 80 on the shared server. If you need TCP or redirect ports alongside shared mode, use a per-proxy Tailscale provider for those containers instead.

• The shared server starts when the first proxy is created and stops when the last proxy is removed

Configuration

defaultProxyProvider: shared

dnsProviders:
  cloudflare:
    provider: cloudflare
    apiToken: "your-cloudflare-api-token"

tlsProviders:
  acme:
    provider: acme
    email: "admin@example.com"

defaultDNSProvider: cloudflare
defaultTLSProvider: acme

tailscale:
  providers:
    shared:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:shared-proxy"
      shared: true
      hostname: "shared-proxy"
  dataDir: /data/

docker:
  local:
    host: unix:///var/run/docker.sock
    defaultProxyProvider: shared

Container labels for shared proxies:

services:
  app1:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app1"
      tsdproxy.domain: "app1.example.com"

  app2:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app2"
      tsdproxy.domain: "app2.example.com"

Requirements

When to use shared mode

• Fewer Tailscale machines in your tailnet
• All domains point to a single Tailscale hostname
• Centralized DNS and TLS management

Services Mode

Services mode uses the Tailscale VIP Services API to automatically assign FQDNs to each proxy. Unlike shared mode, no custom domains, external DNS, or TLS providers are needed — Tailscale handles everything.

How it works

• All services share one tsnet.Server (like shared mode)
• Each proxy is registered as a Tailscale VIP Service
• FQDNs are auto-assigned by Tailscale (e.g. myapp.tailnet-name.ts.net)
• No custom domain support — you cannot set tsdproxy.domain
• No UDP support — only HTTPS, HTTP, and TCP ports
• The shared server starts when the first service is created and stops when the last service is removed

Configuration

defaultProxyProvider: services

tailscale:
  providers:
    services:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:services-proxy"
      services: true
      hostname: "shared-services"
      autoApproveDevices: true
  dataDir: /data/

docker:
  local:
    host: unix:///var/run/docker.sock
    defaultProxyProvider: services

Container labels for services mode proxies:

services:
  app1:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app1"

  app2:
    image: nginx:alpine
    labels:
      tsdproxy.enable: "true"
      tsdproxy.name: "app2"

Requirements

Constraints

• No custom domains — FQDNs are auto-assigned by Tailscale from the tailnet name
• No UDP — VIP Services do not support UDP traffic
• HTTPS, HTTP, and TCP only — all other protocols are rejected at startup
• Mutually exclusive with shared — a provider cannot use both shared: true and services: true

Auto-remove conflicting devices

When switching from per-proxy or shared mode to services mode, existing Tailscale devices may share hostnames with the VIP services being created. This causes the Tailscale API to return a 409 "name is in use but is not a service" error, preventing the proxy from starting.

The autoRemoveConflicts option (default: false) enables automatic removal of conflicting devices when this error is encountered. After removing the device, TSDProxy retries the VIP service creation.

tailscale:
  providers:
    default:
      clientId: "your_client_id"
      clientSecret: "your_client_secret"
      tags: "tag:example"
      services: true
      hostname: "shared-services"
      autoRemoveConflicts: true

When to use services mode

• You want fewer Tailscale machines without managing external DNS
• Auto-assigned .ts.net FQDNs are acceptable for your use case
• You don’t need UDP or custom domains

Proxy Provider Resolution

1. Per-proxy label (tsdproxy.proxyprovider)
2. Target provider default (defaultProxyProvider)
3. Global default (top-level defaultProxyProvider)
4. First available provider

Proxy Lifecycle