type FunnelOption interface {
}

func FunnelOnly() FunnelOption

FunnelOnly configures the listener to only respond to connections from Tailscale Funnel. The local tailnet will not be able to connect to the listener.

FunnelTLSConfig configures the TLS configuration for Server.ListenFunnel

This is rarely needed but can permit requiring client certificates, specific ciphers suites, etc.

The provided conf should at least be able to get a certificate, setting GetCertificate, Certificates or GetConfigForClient appropriately. The most common configuration is to set GetCertificate to Server.LocalClient's GetCertificate method.

Unless FunnelOnly is also used, the configuration is also used for in-tailnet connections that don't arrive over Funnel.

ExampleServer shows you how to construct a ready-to-use tsnet instance.

package main
import (
	"log"
	"tailscale.com/tsnet"
)
func main() {
	srv := new(tsnet.Server)
	if err := srv.Start(); err != nil {
		log.Fatalf("can't start tsnet server: %v", err)
	}
	defer srv.Close()
}

ExampleServer_dir shows you how to configure the persistent directory for a tsnet application. This is where the Tailscale node information is stored so that your application can reconnect to your tailnet when the application is restarted.

By default, tsnet will store data in your user configuration directory based on the name of the binary. Note that this folder must already exist or tsnet calls will fail.

package main
import (
	"log"
	"os"
	"path/filepath"
	"tailscale.com/tsnet"
)
func main() {
	dir := filepath.Join("/data", "tsnet")
	if err := os.MkdirAll(dir, 0700); err != nil {
		log.Fatal(err)
	}
	srv := &tsnet.Server{
		Dir: dir,
	}
	// do something with srv
	_ = srv
}

ExampleServer_hostname shows you how to set a tsnet server's hostname.

This setting lets you control the host name of your program on your tailnet. By default this will be the name of your program (such as foo for a program stored at /usr/local/bin/foo). You can also override this by setting the Hostname field.

package main
import (
	"tailscale.com/tsnet"
)
func main() {
	srv := &tsnet.Server{
		Hostname: "kirito",
	}
	// do something with srv
	_ = srv
}

ExampleServer_ignoreLogsSometimes shows you how to ignore all of the log messages written by a tsnet instance, but allows you to opt-into them if a command-line flag is set.

package main
import (
	"flag"
	"fmt"
	"log"
	"os"
	"tailscale.com/tsnet"
)
func main() {
	tsnetVerbose := flag.Bool("tsnet-verbose", false, "if set, verbosely log tsnet information")
	hostname := flag.String("tsnet-hostname", "hikari", "hostname to use on the tailnet")
	srv := &tsnet.Server{
		Hostname: *hostname,
	}
	if *tsnetVerbose {
		srv.Logf = log.New(os.Stderr, fmt.Sprintf("[tsnet:%s] ", *hostname), log.LstdFlags).Printf
	}
}

ExampleServer_multipleInstances shows you how to configure multiple instances of tsnet per program. This allows you to have multiple Tailscale nodes in the same process/container.

package main
import (
	"log"
	"os"
	"path/filepath"
	"tailscale.com/tsnet"
)
func main() {
	baseDir := "/data"
	var servers []*tsnet.Server
	for _, hostname := range []string{"ichika", "nino", "miku", "yotsuba", "itsuki"} {
		os.MkdirAll(filepath.Join(baseDir, hostname), 0700)
		srv := &tsnet.Server{
			Hostname:  hostname,
			AuthKey:   os.Getenv("TS_AUTHKEY"),
			Ephemeral: true,
			Dir:       filepath.Join(baseDir, hostname),
		}
		if err := srv.Start(); err != nil {
			log.Fatalf("can't start tsnet server: %v", err)
		}
		servers = append(servers, srv)
	}
	// When you're done, close the instances
	defer func() {
		for _, srv := range servers {
			srv.Close()
		}
	}()
}

CapturePcap can be called by the application code compiled with tsnet to save a pcap of packets which the netstack within tsnet sees. This is expected to be useful during debugging, probably not useful for production.

Packets will be written to the pcap until the process exits. The pcap needs a Lua dissector to be installed in Wireshark in order to decode properly: wgengine/capture/ts-dissector.lua in this repository. https://tailscale.com/docs/reference/troubleshooting/network-configuration/inspect-unencrypted-packets

func (*Server) CertDomains ¶ added in v1.38.0

func (s *Server) CertDomains() []string

CertDomains returns the list of domains for which the server can provide TLS certificates. These are also the DNS names for the Server. If the server is not running, it returns nil.

Close stops the server.

It must not be called before or concurrently with Start.

Dial connects to the address on the tailnet. It will start the server if it has not been started yet.

GetRootPath returns the root path of the tsnet server. This is where the state file and other data is stored.

HTTPClient returns an HTTP client that is configured to connect over Tailscale.

