tsnsrv

To avoid the 3-month rotation requirement of standard Tailscale Auth keys, use Tailscale OAuth clients. This is recommended for automated or long-running tsnsrv deployments.

Requirements:

1. An OAuth client minted with auth_key permissions.
2. The client must specify the exact tags you intend to use.
3. You must pass those same tags to tsnsrv using the -tag flag.

Usage: Use the OAuth client secret as the Tailscale auth key when running tsnsrv.

When using -funnel, you can restrict external access to only specific URL paths using the -prefix flag. Any request to a path not matching a provided -prefix will return a 404.

By default, tsnsrv strips the matched prefix before forwarding the request to the upstream service. To keep the prefix intact in the request sent to the upstream, use the -stripPrefix=false flag.

# Example: Exposing only Matrix webhooks to the internet
tsnsrv -name happy-computer-webhook -funnel -stripPrefix=false -prefix /_matrix -prefix /_synapse/client http://127.0.0.1:8000

If you encounter bugs in Tailscale or the tsnet library, you can generate a report directly from your tsnsrv instance.

1. Start tsnsrv with the -enableBugReports flag.
2. Send a POST request to the /bugreport endpoint on your Prometheus API port (default is 9099).
3. The response will contain a bug report ID, which is also logged at the INFO level in tsnsrv.

# Replace placeholders with your actual service name, tailnet name, and prometheus port
curl -X POST http://your-tsnsrv-instance-name.your-tailnet.ts.net:9099/bugreport

To expose a local service (e.g., running on 127.0.0.1:8000) to your tailnet, use the tsnsrv command with the -name flag to specify the service name. This makes the service reachable via its tailnet DNS name but restricts access to members of your tailnet.

Example: Exposing a service named happy-computer running on port 8000.

tsnsrv -name happy-computer http://127.0.0.1:8000

To make a local service accessible to the public internet via Tailscale Funnel, include the -funnel flag in your command. This exposes the service on both your tailnet and the public internet.

tsnsrv -name happy-computer -funnel http://127.0.0.1:8000

You can restrict which URL paths are allowed through the proxy using the -prefix flag. You can also specify whether a prefix is only valid for specific entry points using provenance prefixes:

• tailnet:/api: The path /api is only allowed when accessing via the Tailscale tailnet.
• funnel:/public: The path /public is only allowed when accessing via Tailscale Funnel.
• /api: The path /api is allowed on both the tailnet and via Funnel.

Note: Using provenance-specific prefixes (tailnet: or funnel:) requires a local Tailscale client to be available.

# Example CLI usage
tsnsrv -name my-service -prefix tailnet:/admin -prefix funnel:/public https://upstream.com

The following flags are used to configure the reverse proxy behavior and access control.

-name <name>          The name of the service on the tailnet
-funnel               Enable Tailscale Funnel to expose the service to the internet
-prefix <path>         Add a path to the list of URLs that external clients can see (Anything outside that list returns a 404)
-stripPrefix <bool>    Whether to leave the matched prefix intact (default is true, which strips it)
-suppressWhois        If set, tsnsrv will not look up and attach requestor information headers
-tag <tags>            Specify exact tags for the service (required when using OAuth clients)
-enableBugReports     Enables the ability to submit bug reports to Tailscale

The matchPrefixes function acts as a middleware to restrict which URL paths are allowed to be proxied. It behaves similarly to http.StripPrefix but supports multiple allowed prefixes.

• If the prefixes list is empty, all paths are allowed.
• If a path matches one of the provided prefixes, the request is passed to the handler.
• If strip is true, the matched prefix is stripped from the request URL before reaching the handler.
• If no prefix matches, the middleware returns an http.NotFound (404) response.

The Run(ctx context.Context) method on a ValidTailnetSrv starts the proxy service. It handles:

1. Connecting to the Tailscale network via tsnet.
2. Setting up the upstream dialer (TCP, Unix, or Tailnet-aware).
3. Starting the HTTP server(s) for the tailnet and/or the Funnel.
4. Initializing the Prometheus metrics endpoint if configured.

If the service is configured with -funnelOnly, Run will block until the funnel server exits.

err := validSrv.Run(ctx)