Skip to content

Commit 34e0f8e

Browse files
Sesame2Sesame2
committed
docs: 新增tun模式的功能与参数介绍
1 parent 65bbc00 commit 34e0f8e

File tree

2 files changed

+158
-36
lines changed

2 files changed

+158
-36
lines changed

‎README-CN.md‎

Lines changed: 71 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@
6868
- ✅ 支持多级跳板机 (Jump Host)，轻松穿透复杂网络
6969
- ✅ 支持跨平台运行（Windows / Linux / macOS）
7070
- ✅ 支持作为系统 HTTP 代理（可选扩展）
71+
- ✅ 支持 TUN 模式: 支持所有基于 TCP 协议的应用代理
7172
- ✅ 自定义路由规则: 支持通过自定义的规则文件进行流量分流
7273
- ✅ 命令行自动补全: 支持 Bash, Zsh, Fish, PowerShell
7374

@@ -157,18 +158,25 @@ gotun --socks5 :1080 user@example.com
157158

158159
| 参数 | 简写 | 说明 | 默认值 |
159160
|------|------|------|--------|
160-
| `--listen` | `-l` | 本地HTTP代理监听地址 | `:8080` |
161-
| `--port` | `-p` | SSH服务器端口 | `22` |
162-
| `--pass` | | SSH密码 (不安全, 建议使用交互式认证) | |
161+
| `--http` | | 本地 HTTP 代理监听地址 (别名 `--listen`) | `:8080` |
162+
| `--listen` | `-l` | [已废弃] 同 `--http` | `:8080` |
163+
| `--socks5` | | SOCKS5 代理监听地址 | `:1080` |
164+
| `--port` | `-p` | SSH 服务器端口 | `22` |
165+
| `--pass` | | SSH 密码 (不安全, 建议使用交互式认证) | |
163166
| `--identity_file` | `-i` | 用于认证的私钥文件路径 | |
164167
| `--jump` | `-J` | 跳板机列表,用逗号分隔 (格式: user@host:port) | |
165-
| `--target` | | 可选的目标网络覆盖 | |
166-
| `--socks5` | | SOCKS5 代理监听地址 | `:1080` |
168+
| `--http-upstream` | | 强制将所有 HTTP 请求转发到此上游 (格式: host:port) | |
169+
| `--target` | | [已废弃] 同 `--http-upstream` | |
167170
| `--timeout` | | 连接超时时间 | `10s` |
168171
| `--verbose` | `-v` | 启用详细日志 | `false` |
169172
| `--log` | | 日志文件路径 | 输出到标准输出 |
170173
| `--sys-proxy` | | 自动设置/恢复系统代理 | `true` |
171174
| `--rules` | | 代理规则配置文件路径 | |
175+
| `--tun` | | 启用 TUN 模式 (VPN 模式) | `false` |
176+
| `--tun-global` | `-g` | 启用全局 TUN 模式 (转发所有流量) | `false` |
177+
| `--tun-ip` | | TUN 设备 CIDR 地址 | `10.0.0.1/24` |
178+
| `--tun-route` | | 添加静态路由到 TUN (CIDR格式, 可多次使用) | |
179+
| `--tun-nat` | | NAT 映射规则 (格式: LocalCIDR:RemoteCIDR) | |
172180

173181
### 使用场景
174182

@@ -316,30 +324,75 @@ gotun --rules ./rules.yaml user@your_ssh_server.com
316324
现在，当您访问 `internal.company.com` 时，流量会直接发送；而访问 `google.com` 时，流量则会通过 SSH 隧道代理。
317325

318326

