nat

README

go-nat

Forked from: libp2p/go-nat, itself forked from fd/go-nat.

This fork adds PCP (RFC 6887) with IPv6 firewall pinholes and unicast SSDP discovery. It carries its own module path so that it can be required directly, rather than through a replace directive: a replace applies only to the main module, so anything importing a consumer of this package as a library would otherwise resolve to upstream go-nat and fail to build against the added API.

---

The last gx published version of this module was: 1.0.3: QmdwkZHamNNrj7k3G29rnurmW3mFzsDhnyXppNcgYsiBVz

Documentation

Overview

Package nat implements NAT handling facilities

Index

• Variables
• func DiscoverNATs(ctx context.Context) <-chan NAT
• type HealthChecker
• type IPv6PinholeReporter
• type NAT
  • func DiscoverGateway(ctx context.Context) (NAT, error)

Variables

var ErrNoExternalAddress = errors.New("no external address")

var ErrNoInternalAddress = errors.New("no internal address")

var ErrNoNATFound = errors.New("no NAT found")

Functions

func DiscoverNATs

func DiscoverNATs(ctx context.Context) <-chan NAT

DiscoverNATs returns all NATs discovered in the network. Callers choose between the returned protocols; use DiscoverGateway for PCP preference and automatic dual-stack mapping.

Types

type HealthChecker

type HealthChecker interface {
	// CheckServerHealth reports the gateway's current epoch and whether it
	// appears to have lost state, in which case mappings must be recreated.
	CheckServerHealth(ctx context.Context) (epoch uint32, serverRestarted bool, err error)
}

HealthChecker is implemented by gateways that can report whether they still hold the mappings they were asked for, PCP being the only one today.

Assert on this interface rather than on a concrete NAT type: a dual-stack gateway is a wrapper around the IPv4 NAT, so a type assertion misses it.

type IPv6PinholeReporter

type IPv6PinholeReporter interface {
	// IPv6PinholeError returns the error from the most recent IPv6 pinhole
	// operation, or nil when it succeeded.
	IPv6PinholeError() error
}

IPv6PinholeReporter is implemented by dual-stack gateways that open IPv6 firewall pinholes alongside the IPv4 port mapping. Pinholes are best effort and never fail AddPortMapping or DeletePortMapping on their own, so this is the only way to find out whether one was actually opened.

type NAT

type NAT interface {
	// Type returns the kind of NAT port mapping service that is used
	Type() string

	// GetDeviceAddress returns the internal address of the gateway device.
	GetDeviceAddress() (addr net.IP, err error)

	// GetExternalAddress returns the external address of the gateway device.
	GetExternalAddress() (addr net.IP, err error)

	// GetInternalAddress returns the address of the local host.
	GetInternalAddress() (addr net.IP, err error)

	// AddPortMapping maps a port on the local host to an external port.
	AddPortMapping(ctx context.Context, protocol string, internalPort int, description string, timeout time.Duration) (mappedExternalPort int, err error)

	// DeletePortMapping removes a port mapping.
	DeletePortMapping(ctx context.Context, protocol string, internalPort int) (err error)
}

protocol is either "udp" or "tcp"

func DiscoverGateway

func DiscoverGateway(ctx context.Context) (NAT, error)

DiscoverGateway attempts to find a gateway device. It prefers PCP for IPv4, independently enables PCP for IPv6, then falls back to the first UPnP or NAT-PMP gateway discovered.