holepunch

A commandline tool (cli) and library (node.js api) for making devices in your home and office Internet-accessible.

Uses UPnP / SSDP and NAT-PMP / ZeroConf (Bonjour) for port forwarding / port mapping.

Works for IPv4 and IPv6 interfaces.

Status

Published as alpha, but nearing release quality.

git clone git.rootprojects.org/root/holepunch.js.git
 
pushd holepunch
 
node bin/holepunch.js --debug

Install

Commandline Tool

npm install --global holepunch

node.js Library

npm install --save holepunch

Examples

Some examples that work with what's currently published.

Commandline (CLI)

holepunch --help

holepunch --plain-ports 80,65080 --tls-ports 443,65443

API

This is the current Dec 30th api in master

var punch = require('holepunch');
 
punch({
  debug: true
, mappings: [{ internal: 443, external: 443, secure: true }]
, ipifyUrls: ['api.ipify.org'],
, protocols: ['none', 'upnp', 'pmp']
, rvpnConfigs: []
}).then(function (mappings) {
  // be sure to check for an `error` attribute on each mapping
  console.log(mappings);
}, function (err) {
  console.log(err);
});

API (v1.0.0 draft)

TODO: This is the api that I think I'd like to use for the solid v1.0.0

punch(opts)
 
  opts.debug = true | false     // print extra debug info
 
  opts.mappings = [             // these ports will be tested via tcp / http
    { internal: 80              // the port which is bound locally
    , external: 80              // the port as it is exposed on the internet
    , loopback: true | false    // whether or not to attempt an http(s) loopback test
    , secure: true | false      // (default: true) whether to use tls or plaintext
    }
  ]
 
  opts.ipifyUrls = [            // ipify urls
    'api.ipify.org'             // default
  ]
 
  opts.upnp = true | false      // attempt mapping via nat-upnp
 
  opts.pmp = true | false       // attempt mapping via nat-pmp
 
  opts.rvpnConfigs = [
    '/etc/holepunch/rvpn.json'  // TODO (not implemented)
  ]

Commandline

TODO --prebound-ports 22

Usage:
  holepunch.js [OPTIONS] [ARGS]

Options:
      --debug BOOLEAN       show traces and logs

      --plain-ports STRING  Port numbers to test with plaintext loopback.
                            (default: 65080)
                            (formats: <port>,<internal:external>)

      --tls-ports STRING    Port numbers to test with tls loopback.
                            (default: null)

      --ipify-urls STRING   Comma separated list of URLs to test for external ip.
                            (default: api.ipify.org)

      --protocols STRING    Comma separated list of ip mapping protocols.
                            (default: none,upnp,pmp)

      --rvpn-configs STRING Comma separated list of Reverse VPN config files in
                            the order they should be tried. (default: null)

  -h, --help                Display help and usage details

Non-Root

You do not need root to map ports, but you may need root to test them.

If you're cool with allowing all node programs to bind to privileged ports, try this:

sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/node

License

MPL-2.0