319-
### 故障排除
327+
### TUN 模式 (高级)
328+
329+
gotun 可以在本地创建一个虚拟网卡，将所有（或指定）TCP 流量拦截并通过 SSH 隧道透明传输。这使得不支持代理设置的软件也能通过 SSH 隧道访问远程资源。
330+
331+
#### 为什么使用 TUN 模式？
332+
333+
- **全应用代理**: 完美支持 **RDP 远程桌面**、**数据库连接** (MySQL/PostgreSQL)、**Redis** 等基于 TCP 的应用层协议。
334+
- **无需配置**: 启用全局模式后，所有 TCP 流量自动走代理，无需在软件中逐个配置代理。
335+
- **网络映射**: 可以将远程内网的整个网段映射到本地，解决本地与远程网段冲突的问题。
336+
337+
> **⚠️ 注意**: 当前版本的 TUN 模式仅支持 **TCP 协议**。不支持 UDP 流量和 ICMP 协议（因此无法使用 `ping` 命令测试连通性，请使用 `telnet` 或 `nc -vz` 测试 TCP 端口）。
338+
339+
#### 核心参数
340+
341+
| 参数 | 简写 | 说明 |
342+
|------|------|------|
343+
| `--tun` | | 显式启用 TUN 模式 (通常配合路由参数自动启用，可省略) |
344+
| `--tun-global` | `-g` | **全局模式**：接管本机所有网络流量 (自动处理网关防止 SSH 断连) |
345+
| `--tun-route` | | **指定网段代理**：仅将指定网段路由到 TUN (支持 CIDR，可多次使用) |
346+
| `--tun-nat` | | **NAT 网段映射**：将本地网段映射到远程网段 (格式 `LocalCIDR:RemoteCIDR`) |
347+
| `--tun-ip` | | 指定 TUN 设备的内部 IP (默认 `10.0.0.1/24`) |
348+
349+
#### 使用示例
350+
351+
**1. 全局模式**
352+
353+
将本机所有流量通过远程服务器转发。
320354

321-
#### 连接问题
355+
> **⚠️ 警告**: 启动虚拟网卡可能会与 Clash、ZeroTier 等同样操作网卡或路由表的软件产生冲突。请谨慎使用全局 TUN 模式，建议优先使用指定网段代理模式。
322356

323357
```bash
324-
# 启用详细日志进行调试
325-
gotun -v user@example.com
358+
# -g 自动启用 TUN 模式
359+
sudo gotun -g user@server.com
360+
```
361+
362+
**2. 指定网段代理**
363+
364+
仅将指定网段的流量放入隧道，其他流量直连。例如，只有访问 `10.0.0.0/24` 网段的流量才通过 SSH 隧道：
326365

327-
# 指定日志文件
328-
gotun -v --log ./gotun.log user@example.com
366+
```bash
367+
# 访问 10.0.0.x 的流量走 SSH，其他走本地
368+
sudo gotun --tun-route 10.0.0.0/24 user@server.com
329369
```
330370

331-
#### 权限问题
371+
**3. NAT 网段映射**
332372

333-
在某些系统上设置系统代理需要管理员权限：
373+
解决网段冲突问题。例如：你需要访问的远程目标网段为 `192.168.0.0/24`，但你本地也有物理网卡或其他网络环境使用了 `192.168.0.0/24`。为了避免冲突，可以将远程的 `192.168.0.0/24` 映射到本地的一个无冲突网段（如 `10.0.0.0/24`）。
334374

335375
```bash
336-
# macOS/Linux
337-
sudo gotun user@example.com
376+
# 访问本地 10.0.0.1 -> 自动 NAT 到远程 192.168.0.1
377+
sudo gotun --tun-nat 10.0.0.0/24:192.168.0.0/24 user@server.com
378+
```
379+
380+
> **注意**:
381+
> - **权限**: TUN 模式需要 `sudo` (macOS/Linux) 或管理员权限 (Windows)。
382+
> - **Windows 用户**: 首次运行时会自动释放 `wintun.dll`，无需手动安装驱动。
338383

339-
# Windows (以管理员身份运行 PowerShell/CMD)
340-
.\gotun.exe user@example.com
384+
**4. RDP 远程桌面连接示例**
385+
386+
场景：你需要远程桌面连接到位于 `192.168.2.0/24` 网段的 Windows 机器（IP: `192.168.2.1`），但该网段无法直接访问。你有一台位于同一网段的 Linux 服务器（IP: `192.168.2.2`）开启了 SSH 服务。
387+
388+
```bash
389+
# 将 192.168.2.0/24 网段的流量通过 SSH 隧道转发
390+
sudo gotun --tun-route 192.168.2.0/24 user@192.168.2.2
341391
```
342392

393+
启动后，你就可以直接打开 Windows 远程桌面客户端，输入 `192.168.2.1` 进行连接，就像你在同一个局域网内一样。
394+
395+
343396
---
344397