This is useful if you need to have your tsnet services connect to other devices on your tailnet.

package main
import (
	"log"
	"tailscale.com/tsnet"
)
func main() {
	srv := &tsnet.Server{}
	cli := srv.HTTPClient()
	resp, err := cli.Get("https://hello.ts.net")
	if resp == nil {
		log.Fatal(err)
	}
	// do something with resp
	_ = resp
}

Listen announces only on the Tailscale network. It will start the server if it has not been started yet.

Listeners which do not specify an IP address will match for traffic for the local node (that is, a destination address of the IPv4 or IPv6 address of this node) only. To listen for traffic on other addresses such as those routed inbound via subnet routes, explicitly specify the listening address or use RegisterFallbackTCPHandler.

package main
import (
	"fmt"
	"log"
	"net/http"
	"tailscale.com/tsnet"
)
func main() {
	srv := &tsnet.Server{
		Hostname: "tadaima",
	}
	ln, err := srv.Listen("tcp", ":80")
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "Hi there! Welcome to the tailnet!")
	})))
}

ListenFunnel announces on the public internet using Tailscale Funnel.

It also by default listens on your local tailnet, so connections can come from either inside or outside your network. To restrict connections to be just from the internet, use the FunnelOnly option.

Currently (2023-03-10), Funnel only supports TCP on ports 443, 8443, and 10000. The supported host name is limited to that configured for the tsnet.Server. As such, the standard way to create funnel is:

s.ListenFunnel("tcp", ":443")

and the only other supported addrs currently are ":8443" and ":10000".

It will start the server if it has not been started yet.

package main
import (
	"fmt"
	"log"
	"net/http"
	"tailscale.com/tsnet"
)
func main() {
	srv := &tsnet.Server{
		Hostname: "ophion",
	}
	ln, err := srv.ListenFunnel("tcp", ":443")
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "Hi there! Welcome to the tailnet!")
	})))
}

package main
import (
	"fmt"
	"log"
	"net/http"
	"tailscale.com/tsnet"
)
func main() {
	srv := new(tsnet.Server)
	srv.Hostname = "ophion"
	ln, err := srv.ListenFunnel("tcp", ":443", tsnet.FunnelOnly())
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "Hi there! Welcome to the tailnet!")
	})))
}

ListenPacket announces on the Tailscale network.

The network must be "udp", "udp4" or "udp6". The addr must be of the form "ip:port" (or "[ip]:port") where ip is a valid IPv4 or IPv6 address corresponding to "udp4" or "udp6" respectively. IP must be specified.

If s has not been started yet, it will be started.

ListenSSH listens on the Tailscale network for SSH connections at the given addr (e.g. ":2222"). The returned listener's Accept method yields net.Conn values that are actually *tailssh.Session, providing access to the connecting peer's Tailscale identity, PTY information, signals, and more.

Basic applications can use the returned connections as plain net.Conn (Read/Write/Close). Applications that need richer SSH semantics should type-assert to *tailssh.Session.

SSH support must be linked into the binary by importing _ "tailscale.com/feature/ssh". Without that import, ListenSSH returns an error.

If s has not been started yet, it will be started.

ListenService creates a network listener for a Tailscale Service. This will advertise this node as hosting the Service. Note that:

• Approval must still be granted by an admin or by ACL auto-approval rules.
• Service hosts must be tagged nodes.
• A valid Service host must advertise all ports defined for the Service.

To advertise a Service with multiple ports, run ListenService multiple times. For more information about Services, see https://tailscale.com/kb/1552/tailscale-services

This function will start the server if it is not already started.

package main
import (
	"fmt"
	"log"
	"net/http"
	"tailscale.com/tsnet"
)
func main() {
	srv := &tsnet.Server{
		Hostname: "atum",
	}
	ln, err := srv.ListenService("svc:my-service", tsnet.ServiceModeHTTP{
		HTTPS: true,
		Port:  443,
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("Listening on https://%v\n", ln.FQDN)
	log.Fatal(http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "<html><body><h1>Hello, tailnet!</h1>")
	})))
}

