Tunnel-SSH

==========

ssh -L [LOCAL_IP:]LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER

Tunnel-ssh is based on the fantastic ssh2 library by Brian White.

Please note that release 5.0.0 uses a complete different approch for configuration and is not compatible to prio versions.

• Reuse of ssh client instead of creating a new one for each connection
• Promise / Async Await support

Tunnel-ssh v5 is designed to be very extendable and does not provide as much sematic sugar as prio versions.

The design goal was to use the original settings for each part used in the project to be able to use all possible binding features from client and server.

The configuration is separated in the following parts:

• Tunnel server
• TCP Server
• SSH Client
• SSH Forwarding

This configuration controls be behaviour of the tunnel server. Currently there is only one option available.

Example:

const tunnelOptions = {
	autoClose:true
}

autoclose - closes the Tunnel-Server once all clients disconnect from the server. Its useful for tooling or scripts that require a temporary ssh tunnel to operate. For example a mongodump.

Set this option to false will keep the server alive until you close it manually.

Controls the behaviour of the tcp server on your local machine. For all possible options please refere to the official node.js documentation: ServerListenOptions

Example:

const serverOptions = {
	host:'127.0.0.1',
	port: 27017
}

Options to tell the ssh client how to connect to your remote machine. For all possible options please refere to the ssh2 documentation: ssh2 documentation You will find different examples there for using a privateKey, password etc..

Example:

const sshOptions = {
	host: '192.168.100.100',
	port: 22,
	username: 'frylock',
	password: 'nodejsrules'
};

Options to control the source and destination of the tunnel.

Example:

const forwardOptions = {
	srcAddr:'0.0.0.0',
	srcPort:27017,
	dstAddr:'127.0.0.1',
	dstPort:27017
}

Tunnel-SSH exposes currently only one method: createTunnel

createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions);

The method retuns a promise containing the server and ssh-client instance. For most cases you will not need those instances. But in case you want to extend the functionallity you can use them to bind to there events like that:

createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions).
then(([server, conn], error)=>{

    server.on('error',(e)=>{
        console.log(e);
    });

    conn.on('error',(e)=>{
        console.log(e);
    });
});

For a list of all possible Events please refere to the node.js documentation for the server and the ssh2 documentation for the client.

The following example shows how to connect to a remote mongodb and bind it to all local interfaces.

import {createTunnel} from 'tunnel-ssh';

const port = 27017;

const tunnelOptions = {
	autoClose:true
};
const serverOptions = {
	port: port
};
const sshOptions = {
	host: '192.168.100.100',
	port: 22,
	username: 'frylock',
	password: 'nodejsrules'
};
const forwardOptions = {
	srcAddr:'0.0.0.0',
	srcPort:port,
	dstAddr:'127.0.0.1',
	dstPort:port
};

let [server, conn] = await createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions);

server.on('connection', (connection) =>{
    console.log('new connection');
});

If you just searching for an easy way to forward a remote port to your local machine try the following:

import {createTunnel} from 'tunnel-ssh';
const sshOptions = {
	host: '192.168.100.100',
	port: 22,
	username: 'frylock',
	password: 'nodejsrules'
};

function mySimpleTunnel(sshOptions, port, autoClose = true){
    let forwardOptions = {
        srcAddr:'127.0.0.1',
        srcPort:port,
        dstAddr:'127.0.0.1',
        dstPort:port
    }

    let tunnelOptions = {
        autoClose:autoClose
    }
    
    let serverOptions = {
        port: port
    }

    return createTunnel(tunnelOptions, serverOptions, sshOptions, autoClose);
}

await mySimpleTunnel(sshOptions, 27017);