package portmapper

import "tailscale.com/net/portmapper"

Package portmapper is a UDP port mapping client. It currently allows for mapping over NAT-PMP, UPnP, and PCP.

Index ¶

• Variables
• func IsNoMappingError(err error) bool
• type Client
• func NewClient(c Config) *Client
• func (c *Client) Close() error
• func (c *Client) GetCachedMappingOrStartCreatingOne() (external netip.AddrPort, ok bool)
• func (c *Client) HaveMapping() bool
• func (c *Client) NoteNetworkDown()
• func (c *Client) Probe(ctx context.Context) (res ProbeResult, err error)
• func (c *Client) SetGatewayLookupFunc(f func() (gw, myIP netip.Addr, ok bool))
• func (c *Client) SetLocalPort(localPort uint16)
• type Config
• type DebugKnobs
• type Mapping
• type NoMappingError
• func (nme NoMappingError) Error() string
• func (nme NoMappingError) Unwrap() error
• type ProbeResult

Variables ¶

var (
	ErrNoPortMappingServices = errors.New("no port mapping services were found")
	ErrGatewayRange          = errors.New("skipping portmap; gateway range likely lacks support")
	ErrGatewayIPv6           = errors.New("skipping portmap; no IPv6 support for portmapping")
	ErrPortMappingDisabled   = errors.New("port mapping is disabled")
)

Functions ¶

func IsNoMappingError ¶

func IsNoMappingError(err error) bool

IsNoMappingError reports whether err is of type NoMappingError.

Types ¶

type Client ¶

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

Client is a port mapping client.

func NewClient ¶

func NewClient(c Config) *Client

NewClient constructs a new portmapping Client from c. It will panic if any required parameters are omitted.

func (*Client) Close ¶

func (c *Client) Close() error

func (*Client) GetCachedMappingOrStartCreatingOne ¶

func (c *Client) GetCachedMappingOrStartCreatingOne() (external netip.AddrPort, ok bool)

GetCachedMappingOrStartCreatingOne quickly returns with our current cached portmapping, if any. If there's not one, it starts up a background goroutine to create one. If the background goroutine ends up creating one, the onChange hook registered with the NewClient constructor (if any) will fire.

func (*Client) HaveMapping ¶

func (c *Client) HaveMapping() bool

HaveMapping reports whether we have a current valid mapping.

func (*Client) NoteNetworkDown ¶

func (c *Client) NoteNetworkDown()

NoteNetworkDown should be called when the network has transitioned to a down state. It's too late to release port mappings at this point (the user might've just turned off their wifi), but we can make sure we invalidate mappings for later when the network comes back.

func (*Client) Probe ¶

func (c *Client) Probe(ctx context.Context) (res ProbeResult, err error)

Probe returns a summary of which port mapping services are available on the network.

If a probe has run recently and there haven't been any network changes since, the returned result might be server from the Client's cache, without sending any network traffic.

func (*Client) SetGatewayLookupFunc ¶

func (c *Client) SetGatewayLookupFunc(f func() (gw, myIP netip.Addr, ok bool))

SetGatewayLookupFunc set the func that returns the machine's default gateway IP, and the primary IP address for that gateway. It must be called before the client is used. If not called, interfaces.LikelyHomeRouterIP is used.

func (*Client) SetLocalPort ¶

func (c *Client) SetLocalPort(localPort uint16)

SetLocalPort updates the local port number to which we want to port map UDP traffic.

type Config ¶

type Config struct {
	// EventBus, if non-nil, is used for event publication and subscription by
	// portmapper clients created from this config.
	//
	// TODO(creachadair): As of 2025-03-19 this is optional, but is intended to
	// become required non-nil.
	EventBus *eventbus.Bus

	// Logf is called to generate text logs for the client. If nil, logger.Discard is used.
	Logf logger.Logf

	// NetMon is the network monitor used by the client. It must be non-nil.
	NetMon *netmon.Monitor

	// DebugKnobs, if non-nil, configure the behaviour of the portmapper for
	// debugging.  If nil, a sensible set of defaults will be used.
	DebugKnobs *DebugKnobs

	// ControlKnobs, if non-nil, specifies knobs from the control plane that
	// might disable port mapping.
	ControlKnobs *controlknobs.Knobs

	// OnChange is called to run in a new goroutine whenever the port mapping
	// status has changed. If nil, no callback is issued.
	OnChange func()
}

Config carries the settings for a Client.

type DebugKnobs ¶

type DebugKnobs struct {
	// VerboseLogs tells the Client to print additional debug information
	// to its logger.
	VerboseLogs bool

	// LogHTTP tells the Client to print the raw HTTP logs (from UPnP) to
	// its logger. This is useful when debugging buggy UPnP
	// implementations.
	LogHTTP bool

	// Disable* disables a specific service from mapping.
	DisableUPnP bool
	DisablePMP  bool
	DisablePCP  bool

	// DisableAll, if non-nil, is a func that reports whether all port
	// mapping attempts should be disabled.
	DisableAll func() bool
}

DebugKnobs contains debug configuration that can be provided when creating a Client. The zero value is valid for use.

type Mapping ¶

type Mapping struct {
	External  netip.AddrPort
	Type      string
	GoodUntil time.Time
}

Mapping is an event recording the allocation of a port mapping.

type NoMappingError ¶

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

NoMappingError is returned when no NAT mapping could be done.

func (NoMappingError) Error ¶

func (nme NoMappingError) Error() string

func (NoMappingError) Unwrap ¶

func (nme NoMappingError) Unwrap() error

type ProbeResult ¶

type ProbeResult struct {
	PCP  bool
	PMP  bool
	UPnP bool
}

Source Files ¶

legacy_upnp.go pcp.go pcpresultcode_string.go pmpresultcode_string.go portmapper.go upnp.go