tailnet

Documentation

Index

• func CoordinatorHTTPDebug(agentSocketsMap map[uuid.UUID]*TrackedConn, ...) func(w http.ResponseWriter, _ *http.Request)
• func IP() netip.Addr
• func Logger(logger slog.Logger) tslogger.Logf
• func NewDERPMap(ctx context.Context, region *tailcfg.DERPRegion, stunAddrs []string, ...) (*tailcfg.DERPMap, error)
• func ServeCoordinator(conn net.Conn, updateNodes func(node []*Node) error) (func(node *Node), <-chan error)
• func WithWebsocketSupport(s *derp.Server, base http.Handler) (http.Handler, func())
• type Conn
  • func NewConn(options *Options) (conn *Conn, err error)
  • func (c *Conn) AwaitReachable(ctx context.Context, ip netip.Addr) bool
  • func (c *Conn) Close() error
  • func (c *Conn) Closed() <-chan struct{}
  • func (c *Conn) DERPMap() *tailcfg.DERPMap
  • func (c *Conn) DialContextTCP(ctx context.Context, ipp netip.AddrPort) (*gonet.TCPConn, error)
  • func (c *Conn) DialContextUDP(ctx context.Context, ipp netip.AddrPort) (*gonet.UDPConn, error)
  • func (c *Conn) Listen(network, addr string) (net.Listener, error)
  • func (c *Conn) Node() *Node
  • func (c *Conn) NodeAddresses(publicKey key.NodePublic) ([]netip.Prefix, bool)
  • func (c *Conn) Ping(ctx context.Context, ip netip.Addr) (time.Duration, bool, *ipnstate.PingResult, error)
  • func (c *Conn) RemoveAllPeers() error
  • func (c *Conn) SetConnStatsCallback(maxPeriod time.Duration, maxConns int, dump func(start, end time.Time, ...))
  • func (c *Conn) SetDERPMap(derpMap *tailcfg.DERPMap)
  • func (c *Conn) SetDERPRegionDialer(dialer func(ctx context.Context, region *tailcfg.DERPRegion) net.Conn)
  • func (c *Conn) SetForwardTCPCallback(callback func(conn net.Conn, listenerExists bool) net.Conn)
  • func (c *Conn) SetNodeCallback(callback func(node *Node))
  • func (c *Conn) Status() *ipnstate.Status
  • func (c *Conn) UpdateNodes(nodes []*Node, replacePeers bool) error
• type Coordinator
  • func NewCoordinator() Coordinator
• type Node
• type Options
• type TrackedConn
  • func (t *TrackedConn) Write(b []byte) (n int, err error)

Functions

func CoordinatorHTTPDebug

func CoordinatorHTTPDebug(
	agentSocketsMap map[uuid.UUID]*TrackedConn,
	agentToConnectionSocketsMap map[uuid.UUID]map[uuid.UUID]*TrackedConn,
	agentNameCache *lru.Cache[uuid.UUID, string],
) func(w http.ResponseWriter, _ *http.Request)

func IP

func IP() netip.Addr

IP generates a new IP with a static service prefix.

func Logger

func Logger(logger slog.Logger) tslogger.Logf

Logger converts the Tailscale logging function to use slog.

func NewDERPMap

func NewDERPMap(ctx context.Context, region *tailcfg.DERPRegion, stunAddrs []string, remoteURL, localPath string) (*tailcfg.DERPMap, error)

NewDERPMap constructs a DERPMap from a set of STUN addresses and optionally a remote URL to fetch a mapping from e.g. https://controlplane.tailscale.com/derpmap/default.

func ServeCoordinator

func ServeCoordinator(conn net.Conn, updateNodes func(node []*Node) error) (func(node *Node), <-chan error)

ServeCoordinator matches the RW structure of a coordinator to exchange node messages.

func WithWebsocketSupport

func WithWebsocketSupport(s *derp.Server, base http.Handler) (http.Handler, func())

WithWebsocketSupport returns an http.Handler that upgrades connections to the "derp" subprotocol to WebSockets and passes them to the DERP server. Taken from: https://github.com/tailscale/tailscale/blob/e3211ff88ba85435f70984cf67d9b353f3d650d8/cmd/derper/websocket.go#L21

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is an actively listening Wireguard connection.

func NewConn

func NewConn(options *Options) (conn *Conn, err error)

NewConn constructs a new Wireguard server that will accept connections from the addresses provided.

func (*Conn) AwaitReachable

func (c *Conn) AwaitReachable(ctx context.Context, ip netip.Addr) bool

AwaitReachable pings the provided IP continually until the address is reachable. It's the callers responsibility to provide a timeout, otherwise this function will block forever.

func (*Conn) Close

func (c *Conn) Close() error

Close shuts down the Wireguard connection.

func (*Conn) Closed

func (c *Conn) Closed() <-chan struct{}

Closed is a channel that ends when the connection has been closed.

func (*Conn) DERPMap

func (c *Conn) DERPMap() *tailcfg.DERPMap

DERPMap returns the currently set DERP mapping.

func (*Conn) DialContextTCP

func (c *Conn) DialContextTCP(ctx context.Context, ipp netip.AddrPort) (*gonet.TCPConn, error)

func (*Conn) DialContextUDP

func (c *Conn) DialContextUDP(ctx context.Context, ipp netip.AddrPort) (*gonet.UDPConn, error)

func (*Conn) Listen

func (c *Conn) 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 (*Conn) Node

func (c *Conn) Node() *Node

Node returns the last node that was sent to the node callback.

func (*Conn) NodeAddresses

func (c *Conn) NodeAddresses(publicKey key.NodePublic) ([]netip.Prefix, bool)

