|pyversions| |license|

作者: Pahaz_

仓库: https://github.com/pahaz/sshtunnel/

灵感来源于 https://github.com/jmagnusson/bgtunnel，但其在 Windows 上无法运行。

另见：https://github.com/paramiko/paramiko/blob/master/demos/forward.py

要求

paramiko_

安装

sshtunnel_ 托管在 PyPI 上，所以直接运行：

pip install sshtunnel

或者 ::

easy_install sshtunnel

或者 ::

conda install -c conda-forge sshtunnel

即可在您的环境中安装。

如需从源码安装，克隆 仓库 <https://github.com/pahaz/sshtunnel>_ 并运行：::

python setup.py install

测试包

若要运行测试，您首先需要安装 tox <https://testrun.org/tox/latest/>_，然后运行：::

python setup.py test

使用场景

sshtunnel 的典型应用场景之一如下图所示。用户可能需要连接远程服务器的某个端口（例如 8080），而该服务器只有 SSH 端口（通常是端口 22）可达。 ::

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

                            |
-------------+              |    +----------+
    LOCAL    |              |    |  REMOTE  | :22 SSH
    CLIENT   | <== SSH ========> |  SERVER  | :8080 web service
-------------+              |    +----------+
                            |
                         FIREWALL (only port 22 is open)

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

图1: 如何通过 SSH 隧道连接到被防火墙阻挡的服务。

如果 SSH 服务器允许，还可以访问一个从外部（LOCAL CLIENT 的角度）不可见的私有服务器（从 REMOTE SERVER 的角度看）。 ::

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

                            |
-------------+              |    +----------+               +---------
    LOCAL    |              |    |  REMOTE  |               | PRIVATE
    CLIENT   | <== SSH ========> |  SERVER  | <== local ==> | SERVER
-------------+              |    +----------+               +---------
                            |
                         FIREWALL (only port 443 is open)

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

图2: 如何通过 SSH 隧道连接到 PRIVATE SERVER。

使用示例

API 允许初始化隧道并启动，或使用 with 上下文管理，后者会自动处理隧道的启动和停止：

示例 1

以下代码对应上图图1，远程服务器地址为 pahaz.urfuclub.ru，使用密码认证并随机分配本地绑定端口。

.. code-block:: python

from sshtunnel import SSHTunnelForwarder

server = SSHTunnelForwarder(
    'alfa.8iq.dev',
    ssh_username="pahaz",
    ssh_password="secret",
    remote_bind_address=('127.0.0.1', 8080)
)

server.start()

print(server.local_bind_port)  # 显示分配的本地端口
# 通过 `server.local_bind_port` 与 `SECRET SERVICE` 工作

server.stop()

示例 2

以下示例演示将端口转发到无法直接访问的私有服务器，假设使用密码保护的私钥认证、远程服务器 SSH 服务监听在端口 443 且该端口已在防火墙中开放（图2）：

.. code-block:: python

import paramiko
import sshtunnel

with sshtunnel.open_tunnel(
    (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)
    # 通过 client 会话执行某些操作
    client.close()

print('FINISH!')

示例 3

将端口转发到 Vagrant MySQL 本地端口的示例：

.. code-block:: python

from sshtunnel import open_tunnel
from time import sleep

with open_tunnel(
    ('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:
        # 按 Ctrl-C 停止
        sleep(1)

print('FINISH!')

或直接使用 CLI：

.. code-block:: console

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

示例 4

通过两个隧道跳转打开 SSH 会话。SSH 传输和隧道将以守护进程模式运行，关闭时不会等待连接停止。

.. code-block:: python

import sshtunnel
from paramiko import SSHClient


with sshtunnel.open_tunnel(
    ssh_address_or_host=('GW1_ip', 20022),
    remote_bind_address=('GW2_ip', 22),
) as tunnel1:
    print('连接 tunnel1 (GW1_ip:GW1_port) 成功...')
    with sshtunnel.open_tunnel(
        ssh_address_or_host=('localhost', tunnel1.local_bind_port),
        remote_bind_address=('target_ip', 22),
        ssh_username='GW2_user',
        ssh_password='GW2_pwd',
    ) as tunnel2:
        print('连接 tunnel2 (GW2_ip:GW2_port) 成功...')
        with SSHClient() as ssh:
            ssh.connect('localhost',
                port=tunnel2.local_bind_port,
                username='target_user',
                password='target_pwd',
            )
            ssh.exec_command(...)

CLI 使用

$ sshtunnel --help
usage: sshtunnel [-h] [-U SSH_USERNAME] [-p SSH_PORT] [-P SSH_PASSWORD] -R
                 IP:PORT [IP:PORT ...] [-L [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 ...]]
                 ssh_address

Pure python ssh tunnel utils
Version 0.4.0

positional arguments:
  ssh_address           SSH 服务器 IP 地址（SSH 隧道的网关）
                        若紧跟在 -R 或 -L 之后，请使用 "-- ssh_address" 设置

options:
  -h, --help            显示此帮助信息并退出
  -U SSH_USERNAME, --username SSH_USERNAME
                        SSH 服务器账户用户名
  -p SSH_PORT, --server_port SSH_PORT
                        SSH 服务器 TCP 端口（默认：22）
  -P SSH_PASSWORD, --password SSH_PASSWORD
                        SSH 服务器账户密码
  -R IP:PORT [IP:PORT ...], --remote_bind_address IP:PORT [IP:PORT ...]
                        远程绑定地址序列：ip_1:port_1 ip_2:port_2 ... ip_n:port_n
                        等价于 ssh -Lxxxx:IP_ADDRESS:PORT
                        如果省略端口，默认为 22。
                        示例：-R 10.10.10.10: 10.10.10.10:5900
  -L [IP:PORT ...], --local_bind_address [IP:PORT ...]
                        本地绑定地址序列：ip_1:port_1 ip_2:port_2 ... ip_n:port_n
                        元素也可以是有效的 UNIX 套接字域：
                        /tmp/foo.sock /tmp/bar.sock ... /tmp/baz.sock
                        等价于 ssh -LPORT:xxxxxxxxx:xxxx，本地 IP 地址可选。
                        默认监听所有接口（0.0.0.0）并随机选择端口。
                        示例：-L :40000
  -k SSH_HOST_KEY, --ssh_host_key SSH_HOST_KEY
                        网关的主机密钥
  -K KEY_FILE, --private_key_file KEY_FILE
                        RSA/DSS/ECDSA 私钥文件
  -S KEY_PASSWORD, --private_key_password KEY_PASSWORD
                        RSA/DSS/ECDSA 私钥密码
  -t, --threaded        允许同时连接每个隧道
  -v, --verbose         增加输出详细程度（默认：ERROR）
  -V, --version         显示版本号并退出
  -x IP:PORT, --proxy IP:PORT
                        目标 SSH 代理的 IP 和端口
  -c SSH_CONFIG_FILE, --config SSH_CONFIG_FILE
                        SSH 配置文件，默认为 ~/.ssh/config
  -z, --compress        请求服务器对 SSH 传输进行压缩
  -n, --noagent         禁止从 SSH 代理中查找密钥
  -d [FOLDER ...], --host_pkey_directories [FOLDER ...]
                        可找到 SSH 私钥（格式为 `id_*`）的目录列表

.. _Pahaz: 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: 文档状态 .. |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

sshtunnel

最受欢迎

要求

安装

测试包

使用场景

使用示例

示例 1

示例 2

示例 3

示例 4

CLI 使用