tailscale.com – tailscale.com/net/netmon Index | Files

package netmon

import "tailscale.com/net/netmon"

Package monitor provides facilities for monitoring network interface and route changes. It primarily exists to know when portable devices move between different networks.

Index

Variables 

var LoginEndpointForProxyDetermination = "https://controlplane.tailscale.com/"

LoginEndpointForProxyDetermination is the URL used for testing which HTTP proxy the system should use.

Functions

func DefaultRouteInterface 

func DefaultRouteInterface() (string, error)

DefaultRouteInterface is like DefaultRoute but only returns the interface name.

func ForeachInterface 

func ForeachInterface(fn func(Interface, []netip.Prefix)) error

ForeachInterface is a wrapper for GetList, then List.ForeachInterface.

func ForeachInterfaceAddress 

func ForeachInterfaceAddress(fn func(Interface, netip.Prefix)) error

ForeachInterfaceAddress is a wrapper for GetList, then List.ForeachInterfaceAddress.

func HTTPOfListener 

func HTTPOfListener(ln net.Listener) string

HTTPOfListener returns the HTTP address to ln. If the listener is listening on the unspecified address, it it tries to find a reasonable interface address on the machine to use.

func InterfaceDebugExtras 

func InterfaceDebugExtras(ifIndex int) (string, error)

InterfaceDebugExtras returns extra debugging information about an interface if any (an empty string will be returned if there are no additional details). Formatting is platform-dependent and should not be parsed.

func LikelyHomeRouterIP 

func LikelyHomeRouterIP() (gateway, myIP netip.Addr, ok bool)

LikelyHomeRouterIP returns the likely IP of the residential router, which will always be an IPv4 private address, if found. In addition, it returns the IP address of the current machine on the LAN using that gateway. This is used as the destination for UPnP, NAT-PMP, PCP, etc queries.

func LinkChangeLogLimiter 

func LinkChangeLogLimiter(logf logger.Logf, nm *Monitor) (_ logger.Logf, unregister func())

LinkChangeLogLimiter returns a new logger.Logf that logs each unique format string to the underlying logger only once per major LinkChange event.

The returned function should be called when the logger is no longer needed, to release resources from the Monitor.

func LocalAddresses 

func LocalAddresses() (regular, loopback []netip.Addr, err error)

LocalAddresses returns the machine's IP addresses, separated by whether they're loopback addresses. If there are no regular addresses it will return any IPv4 linklocal or IPv6 unique local addresses because we know of environments where these are used with NAT to provide connectivity.

func RegisterInterfaceGetter 

func RegisterInterfaceGetter(getInterfaces func() ([]Interface, error))

RegisterInterfaceGetter sets the function that's used to query the system network interfaces.

Types

type ChangeDelta 

type ChangeDelta struct {
	// Monitor is the network monitor that sent this delta.
	Monitor *Monitor

	// Old is the old interface state, if known.
	// It's nil if the old state is unknown.
	// Do not mutate it.
	Old *State

	// New is the new network state.
	// It is always non-nil.
	// Do not mutate it.
	New *State

	// Major is our legacy boolean of whether the network changed in some major
	// way.
	//
	// Deprecated: do not remove. As of 2023-08-23 we're in a renewed effort to
	// remove it and ask specific qustions of ChangeDelta instead. Look at Old
	// and New (or add methods to ChangeDelta) instead of using Major.
	Major bool

	// TimeJumped is whether there was a big jump in wall time since the last
	// time we checked. This is a hint that a mobile sleeping device might have
	// come out of sleep.
	TimeJumped bool
}

ChangeDelta describes the difference between two network states.

type ChangeFunc 

type ChangeFunc func(*ChangeDelta)

ChangeFunc is a callback function registered with Monitor that's called when the network changed.

type DefaultRouteDetails 

