netcheck

Documentation

Overview

Package netcheck checks the network conditions from the current host.

Index

• type Client
  • func (c *Client) GetReport(ctx context.Context, dm *tailcfg.DERPMap) (_ *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 Report
  • func (r *Report) AnyPortMappingChecked() bool
  • func (r *Report) Clone() *Report

Types

type Client

type Client struct {
	// Verbose enables verbose logging.
	Verbose bool

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

	// NetMon optionally provides a netmon.Monitor to use to get the current
	// (cached) network interface.
	// If nil, the interface will be looked up dynamically.
	// TODO(bradfitz): make NetMon required. As of 2023-08-01, it basically always is
	// present anyway.
	NetMon *netmon.Monitor

	// 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) (_ *Report, reterr error)

GetReport gets 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 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

	// HairPinning is whether the router supports communicating
	// between two local devices through the NATted public IP address
	// (on IPv4).
	HairPinning 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

	GlobalV4 string // ip:port of global IPv4
	GlobalV6 string // [ip]:port of global IPv6

	// 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