345398

@@ -357,7 +410,7 @@ sudo gotun user@example.com
357410
- [x] **自定义路由规则**: 支持自定义的规则文件进行流量分流
358411
- [x] **命令行自动补全**: 基于 Cobra 的智能提示
359412
- [x] **SOCKS5 代理支持**: 更广泛的协议支持
360-
- [ ] **RDP网关**：支持RDP远程桌面网关
413+
- [x] **TUN 模式**: L3 级 VPN 支持 (全局/规则/NAT)
361414
- [ ] **托盘 GUI 界面**: 图形化用户界面
362415
- [ ] **配置文件导出/导入**: 配置管理功能
363416
- [ ] **连接池优化**: 提升性能和稳定性

‎README.md‎

Lines changed: 87 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ Your machine SSH (tcp/22) Bastion I
7070
- Supports single and multi-hop SSH jump hosts
7171
- Cross-platform: Windows, Linux, macOS
7272
- Can be used as a system HTTP proxy (optional)
73+
- **TUN Mode**: Supports standard TCP-based application proxying
7374
- Rule-based traffic splitting via configuration file
7475
- Shell completion support for Bash, Zsh, Fish, PowerShell
7576
- Structured logging and verbose mode for debugging
@@ -164,22 +165,22 @@ If system proxy support is enabled, some platforms can be configured automatical
164165

165166
## Command-line options
166167

167-
| Flag | Short | Description | Default |
168-
|-------------------|-------|---------------------------------------------------|--------------|
169-
| `--listen` | `-l` | Local HTTP proxy bind address | `:8080` |
170-
| `--port` | `-p` | SSH server port | `22` |
171-
| `--pass` | | SSH password (not recommended; use interactively) | |
172-
| `--identity_file` | `-i` | Private key file path | |
173-
| `--jump` | `-J` | Comma-separated jump hosts (`user@host:port`) | |
174-
| `--target` | | Optional target network scope/coverage | |
175-
| `--socks5` | | SOCKS5 proxy bind address | `:1080` |
176-
| `--timeout` | | SSH connection timeout | `10s` |
177-
| `--verbose` | `-v` | Enable verbose logging | `false` |
178-
| `--log` | | Log file path | stdout |
179-
| `--sys-proxy` | | Enable automatic system proxy configuration | `true` |
180-
| `--rules` | | Path to routing rules configuration file | |
181-
182-
Run `gotun --help` for the full list of options.
168+
| Flag | Short | Description | Default |
169+
|------|-------|-------------|---------|
170+
| `--http` | | Local HTTP proxy listen address (alias for `--listen`) | `:8080` |
171+
| `--listen` | `-l` | [Deprecated] Same as `--http` | `:8080` |
172+
| `--socks5` | | SOCKS5 proxy listen address | `:1080` |
173+
| `--port` | `-p` | SSH server port | `22` |
174+
| `--pass` | | SSH password (insecure, interactive preferred) | |
175+
| `--identity_file` | `-i` | Private key file path | |
176+
| `--jump` | `-J` | Comma-separated jump hosts (`user@host:port`) | |
177+
| `--http-upstream` | | Force forward all HTTP requests to this upstream (`host:port`) | |
178+
| `--target` | | [Deprecated] Same as `--http-upstream` | |
179+
| `--timeout` | | Connection timeout | `10s` |
180+
| `--verbose` | `-v` | Enable verbose logging | `false` |
181+
| `--log` | | Log file path | stdout |
182+
| `--sys-proxy` | | Auto-configure system proxy | `true` |
183+
| `--rules` | | Path to routing rules config file | |
183184

184185
---
185186

@@ -312,7 +313,7 @@ Platform notes:
312313

313314
---
314315

315-
## Rule-based routing (advanced)
316+
## Rule-based routing (Advanced)
316317

317318
`gotun` can read a Clash-style YAML rules file to decide which traffic is sent via the SSH proxy and which goes directly.
318319

@@ -353,7 +354,75 @@ gotun --rules ./rules.yaml user@your_ssh_server.com
353354
Requests will be matched from top to bottom; the first matching rule applies.
354355

355356
---
357+
## TUN Mode (Advanced)
356358

