tunnel-ssh

What is tunnel-ssh?

The tunnel-ssh npm package allows you to create SSH tunnels in Node.js applications. This can be useful for securely connecting to remote servers, databases, or other services that require SSH tunneling.

What are tunnel-ssh's main functionalities?

Basic SSH Tunnel

This code sample demonstrates how to set up a basic SSH tunnel using the tunnel-ssh package. The configuration object includes details such as the SSH username, host, port, destination host and port, local host and port, and the private key for authentication.

const tunnel = require('tunnel-ssh');

const config = {
  username: 'user',
  host: 'remote.server.com',
  port: 22,
  dstHost: '127.0.0.1',
  dstPort: 27017,
  localHost: '127.0.0.1',
  localPort: 27017,
  privateKey: require('fs').readFileSync('/path/to/private/key')
};

tunnel(config, function (error, server) {
  if (error) {
    console.error('SSH connection error: ', error);
  } else {
    console.log('SSH tunnel established');
  }
});

SSH Tunnel with Forwarding

This code sample shows how to set up an SSH tunnel with port forwarding. The 'keepAlive' option is set to true to maintain the connection. This is useful for applications that need to keep a persistent connection to a remote database or service.

const tunnel = require('tunnel-ssh');

const config = {
  username: 'user',
  host: 'remote.server.com',
  port: 22,
  dstHost: '127.0.0.1',
  dstPort: 3306,
  localHost: '127.0.0.1',
  localPort: 3306,
  privateKey: require('fs').readFileSync('/path/to/private/key'),
  keepAlive: true
};

tunnel(config, function (error, server) {
  if (error) {
    console.error('SSH connection error: ', error);
  } else {
    console.log('SSH tunnel with forwarding established');
  }
});

Dynamic Port Forwarding

This code sample demonstrates how to set up a dynamic SSH tunnel, which can be used as a SOCKS proxy. The 'dynamic' option is set to true, allowing the tunnel to dynamically forward traffic to different destinations.

const tunnel = require('tunnel-ssh');

const config = {
  username: 'user',
  host: 'remote.server.com',
  port: 22,
  dstHost: '0.0.0.0',
  dstPort: 0,
  localHost: '127.0.0.1',
  localPort: 1080,
  privateKey: require('fs').readFileSync('/path/to/private/key'),
  dynamic: true
};

tunnel(config, function (error, server) {
  if (error) {
    console.error('SSH connection error: ', error);
  } else {
    console.log('Dynamic SSH tunnel established');
  }
});

Other packages similar to tunnel-ssh

ssh2

The ssh2 package is a more general-purpose SSH client for Node.js. It provides a wide range of SSH functionalities, including tunneling, executing commands, and file transfers. Compared to tunnel-ssh, ssh2 offers more flexibility and control over SSH connections but requires more setup and configuration.

node-ssh

The node-ssh package is a high-level SSH client for Node.js that simplifies the process of connecting to SSH servers, executing commands, and transferring files. It is easier to use than ssh2 but offers less control over the SSH connection. It is a good alternative to tunnel-ssh for users who need basic SSH functionalities without the complexity.

ssh2-sftp-client

The ssh2-sftp-client package is built on top of ssh2 and provides a simplified API for SFTP (SSH File Transfer Protocol) operations. While it focuses on file transfers, it can also be used to create SSH tunnels. It is a good choice for users who primarily need SFTP capabilities with occasional SSH tunneling.

README

Tunnel-SSH

Tunnel-SSH - v3.0.0-BETA

This package is ssh user@remote -L 2000:localhost:27017 the node way.

THIS IS A BETA RELEASE - THX for Testing and providing feedback

• Easy to setup
• Easy to integrate
• Can do reverse tunnel
• Automatic connection handling for your cli scripts.

Changes from 2.0.x

• Promise api
• Reusing SSH Connection for faster Pooling or mass connections.
• New option timeout
• "patchNet" - API (@see below)

Fast lane

