Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Pure python SSH tunnels

Project Description
|CircleCI| |AppVeyor| |readthedocs| |coveralls| |version|

|DwnMonth| |DwnWeek| |DwnDay|

|pyversions| |license|

**Author**: `Pahaz Blinov`_


Inspired by, but it doesn't work on

See also:


* `paramiko`_


`sshtunnel`_ is on PyPI, so simply run:


pip install sshtunnel

or ::

easy_install sshtunnel

to have it installed in your environment.

For installing from source, clone the
`repo <>`_ and run::

python install

Testing the package

In order to run the tests you first need
`tox <>`_ and run::

python 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). ::


-------------+ | +----------+ +---------
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
````, password authentication and randomly assigned local bind

.. code-block:: py

from sshtunnel import SSHTunnelForwarder

server = SSHTunnelForwarder(
remote_bind_address=('', 8080)


print(server.local_bind_port) # show assigned local port
# work with `SECRET SERVICE` through `server.local_bind_port`.


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_bind_address=(PRIVATE_SERVER_IP, 22),
local_bind_address=('', 10022)
) as tunnel:
client = paramiko.SSHClient()
client.connect('', 10022)
# do some operations with client session


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),
remote_bind_address=('', 3306)
) as server:

while True:
# press Ctrl-C for stopping


Or simply using the CLI:

.. code-block:: console

(bash)$ python -m sshtunnel -U vagrant -P vagrant -L :3306 -R -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 ...]]]
[-V] [-x IP:PORT] [-c SSH_CONFIG_FILE] [-z] [-n]

Pure python ssh tunnel utils

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
SSH server account username
-p SSH_PORT, --server_port SSH_PORT
SSH server TCP port (default: 22)
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
-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 ( 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
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

.. _Pahaz Blinov:
.. _sshtunnel:
.. _paramiko:
.. |CircleCI| image::
.. |AppVeyor| image::
.. |readthedocs| image::
:alt: Documentation Status
.. |coveralls| image::
.. |DwnMonth| image::
.. |DwnWeek| image::
.. |DwnDay| image::
.. |pyversions| image::
.. |version| image::
:target: `sshtunnel`_
.. |license| image::

Online documentation

Documentation may be found at `readthedocs`_.

.. _readthedocs:


- `Cameron Maske`_
- `Gustavo Machado`_
- `Colin Jermain`_
- `JM Fernández`_ - (big thanks!)
- `Lewis Thompson`_
- `Erik Rogers`_
- `Mart Sõmermaa`_
- `Chronial`_
- `Dan Harbin`_

- 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. (`Pahaz Blinov`_)
+ fix issue `#24`_ - hide ssh password in logs (`Pahaz Blinov`_)

- v. (`Pahaz Blinov`_)
+ fix default port issue `#19`_ (`Pahaz Blinov`_)

- v. (`Pahaz Blinov`_)
+ fix Thread.daemon mode for Python < 3.3 `#16`_, `#21`_ (`Lewis Thompson`_, `Erik Rogers`_)

- v. (`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:
.. _Gustavo Machado:
.. _Colin Jermain:
.. _JM Fernández:
.. _Lewis Thompson:
.. _Erik Rogers:
.. _Mart Sõmermaa:
.. _Chronial:
.. _Dan Harbin:
.. _#13:
.. _#16:
.. _#19:
.. _#21:
.. _#24:
.. _#29:
.. _#31:
.. _#33:
.. _#34:
.. _#36:
.. _#41:
.. _#43:
.. _#46:
.. _detail:
Release History

Release History

This version
History Node


History Node


History Node


History Node

History Node

History Node


History Node


History Node


History Node


History Node

History Node

History Node

History Node

History Node


History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sshtunnel-0.1.2.tar.gz (34.4 kB) Copy SHA256 Checksum SHA256 Source Oct 27, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting