caddy-tailscale

Tailscale logs are emitted using a dedicated Caddy logger named tailscale. You can customize the logging level or output using the standard Caddy log global option.

{
  log tailscale {
    level DEBUG
  }
}

To use the Tailscale plugin, you must build a custom Caddy binary that includes it. The recommended way is using xcaddy.

Alternatively, you can build the included cmd/caddy package directly using go build.

# Using xcaddy (Recommended)
xcaddy build v2.9.1 --with github.com/tailscale/caddy-tailscale

# Using go build
go build ./cmd/caddy

The Tailscale network listener allows Caddy to serve sites directly on your tailnet. Use the bind directive within a site block to specify a Tailscale network address.

• Use tailscale/ (with a trailing slash) to use the default node configuration.
• Use tailscale/<node_name> to use a specific named node configuration.
• You can bind to multiple addresses (e.g., Tailscale and localhost) in a single site block.

# Bind to the default Tailscale node
:80 {
  bind tailscale/
}

# Bind to a specific named node
:80 {
  bind tailscale/myapp
}

# Bind to multiple interfaces
:80 {
  bind tailscale/myhost tailscale/my-other-host localhost
}

Caddy can use Tailscale's HTTPS support to automatically issue certificates for your node's hostname.

1. If using the full ts.net hostname: No extra configuration is needed.
2. If using a partial hostname: You must explicitly specify the tailscale certificate manager in the tls block.

# Option 1: Full hostname (Automatic)
https://myhost.tail1234.ts.net {
  bind tailscale/myhost
}

# Option 2: Partial hostname (Requires explicit cert manager)
:443 {
  bind tailscale/myhost
  tls {
    get_certificate tailscale
  }
}

You can use a pre-built Docker image containing the plugin, or build your own using the provided Dockerfile.

When running via Docker, it is recommended to:

1. Provide a TS_AUTHKEY environment variable.
2. Mount a volume to /config to persist the Tailscale state directory so nodes aren't re-registered on every restart.
3. Mount a custom Caddyfile to /etc/caddy/Caddyfile.

docker run -it --rm \
  -e TS_AUTHKEY="tskey-auth-XXX" \
  -v ./custom.caddyfile:/etc/caddy/Caddyfile -v ./config:config \
  ghcr.io/tailscale/caddy-tailscale

Use the tailscale global option in your Caddyfile to define how Tailscale nodes are registered and managed. You can define global settings or specific named node configurations that override the globals.

Note: Nodes are only registered and connected to your tailnet when they are actually used (e.g., via a bind directive).

{
  tailscale {
    # Global settings
    auth_key <auth_key>
    ephemeral true
    state_dir /var/lib/tailscale

    # Named node override
    my-app {
      auth_key <different-key>
      hostname custom-host
      tags tag:production
    }
  }
}

The Tailscale plugin provides a global tailscale directive for Caddyfiles to configure the App and its Nodes.

Basic syntax:

tailscale {
    auth_key <key>
    ephemeral
    tags <tag1> <tag2>

    node-name {
        auth_key <key>
        hostname <name>
    }
}

Note: For ephemeral and webui, providing the keyword without a value (e.g., just ephemeral) defaults the value to true during parsing.

tailscale {
    auth_key tskey-auth-123
    state_dir /var/lib/tailscale

    web-server-node {
        hostname caddy-node
        port 443
        tags tag:production
    }
}

The Transport module is a Caddy HTTP reverse proxy transport that routes requests through a Tailscale node. It allows Caddy to proxy traffic to services running on your Tailnet.

To use it, configure a reverse_proxy block in your Caddyfile and specify the tailscale transport followed by the name of the node you wish to use.

If no node name is provided, it defaults to caddy-proxy.

reverse_proxy {
  transport tailscale my-node
}

You can pass Tailscale identity information to upstream applications (like Gitea or Grafana) by mapping the tailscale_auth user fields to HTTP headers using header_up within a reverse_proxy block. This is useful for applications that support proxy authentication.

:80 {
  bind tailscale/gitea
  tailscale_auth
  reverse_proxy http://localhost:3000 {
    header_up X-Webauth-User {http.auth.user.tailscale_login}
    header_up X-Webauth-Email {http.auth.user.tailscale_user}
    header_up X-Webauth-Name {http.auth.user.tailscale_name}
  }
}

The tailscale proxy transport allows Caddy to use a Tailscale node to connect to an upstream reverse proxy. This enables proxying non-Tailscale traffic to a node on your tailnet (similar to Tailscale Funnel).

In the reverse_proxy directive, you can specify a named node configuration. If no name is provided, the default caddy-proxy node is used. Note that the node name is separated by a space (not a slash) in the transport configuration.

:8080 {
  reverse_proxy http://my-other-node:10000 {
    transport tailscale myhost
  }
}