The most common case is to tunnel a remote database via port mapping. The following example creates a tunnel to a remote database.

var tunnel = require('tunnel-ssh');
var config = {
    username:'root',
    password:'secret',
    host:'remote.mysql.server.com',
    port:3306
}

tunnel(config, function(e, sshTunnel){
    //Now, you should be able to connect to the tunnel via localhost:3336.
});

Configuration

var config = {

    username:'root', 
    // ssh username used to connect to the sshServer
    // default: current user, fallback root
    
    password:'secret', 
    // ssh password to connect to the sshServer
    // if you plan to use private keys you don't need a password.
    
    privateKey:'/Users/[username]/.ssh/id_rsa'
    // ssh key to use for the sshServer
    // Optional. no default 
    
    agent:'/private/tmp/com.apple.launchd.wTs9rJUSK4/Listeners'
    // ssh-agent socket path used to connect to the sshServer
    // default: process.env['SSH_AUTH_SOCK']
    
    srcHost:'localhost', 
    // the Host we tunnel from (interpreted from local machine).
    // So localhost means this machine.
    // Default 127.0.0.1
    
    srcPort: '27017' 
    // The port we tunnel from 
    // Alias: Port
    // Default: autogenerated by finding a free port 
    
    host:'remote.mysql.server.com', 
     // Hostname or IP to connect to the sshserver  
     // Default: 127.0.0.1
     // Alias: sshHost
    
    sshHost:'remote.mysql.server.com', 
    // Hostname or IP to connect to the sshserver  
    // Default: 127.0.0.1
    // Alias: host
    
    sshPort:22, 
    // Port to connect to the sshserver
    // Default: 22
    
    dstHost:'localhost', 
    // Hind: dst means destination here
    // Hostname to tunnel to (interpreted by sshHost) 
    // default: '127.0.0.1' (same as sshHost)
    
    dstPort: '27017',
    // Hind: dst means destination here
    // The port to tunnel to. 
    // Required !
    // Alias: port
    
    port:3306 
    // Alias for src- and dstPort
    // Used to simple map a remote service to 
	// a localhost without remapping the port.
    
    shutdown:
    
    keepAlive:false
    // deprecated 
    // 
    // keepAlive will keep the tunnel open even if no connection is left. 
    // This can be used if you want a classic tunnel for external tools
    // like (navicat, mongoshell)
    // to close the tunnel you need to manually call "tunnel.close()
    // default: false;
    
    timeout:1000
    // KeepAlive for 1 second, countdown starts if no connection is left 
    // Example: If you set the timer for 2 seconds and reconnect every 
    // second to the tunnel  
    // The tunnel will stay open.
    // default: not set
}

from the first example looks like you setting up a configuration for one host, but Source Destination SSH

The configuration is based on the original SSH2 configuration, since v3 we put some sugar into the config, so the following convention can be used:

if a hostname is not set (srcHost, dstHost, host) then the hostname will be 127.0.0.1 (localhost).

Pro tip: If you plan to expose a local port on a remote machine you need to enable the "GatewayPorts" option in your 'sshd_config'

#What ports, IPs and protocols we listen for
Port 22
GatewayPorts yes

####map remote port to localhost:

    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, result) {
        //you can start using your resources here. (mongodb, mysql, ....)
        console.log('connected');
    });

####remap remote port to localhost

    // add a localPort for more more control
    var config = {
        host: '172.16.0.8',
        username: 'root',
        dstPort: 3306,
        localPort: 3000
    };
    
    var server = tunnel(config, function (error, result) {
        console.log('connected');
    });

You can find more examples here

tunnel-ssh supports the default ssh2 configuration.

    {
        username: 'root',
        port: 22,
        srcPort: 0,
        srcHost: 'localhost',
        dstPort: null,
        dstHost: 'localhost',
        agent : process.env.SSH_AUTH_SOCK,
        privateKey:require('fs').readFileSync('/here/is/my/key'),
        password:'secret'
    } `