Neolithic Psychedelic Mushrooms

    holepunch

    1.0.0-alpha.3 • Public • Published

    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

    Install

    npm i holepunch

    DownloadsWeekly Downloads

    1

    Version

    1.0.0-alpha.3

    License

    MPL-2.0

    Unpacked Size

    50 kB

    Total Files

    19

    Last publish

    Collaborators

    • coolaj86