```
_____ _ _____ _
/__ \_ _ _ __| |__ ___/__ \_ _ _ __ _ __ ___| |
/ /\/ | | | '__| '_ \ / _ \ / /\/ | | | '_ \| '_ \ / _ \ |
/ / | |_| | | | |_) | (_) / / | |_| | | | | | | | __/ |
\/ \__,_|_| |_.__/ \___/\/ \__,_|_| |_|_| |_|\___|_|
```
[](https://pypi.python.org/pypi/turbo-tunnel/)
[](https://codecov.io/github/drunkdream/turbo-tunnel)
[中文 README](./README_zh.md)
## Runtime Environment
- Operating System： `Windows`、`Linux`、`MacOS`
- Python: `>=3.5`
## Primary Function
- Provide access to various tunnel / proxy services
- Supported tunnel / proxy service types：`https`/`socks4`/`socks5`/`websocket`/`ssh`/`icmp`/`k8s`
- The types of tunnel / proxy services supported to create：`https`/`socks4`/`socks5`/`websocket`/`ssh`
- Support TCP port forwarding and SSL port forwarding
- It supports specifying different policies through configuration file, allowing access different services through different tunnel / proxy services
## Installation
```bash
python3 -m pip install turbo-tunnel
```
## Basic Functions
Detail in [Document](https://ttun.top/)
### Port Forwarding
```bash
turbo-tunnel -l tcp://127.0.0.1:8080 -t tcp://www.qq.com:443
```
This command can forward `www.qq.com:443` to local `8080` port.
```bash
turbo-tunnel -l tcp://127.0.0.1:8080 -t http://web-proxy.com:8080 -t tcp://www.qq.com:443
```
This command can forward `www.qq.com:443` to local `8080` port through `https` proxy `web-proxy.com:8080`.
If address is not specified, default is `0.0.0.0`.
### Create Tunnel Server
Use `-l` or `--listen` parameter to create a tunnel server.
- Create https proxy tunnel server
```bash
turbo-tunnel -l http://username:password@:8080
```
The variable `username` and `password` is used for authentication. If username and password not specified, authentication will be disabled. If the password include special characters, it should be encoded by `urlencode`. For example, `pwd@123` should be encoded to `pwd%40123`.
- Create socks4 proxy tunnel server
```bash
turbo-tunnel -l socks4://userid@127.0.0.1:1080
```
`socks4://` can also replaced by `socks://`，because `socks4` is the default socks protocol.
`userid` is used for authentication.
- Create WebSocket proxy tunnel server
```bash
turbo-tunnel -l ws://username:password@127.0.0.1/proxy/{addr}/{port}
```
`{addr}`and `{port}` are variable placeholders here, which are used to indicate the parameters of target address and target port. This is due to the WebSocket protocol is not a native proxy protocol, which need specil fields to indicate these information. For example, if the user want to visit `1.1.1.1:8888`, turbo-tunnel will create request path `/proxy/1.1.1.1/8888` dynamically.
User can change the path to different formats, such as `/proxy-{addr}-{port}`.
> The client and server `MUST` use the same format.
The `wss` protocol is not supported currently, user can run wss server with `nginx`.
### Config Tunnel Client
With `-t` or `--tunnel` param, turbo-tunnel process can access target server through specified tunnel, default is direct connection.
- Config single tunnel
```bash
turbo-tunnel -l http://127.0.0.1:8080 -t wss://username:password@proxy.com/{addr}/{port}
```
All requests to the https proxy server will be forwarded to the `WebSocket` tunnel server.
> This method can be used to convert tunnel protocol.
- Config multiple tunnels
```bash
turbo-tunnel -l http://127.0.0.1:8080 -t socks://10.1.1.1:1080 -t ssh://username:password@10.2.2.2:22
```
When multiple channels configured, the tunnel will be nested. So data packet can cross all tunnels in turn and access the target service.
### Config global transparent proxy
When proxy server is created, program is expected to access network through proxy automatically. This problem can bed solved by configing global transparent proxy.
- Windows & MacOS can use `Proxifier` tool to config various rules, different rule will be selected to access different server.
- Linux can use `proxychains` tool, which is like `Proxifier`, but can't config rule, and need to add `proxychains` before cmdline.
## Advanced Usage
### Config file
The user can use `-c` or `--config` param to specify a `yaml` format config file, which can config access rules.
Config file example:
```yaml
version: 1.0
listen: http://127.0.0.1:6666 # Listen address
hosts:
- domain: www.test.com
ip: 1.2.3.4
tunnels:
- id: direct
url: tcp://
default: true # Default is direct connect
- id: block
url: block:// # Forbidden rule
- id: web
url: http://web-proxy.com:8080
- id: private
url: wss://test:mypassword@ws-proxy.com/proxy/{addr}/{port}
dependency: web # Depend web tunnel
rules:
- id: local
priority: 100 # Priority, 1-100, highest priority rule will be selected when rule conflict
addr: 127.0.0.1
tunnel: direct
- id: internal
priority: 99
addr: "192.168.*"
port: 1-65535
tunnel: direct
- id: public
priority: 90
addr: "*"
port: 80;443;8080
tunnel: web # Access public network with web tunnel
- id: private
priority: 95
addr: "*.private.com"
port: 1-65535
tunnel: private
- id: test
priority: 90
addr: "*.baidu.com"
port: 80;443
tunnel: block # Connection will be blocked
```
### Extend plugin
turbo-tunnel is allowing users to develop their own plugins, which can support new proxy server or tunnel. They can also perform special operations, such as dynamically modify sending and receiving data.
Built-in plugins:
- terminal: Show current active connections
```bash
turbo-tunnel -l http://127.0.0.1:8080 -p terminal -p xxx
```
User can use `-p` or `--plugin` params to specify `1-N` plugins. Plugin load order is decided by `-p` params order.
### Docker
- build
```bash
# AMD64
docker buildx build --platform 'linux/amd64' -t turbo-tunnel:amd64 .
# ARM64
docker buildx build --platform 'linux/arm64' -t turbo-tunnel:arm64 .
# Multi
docker buildx create --use --platform=linux/arm64,linux/amd64 --name multi-platform-builder
docker buildx inspect --bootstrap
docker buildx build --platform 'linux/amd64,linux/arm64' -t turbo-tunnel:latest .
```
Raw data
{
"_id": null,
"home_page": "https://github.com/drunkdream/turbo-tunnel",
"name": "turbo-tunnel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": null,
"author": "drunkdream",
"author_email": "drunkdream@qq.com",
"download_url": "https://files.pythonhosted.org/packages/9d/37/83c20961b681047caa1aa48004d07043a364d391c232a50fba7c0b254cd8/turbo_tunnel-0.18.5.tar.gz",
"platform": null,
"description": "```\n _____ _ _____ _\n/__ \\_ _ _ __| |__ ___/__ \\_ _ _ __ _ __ ___| |\n / /\\/ | | | '__| '_ \\ / _ \\ / /\\/ | | | '_ \\| '_ \\ / _ \\ |\n / / | |_| | | | |_) | (_) / / | |_| | | | | | | | __/ |\n \\/ \\__,_|_| |_.__/ \\___/\\/ \\__,_|_| |_|_| |_|\\___|_|\n```\n\n[](https://pypi.python.org/pypi/turbo-tunnel/)\n\n[](https://codecov.io/github/drunkdream/turbo-tunnel)\n\n[\u4e2d\u6587 README](./README_zh.md)\n\n## Runtime Environment\n\n- Operating System\uff1a `Windows`\u3001`Linux`\u3001`MacOS`\n- Python: `>=3.5`\n\n## Primary Function\n\n- Provide access to various tunnel / proxy services\n- Supported tunnel / proxy service types\uff1a`https`/`socks4`/`socks5`/`websocket`/`ssh`/`icmp`/`k8s`\n- The types of tunnel / proxy services supported to create\uff1a`https`/`socks4`/`socks5`/`websocket`/`ssh`\n- Support TCP port forwarding and SSL port forwarding\n- It supports specifying different policies through configuration file, allowing access different services through different tunnel / proxy services\n\n## Installation\n\n```bash\npython3 -m pip install turbo-tunnel\n```\n\n## Basic Functions\n\nDetail in [Document](https://ttun.top/)\n\n### Port Forwarding\n\n```bash\nturbo-tunnel -l tcp://127.0.0.1:8080 -t tcp://www.qq.com:443\n```\n\nThis command can forward `www.qq.com:443` to local `8080` port.\n\n```bash\nturbo-tunnel -l tcp://127.0.0.1:8080 -t http://web-proxy.com:8080 -t tcp://www.qq.com:443\n```\n\nThis command can forward `www.qq.com:443` to local `8080` port through `https` proxy `web-proxy.com:8080`.\n\nIf address is not specified, default is `0.0.0.0`.\n\n### Create Tunnel Server\n\nUse `-l` or `--listen` parameter to create a tunnel server.\n\n- Create https proxy tunnel server\n\n```bash\nturbo-tunnel -l http://username:password@:8080\n```\n\nThe variable `username` and `password` is used for authentication. If username and password not specified, authentication will be disabled. If the password include special characters, it should be encoded by `urlencode`. For example, `pwd@123` should be encoded to `pwd%40123`.\n\n- Create socks4 proxy tunnel server\n\n```bash\nturbo-tunnel -l socks4://userid@127.0.0.1:1080\n```\n\n`socks4://` can also replaced by `socks://`\uff0cbecause `socks4` is the default socks protocol.\n\n`userid` is used for authentication.\n\n- Create WebSocket proxy tunnel server\n\n```bash\nturbo-tunnel -l ws://username:password@127.0.0.1/proxy/{addr}/{port}\n```\n\n`{addr}`and `{port}` are variable placeholders here, which are used to indicate the parameters of target address and target port. This is due to the WebSocket protocol is not a native proxy protocol, which need specil fields to indicate these information. For example, if the user want to visit `1.1.1.1:8888`, turbo-tunnel will create request path `/proxy/1.1.1.1/8888` dynamically.\n\nUser can change the path to different formats, such as `/proxy-{addr}-{port}`.\n\n> The client and server `MUST` use the same format.\n\nThe `wss` protocol is not supported currently, user can run wss server with `nginx`.\n\n### Config Tunnel Client\n\nWith `-t` or `--tunnel` param, turbo-tunnel process can access target server through specified tunnel, default is direct connection.\n\n- Config single tunnel\n\n```bash\nturbo-tunnel -l http://127.0.0.1:8080 -t wss://username:password@proxy.com/{addr}/{port}\n```\n\nAll requests to the https proxy server will be forwarded to the `WebSocket` tunnel server.\n\n> This method can be used to convert tunnel protocol.\n\n- Config multiple tunnels\n\n```bash\nturbo-tunnel -l http://127.0.0.1:8080 -t socks://10.1.1.1:1080 -t ssh://username:password@10.2.2.2:22\n```\n\nWhen multiple channels configured, the tunnel will be nested. So data packet can cross all tunnels in turn and access the target service.\n\n### Config global transparent proxy\n\nWhen proxy server is created, program is expected to access network through proxy automatically. This problem can bed solved by configing global transparent proxy.\n\n- Windows & MacOS can use `Proxifier` tool to config various rules, different rule will be selected to access different server.\n\n- Linux can use `proxychains` tool, which is like `Proxifier`, but can't config rule, and need to add `proxychains` before cmdline.\n\n## Advanced Usage\n\n### Config file\n\nThe user can use `-c` or `--config` param to specify a `yaml` format config file, which can config access rules.\n\nConfig file example:\n\n```yaml\nversion: 1.0\n\nlisten: http://127.0.0.1:6666 # Listen address\n\nhosts:\n - domain: www.test.com\n ip: 1.2.3.4\n\ntunnels:\n - id: direct\n url: tcp://\n default: true # Default is direct connect\n\n - id: block\n url: block:// # Forbidden rule\n\n - id: web\n url: http://web-proxy.com:8080\n\n - id: private\n url: wss://test:mypassword@ws-proxy.com/proxy/{addr}/{port}\n dependency: web # Depend web tunnel\n\nrules:\n - id: local\n priority: 100 # Priority, 1-100, highest priority rule will be selected when rule conflict\n addr: 127.0.0.1\n tunnel: direct\n\n - id: internal\n priority: 99\n addr: \"192.168.*\"\n port: 1-65535\n tunnel: direct\n\n - id: public\n priority: 90\n addr: \"*\"\n port: 80;443;8080\n tunnel: web # Access public network with web tunnel\n\n - id: private\n priority: 95\n addr: \"*.private.com\"\n port: 1-65535\n tunnel: private\n\n - id: test\n priority: 90\n addr: \"*.baidu.com\"\n port: 80;443\n tunnel: block # Connection will be blocked\n```\n\n### Extend plugin\n\nturbo-tunnel is allowing users to develop their own plugins, which can support new proxy server or tunnel. They can also perform special operations, such as dynamically modify sending and receiving data.\n\nBuilt-in plugins:\n\n- terminal: Show current active connections\n\n```bash\nturbo-tunnel -l http://127.0.0.1:8080 -p terminal -p xxx\n```\n\n\n\nUser can use `-p` or `--plugin` params to specify `1-N` plugins. Plugin load order is decided by `-p` params order.\n\n### Docker\n\n- build\n\n```bash\n# AMD64\ndocker buildx build --platform 'linux/amd64' -t turbo-tunnel:amd64 .\n\n# ARM64\ndocker buildx build --platform 'linux/arm64' -t turbo-tunnel:arm64 .\n\n# Multi\ndocker buildx create --use --platform=linux/arm64,linux/amd64 --name multi-platform-builder\ndocker buildx inspect --bootstrap\ndocker buildx build --platform 'linux/amd64,linux/arm64' -t turbo-tunnel:latest .\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Fast tcp/https/websocket/socks4/ssh tunnel serving as unified proxy server.",
"version": "0.18.5",
"project_urls": {
"Homepage": "https://github.com/drunkdream/turbo-tunnel"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a58fdaf9e623662373a61b21ccba14aa15c58fd6a0a175283dabfbb53e5738e",
"md5": "2d013bfe63f2b14d0d40d5c5e3f944fe",
"sha256": "063d139d2b37beff947cf4e5b27befbc3c884d835ca5a863a9971f795307712c"
},
"downloads": -1,
"filename": "turbo_tunnel-0.18.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d013bfe63f2b14d0d40d5c5e3f944fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 58815,
"upload_time": "2025-01-03T13:25:31",
"upload_time_iso_8601": "2025-01-03T13:25:31.710504Z",
"url": "https://files.pythonhosted.org/packages/4a/58/fdaf9e623662373a61b21ccba14aa15c58fd6a0a175283dabfbb53e5738e/turbo_tunnel-0.18.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9d3783c20961b681047caa1aa48004d07043a364d391c232a50fba7c0b254cd8",
"md5": "65fff21260507c73600251ee67beb862",
"sha256": "11763e9623bd10219ca9afe92479268157e47399eca1adaba0b91445ae7e455d"
},
"downloads": -1,
"filename": "turbo_tunnel-0.18.5.tar.gz",
"has_sig": false,
"md5_digest": "65fff21260507c73600251ee67beb862",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 59738,
"upload_time": "2025-01-03T13:25:33",
"upload_time_iso_8601": "2025-01-03T13:25:33.037222Z",
"url": "https://files.pythonhosted.org/packages/9d/37/83c20961b681047caa1aa48004d07043a364d391c232a50fba7c0b254cd8/turbo_tunnel-0.18.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-03 13:25:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "drunkdream",
"github_project": "turbo-tunnel",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "async_dns",
"specs": []
},
{
"name": "asyncssh",
"specs": [
[
">=",
"2.3.0"
],
[
"<",
"2.9.0"
]
]
},
{
"name": "cryptography",
"specs": [
[
"<",
"37.0.0"
]
]
},
{
"name": "msgpack",
"specs": []
},
{
"name": "python-daemon",
"specs": [
[
"==",
"2.3.2"
]
]
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "tornado",
"specs": [
[
"==",
"6.1"
]
]
}
],
"lcname": "turbo-tunnel"
}
JSON
