1 | Tunnel-SSH
|
2 | ==========
|
3 |
|
4 | One to connect them all !
|
5 |
|
6 | ![Tunnel-SSH Logo](http://i.imgur.com/I5PRnDD.jpg)
|
7 |
|
8 | Tunnel-ssh is based on the fantastic [ssh2](https://github.com/mscdex/ssh2) library by Brian White.
|
9 | Trouble ? Please study the ssh2 configuration.
|
10 |
|
11 | Changelog 4.1.0 / 2016-08-09
|
12 | ==================
|
13 |
|
14 | * style: Change codestyle to xo.
|
15 | * Refactor: Improved configuration error handling.
|
16 | * refactor: clean up examples
|
17 | * style: Remove jscs in favor of eslint.
|
18 | * doc: Improve examples
|
19 | * Merge pull request #42 from kinsi55/master
|
20 | * Merge pull request #43 from pedroventura/master
|
21 | * doc: Update Readme.md
|
22 | * Fix wrong comparison causing localPort to stay "null" if not explicitly defined.
|
23 | * Doc: Update Readme.md
|
24 |
|
25 |
|
26 |
|
27 | ### related projects
|
28 | * [If you don't want to wrap a tunnel around your code: inject-tunnel-ssh](https://github.com/agebrock/inject-tunnel-ssh)
|
29 | * [If you need it the other way around: reverse-tunnel-ssh](https://github.com/agebrock/reverse-tunnel-ssh)
|
30 |
|
31 | ### Integration
|
32 | 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.
|
33 | If you need the tunnel to stay open, use the "keepAlive:true" option within
|
34 | the configuration.
|
35 |
|
36 |
|
37 | ```js
|
38 |
|
39 | var config = {
|
40 | ...
|
41 | keepAlive:true
|
42 | };
|
43 |
|
44 | var tnl = tunnel(config, function(error, tnl){
|
45 | yourClient.connect();
|
46 | yourClient.disconnect();
|
47 | setTimeout(function(){
|
48 | // you only need to close the tunnel by yourself if you set the
|
49 | // keepAlive:true option in the configuration !
|
50 | tnl.close();
|
51 | },2000);
|
52 | });
|
53 |
|
54 | // you can also close the tunnel from here...
|
55 | setTimeout(function(){
|
56 | tnl.close();
|
57 | },2000);
|
58 |
|
59 | ```
|
60 |
|
61 |
|
62 | ## Understanding the configuration
|
63 |
|
64 | 1. A local server listening for connections to forward via ssh
|
65 | Description: This is where you bind your interface.
|
66 | Properties:
|
67 | ** localHost (default is '127.0.0.1')
|
68 | ** localPort (default is dstPort)
|
69 |
|
70 |
|
71 | 2. The ssh configuration
|
72 | Description: The host you want to use as ssh-tunnel server.
|
73 | Properties:
|
74 | ** host
|
75 | ** port (22)
|
76 | ** username
|
77 | ** ...
|
78 |
|
79 |
|
80 | 3. The destination host configuration (based on the ssh host)
|
81 | Imagine you just connected to The host you want to connect to. (via host:port)
|
82 | now that server connects requires a target to tunnel to.
|
83 | Properties:
|
84 | ** dstHost (localhost)
|
85 | ** dstPort
|
86 |
|
87 |
|
88 | ### Config example
|
89 |
|
90 | ```js
|
91 |
|
92 | var config = {
|
93 | username:'root',
|
94 | host:sshServer,
|
95 | port:22,
|
96 | dstHost:destinationServer,
|
97 | dstPort:27017,
|
98 | localHost:'127.0.0.1',
|
99 | localPort: 27000
|
100 | };
|
101 |
|
102 | var tunnel = require('tunnel-ssh');
|
103 | tunnel(config, function (error, server) {
|
104 | //....
|
105 | });
|
106 | ```
|
107 | #### Sugar configuration
|
108 |
|
109 | In many cases host 1. and 2. are the same, for example if you want to connect to a database
|
110 | where the port from that database is bound to a local interface (127.0.0.1:27017)
|
111 | but you are able to connect via ssh (port 22 by default).
|
112 | You can skip the "dstHost" or the "host" configuration if they are the same.
|
113 | You can also skip the local configuration if you want to connect to localhost and
|
114 | the same port as "dstPort".
|
115 |
|
116 | ```js
|
117 |
|
118 | var config = {
|
119 | username:'root',
|
120 | dstHost:destinationServer,
|
121 | dstPort:27017
|
122 | };
|
123 |
|
124 | var tunnel = require('tunnel-ssh');
|
125 | tunnel(config, function (error, server) {
|
126 | //....
|
127 | });
|
128 | ```
|
129 |
|
130 | #### More configuration options
|
131 | tunnel-ssh pipes the configuration direct into the ssh2 library so every config option
|
132 | provided by ssh2 still works.
|
133 |
|
134 | Common examples are:
|
135 | ```js
|
136 |
|
137 | var config = {
|
138 | agent : process.env.SSH_AUTH_SOCK, // enabled by default
|
139 | privateKey:require('fs').readFileSync('/here/is/my/key'),
|
140 | password:'secret'
|
141 | }
|
142 |
|
143 | ```
|
144 |
|
145 | ####catch errors:
|
146 | ```js
|
147 | var tunnel = require('tunnel-ssh');
|
148 | //map port from remote 3306 to localhost 3306
|
149 | var server = tunnel({host: '172.16.0.8', dstPort: 3306}, function (error, server) {
|
150 | if(error){
|
151 | //catch configuration and startup errors here.
|
152 | }
|
153 | });
|
154 |
|
155 | // Use a listener to handle errors outside the callback
|
156 | server.on('error', function(err){
|
157 | console.error('Something bad happened:', err);
|
158 | });
|
159 | ```
|