359+
gotun creates a local virtual network interface that intercepts specific (or all) TCP traffic and transparently tunnels it via SSH. This allows applications that don't support proxy settings to access remote resources through the SSH tunnel.
360+
361+
### Why use TUN Mode?
362+
363+
- **Full Application Proxy**: Perfectly supports **RDP (Remote Desktop)**, **Database connections** (MySQL/PostgreSQL), **Redis**, and other TCP-based application protocols.
364+
- **Zero Config**: In Global Mode, all TCP traffic is routed automatically without per-app configuration.
365+
- **Network Mapping**: Map a remote internal subnet to your local machine, solving IP conflict issues between local and remote networks.
366+
367+
> **⚠️ Note**: Current TUN Mode only supports **TCP protocol**. UDP traffic and ICMP (ping) are not supported (use `telnet` or `nc -vz` to test connectivity).
368+
369+
### Core Parameters
370+
371+
| Flag | Short | Description |
372+
|------|-------|-------------|
373+
| `--tun` | | Explicitly enable TUN mode (auto-enabled by other TUN flags, optional) |
374+
| `--tun-global` | `-g` | **Global Mode**: Routes ALL network traffic (auto-handles gateway to prevent SSH drop) |
375+
| `--tun-route` | | **Split Tunneling**: Route specific CIDRs to TUN (can be repeated) |
376+
| `--tun-nat` | | **NAT Mapping**: Map local subnet to remote subnet (`LocalCIDR:RemoteCIDR`) |
377+
| `--tun-ip` | | Internal IP for the TUN interface (default `10.0.0.1/24`) |
378+
379+
### Usage Examples
380+
381+
**1. Global Mode**
382+
383+
Route all local traffic through the remote server.
384+
385+
> **⚠️ Warning**: Global TUN mode might conflict with other software that modifies routing tables (e.g., Clash, ZeroTier). Use with caution or prefer Split Tunneling.
386+
387+
```bash
388+
# -g automatically enables TUN mode
389+
sudo gotun -g user@server.com
390+
```
391+
392+
**2. Split Tunneling**
393+
394+
Route only specific subnets through the tunnel. For example, only traffic to `10.0.0.0/24` goes via SSH:
395+
396+
```bash
397+
# Traffic to 10.0.0.x goes via SSH, everything else is direct
398+
sudo gotun --tun-route 10.0.0.0/24 user@server.com
399+
```
400+
401+
**3. NAT Mapping**
402+
403+
Solve subnet conflicts. For example, remote target is `192.168.0.0/24`, but your local network also uses this range. Map it to a conflict-free local range (e.g., `10.0.0.0/24`).
404+
405+
```bash
406+
# Access Local 10.0.0.1 -> Auto-NAT -> Remote 192.168.0.1
407+
sudo gotun --tun-nat 10.0.0.0/24:192.168.0.0/24 user@server.com
408+
```
409+
410+
> **Note**:
411+
> - **Privileges**: TUN mode requires `sudo` (macOS/Linux) or Admin (Windows).
412+
> - **Windows**: `wintun.dll` is auto-extracted on first run; no manual driver installation needed.
413+
414+
**4. RDP Remote Desktop Example**
415+
416+
Scenario: You need to RDP into a Windows machine at `192.168.2.1` (behind the SSH server), but you can't reach that IP directly. The SSH server (`192.168.2.2`) can reach it.
417+
418+
```bash
419+
# Route traffic for 192.168.2.0/24 through the SSH tunnel
420+
sudo gotun --tun-route 192.168.2.0/24 user@192.168.2.2
421+
```
422+
423+
Once started, open your Remote Desktop Client and connect to `192.168.2.1` directly. It will feel like you are on the same LAN.
424+
425+
---
357426
## Troubleshooting
358427

359428
### Connection issues
@@ -408,10 +477,10 @@ Implemented:
408477
- [x] Rule-based routing
409478
- [x] Shell completion for common shells
410479
- [x] SOCKS5 proxy support
480+
- [x] **TUN Mode**: L3 VPN support (Global/Split/NAT)
411481

412482
Planned:
413483

414-
- [ ] RDP gateway support
415484
- [ ] Tray/GUI frontend
416485
- [ ] Export/import of configuration profiles
417486
- [ ] Connection pooling and performance tuning

0 commit comments

Comments
 (0)