tunnel-ssh - npm Package Compare versions

Comparing version 5.0.0 to 5.0.1

index.js

		@@ -5,11 +5,10 @@ const net = require('net');

		function autoClose(server){
		let interval = setInterval(()=>{
		function autoClose(server, connection){
		connection.on('close',()=>{
		server.getConnections((error, count)=>{
		if(count === 0){
		server.close();
		clearInterval(interval);
		}
		});
		}, 1000);
		});
		}
		@@ -37,11 +36,10 @@

		let isVirginConnection = true;

		return new Promise(function(resolve, reject){
		createServer(serverOptions).then(function(server, reject){
		createClient(sshOptions).then(function(conn){

		server.on('connection',(connection)=>{
		if(isVirginConnection && tunnelOptions.autoClose){
		isVirginConnection = false;
		autoClose(server);

		if(tunnelOptions.autoClose){
		autoClose(server, connection);
		}
		@@ -56,2 +54,3 @@
		});

		});
		@@ -65,2 +64,3 @@ server.on('close',()=> conn.end());


		exports.createTunnel = createTunnel;

package.json

		{
		"name": "tunnel-ssh",
		"version": "5.0.0",
		"version": "5.0.1",
		"description": "Easy extendable SSH tunnel",
		@@ -5,0 +5,0 @@ "main": "index.js",

202

README.md

		Tunnel-SSH

		==========



		One to connect them all !



		![Tunnel-SSH Logo](http://i.imgur.com/I5PRnDD.jpg)



		Tunnel-ssh is based on the fantastic [ssh2](https://github.com/mscdex/ssh2) library by Brian White.
		Trouble ? Please study the ssh2 configuration.


		### Latest Relese 5.0.0
		### Latest Release 5.0.0



		### Breaking change in 5.0.0

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

		#### New Features
		* Reuse of ssh client instead of creating a new one for each connection
		* Promise / Async Await support

		## Concept

		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 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:
		@@ -28,127 +43,124 @@

		### Tunnel Server Options

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

		```
		Example:

		```js
		const tunnelOptions = {
		autoClose:true
		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.

		### 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.
		Set this option to false will keep the server alive until you close it manually.

		### TCP Server options

		Controls the behaviour of the tcp server on your local machine.
		For all possible options please refere to the official node.js documentation:
		[ServerListenOptions](https://nodejs.org/api/net.html#serverlistenoptions-callback)

		Example:

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

		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);
		});
		### SSH client options
		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](https://www.npmjs.com/package/ssh2#installation)
		You will find different examples there for using a privateKey, password etc..

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

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

		### SSH Forwarding options
		Options to control the source and destination of the tunnel.

		## Understanding the configuration
		Example:

		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)
		```js
		const forwardOptions = {
		srcAddr:'0.0.0.0',
		srcPort:27017,
		dstAddr:'127.0.0.1',
		dstPort:27017
		}
		```


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

		Tunnel-SSH exposes currently only one method: createTunnel

		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

		```js

		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) {
		//....
		});
		createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions);
		```
		#### 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.
		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:


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

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

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

		#### More configuration options
		tunnel-ssh pipes the configuration direct into the ssh2 library so every config option provided by ssh2 still works.
		[ssh2 configuration](https://github.com/mscdex/ssh2#client-methods)
		For a list of all possible Events please refere to the node.js documentation for the server and the ssh2 documentation for the client.


		#### catching errors:
		### Usage Example
		```js
		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.
		}
		});
		const { createTunnel } = require('tunnel-ssh');
		const tunnelOptions = {
		autoClose:true
		};
		const serverOptions = {
		port: 27017
		};
		const sshOptions = {
		host: '192.168.100.100',
		port: 22,
		username: 'frylock',
		password: 'nodejsrules'
		};
		const forwardOptions = {
		srcAddr:'0.0.0.0',
		srcPort:27017,
		dstAddr:'127.0.0.1',
		dstPort:27017
		};

		// Use a listener to handle errors outside the callback
		server.on('error', function(err){
		console.error('Something bad happened:', err);
		});
		```
		[server, conn] = await createTunnel(tunnelOptions, serverOptions, sshOptions, forwardOptions);

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

tunnel-ssh - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics