netcheck

Documentation

Overview

Package netcheck checks the network conditions from the current host.

Index

• Constants
• type Client
  • func (c *Client) GetReport(ctx context.Context, dm *tailcfg.DERPMap, opts *GetReportOpts) (_ *Report, reterr error)
  • func (c *Client) MakeNextReportFull()
  • func (c *Client) ReceiveSTUNPacket(pkt []byte, src netip.AddrPort)
  • func (c *Client) Standalone(ctx context.Context, bindAddr string) error
• type GetReportOpts
• type Report
  • func (r *Report) AnyPortMappingChecked() bool
  • func (r *Report) Clone() *Report
  • func (r *Report) GetGlobalAddrs() (v4, v6 []netip.AddrPort)

Constants

const (

	// PreferredDERPFrameTime is the time which, if a DERP frame has been
	// received within that period, we treat that region as being present
	// even without receiving a STUN response.
	// Note: must remain higher than the derp package frameReceiveRecordRate
	PreferredDERPFrameTime = 8 * time.Second
)

const (
	// ReportTimeout is the maximum amount of time netcheck will
	// spend gathering a single report.
	ReportTimeout = 5 * time.Second
)

The various default timeouts for things.

Types

type Client

type Client struct {
	// NetMon is the netmon.Monitor to use to get the current
	// (cached) network interface.
	// It must be non-nil.
	NetMon *netmon.Monitor

	// Verbose enables verbose logging.
	Verbose bool

	// Logf optionally specifies where to log to.
	// If nil, log.Printf is used.
	Logf logger.Logf

	// TimeNow, if non-nil, is used instead of time.Now.
	TimeNow func() time.Time

	// SendPacket is required to send a packet to the specified address. For
	// convenience it shares a signature with WriteToUDPAddrPort.
	SendPacket func([]byte, netip.AddrPort) (int, error)

	// SkipExternalNetwork controls whether the client should not try
	// to reach things other than localhost. This is set to true
	// in tests to avoid probing the local LAN's router, etc.
	SkipExternalNetwork bool

	// PortMapper, if non-nil, is used for portmap queries.
	// If nil, portmap discovery is not done.
	PortMapper *portmapper.Client // lazily initialized on first use

	// UseDNSCache controls whether this client should use a
	// *dnscache.Resolver to resolve DERP hostnames, when no IP address is
	// provided in the DERP map. Note that Tailscale-provided DERP servers
	// all specify explicit IPv4 and IPv6 addresses, so this is mostly
	// helpful for users with custom DERP servers.
	//
	// If false, the default net.Resolver will be used, with no caching.
	UseDNSCache bool
	// contains filtered or unexported fields
}

Client generates Reports describing the result of both passive and active network configuration probing. It provides two different modes of report, a full report (see MakeNextReportFull) and a more lightweight incremental report. The client must be provided with SendPacket in order to perform active probes, and must receive STUN packet replies via ReceiveSTUNPacket. Client can be used in a standalone fashion via the Standalone method.

func (*Client) GetReport

func (c *Client) GetReport(ctx context.Context, dm *tailcfg.DERPMap, opts *GetReportOpts) (_ *Report, reterr error)

GetReport gets a report. The 'opts' argument is optional and can be nil. Callers are discouraged from passing a ctx with an arbitrary deadline as this may cause GetReport to return prematurely before all reporting methods have executed. ReportTimeout is the maximum amount of time GetReport will spend gathering a report.

It may not be called concurrently with itself.

func (*Client) MakeNextReportFull

func (c *Client) MakeNextReportFull()

MakeNextReportFull forces the next GetReport call to be a full (non-incremental) probe of all DERP regions.

func (*Client) ReceiveSTUNPacket

func (c *Client) ReceiveSTUNPacket(pkt []byte, src netip.AddrPort)

ReceiveSTUNPacket must be called when a STUN packet is received as a reply to packet the client sent using SendPacket. In Standalone this is performed by the loop started by Standalone, in normal operation in tailscaled incoming STUN replies are routed to this method.

func (*Client) Standalone

func (c *Client) Standalone(ctx context.Context, bindAddr string) error

Standalone creates the necessary UDP sockets on the given bindAddr and starts an IO loop so that the Client can perform active probes with no further need for external driving of IO (no need to set/implement SendPacket, or call ReceiveSTUNPacket). It must be called prior to starting any reports and is shut down by cancellation of the provided context. If both IPv4 and IPv6 fail to bind, errors will be returned, if one or both protocols can bind no error is returned.

type GetReportOpts

type GetReportOpts struct {
	// GetLastDERPActivity is a callback that, if provided, should return
	// the absolute time that the calling code last communicated with a
	// given DERP region. This is used to assist in avoiding PreferredDERP
	// ("home DERP") flaps.
	//
	// If no communication with that region has occurred, or it occurred
	// too far in the past, this function should return the zero time.
	GetLastDERPActivity func(int) time.Time
	// OnlyTCP443 constrains netcheck reporting to measurements over TCP port
	// 443.
	OnlyTCP443 bool
}

GetReportOpts contains options that can be passed to GetReport. Unless specified, all fields are optional and can be left as their zero value.

type Report

type Report struct {
	UDP         bool // a UDP STUN round trip completed
	IPv6        bool // an IPv6 STUN round trip completed
	IPv4        bool // an IPv4 STUN round trip completed
	IPv6CanSend bool // an IPv6 packet was able to be sent
	IPv4CanSend bool // an IPv4 packet was able to be sent
	OSHasIPv6   bool // could bind a socket to ::1
	ICMPv4      bool // an ICMPv4 round trip completed

	// MappingVariesByDestIP is whether STUN results depend which
	// STUN server you're talking to (on IPv4).
	MappingVariesByDestIP opt.Bool

	// UPnP is whether UPnP appears present on the LAN.
	// Empty means not checked.
	UPnP opt.Bool
	// PMP is whether NAT-PMP appears present on the LAN.
	// Empty means not checked.
	PMP opt.Bool
	// PCP is whether PCP appears present on the LAN.
	// Empty means not checked.
	PCP opt.Bool

	PreferredDERP   int                   // or 0 for unknown
	RegionLatency   map[int]time.Duration // keyed by DERP Region ID
	RegionV4Latency map[int]time.Duration // keyed by DERP Region ID
	RegionV6Latency map[int]time.Duration // keyed by DERP Region ID

	GlobalV4Counters map[netip.AddrPort]int // number of times the endpoint was observed
	GlobalV6Counters map[netip.AddrPort]int // number of times the endpoint was observed

	GlobalV4 netip.AddrPort
	GlobalV6 netip.AddrPort

	// CaptivePortal is set when we think there's a captive portal that is
	// intercepting HTTP traffic.
	CaptivePortal opt.Bool
}

Report contains the result of a single netcheck.

func (*Report) AnyPortMappingChecked

func (r *Report) AnyPortMappingChecked() bool

AnyPortMappingChecked reports whether any of UPnP, PMP, or PCP are non-empty.

func (*Report) Clone

func (r *Report) Clone() *Report

func (*Report) GetGlobalAddrs

func (r *Report) GetGlobalAddrs() (v4, v6 []netip.AddrPort)

GetGlobalAddrs returns the v4 and v6 global addresses observed during the netcheck, which includes the best latency endpoint first, followed by any other endpoints that were observed repeatedly. It excludes singular endpoints that are likely only the result of a hard NAT.