tsnet

Documentation

Overview

Package tsnet provides Tailscale as a library.

It is an experimental work in progress.

Index

• type FunnelOption
  • func FunnelOnly() FunnelOption
• type Server
  • func (s *Server) APIClient() (*tailscale.Client, error)
  • func (s *Server) CertDomains() []string
  • func (s *Server) Close() error
  • func (s *Server) Dial(ctx context.Context, network, address string) (net.Conn, error)
  • func (s *Server) HTTPClient() *http.Client
  • func (s *Server) Listen(network, addr string) (net.Listener, error)
  • func (s *Server) ListenFunnel(network, addr string, opts ...FunnelOption) (net.Listener, error)
  • func (s *Server) ListenTLS(network, addr string) (net.Listener, error)
  • func (s *Server) LocalClient() (*tailscale.LocalClient, error)
  • func (s *Server) Loopback() (addr string, proxyCred, localAPICred string, err error)
  • func (s *Server) ReplaceGlobalLoggers() (undo func())
  • func (s *Server) Start() error
  • func (s *Server) TailscaleIPs() (ip4, ip6 netip.Addr)
  • func (s *Server) Up(ctx context.Context) (*ipnstate.Status, error)

Types

type FunnelOption

type FunnelOption interface {
	// contains filtered or unexported methods
}

FunnelOption is an option passed to ListenFunnel to configure the listener.

func FunnelOnly

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.

type Server

type Server struct {
	// Dir specifies the name of the directory to use for
	// state. If empty, a directory is selected automatically
	// under os.UserConfigDir (https://golang.org/pkg/os/#UserConfigDir).
	// based on the name of the binary.
	Dir string

	// Store specifies the state store to use.
	//
	// If nil, a new FileStore is initialized at `Dir/tailscaled.state`.
	// See tailscale.com/ipn/store for supported stores.
	//
	// Logs will automatically be uploaded to uploaded to log.tailscale.io,
	// where the configuration file for logging will be saved at
	// `Dir/tailscaled.log.conf`.
	Store ipn.StateStore

	// Hostname is the hostname to present to the control server.
	// If empty, the binary name is used.
	Hostname string

	// Logf, if non-nil, specifies the logger to use. By default,
	// log.Printf is used.
	Logf logger.Logf

	// Ephemeral, if true, specifies that the instance should register
	// as an Ephemeral node (https://tailscale.com/s/ephemeral-nodes).
	Ephemeral bool

	// AuthKey, if non-empty, is the auth key to create the node
	// and will be preferred over the TS_AUTHKEY environment
	// variable. If the node is already created (from state
	// previously stored in in Store), then this field is not
	// used.
	AuthKey string

	// ControlURL optionally specifies the coordination server URL.
	// If empty, the Tailscale default is used.
	ControlURL string
	// contains filtered or unexported fields
}

Server is an embedded Tailscale server.

Its exported fields may be changed until the first call to Listen.

func (*Server) APIClient

func (s *Server) APIClient() (*tailscale.Client, error)

APIClient returns a tailscale.Client that can be used to make authenticated requests to the Tailscale control server. It requires the user to set tailscale.I_Acknowledge_This_API_Is_Unstable.

func (*Server) CertDomains

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.

func (*Server) Close

func (s *Server) Close() error

Close stops the server.

It must not be called before or concurrently with Start.

func (*Server) Dial

func (s *Server) Dial(ctx context.Context, network, address string) (net.Conn, error)

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

func (*Server) HTTPClient

func (s *Server) HTTPClient() *http.Client

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.

func (*Server) Listen

func (s *Server) Listen(network, addr string) (net.Listener, error)

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

func (*Server) ListenFunnel

func (s *Server) ListenFunnel(network, addr string, opts ...FunnelOption) (net.Listener, error)

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.

func (*Server) ListenTLS

func (s *Server) ListenTLS(network, addr string) (net.Listener, error)

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.

func (*Server) LocalClient

func (s *Server) LocalClient() (*tailscale.LocalClient, error)

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.

func (*Server) Loopback

func (s *Server) Loopback() (addr string, proxyCred, localAPICred string, err error)

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) ReplaceGlobalLoggers

func (s *Server) ReplaceGlobalLoggers() (undo func())

ReplaceGlobalLoggers will replace any Tailscale-specific package-global loggers with this Server's logger. It returns a function that, when called, will undo any changes made.

Note that calling this function from multiple Servers will result in the last call taking all logs; logs are not duplicated.

func (*Server) Start

func (s *Server) Start() error

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

func (*Server) TailscaleIPs

func (s *Server) TailscaleIPs() (ip4, ip6 netip.Addr)

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().

func (*Server) Up

func (s *Server) Up(ctx context.Context) (*ipnstate.Status, error)

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.