natpmp

README

go-nat-pmp

A Go language client for the NAT-PMP internet protocol for port mapping and discovering the external IP address of a firewall.

NAT-PMP is supported by Apple brand routers and open source routers like Tomato and DD-WRT.

See https://tools.ietf.org/rfc/rfc6886.txt

Get the package

# Get the go-nat-pmp package.
go get -u github.com/jackpal/go-nat-pmp

Usage

Get one more package, used by the example code:

go get -u github.com/jackpal/gateway

Create a directory:

cd ~/go
mkdir -p src/hello
cd src/hello

Create a file hello.go with these contents:

package main

import (
    "fmt"

    "github.com/jackpal/gateway"
    natpmp "github.com/jackpal/go-nat-pmp"
)

func main() {
    gatewayIP, err := gateway.DiscoverGateway()
    if err != nil {
        return
    }

    client := natpmp.NewClient(gatewayIP)
    response, err := client.GetExternalAddress()
    if err != nil {
        return
    }
    fmt.Printf("External IP address: %v\n", response.ExternalIPAddress)
}

Build the example

go build
./hello

External IP address: [www xxx yyy zzz]

Clients

This library is used in the Taipei Torrent BitTorrent client http://github.com/jackpal/Taipei-Torrent

Complete documentation

http://godoc.org/github.com/jackpal/go-nat-pmp

License

This project is licensed under the Apache License 2.0.

Documentation

Index

• Constants
• type AddPortMappingResult
• type Client
  • func NewClient(gateway net.IP) (nat *Client)
  • func NewClientWithLocal(gateway net.IP, local net.IP) (nat *Client)
  • func NewClientWithLocalAndTimeout(gateway net.IP, local net.IP, timeout time.Duration) (nat *Client)
  • func NewClientWithTimeout(gateway net.IP, timeout time.Duration) (nat *Client)
  • func (n *Client) AddPortMapping(protocol string, internalPort, requestedExternalPort int, lifetime int) (result *AddPortMappingResult, err error)
  • func (n *Client) AddPortMappingWithDuration(protocol string, internalPort, requestedExternalPort int, ...) (result *AddPortMappingResult, err error)
  • func (n *Client) GetExternalAddress() (result *GetExternalAddressResult, err error)
• type GetExternalAddressResult

Constants

const RECOMMENDED_MAPPING_LIFETIME_SECONDS = 3600

The recommended mapping lifetime for AddPortMapping.

Types

type AddPortMappingResult

type AddPortMappingResult struct {
	SecondsSinceStartOfEpoc      uint32
	InternalPort                 uint16
	MappedExternalPort           uint16
	PortMappingLifetimeInSeconds uint32
}

Results of the NAT-PMP AddPortMapping operation

type Client

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

Client is a NAT-PMP protocol client.

func NewClient

func NewClient(gateway net.IP) (nat *Client)

Create a NAT-PMP client for the NAT-PMP server at the gateway. Uses default timeout which is around 128 seconds.

func NewClientWithLocal

func NewClientWithLocal(gateway net.IP, local net.IP) (nat *Client)

Create a NAT-PMP client for the NAT-PMP server at the gateway, bound to a specific local IP address. Uses default timeout which is around 128 seconds.

func NewClientWithLocalAndTimeout

func NewClientWithLocalAndTimeout(gateway net.IP, local net.IP, timeout time.Duration) (nat *Client)

Create a NAT-PMP client for the NAT-PMP server at the gateway, bound to a specific local IP address and with a timeout. Timeout defines the total amount of time we will keep retrying before giving up.

func NewClientWithTimeout

func NewClientWithTimeout(gateway net.IP, timeout time.Duration) (nat *Client)

Create a NAT-PMP client for the NAT-PMP server at the gateway, with a timeout. Timeout defines the total amount of time we will keep retrying before giving up.

func (*Client) AddPortMapping

func (n *Client) AddPortMapping(protocol string, internalPort, requestedExternalPort int, lifetime int) (result *AddPortMappingResult, err error)

Add (or delete) a port mapping. To delete a mapping, set the requestedExternalPort and lifetime to 0. Lifetime is specified in seconds. Note that this call can take up to 128 seconds to return.

func (*Client) AddPortMappingWithDuration

func (n *Client) AddPortMappingWithDuration(protocol string, internalPort, requestedExternalPort int, duration time.Duration) (result *AddPortMappingResult, err error)

Add (or delete) a port mapping using time.Duration for the lifetime. Note that NAT-PMP specifies lifetimes in seconds, so duration will be truncated to seconds. Note that this call can take up to 128 seconds to return.

func (*Client) GetExternalAddress

func (n *Client) GetExternalAddress() (result *GetExternalAddressResult, err error)

Get the external address of the router.

Note that this call can take up to 128 seconds to return.

type GetExternalAddressResult

type GetExternalAddressResult struct {
	SecondsSinceStartOfEpoc uint32
	ExternalIPAddress       [4]byte
}

Results of the NAT-PMP GetExternalAddress operation.