NodeAddresses returns the addresses of a node from the NetworkMap.

func (*Conn) Ping

func (c *Conn) Ping(ctx context.Context, ip netip.Addr) (time.Duration, bool, *ipnstate.PingResult, error)

Ping sends a Disco ping to the Wireguard engine. The bool returned is true if the ping was performed P2P.

func (*Conn) RemoveAllPeers

func (c *Conn) RemoveAllPeers() error

func (*Conn) SetConnStatsCallback

func (c *Conn) SetConnStatsCallback(maxPeriod time.Duration, maxConns int, dump func(start, end time.Time, virtual, physical map[netlogtype.Connection]netlogtype.Counts))

SetConnStatsCallback sets a callback to be called after maxPeriod or maxConns, whichever comes first. Multiple calls overwrites the callback.

func (*Conn) SetDERPMap

func (c *Conn) SetDERPMap(derpMap *tailcfg.DERPMap)

SetDERPMap updates the DERPMap of a connection.

func (*Conn) SetDERPRegionDialer

func (c *Conn) SetDERPRegionDialer(dialer func(ctx context.Context, region *tailcfg.DERPRegion) net.Conn)

SetDERPRegionDialer updates the dialer to use for connecting to DERP regions.

func (*Conn) SetForwardTCPCallback

func (c *Conn) SetForwardTCPCallback(callback func(conn net.Conn, listenerExists bool) net.Conn)

SetForwardTCPCallback is called every time a TCP connection is initiated inbound. listenerExists is true if a listener is registered for the target port. If there isn't one, traffic is forwarded to the local listening port.

This allows wrapping a Conn to track reads and writes.

func (*Conn) SetNodeCallback

func (c *Conn) SetNodeCallback(callback func(node *Node))

func (*Conn) Status

func (c *Conn) Status() *ipnstate.Status

Status returns the current ipnstate of a connection.

func (*Conn) UpdateNodes

func (c *Conn) UpdateNodes(nodes []*Node, replacePeers bool) error

UpdateNodes connects with a set of peers. This can be constantly updated, and peers will continually be reconnected as necessary. If replacePeers is true, all peers will be removed before adding the new ones.

type Coordinator

type Coordinator interface {
	// ServeHTTPDebug serves a debug webpage that shows the internal state of
	// the coordinator.
	ServeHTTPDebug(w http.ResponseWriter, r *http.Request)
	// Node returns an in-memory node by ID.
	Node(id uuid.UUID) *Node
	// ServeClient accepts a WebSocket connection that wants to connect to an agent
	// with the specified ID.
	ServeClient(conn net.Conn, id uuid.UUID, agent uuid.UUID) error
	// ServeAgent accepts a WebSocket connection to an agent that listens to
	// incoming connections and publishes node updates.
	// Name is just used for debug information. It can be left blank.
	ServeAgent(conn net.Conn, id uuid.UUID, name string) error
	// Close closes the coordinator.
	Close() error
}

Coordinator exchanges nodes with agents to establish connections. ┌──────────────────┐ ┌────────────────────┐ ┌───────────────────┐ ┌──────────────────┐ │tailnet.Coordinate├──►│tailnet.AcceptClient│◄─►│tailnet.AcceptAgent│◄──┤tailnet.Coordinate│ └──────────────────┘ └────────────────────┘ └───────────────────┘ └──────────────────┘ Coordinators have different guarantees for HA support.

func NewCoordinator

func NewCoordinator() Coordinator

NewCoordinator constructs a new in-memory connection coordinator. This coordinator is incompatible with multiple Coder replicas as all node data is in-memory.

type Node

type Node struct {
	// ID is used to identify the connection.
	ID tailcfg.NodeID `json:"id"`
	// AsOf is the time the node was created.
	AsOf time.Time `json:"as_of"`
	// Key is the Wireguard public key of the node.
	Key key.NodePublic `json:"key"`
	// DiscoKey is used for discovery messages over DERP to establish peer-to-peer connections.
	DiscoKey key.DiscoPublic `json:"disco"`
	// PreferredDERP is the DERP server that peered connections
	// should meet at to establish.
	PreferredDERP int `json:"preferred_derp"`
	// DERPLatency is the latency in seconds to each DERP server.
	DERPLatency map[string]float64 `json:"derp_latency"`
	// DERPForcedWebsocket contains a mapping of DERP regions to
	// error messages that caused the connection to be forced to
	// use WebSockets. We don't use WebSockets by default because
	// they are less performant.
	DERPForcedWebsocket map[int]string `json:"derp_forced_websockets"`
	// Addresses are the IP address ranges this connection exposes.
	Addresses []netip.Prefix `json:"addresses"`
	// AllowedIPs specify what addresses can dial the connection.
	// We allow all by default.
	AllowedIPs []netip.Prefix `json:"allowed_ips"`
	// Endpoints are ip:port combinations that can be used to establish
	// peer-to-peer connections.
	Endpoints []string `json:"endpoints"`
}

Node represents a node in the network.

type Options

type Options struct {
	Addresses  []netip.Prefix
	DERPMap    *tailcfg.DERPMap
	DERPHeader *http.Header

	// BlockEndpoints specifies whether P2P endpoints are blocked.
	// If so, only DERPs can establish connections.
	BlockEndpoints bool
	Logger         slog.Logger
}

type TrackedConn

type TrackedConn struct {
	net.Conn

	// ID is an ephemeral UUID used to uniquely identify the owner of the
	// connection.
	ID uuid.UUID

	Name       string
	Start      int64
	LastWrite  int64
	Overwrites int64
}

func (*TrackedConn) Write

func (t *TrackedConn) Write(b []byte) (n int, err error)