holepunch

A node.js library (api) and command (cli) for using UPnP SSDP and ZeroConf (Bonjour) NAT-PMP to make home and office devices and services Internet-accessible.

Progress

it now works :-)

still in development

git clone git@github.com:Daplie/holepunch.git

pushd holepunch

node bin/holepunch.js --debug

Install

Commandline Tool

npm install --global holepunch

node.js Library

npm install --save holepunch

Examples

Commandline (CLI)

holepunch --help

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

API

var punch = require('holepunch');

punch({
  debug: true
, plainPorts: [{ internal: 80, external: 80 }]
, tlsPorts: [{ internal: 443, external: 443 }]
, ipifyUrls: ['api.ipify.org'],
, protocols: ['none', 'upnp', 'pmp']
, rvpnConfigs: []
}).then(function () {
});

API

punch(opts)
  debug                     // print extra debug info

  tcpPorts                  // these ports will be tested via tcp / http

  tlsPorts                  // these ports will be tested via tls / https

  udpPorts                  // not implemented, not tested

  loopback                  // test ports via http / https

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