README.md

Tunnel-SSH

One to connect them all !

Tunnel-ssh is based on the fantastic ssh2 library by Brian White. Trouble ? Please study the ssh2 configuration.

Latest Relese 4.1.3

Release notes

• Closing sshconnections correctly thx @actionshrimp
• Improved readme
• Updated modules

Special thanks to @vweevers and @dickeyxxx

Related projects

• If you don't want to wrap a tunnel around your code: inject-tunnel-ssh
• If you need it the other way around: reverse-tunnel-ssh

Integration

By default tunnel-ssh will close the tunnel after a client disconnects, so your cli tools should work in the same way, they do if you connect directly. If you need the tunnel to stay open, use the "keepAlive:true" option within the configuration.

    var config = {
      ...
      keepAlive:true
    };

    var tnl = tunnel(config, function(error, tnl){
          yourClient.connect();
          yourClient.disconnect();
          setTimeout(function(){
            // you only need to close the tunnel by yourself if you set the
            // keepAlive:true option in the configuration !
            tnl.close();
          },2000);
      });

    // you can also close the tunnel from here...
    setTimeout(function(){
      tnl.close();
    },2000);

Understanding the configuration

1. A local server listening for connections to forward via ssh Description: This is where you bind your interface. Properties: ** localHost (default is '127.0.0.1') ** localPort (default is dstPort)

2. The ssh configuration Description: The host you want to use as ssh-tunnel server. Properties: ** host ** port (22) ** username ** ...

3. The destination host configuration (based on the ssh host) Imagine you just connected to The host you want to connect to. (via host:port) now that server connects requires a target to tunnel to. Properties: ** dstHost (localhost) ** dstPort

Config example

    var config = {
      username:'root',
      password:'secret',
      host:sshServer,
      port:22,
      dstHost:destinationServer,
      dstPort:27017,
      localHost:'127.0.0.1',
      localPort: 27000
    };

    var tunnel = require('tunnel-ssh');
    tunnel(config, function (error, server) {
      //....
    });

Sugar configuration

tunnel-ssh assumes that you want to map the same port on a remote machine to your localhost using the ssh-server on the remote machine.

    var config = {
      username:'root',
      dstHost:'remotehost.with.sshserver.com',
      dstPort:27017,
      privateKey:require(fs).readFileSync('/path/to/key'),
      passphrase:'secret'
    };

More configuration options

tunnel-ssh pipes the configuration direct into the ssh2 library so every config option provided by ssh2 still works. ssh2 configuration

catching errors:

    var tunnel = require('tunnel-ssh');
    //map port from remote 3306 to localhost 3306
    var server = tunnel({host: '172.16.0.8', dstPort: 3306}, function (error, server) {
       if(error){
        //catch configuration and startup errors here.
       }
    });

    // Use a listener to handle errors outside the callback
    server.on('error', function(err){
        console.error('Something bad happened:', err);
    });