Documentation
¶
Overview ¶
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
- func DefaultRouteInterface() (string, error)
- func ForeachInterface(fn func(Interface, []netip.Prefix)) error
- func ForeachInterfaceAddress(fn func(Interface, netip.Prefix)) error
- func HTTPOfListener(ln net.Listener) string
- func InterfaceDebugExtras(ifIndex int) (string, error)
- func LikelyHomeRouterIP() (gateway, myIP netip.Addr, ok bool)
- func LinkChangeLogLimiter(ctx context.Context, logf logger.Logf, nm *Monitor) logger.Logf
- func LocalAddresses() (regular, loopback []netip.Addr, err error)
- func RegisterInterfaceGetter(getInterfaces func() ([]Interface, error))
- func SetTailscaleInterfaceProps(ifName string, ifIndex int)
- func TailscaleInterfaceIndex() (int, error)
- func TailscaleInterfaceName() (string, error)
- type ChangeDelta
- type ChangeFunc
- type DefaultRouteDetails
- type Interface
- type InterfaceList
- type Monitor
- func (m *Monitor) Close() error
- func (m *Monitor) GatewayAndSelfIP() (gw, myIP netip.Addr, ok bool)
- func (m *Monitor) HasCGNATInterface() (bool, error)
- func (m *Monitor) InjectEvent()
- func (m *Monitor) InterfaceState() *State
- func (m *Monitor) Poll()
- func (m *Monitor) RegisterChangeCallback(callback ChangeFunc) (unregister func())
- func (m *Monitor) SetTailscaleInterfaceName(ifName string)
- func (m *Monitor) Start()
- type RuleDeleted
- type State
Constants ¶
This section is empty.
Variables ¶
var IsInterestingInterface func(Interface, []netip.Prefix) bool
IsInterestingInterface is the function used to determine whether a given interface name is interesting enough to pay attention to for network change monitoring purposes.
If nil, all interfaces are considered interesting.
var LoginEndpointForProxyDetermination = "https://controlplane.tailscale.com/"
LoginEndpointForProxyDetermination is the URL used for testing which HTTP proxy the system should use.
Functions ¶
func DefaultRouteInterface ¶ added in v1.66.0
DefaultRouteInterface is like DefaultRoute but only returns the interface name.
func ForeachInterface ¶ added in v1.66.0
ForeachInterface is a wrapper for GetList, then List.ForeachInterface.
func ForeachInterfaceAddress ¶ added in v1.66.0
ForeachInterfaceAddress is a wrapper for GetList, then List.ForeachInterfaceAddress.
func HTTPOfListener ¶ added in v1.66.0
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 ¶ added in v1.66.0
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 ¶ added in v1.66.0
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 ¶ added in v1.82.0
LinkChangeLogLimiter returns a new logger.Logf that logs each unique format string to the underlying logger only once per major LinkChange event with a cooldownSeconds second cooldown.
The logger stops tracking seen format strings when the provided context is done.
func LocalAddresses ¶ added in v1.66.0
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 ¶ added in v1.66.0
RegisterInterfaceGetter sets the function that's used to query the system network interfaces.
func SetTailscaleInterfaceProps ¶ added in v1.94.1
SetTailscaleInterfaceProps sets the name of the Tailscale interface and its index for use by various listeners/dialers. If the index is zero, an attempt will be made to look it up by name. This makes no attempt to validate that the interface exists at the time of calling.
If this method is called, it is the responsibility of the caller to update the interface name and index if they change.
This should be called as early as possible during tailscaled startup.
func TailscaleInterfaceIndex ¶ added in v1.94.1
TailscaleInterfaceIndex returns the index of the Tailscale interface or an error if unset.
Callers must handle errors, as the Tailscale interface index may not be set in some environments.
func TailscaleInterfaceName ¶ added in v1.94.1
TailscaleInterfaceName returns the name of the Tailscale interface. For example, "tailscale0", "tun0", "utun3", etc or an error if unset.
Callers must handle errors, as the Tailscale interface name may not be set in some environments.
Types ¶
type ChangeDelta ¶ added in v1.50.0
type ChangeDelta struct {
// TimeJumped is whether there was a big jump in wall time since the last
// time we checked. This is a hint that a sleeping device might have
// come out of sleep.
TimeJumped bool
DefaultRouteInterface string
DefaultInterfaceChanged bool // whether default route interface changed
IsLessExpensive bool // whether new state's default interface is less expensive than old.
HasPACOrProxyConfigChanged bool // whether PAC/HTTP proxy config changed
InterfaceIPsChanged bool // whether any interface IPs changed in a meaningful way
AvailableProtocolsChanged bool // whether we have seen a change in available IPv4/IPv6
DefaultInterfaceMaybeViable bool // whether the default interface is potentially viable (has usable IPs, is up and is not the tunnel itself)
IsInitialState bool // whether this is the initial state (old == nil, new != nil)
// RebindLikelyRequired combines the various fields above to report whether this change likely requires us
// to rebind sockets. This is a very conservative estimate and covers a number ofcases where a rebind
// may not be strictly necessary. Consumers of the ChangeDelta should consider checking the individual fields
// above or the state of their sockets.
RebindLikelyRequired bool
// contains filtered or unexported fields
}
ChangeDelta describes the difference between two network states.
Use NewChangeDelta to construct a delta and compute the cached fields.
func NewChangeDelta ¶ added in v1.94.0
func NewChangeDelta(old, new *State, timeJumped bool, forceViability bool) (*ChangeDelta, error)
NewChangeDelta builds a ChangeDelta and eagerly computes the cached fields. forceViability, if true, forces DefaultInterfaceMaybeViable to be true regardless of the actual state of the default interface. This is useful in testing.
func (*ChangeDelta) AnyInterfaceUp ¶ added in v1.94.0
func (cd *ChangeDelta) AnyInterfaceUp() bool
AnyInterfaceUp reports whether any interfaces are up in the new state.
func (*ChangeDelta) CurrentState ¶ added in v1.94.0
func (cd *ChangeDelta) CurrentState() *State
CurrentState returns the current (new) state after the change.
func (*ChangeDelta) InterfaceIPDisappeared ¶ added in v1.94.0
func (cd *ChangeDelta) InterfaceIPDisappeared(ip netip.Addr) bool
InterfaceIPDisappeared reports whether the given IP address exists on any interface in the old state, but not in the new state.
func (*ChangeDelta) StateDesc ¶ added in v1.94.0
func (cd *ChangeDelta) StateDesc() string
StateDesc returns a description of the old and new states for logging.
type ChangeFunc ¶
type ChangeFunc func(*ChangeDelta)
ChangeFunc is a callback function registered with Monitor that's called when the network changed.
type DefaultRouteDetails ¶ added in v1.66.0
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 ¶ added in v1.66.0
func DefaultRoute() (DefaultRouteDetails, error)
DefaultRoute returns details of the network interface that owns the default route, not including any tailscale interfaces.
type Interface ¶ added in v1.66.0
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) IsLoopback ¶ added in v1.66.0
type InterfaceList ¶ added in v1.66.0
type InterfaceList []Interface
InterfaceList is a list of interfaces on the machine.
func GetInterfaceList ¶ added in v1.66.0
func GetInterfaceList() (InterfaceList, error)
GetInterfaceList returns the list of interfaces on the machine.
func (InterfaceList) ForeachInterface ¶ added in v1.66.0
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 ¶ added in v1.66.0
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 ¶
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 ¶ added in v1.66.0
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) GatewayAndSelfIP ¶
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 ¶ added in v1.82.0
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 ¶
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) Poll ¶ added in v1.50.0
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) SetTailscaleInterfaceName ¶ added in v1.50.0
TODO (barnstar): This doesn't need the Monitor receiver anymore but we're keeping it for API compatibility to avoid a breaking change. This can be removed when the various clients have switched to SetTailscaleInterfaceProps
type RuleDeleted ¶ added in v1.84.0
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 ¶ added in v1.66.0
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 ¶ added in v1.66.0
AnyInterfaceUp reports whether any interface seems like it has Internet access.
Source Files