upnp

Documentation

Overview

Package upnp provides a simple and opinionated interface to UPnP-enabled routers, allowing users to forward ports and discover their external IP address. Specific quirks:

- When attempting to discover UPnP-enabled routers on the network, only the first such router is returned. If you have multiple routers, this may cause some trouble. But why would you do that?

- Forwarded ports are always symmetric, e.g. the router's port 9980 will be mapped to the client's port 9980. This will be unacceptable for some purposes, but too bad. Symmetric mappings are the desired behavior 99% of the time, and they save a function argument.

- TCP and UDP protocols are forwarded together.

- Ports are forwarded permanently. Some other implementations lease a port mapping for a set duration, and then renew it periodically. This is nice, because it means mappings won't stick around after they've served their purpose. Unfortunately, some routers only support permanent mappings, so this package has chosen to support the lowest common denominator. To un-forward a port, you must use the Clear function (or do it manually).

Once you've discovered your router, you can retrieve its address by calling its Location method. This address can be supplied to Load to connect to the router directly, which is much faster than calling Discover.

Based on https://gitlab.com/NebulousLabs/go-upnp

Instead of copying https://github.com/huin/goupnp this package uses it as an import. This means that, unlike NebulousLabs' implementation, we cannot pass a context to `Discover()`. On the other hand, we benefit from easy updates from upstream.

Index

• type IGD
  • func Discover() (*IGD, error)
  • func (d *IGD) Clear(port uint16) error
  • func (d *IGD) ExternalIP() (string, error)
  • func (d *IGD) Forward(port uint16, desc string) error
  • func (d *IGD) IsForwardedTCP(port uint16) (bool, error)
  • func (d *IGD) IsForwardedUDP(port uint16) (bool, error)
  • func (d *IGD) Location() string

Types

type IGD

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

An IGD provides an interface to the most commonly used functions of an Internet Gateway Device: discovering the external IP, and forwarding ports.

func Discover

func Discover() (*IGD, error)

Discover scans the local network for routers and returns the first UPnP-enabled router it encounters. It will try up to 3 times to find a router, sleeping a random duration between each attempt. This is to mitigate a race condition with many callers attempting to discover simultaneously.

func (*IGD) Clear

func (d *IGD) Clear(port uint16) error

Clear un-forwards a port, removing it from the router's port mapping table.

func (*IGD) ExternalIP

func (d *IGD) ExternalIP() (string, error)

ExternalIP returns the router's external IP.

func (*IGD) Forward

func (d *IGD) Forward(port uint16, desc string) error

Forward forwards the specified port, and adds its description to the router's port mapping table.

func (*IGD) IsForwardedTCP

func (d *IGD) IsForwardedTCP(port uint16) (bool, error)

IsForwardedTCP checks whether a specific TCP port is forwarded to this host.

func (*IGD) IsForwardedUDP

func (d *IGD) IsForwardedUDP(port uint16) (bool, error)

IsForwardedUDP checks whether a specific UDP port is forwarded to this host.

func (*IGD) Location

func (d *IGD) Location() string

Location returns the URL of the router, for future lookups (see Load).