Requirements

paramiko

Installation

sshtunnel is on PyPI, so simply run:

pip install sshtunnel

easy_install sshtunnel

to have it installed in your environment.

For installing from source, clone the repo and run:

python setup.py install

Testing the package

In order to run the tests you first need tox 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

----------------------------------------------------------------------

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

from sshtunnel import SSHTunnelForwarder

server = SSHTunnelForwarder(
    ('pahaz.urfuclub.ru', 22),
    ssh_username="pahaz",
    ssh_password="secret",
    remote_bind_address=('127.0.0.1', 5555)
)

server.start()

print(server.local_bind_port)
# work with `SECRET SERVICE` through `server.local_bind_port`.

server.stop()

Example 2

Example of a port forwarding for the Vagrant MySQL local port:

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:

$ python -m sshtunnel -U vagrant -P vagrant -L :3306 -R 127.0.0.1:3306 -p 2222 localhost

CLI usage

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]
                 ssh_address

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
  -U, --username SSH_USERNAME
                        SSH server account username
  -p, --server_port SSH_PORT
                        SSH server TCP port (default: 22)
  -P, --password SSH_PASSWORD
                        SSH server account password
  -R, --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 omitted, default port is 22.
                        Example: -R 10.10.10.10: 10.10.10.10:5900
  -L, --local_bind_address [IP:PORT [IP:PORT ...]]
                        Local bind address sequence: ip_1:port_1 ip_2:port_2 ... ip_n:port_n
                        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
                        Gateway's host key
  -K, --private_key_file KEY_FILE
                        RSA/DSS/ECDSA private key file
  -S, --private_key_file_password KEY_PASSWORD
                        RSA/DSS/ECDSA private key password
  -t, --threaded        Allow concurrent connections to each tunnel
  -v, --verbosity       Increase output verbosity (default: ERROR)
  -V, --version         Show version number and quit
  -x, --proxy IP:PORT   IP and por for SSH proxy to destination
  -c, --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

Online documentation

Documentation may be found at readthedocs.

CONTRIBUTORS

CHANGELOG

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)
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)

Metadata

Release files for sshtunnel 0.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sshtunnel 0.0.8
File	Size	Uploaded
sshtunnel-0.0.8.tar.gz	32.3 kB	Mar 8, 2016	Details

Release files / sshtunnel-0.0.8.tar.gz

Download URL	sshtunnel-0.0.8.tar.gz
Size	32.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`60c7ccd521562fb647d7204844476b97ec7eea811b5f53789e6aa39b791c0026`
BLAKE2b-256 checksum How to use checksums	`fe0e41977c19f6ff56ad74b79bd29a43adf5e31f72987eefe10bf8a4037471d9`
Upload date	Mar 8, 2016
Uploaded using Trusted Publishing? What is trusted publishing?	No