type DefaultRouteDetails struct {
	// InterfaceName is the interface name. It must always be populated.
	// It's like "eth0" (Linux), "Ethernet 2" (Windows), "en0" (macOS).
	InterfaceName string

	// InterfaceDesc is populated on Windows at least. It's a
	// longer description, like "Red Hat VirtIO Ethernet Adapter".
	InterfaceDesc string

	// InterfaceIndex is like net.Interface.Index.
	// Zero means not populated.
	InterfaceIndex int
}

DefaultRouteDetails are the details about a default route returned by DefaultRoute.

func DefaultRoute 

func DefaultRoute() (DefaultRouteDetails, error)

DefaultRoute returns details of the network interface that owns the default route, not including any tailscale interfaces.

type Interface 

type Interface struct {
	*net.Interface
	AltAddrs []net.Addr // if non-nil, returned by Addrs
	Desc     string     // extra description (used on Windows)
}

Interface is a wrapper around Go's net.Interface with some extra methods.

func (Interface) Addrs 

func (i Interface) Addrs() ([]net.Addr, error)

func (Interface) Equal 

func (a Interface) Equal(b Interface) bool

func (Interface) IsLoopback 

func (i Interface) IsLoopback() bool

func (Interface) IsUp 

func (i Interface) IsUp() bool

type InterfaceList 

type InterfaceList []Interface

InterfaceList is a list of interfaces on the machine.

func GetInterfaceList 

func GetInterfaceList() (InterfaceList, error)

GetInterfaceList returns the list of interfaces on the machine.

func (InterfaceList) ForeachInterface 

func (ifaces InterfaceList) ForeachInterface(fn func(Interface, []netip.Prefix)) error

ForeachInterface calls fn for each interface in ifaces, with all its addresses. The IPPrefix's IP is the IP address assigned to the interface, and Bits are the subnet mask.

func (InterfaceList) ForeachInterfaceAddress 

func (ifaces InterfaceList) ForeachInterfaceAddress(fn func(Interface, netip.Prefix)) error

ForeachInterfaceAddress calls fn for each interface in ifaces, with all its addresses. The IPPrefix's IP is the IP address assigned to the interface, and Bits are the subnet mask.

type Monitor 

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

Monitor represents a monitoring instance.

func New 

func New(bus *eventbus.Bus, logf logger.Logf) (*Monitor, error)

New instantiates and starts a monitoring instance. The returned monitor is inactive until it's started by the Start method. Use RegisterChangeCallback to get notified of network changes.

func NewStatic 

func NewStatic() *Monitor

NewStatic returns a Monitor that's a one-time snapshot of the network state but doesn't actually monitor for changes. It should only be used in tests and situations like cleanups or short-lived CLI programs.

func (*Monitor) Close 

func (m *Monitor) Close() error

Close closes the monitor.

func (*Monitor) GatewayAndSelfIP 

func (m *Monitor) GatewayAndSelfIP() (gw, myIP netip.Addr, ok bool)

GatewayAndSelfIP returns the current network's default gateway, and the machine's default IP for that gateway.

It's the same as interfaces.LikelyHomeRouterIP, but it caches the result until the monitor detects a network change.

func (*Monitor) HasCGNATInterface 

func (m *Monitor) HasCGNATInterface() (bool, error)

HasCGNATInterface reports whether there are any non-Tailscale interfaces that use a CGNAT IP range.

func (*Monitor) InjectEvent 

func (m *Monitor) InjectEvent()

InjectEvent forces the monitor to pretend there was a network change and re-check the state of the network. Any registered ChangeFunc callbacks will be called within the event coalescing period (under a fraction of a second).

func (*Monitor) InterfaceState 

func (m *Monitor) InterfaceState() *State

InterfaceState returns the latest snapshot of the machine's network interfaces.

The returned value is owned by Mon; it must not be modified.

func (*Monitor) IsMajorChangeFrom 

func (m *Monitor) IsMajorChangeFrom(s1, s2 *State) bool

IsMajorChangeFrom reports whether the transition from s1 to s2 is a "major" change, where major roughly means it's worth tearing down a bunch of connections and rebinding.

TODO(bradiftz): tigten this definition.

func (*Monitor) Poll 

func (m *Monitor) Poll()

Poll forces the monitor to pretend there was a network change and re-check the state of the network.

This is like InjectEvent but only fires ChangeFunc callbacks if the network state differed at all.

func (*Monitor) RegisterChangeCallback 

func (m *Monitor) RegisterChangeCallback(callback ChangeFunc) (unregister func())

RegisterChangeCallback adds callback to the set of parties to be notified (in their own goroutine) when the network state changes. To remove this callback, call unregister (or close the monitor).

func (*Monitor) RegisterRuleDeleteCallback 

func (m *Monitor) RegisterRuleDeleteCallback(callback RuleDeleteCallback) (unregister func())

RegisterRuleDeleteCallback adds callback to the set of parties to be notified (in their own goroutine) when a Linux ip rule is deleted. To remove this callback, call unregister (or close the monitor).

func (*Monitor) SetTailscaleInterfaceName 

func (m *Monitor) SetTailscaleInterfaceName(ifName string)

SetTailscaleInterfaceName sets the name of the Tailscale interface. For example, "tailscale0", "tun0", "utun3", etc.

This must be called only early in tailscaled startup before the monitor is used.

func (*Monitor) Start 

func (m *Monitor) Start()

Start starts the monitor. A monitor can only be started & closed once.

type RuleDeleteCallback 

type RuleDeleteCallback func(table uint8, priority uint32)

RuleDeleteCallback is a callback when a Linux IP policy routing rule is deleted. The table is the table number (52, 253, 354) and priority is the priority order number (for Tailscale rules currently: 5210, 5230, 5250, 5270)

type RuleDeleted 

type RuleDeleted struct {
	// Table is the table number that the deleted rule referenced.
	Table uint8
	// Priority is the lookup priority of the deleted rule.
	Priority uint32
}

RuleDeleted reports that one of Tailscale's policy routing rules was deleted.

type State 

type State struct {
	// InterfaceIPs maps from an interface name to the IP addresses
	// configured on that interface. Each address is represented as an
	// IPPrefix, where the IP is the interface IP address and Bits is
	// the subnet mask.
	InterfaceIPs map[string][]netip.Prefix
	Interface    map[string]Interface

	// HaveV6 is whether this machine has an IPv6 Global or Unique Local Address
	// which might provide connectivity on a non-Tailscale interface that's up.
	HaveV6 bool

	// HaveV4 is whether the machine has some non-localhost,
	// non-link-local IPv4 address on a non-Tailscale interface that's up.
	HaveV4 bool

	// IsExpensive is whether the current network interface is
	// considered "expensive", which currently means LTE/etc
	// instead of Wifi. This field is not populated by GetState.
	IsExpensive bool

	// DefaultRouteInterface is the interface name for the
	// machine's default route.
	//
	// It is not yet populated on all OSes.
	//
	// When non-empty, its value is the map key into Interface and
	// InterfaceIPs.
	DefaultRouteInterface string

	// HTTPProxy is the HTTP proxy to use, if any.
	HTTPProxy string

	// PAC is the URL to the Proxy Autoconfig URL, if applicable.
	PAC string
}

State is intended to store the state of the machine's network interfaces, routing table, and other network configuration. For now it's pretty basic.

func (*State) AnyInterfaceUp 

func (s *State) AnyInterfaceUp() bool

AnyInterfaceUp reports whether any interface seems like it has Internet access.

func (*State) Equal 

func (s *State) Equal(s2 *State) bool

Equal reports whether s and s2 are exactly equal.

func (*State) HasIP 

func (s *State) HasIP(ip netip.Addr) bool

HasIP reports whether any interface has the provided IP address.

func (*State) HasPAC 

func (s *State) HasPAC() bool

func (*State) String 

func (s *State) String() string

Source Files

interfaces_linux.go loghelper.go netmon.go netmon_linux.go polling.go state.go

Version
v1.84.0 (latest)
Published
May 21, 2025
Platform
linux/amd64
Imports
33 packages
Last checked
1 day ago –

Tools for package owners.