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 | ### Latest Relese 4.1.2
|
12 |
|
13 | ##Highlights
|
14 | * Updated packages to the latest versions
|
15 | * Add "npm test" for eslint and mocha
|
16 | * Password and PrivateKey are hidden when using Debug (DEBUG=tunnel-ssh-config)
|
17 |
|
18 | Special thanks to
|
19 | @vweevers and @dickeyxxx
|
20 |
|
21 |
|
22 | ### related projects
|
23 | * [If you don't want to wrap a tunnel around your code: inject-tunnel-ssh](https://github.com/agebrock/inject-tunnel-ssh)
|
24 | * [If you need it the other way around: reverse-tunnel-ssh](https://github.com/agebrock/reverse-tunnel-ssh)
|
25 |
|
26 | ### Integration
|
27 | 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.
|
28 | If you need the tunnel to stay open, use the "keepAlive:true" option within
|
29 | the configuration.
|
30 |
|
31 |
|
32 | ```js
|
33 |
|
34 | var config = {
|
35 | ...
|
36 | keepAlive:true
|
37 | };
|
38 |
|
39 | var tnl = tunnel(config, function(error, tnl){
|
40 | yourClient.connect();
|
41 | yourClient.disconnect();
|
42 | setTimeout(function(){
|
43 | // you only need to close the tunnel by yourself if you set the
|
44 | // keepAlive:true option in the configuration !
|
45 | tnl.close();
|
46 | },2000);
|
47 | });
|
48 |
|
49 | // you can also close the tunnel from here...
|
50 | setTimeout(function(){
|
51 | tnl.close();
|
52 | },2000);
|
53 |
|
54 | ```
|
55 |
|
56 |
|
57 | ## Understanding the configuration
|
58 |
|
59 | 1. A local server listening for connections to forward via ssh
|
60 | Description: This is where you bind your interface.
|
61 | Properties:
|
62 | ** localHost (default is '127.0.0.1')
|
63 | ** localPort (default is dstPort)
|
64 |
|
65 |
|
66 | 2. The ssh configuration
|
67 | Description: The host you want to use as ssh-tunnel server.
|
68 | Properties:
|
69 | ** host
|
70 | ** port (22)
|
71 | ** username
|
72 | ** ...
|
73 |
|
74 |
|
75 | 3. The destination host configuration (based on the ssh host)
|
76 | Imagine you just connected to The host you want to connect to. (via host:port)
|
77 | now that server connects requires a target to tunnel to.
|
78 | Properties:
|
79 | ** dstHost (localhost)
|
80 | ** dstPort
|
81 |
|
82 |
|
83 | ### Config example
|
84 |
|
85 | ```js
|
86 |
|
87 | var config = {
|
88 | username:'root',
|
89 | host:sshServer,
|
90 | port:22,
|
91 | dstHost:destinationServer,
|
92 | dstPort:27017,
|
93 | localHost:'127.0.0.1',
|
94 | localPort: 27000
|
95 | };
|
96 |
|
97 | var tunnel = require('tunnel-ssh');
|
98 | tunnel(config, function (error, server) {
|
99 | //....
|
100 | });
|
101 | ```
|
102 | #### Sugar configuration
|
103 |
|
104 | In many cases host 1. and 2. are the same, for example if you want to connect to a database
|
105 | where the port from that database is bound to a local interface (127.0.0.1:27017)
|
106 | but you are able to connect via ssh (port 22 by default).
|
107 | You can skip the "dstHost" or the "host" configuration if they are the same.
|
108 | You can also skip the local configuration if you want to connect to localhost and
|
109 | the same port as "dstPort".
|
110 |
|
111 | ```js
|
112 |
|
113 | var config = {
|
114 | username:'root',
|
115 | dstHost:destinationServer,
|
116 | dstPort:27017
|
117 | };
|
118 |
|
119 | var tunnel = require('tunnel-ssh');
|
120 | tunnel(config, function (error, server) {
|
121 | //....
|
122 | });
|
123 | ```
|
124 |
|
125 | #### More configuration options
|
126 | tunnel-ssh pipes the configuration direct into the ssh2 library so every config option
|
127 | provided by ssh2 still works.
|
128 |
|
129 | Common examples are:
|
130 | ```js
|
131 |
|
132 | var config = {
|
133 | agent : process.env.SSH_AUTH_SOCK, // enabled by default
|
134 | privateKey:require('fs').readFileSync('/here/is/my/key'),
|
135 | password:'secret'
|
136 | }
|
137 |
|
138 | ```
|
139 |
|
140 | ####catch errors:
|
141 | ```js
|
142 | var tunnel = require('tunnel-ssh');
|
143 | //map port from remote 3306 to localhost 3306
|
144 | var server = tunnel({host: '172.16.0.8', dstPort: 3306}, function (error, server) {
|
145 | if(error){
|
146 | //catch configuration and startup errors here.
|
147 | }
|
148 | });
|
149 |
|
150 | // Use a listener to handle errors outside the callback
|
151 | server.on('error', function(err){
|
152 | console.error('Something bad happened:', err);
|
153 | });
|
154 | ```
|