Skip to content
Easy ssh tunneling
JavaScript
Latest commit f3b6006 Jun 25, 2016 @agebrock agebrock Merge branch 'release/4'

README.md

Tunnel-SSH

One to connect them all !

Tunnel-SSH Logo

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

v4 API Changes:

  • Removed Beta v3 api in favor of inject-tunnel-ssh
  • Removed reverse proxy in favor of tunnel-ssh-reverse
  • API now supports node callback style.
  • Improved docs

related projects

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 = {
      user:'root',
      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

In many cases host 1. and 2. are the same, for example if you want to connect to a database where the port from that database is bound to a local interface (127.0.0.1:27017) but you are able to connect via ssh (port 22 by default). You can skip the "dstHost" or the "host" configuration if they are the same. You can also skip the local configuration if you want to connect to localhost and the same port as "dstPort".

    var config = {
      user:'root',
      dstHost:destinationServer,
      dstPort:27017
    };

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

More configuration options

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

Common examples are:

    var config = {
      agent : process.env.SSH_AUTH_SOCK, // enabled by default
      privateKey:require('fs').readFileSync('/here/is/my/key'),
      password:'secret'
    }

catch 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);
    });
Something went wrong with that request. Please try again.