wgengine

Documentation

Index

• Variables
• type ByteCount
• type Engine
  • func NewFakeUserspaceEngine(logf logger.Logf, listenPort uint16) (Engine, error)
  • func NewUserspaceEngine(logf logger.Logf, tunname string, listenPort uint16) (Engine, error)
  • func NewUserspaceEngineAdvanced(conf EngineConfig) (Engine, error)
  • func NewWatchdog(e Engine) Engine
• type EngineConfig
• type NetInfoCallback
• type PeerStatus
• type RouterGen
• type Status
• type StatusCallback

Variables

var ErrNoChanges = errors.New("no changes made to Engine config")

ErrNoChanges is returned by Engine.Reconfig if no changes were made.

Types

type ByteCount

type ByteCount int64

ByteCount is the number of bytes that have been sent or received.

TODO: why is this a type? remove? TODO: document whether it's payload bytes only or if it includes framing overhead.

type Engine

type Engine interface {
	// Reconfig reconfigures WireGuard and makes sure it's running.
	// This also handles setting up any kernel routes.
	//
	// This is called whenever tailcontrol (the control plane)
	// sends an updated network map.
	//
	// The returned error is ErrNoChanges if no changes were made.
	Reconfig(*wgcfg.Config, *router.Config) error

	// GetFilter returns the current packet filter, if any.
	GetFilter() *filter.Filter

	// SetFilter updates the packet filter.
	SetFilter(*filter.Filter)

	// SetDNSMap updates the DNS map.
	SetDNSMap(*tsdns.Map)

	// SetStatusCallback sets the function to call when the
	// WireGuard status changes.
	SetStatusCallback(StatusCallback)

	// RequestStatus requests a WireGuard status update right
	// away, sent to the callback registered via SetStatusCallback.
	RequestStatus()

	// Close shuts down this wireguard instance, remove any routes
	// it added, etc. To bring it up again later, you'll need a
	// new Engine.
	Close()

	// Wait waits until the Engine's Close method is called or the
	// engine aborts with an error. You don't have to call this.
	// TODO: return an error?
	Wait()

	// LinkChange informs the engine that the system network
	// link has changed. The isExpensive parameter is set on links
	// where sending packets uses substantial power or money,
	// such as mobile data on a phone.
	//
	// LinkChange should be called whenever something changed with
	// the network, no matter how minor. The implementation should
	// look at the state of the network and decide whether the
	// change from before is interesting enough to warrant taking
	// action on.
	LinkChange(isExpensive bool)

	// SetDERPMap controls which (if any) DERP servers are used.
	// If nil, DERP is disabled. It starts disabled until a DERP map
	// is configured.
	SetDERPMap(*tailcfg.DERPMap)

	// SetNetworkMap informs the engine of the latest network map
	// from the server. The network map's DERPMap field should be
	// ignored as as it might be disabled; get it from SetDERPMap
	// instead.
	// The network map should only be read from.
	SetNetworkMap(*controlclient.NetworkMap)

	// SetNetInfoCallback sets the function to call when a
	// new NetInfo summary is available.
	SetNetInfoCallback(NetInfoCallback)

	// SetLinkChangeCallback sets the function to call when the
	// link state changes.
	// The provided function is run in a new goroutine once upon
	// initial call (if the engine has a known link state) and
	// upon any change.
	SetLinkChangeCallback(func(major bool, newState *interfaces.State))

	// DiscoPublicKey gets the public key used for path discovery
	// messages.
	DiscoPublicKey() tailcfg.DiscoKey

	// UpdateStatus populates the network state using the provided
	// status builder.
	UpdateStatus(*ipnstate.StatusBuilder)

	// Ping is a request to start a discovery ping with the peer handling
	// the given IP and then call cb with its ping latency & method.
	Ping(ip netaddr.IP, cb func(*ipnstate.PingResult))
}

Engine is the Tailscale WireGuard engine interface.

func NewFakeUserspaceEngine

func NewFakeUserspaceEngine(logf logger.Logf, listenPort uint16) (Engine, error)

func NewUserspaceEngine

func NewUserspaceEngine(logf logger.Logf, tunname string, listenPort uint16) (Engine, error)

NewUserspaceEngine creates the named tun device and returns a Tailscale Engine running on it.

func NewUserspaceEngineAdvanced

func NewUserspaceEngineAdvanced(conf EngineConfig) (Engine, error)

NewUserspaceEngineAdvanced is like NewUserspaceEngine but provides control over all config fields.

func NewWatchdog

func NewWatchdog(e Engine) Engine

NewWatchdog wraps an Engine and makes sure that all methods complete within a reasonable amount of time.

If they do not, the watchdog crashes the process.

type EngineConfig

type EngineConfig struct {
	// Logf is the logging function used by the engine.
	Logf logger.Logf
	// TUN is the tun device used by the engine.
	TUN tun.Device
	// RouterGen is the function used to instantiate the router.
	RouterGen RouterGen
	// ListenPort is the port on which the engine will listen.
	ListenPort uint16
	// Fake determines whether this engine is running in fake mode,
	// which disables such features as DNS configuration and unrestricted ICMP Echo responses.
	Fake bool
}

type NetInfoCallback

type NetInfoCallback func(*tailcfg.NetInfo)

NetInfoCallback is the type used by Engine.SetNetInfoCallback.

type PeerStatus

type PeerStatus struct {
	TxBytes, RxBytes ByteCount
	LastHandshake    time.Time
	NodeKey          tailcfg.NodeKey
}

type RouterGen

type RouterGen func(logf logger.Logf, wgdev *device.Device, tundev tun.Device) (router.Router, error)

RouterGen is the signature for a function that creates a router.Router.

type Status

type Status struct {
	Peers      []PeerStatus
	LocalAddrs []string // TODO(crawshaw): []wgcfg.Endpoint?
	DERPs      int      // number of active DERP connections
}

Status is the Engine status.

TODO(bradfitz): remove this, subset of ipnstate? Need to migrate users.

type StatusCallback

type StatusCallback func(*Status, error)

StatusCallback is the type of status callbacks used by Engine.SetStatusCallback.

Exactly one of Status or error is non-nil.