package main
import (
	"fmt"
	"log"
	"net/http"
	"strings"
	_ "net/http/pprof"
	"tailscale.com/tsnet"
)
func main() {
	srv := &tsnet.Server{
		Hostname: "shu",
	}
	ln, err := srv.ListenService("svc:my-service", tsnet.ServiceModeHTTP{
		HTTPS: true,
		Port:  443,
	})
	if err != nil {
		log.Fatal(err)
	}
	pprofLn, err := srv.ListenService("svc:my-service", tsnet.ServiceModeTCP{
		Port: 6060,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer pprofLn.Close()
	go func() {
		log.Printf("Listening for pprof requests on http://%v:%d\n", pprofLn.FQDN, 6060)
		handler := func(w http.ResponseWriter, r *http.Request) {
			// The pprof listener is separate from our main server, so we can
			// allow users to leave off the /debug/pprof prefix. We'll just
			// attach it here, then pass along to the pprof handlers, which have
			// been added implicitly due to our import of net/http/pprof.
			if !strings.HasPrefix("/debug/pprof", r.URL.Path) {
				r.URL.Path = "/debug/pprof" + r.URL.Path
			}
			http.DefaultServeMux.ServeHTTP(w, r)
		}
		if err := http.Serve(pprofLn, http.HandlerFunc(handler)); err != nil {
			log.Fatal("error serving pprof:", err)
		}
	}()
	log.Printf("Listening on https://%v\n", ln.FQDN)
	// Specifying a handler here means pprof endpoints will not be served by
	// this server (since we are not using http.DefaultServeMux).
	log.Fatal(http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "<html><body><h1>Hello, tailnet!</h1>")
	})))
}

package main
import (
	"log"
	"net/http"
	"net/http/httputil"
	"net/url"
	"tailscale.com/tsnet"
)
func main() {
	// targetAddress represents the address of the backing server.
	const targetAddress = "1.2.3.4:80"
	// We will use a reverse proxy to direct traffic to the backing server.
	reverseProxy := httputil.NewSingleHostReverseProxy(&url.URL{
		Scheme: "http",
		Host:   targetAddress,
	})
	srv := &tsnet.Server{
		Hostname: "tefnut",
	}
	ln, err := srv.ListenService("svc:my-service", tsnet.ServiceModeHTTP{
		HTTPS: true,
		Port:  443,
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("Listening on https://%v\n", ln.FQDN)
	log.Fatal(http.Serve(ln, reverseProxy))
}

ListenTLS announces only on the Tailscale network. It returns a TLS listener wrapping the tsnet listener. It will start the server if it has not been started yet.

package main
import (
	"fmt"
	"log"
	"net/http"
	"tailscale.com/tsnet"
)
func main() {
	srv := &tsnet.Server{
		Hostname: "aegis",
	}
	ln, err := srv.ListenTLS("tcp", ":443")
	if err != nil {
		log.Fatal(err)
	}
	log.Fatal(http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "Hi there! Welcome to the tailnet!")
	})))
}

LocalClient returns a LocalClient that speaks to s.

It will start the server if it has not been started yet. If the server's already been started successfully, it doesn't return an error.

LogtailWriter returns an io.Writer that writes to Tailscale's logging service and will be only visible to Tailscale's support team. Logs written there cannot be retrieved by the user. This method always returns a non-nil value.

Loopback starts a routing server on a loopback address.

The server has multiple functions.

It can be used as a SOCKS5 proxy onto the tailnet. Authentication is required with the username "tsnet" and the value of proxyCred used as the password.

The HTTP server also serves out the "LocalAPI" on /localapi. As the LocalAPI is powerful, access to endpoints requires BOTH passing a "Sec-Tailscale: localapi" HTTP header and passing localAPICred as basic auth.

If you only need to use the LocalAPI from Go, then prefer LocalClient as it does not require communication via TCP.

func (*Server) RegisterFallbackTCPHandler ¶ added in v1.52.0

func (s *Server) RegisterFallbackTCPHandler(cb FallbackTCPHandler) func()

RegisterFallbackTCPHandler registers a callback which will be called to handle a TCP flow to this tsnet node, for which no listeners will handle.

If multiple fallback handlers are registered, they will be called in an undefined order. See FallbackTCPHandler for details on handling a flow.

The returned function can be used to deregister this callback.

Start connects the server to the tailnet. Optional: any calls to Dial/Listen will also call Start.

package main
import (
	"log"
	"tailscale.com/tsnet"
)
func main() {
	srv := new(tsnet.Server)
	if err := srv.Start(); err != nil {
		log.Fatal(err)
	}
	// Be sure to close the server instance at some point. It will stay open until
	// either the OS process ends or the server is explicitly closed.
	defer srv.Close()
}

Sys returns a handle to the Tailscale subsystems of this node.

This is not a stable API, nor are the APIs of the returned subsystems.

TailscaleIPs returns IPv4 and IPv6 addresses for this node. If the node has not yet joined a tailnet or is otherwise unaware of its own IP addresses, the returned ip4, ip6 will be !netip.IsValid().

Up connects the server to the tailnet and waits until it is running. On success it returns the current status, including a Tailscale IP address.

Addr returns the listener's network address. This will be the Service's fully-qualified domain name (FQDN) and the port.

A hostname is not truly a network address, but Services listen on multiple addresses (the IPv4 and IPv6 virtual IPs).

Close closes the listener and clears state related to hosting the Service. Behavior is undefined after the Server has been closed.

type ServiceMode interface {
}

type ServiceModeTCP struct {


	Port uint16


	TerminateTLS bool


	PROXYProtocolVersion int
}