1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
|
Metadata-Version: 1.1
Name: sshtunnel
Version: 0.1.4
Summary: Pure python SSH tunnels
Home-page: https://github.com/pahaz/sshtunnel
Author: Pahaz Blinov
Author-email: pahaz.blinov@gmail.com
License: MIT
Download-URL: https://pypi.python.org/packages/source/s/sshtunnel/sshtunnel-0.1.4.zip
Description-Content-Type: UNKNOWN
Description: |CircleCI| |AppVeyor| |readthedocs| |coveralls| |version|
|pyversions| |license|
**Author**: `Pahaz Blinov`_
**Repo**: https://github.com/pahaz/sshtunnel/
Inspired by https://github.com/jmagnusson/bgtunnel, but it doesn't work on
Windows.
See also: https://github.com/paramiko/paramiko/blob/master/demos/forward.py
Requirements
-------------
* `paramiko`_
Installation
============
`sshtunnel`_ is on PyPI, so simply run:
::
pip install sshtunnel
or ::
easy_install sshtunnel
or ::
conda install -c conda-forge sshtunnel
to have it installed in your environment.
For installing from source, clone the
`repo <https://github.com/pahaz/sshtunnel>`_ and run::
python setup.py install
Testing the package
-------------------
In order to run the tests you first need
`tox <https://testrun.org/tox/latest/>`_ and run::
python setup.py test
Usage scenarios
===============
One of the typical scenarios where ``sshtunnel`` is helpful is depicted in the
figure below. User may need to connect a port of a remote server (i.e. 8080)
where only SSH port (usually port 22) is reachable. ::
----------------------------------------------------------------------
|
-------------+ | +----------+
LOCAL | | | REMOTE | :22 SSH
CLIENT | <== SSH ========> | SERVER | :8080 web service
-------------+ | +----------+
|
FIREWALL (only port 22 is open)
----------------------------------------------------------------------
**Fig1**: How to connect to a service blocked by a firewall through SSH tunnel.
If allowed by the SSH server, it is also possible to reach a private server
(from the perspective of ``REMOTE SERVER``) not directly visible from the
outside (``LOCAL CLIENT``'s perspective). ::
----------------------------------------------------------------------
|
-------------+ | +----------+ +---------
LOCAL | | | REMOTE | | PRIVATE
CLIENT | <== SSH ========> | SERVER | <== local ==> | SERVER
-------------+ | +----------+ +---------
|
FIREWALL (only port 443 is open)
----------------------------------------------------------------------
**Fig2**: How to connect to ``PRIVATE SERVER`` through SSH tunnel.
Usage examples
==============
API allows either initializing the tunnel and starting it or using a ``with``
context, which will take care of starting **and stopping** the tunnel:
Example 1
---------
Code corresponding to **Fig1** above follows, given remote server's address is
``pahaz.urfuclub.ru``, password authentication and randomly assigned local bind
port.
.. code-block:: py
from sshtunnel import SSHTunnelForwarder
server = SSHTunnelForwarder(
'pahaz.urfuclub.ru',
ssh_username="pahaz",
ssh_password="secret",
remote_bind_address=('127.0.0.1', 8080)
)
server.start()
print(server.local_bind_port) # show assigned local port
# work with `SECRET SERVICE` through `server.local_bind_port`.
server.stop()
Example 2
---------
Example of a port forwarding to a private server not directly reachable,
assuming password protected pkey authentication, remote server's SSH service is
listening on port 443 and that port is open in the firewall (**Fig2**):
.. code-block:: py
import paramiko
from sshtunnel import SSHTunnelForwarder
with SSHTunnelForwarder(
(REMOTE_SERVER_IP, 443),
ssh_username="",
ssh_pkey="/var/ssh/rsa_key",
ssh_private_key_password="secret",
remote_bind_address=(PRIVATE_SERVER_IP, 22),
local_bind_address=('0.0.0.0', 10022)
) as tunnel:
client = paramiko.SSHClient()
client.load_system_host_keys()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect('127.0.0.1', 10022)
# do some operations with client session
client.close()
print('FINISH!')
Example 3
---------
Example of a port forwarding for the Vagrant MySQL local port:
.. code-block:: py
from sshtunnel import SSHTunnelForwarder
from time import sleep
with SSHTunnelForwarder(
('localhost', 2222),
ssh_username="vagrant",
ssh_password="vagrant",
remote_bind_address=('127.0.0.1', 3306)
) as server:
print(server.local_bind_port)
while True:
# press Ctrl-C for stopping
sleep(1)
print('FINISH!')
Or simply using the CLI:
.. code-block:: console
(bash)$ python -m sshtunnel -U vagrant -P vagrant -L :3306 -R 127.0.0.1:3306 -p 2222 localhost
CLI usage
=========
::
$ sshtunnel --help
usage: sshtunnel [-h] [-U SSH_USERNAME] [-p SSH_PORT] [-P SSH_PASSWORD] -R
IP:PORT [IP:PORT ...] [-L [IP:PORT [IP:PORT ...]]]
[-k SSH_HOST_KEY] [-K KEY_FILE] [-S KEY_PASSWORD] [-t] [-v]
[-V] [-x IP:PORT] [-c SSH_CONFIG_FILE] [-z] [-n] [-d [FOLDER [FOLDER ...]]]
ssh_address
Pure python ssh tunnel utils
Version 0.1.4
positional arguments:
ssh_address SSH server IP address (GW for SSH tunnels)
set with "-- ssh_address" if immediately after -R or -L
optional arguments:
-h, --help show this help message and exit
-U SSH_USERNAME, --username SSH_USERNAME
SSH server account username
-p SSH_PORT, --server_port SSH_PORT
SSH server TCP port (default: 22)
-P SSH_PASSWORD, --password SSH_PASSWORD
SSH server account password
-R IP:PORT [IP:PORT ...], --remote_bind_address IP:PORT [IP:PORT ...]
Remote bind address sequence: ip_1:port_1 ip_2:port_2 ... ip_n:port_n
Equivalent to ssh -Lxxxx:IP_ADDRESS:PORT
If port is omitted, defaults to 22.
Example: -R 10.10.10.10: 10.10.10.10:5900
-L [IP:PORT [IP:PORT ...]], --local_bind_address [IP:PORT [IP:PORT ...]]
Local bind address sequence: ip_1:port_1 ip_2:port_2 ... ip_n:port_n
Elements may also be valid UNIX socket domains:
/tmp/foo.sock /tmp/bar.sock ... /tmp/baz.sock
Equivalent to ssh -LPORT:xxxxxxxxx:xxxx, being the local IP address optional.
By default it will listen in all interfaces (0.0.0.0) and choose a random port.
Example: -L :40000
-k SSH_HOST_KEY, --ssh_host_key SSH_HOST_KEY
Gateway's host key
-K KEY_FILE, --private_key_file KEY_FILE
RSA/DSS/ECDSA private key file
-S KEY_PASSWORD, --private_key_password KEY_PASSWORD
RSA/DSS/ECDSA private key password
-t, --threaded Allow concurrent connections to each tunnel
-v, --verbose Increase output verbosity (default: ERROR)
-V, --version Show version number and quit
-x IP:PORT, --proxy IP:PORT
IP and port of SSH proxy to destination
-c SSH_CONFIG_FILE, --config SSH_CONFIG_FILE
SSH configuration file, defaults to ~/.ssh/config
-z, --compress Request server for compression over SSH transport
-n, --noagent Disable looking for keys from an SSH agent
-d [FOLDER [FOLDER ...]], --host_pkey_directories [FOLDER [FOLDER ...]]
List of directories where SSH pkeys (in the format `id_*`) may be found
.. _Pahaz Blinov: https://github.com/pahaz
.. _sshtunnel: https://pypi.python.org/pypi/sshtunnel
.. _paramiko: http://www.paramiko.org/
.. |CircleCI| image:: https://circleci.com/gh/pahaz/sshtunnel.svg?style=svg
:target: https://circleci.com/gh/pahaz/sshtunnel
.. |AppVeyor| image:: https://ci.appveyor.com/api/projects/status/oxg1vx2ycmnw3xr9?svg=true&passingText=Windows%20-%20OK&failingText=Windows%20-%20Fail
:target: https://ci.appveyor.com/project/pahaz/sshtunnel
.. |readthedocs| image:: https://readthedocs.org/projects/sshtunnel/badge/?version=latest
:target: http://sshtunnel.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |coveralls| image:: https://coveralls.io/repos/github/pahaz/sshtunnel/badge.svg?branch=master
:target: https://coveralls.io/github/pahaz/sshtunnel?branch=master
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/sshtunnel.svg
.. |version| image:: https://img.shields.io/pypi/v/sshtunnel.svg
:target: `sshtunnel`_
.. |license| image:: https://img.shields.io/pypi/l/sshtunnel.svg
:target: https://github.com/pahaz/sshtunnel/blob/master/LICENSE
Online documentation
====================
Documentation may be found at `readthedocs`_.
.. _readthedocs: https://sshtunnel.readthedocs.org/
CONTRIBUTORS
============
- `Cameron Maske`_
- `Gustavo Machado`_
- `Colin Jermain`_
- `JM Fernández`_ - (big thanks!)
- `Lewis Thompson`_
- `Erik Rogers`_
- `Mart Sõmermaa`_
- `Chronial`_
- `Dan Harbin`_
- `Ignacio Peluffo`_
- `Niels Zeilemaker`_
CHANGELOG
=========
- v.0.1.4 (`Niels Zeilemaker`_)
+ Allow loading pkeys from `~/.ssh`
- v.0.1.3 (`Ignacio Peluffo`_ and others)
+ ``pkey_file`` parameter updated to accept relative paths to user folder using ``~``
+ Several bugfixes
- v.0.1.2 (`JM Fernández`_)
+ Fix #77
- v.0.1.1 (`JM Fernández`_)
+ Fix #72
- v.0.1.0 (`JM Fernández`_)
+ Add `tunnel_bindings` property
+ Several bugfixes (#49, #56, #57, #59, #60, #62, #64, #66, ...)
(`Pahaz Blinov`_, `JM Fernández`_)
+ Add TRACE logging level (`JM Fernández`_)
+ Code and tests refactoring (`JM Fernández`_)
+ Drop python3.2 support
- v.0.0.8 (`JM Fernández`_)
+ Merge `#31`_: Support Unix domain socket (local) forwarding (`Dan Harbin`_)
+ Simplify API (`JM Fernández`_)
+ Add sphinx-based documentation (`JM Fernández`_)
+ Add ``allow_agent`` (fixes `#36`_, `#46`_) (`JM Fernández`_)
+ Add ``compression`` (`JM Fernández`_)
+ Add ``__str__`` method (`JM Fernández`_)
+ Add test functions (`JM Fernández`_)
+ Fix default username when not provided and ssh_config file is skipped (`JM Fernández`_)
+ Fix gateway IP unresolvable exception catching (`JM Fernández`_)
+ Minor fixes (`JM Fernández`_)
+ Add AppVeyor support (`JM Fernández`_)
- v.0.0.7 (`JM Fernández`_)
+ Tunnels can now be stopped and started safely (`#41`_) (`JM Fernández`_)
+ Add timeout to SSH gateway and keep-alive messages (`#29`_) (`JM Fernández`_)
+ Allow sending a pkey directly (`#43`_) (`Chronial`_)
+ Add ``-V`` CLI option to show current version (`JM Fernández`_)
+ Add coverage (`JM Fernández`_)
+ Refactoring (`JM Fernández`_)
- v.0.0.6 (`Pahaz Blinov`_)
+ add ``-S`` CLI options for ssh private key password support (`Pahaz Blinov`_)
- v.0.0.5 (`Pahaz Blinov`_)
+ add ``ssh_proxy`` argument, as well as ``ssh_config(5)`` ``ProxyCommand`` support (`Lewis Thompson`_)
+ add some python 2.6 compatibility fixes (`Mart Sõmermaa`_)
+ ``paramiko.transport`` inherits handlers of loggers passed to ``SSHTunnelForwarder`` (`JM Fernández`_)
+ fix `#34`_, `#33`_, code style and docs (`JM Fernández`_)
+ add tests (`Pahaz Blinov`_)
+ add CI integration (`Pahaz Blinov`_)
+ normal packaging (`Pahaz Blinov`_)
+ disable check distenation socket connection by ``SSHTunnelForwarder.local_is_up`` (`Pahaz Blinov`_) [changed default behavior]
+ use daemon mode = False in all threads by default; detail_ (`Pahaz Blinov`_) [changed default behavior]
- v.0.0.4.4 (`Pahaz Blinov`_)
+ fix issue `#24`_ - hide ssh password in logs (`Pahaz Blinov`_)
- v.0.0.4.3 (`Pahaz Blinov`_)
+ fix default port issue `#19`_ (`Pahaz Blinov`_)
- v.0.0.4.2 (`Pahaz Blinov`_)
+ fix Thread.daemon mode for Python < 3.3 `#16`_, `#21`_ (`Lewis Thompson`_, `Erik Rogers`_)
- v.0.0.4.1 (`Pahaz Blinov`_)
+ fix CLI issues `#13`_ (`Pahaz Blinov`_)
- v.0.0.4 (`Pahaz Blinov`_)
+ daemon mode by default for all threads (`JM Fernández`_, `Pahaz Blinov`_) - *incompatible*
+ move ``make_ssh_forward_server`` to ``SSHTunnelForwarder.make_ssh_forward_server`` (`Pahaz Blinov`_, `JM Fernández`_) - *incompatible*
+ move ``make_ssh_forward_handler`` to ``SSHTunnelForwarder.make_ssh_forward_handler_class`` (`Pahaz Blinov`_, `JM Fernández`_) - *incompatible*
+ rename ``open`` to ``open_tunnel`` (`JM Fernández`_) - *incompatible*
+ add CLI interface (`JM Fernández`_)
+ support opening several tunnels at once (`JM Fernández`_)
+ improve stability and readability (`JM Fernández`_, `Pahaz Blinov`_)
+ improve logging (`JM Fernández`_, `Pahaz Blinov`_)
+ add ``raise_exception_if_any_forwarder_have_a_problem`` argument for opening several tunnels at once (`Pahaz Blinov`_)
+ add ``ssh_config_file`` argument support (`JM Fernández`_)
+ add Python 3 support (`JM Fernández`_, `Pahaz Blinov`_)
- v.0.0.3 (`Pahaz Blinov`_)
+ add ``threaded`` option (`Cameron Maske`_)
+ fix exception error message, correctly printing destination address (`Gustavo Machado`_)
+ fix ``pip install`` failure (`Colin Jermain`_, `Pahaz Blinov`_)
- v.0.0.1 (`Pahaz Blinov`_)
+ ``SSHTunnelForwarder`` class (`Pahaz Blinov`_)
+ ``open`` function (`Pahaz Blinov`_)
.. _Cameron Maske: https://github.com/cameronmaske
.. _Gustavo Machado: https://github.com/gdmachado
.. _Colin Jermain: https://github.com/cjermain
.. _JM Fernández: https://github.com/fernandezcuesta
.. _Lewis Thompson: https://github.com/lewisthompson
.. _Erik Rogers: https://github.com/ewrogers
.. _Mart Sõmermaa: https://github.com/mrts
.. _Chronial: https://github.com/Chronial
.. _Dan Harbin: https://github.com/RasterBurn
.. _Ignacio Peluffo: https://github.com/ipeluffo
.. _Niels Zeilemaker: https://github.com/NielsZeilemaker
.. _#13: https://github.com/pahaz/sshtunnel/issues/13
.. _#16: https://github.com/pahaz/sshtunnel/issues/16
.. _#19: https://github.com/pahaz/sshtunnel/issues/19
.. _#21: https://github.com/pahaz/sshtunnel/issues/21
.. _#24: https://github.com/pahaz/sshtunnel/issues/24
.. _#29: https://github.com/pahaz/sshtunnel/issues/29
.. _#31: https://github.com/pahaz/sshtunnel/issues/31
.. _#33: https://github.com/pahaz/sshtunnel/issues/33
.. _#34: https://github.com/pahaz/sshtunnel/issues/34
.. _#36: https://github.com/pahaz/sshtunnel/issues/36
.. _#41: https://github.com/pahaz/sshtunnel/issues/41
.. _#43: https://github.com/pahaz/sshtunnel/issues/43
.. _#46: https://github.com/pahaz/sshtunnel/issues/46
.. _detail: https://github.com/pahaz/sshtunnel/commit/64af238b799b0e0057c4f9b386cda247e0006da9#diff-76bc1662a114401c2954deb92b740081R127
Keywords: ssh tunnel paramiko proxy tcp-forward
Platform: unix
Platform: macos
Platform: windows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
|
