Skip to content

feat: 新增tun模式支持 #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sesame2 merged 6 commits into from
Jan 3, 2026
Merged

feat: 新增tun模式支持 #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f6e8458
feat: 新增 TUN 模式支持
Sesame2 Dec 27, 2025
c02b2d1
feat: 将tun模式的实现从TAP替换成成wireguard && 并且增加ip别名功能，以解决127.0.0.1、localhost…
Sesame2 Dec 29, 2025
f9f0254
feat: 新增网段映射功能
Sesame2 Dec 29, 2025
d5fac81
refactor: 更新命令行参数，明确参数语义
Sesame2 Dec 29, 2025
65bbc00
feat: 集成 Wintun DLL 以支持 TUN 在Windows平台上启动
Sesame2 Dec 29, 2025
7458178
docs: 新增tun模式的功能与参数介绍
Sesame2 Jan 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 71 additions & 18 deletions README-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@
- ✅ 支持多级跳板机 (Jump Host)，轻松穿透复杂网络
- ✅ 支持跨平台运行（Windows / Linux / macOS）
- ✅ 支持作为系统 HTTP 代理（可选扩展）
- ✅ 支持 TUN 模式: 支持所有基于 TCP 协议的应用代理
- ✅ 自定义路由规则: 支持通过自定义的规则文件进行流量分流
- ✅ 命令行自动补全: 支持 Bash, Zsh, Fish, PowerShell

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

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

### 使用场景

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


### 故障排除
### TUN 模式 (高级)

gotun 可以在本地创建一个虚拟网卡，将所有（或指定）TCP 流量拦截并通过 SSH 隧道透明传输。这使得不支持代理设置的软件也能通过 SSH 隧道访问远程资源。

#### 为什么使用 TUN 模式？

- **全应用代理**: 完美支持 **RDP 远程桌面**、**数据库连接** (MySQL/PostgreSQL)、**Redis** 等基于 TCP 的应用层协议。
- **无需配置**: 启用全局模式后，所有 TCP 流量自动走代理，无需在软件中逐个配置代理。
- **网络映射**: 可以将远程内网的整个网段映射到本地，解决本地与远程网段冲突的问题。

> **⚠️ 注意**: 当前版本的 TUN 模式仅支持 **TCP 协议**。不支持 UDP 流量和 ICMP 协议（因此无法使用 `ping` 命令测试连通性，请使用 `telnet` 或 `nc -vz` 测试 TCP 端口）。

#### 核心参数

| 参数 | 简写 | 说明 |
|------|------|------|
| `--tun` | | 显式启用 TUN 模式 (通常配合路由参数自动启用，可省略) |
| `--tun-global` | `-g` | **全局模式**：接管本机所有网络流量 (自动处理网关防止 SSH 断连) |
| `--tun-route` | | **指定网段代理**：仅将指定网段路由到 TUN (支持 CIDR，可多次使用) |
| `--tun-nat` | | **NAT 网段映射**：将本地网段映射到远程网段 (格式 `LocalCIDR:RemoteCIDR`) |
| `--tun-ip` | | 指定 TUN 设备的内部 IP (默认 `10.0.0.1/24`) |

#### 使用示例

**1. 全局模式**

将本机所有流量通过远程服务器转发。

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

```bash
# 启用详细日志进行调试
gotun -v user@example.com
# -g 自动启用 TUN 模式
sudo gotun -g user@server.com
```

**2. 指定网段代理**

仅将指定网段的流量放入隧道，其他流量直连。例如，只有访问 `10.0.0.0/24` 网段的流量才通过 SSH 隧道：

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

#### 权限问题
**3. NAT 网段映射**

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

```bash
# macOS/Linux
sudo gotun user@example.com
# 访问本地 10.0.0.1 -> 自动 NAT 到远程 192.168.0.1
sudo gotun --tun-nat 10.0.0.0/24:192.168.0.0/24 user@server.com
```

> **注意**:
> - **权限**: TUN 模式需要 `sudo` (macOS/Linux) 或管理员权限 (Windows)。
> - **Windows 用户**: 首次运行时会自动释放 `wintun.dll`，无需手动安装驱动。

# Windows (以管理员身份运行 PowerShell/CMD)
.\gotun.exe user@example.com
**4. RDP 远程桌面连接示例**

场景：你需要远程桌面连接到位于 `192.168.2.0/24` 网段的 Windows 机器（IP: `192.168.2.1`），但该网段无法直接访问。你有一台位于同一网段的 Linux 服务器（IP: `192.168.2.2`）开启了 SSH 服务。

```bash
# 将 192.168.2.0/24 网段的流量通过 SSH 隧道转发
sudo gotun --tun-route 192.168.2.0/24 user@192.168.2.2
```

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


---


Expand All @@ -357,7 +410,7 @@ sudo gotun user@example.com
- [x] **自定义路由规则**: 支持自定义的规则文件进行流量分流
- [x] **命令行自动补全**: 基于 Cobra 的智能提示
- [x] **SOCKS5 代理支持**: 更广泛的协议支持
- [ ] **RDP网关**：支持RDP远程桌面网关
- [x] **TUN 模式**: L3 级 VPN 支持 (全局/规则/NAT)
- [ ] **托盘 GUI 界面**: 图形化用户界面
- [ ] **配置文件导出/导入**: 配置管理功能
- [ ] **连接池优化**: 提升性能和稳定性
Expand Down
105 changes: 87 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ Your machine SSH (tcp/22) Bastion I
- Supports single and multi-hop SSH jump hosts
- Cross-platform: Windows, Linux, macOS
- Can be used as a system HTTP proxy (optional)
- TUN Mode: Supports standard TCP-based application proxying
- Rule-based traffic splitting via configuration file
- Shell completion support for Bash, Zsh, Fish, PowerShell
- Structured logging and verbose mode for debugging
Expand Down Expand Up @@ -164,22 +165,22 @@ If system proxy support is enabled, some platforms can be configured automatical

## Command-line options

| Flag | Short | Description | Default |
|-------------------|-------|---------------------------------------------------|--------------|
| `--listen` | `-l` | Local HTTP proxy bind address | `:8080` |
| `--port` | `-p` | SSH server port | `22` |
| `--pass` | | SSH password (not recommended; use interactively) | |
| `--identity_file` | `-i` | Private key file path | |
| `--jump` | `-J` | Comma-separated jump hosts (`user@host:port`) | |
| `--target` | | Optional target network scope/coverage | |
| `--socks5` | | SOCKS5 proxy bind address | `:1080` |
| `--timeout` | | SSH connection timeout | `10s` |
| `--verbose` | `-v` | Enable verbose logging | `false` |
| `--log` | | Log file path | stdout |
| `--sys-proxy` | | Enable automatic system proxy configuration | `true` |
| `--rules` | | Path to routing rules configuration file | |

Run `gotun --help` for the full list of options.
| Flag | Short | Description | Default |
|------|-------|-------------|---------|
| `--http` | | Local HTTP proxy listen address (alias for `--listen`) | `:8080` |
| `--listen` | `-l` | [Deprecated] Same as `--http` | `:8080` |
| `--socks5` | | SOCKS5 proxy listen address | `:1080` |
| `--port` | `-p` | SSH server port | `22` |
| `--pass` | | SSH password (insecure, interactive preferred) | |
| `--identity_file` | `-i` | Private key file path | |
| `--jump` | `-J` | Comma-separated jump hosts (`user@host:port`) | |
| `--http-upstream` | | Force forward all HTTP requests to this upstream (`host:port`) | |
| `--target` | | [Deprecated] Same as `--http-upstream` | |
| `--timeout` | | Connection timeout | `10s` |
| `--verbose` | `-v` | Enable verbose logging | `false` |
| `--log` | | Log file path | stdout |
| `--sys-proxy` | | Auto-configure system proxy | `true` |
| `--rules` | | Path to routing rules config file | |

---

Expand Down Expand Up @@ -312,7 +313,7 @@ Platform notes:

---

## Rule-based routing (advanced)
## Rule-based routing (Advanced)

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

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

---
## TUN Mode (Advanced)

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.

### Why use TUN Mode?

- **Full Application Proxy**: Perfectly supports **RDP (Remote Desktop)**, **Database connections** (MySQL/PostgreSQL), **Redis**, and other TCP-based application protocols.
- **Zero Config**: In Global Mode, all TCP traffic is routed automatically without per-app configuration.
- **Network Mapping**: Map a remote internal subnet to your local machine, solving IP conflict issues between local and remote networks.

> **⚠️ Note**: Current TUN Mode only supports **TCP protocol**. UDP traffic and ICMP (ping) are not supported (use `telnet` or `nc -vz` to test connectivity).

### Core Parameters

| Flag | Short | Description |
|------|-------|-------------|
| `--tun` | | Explicitly enable TUN mode (auto-enabled by other TUN flags, optional) |
| `--tun-global` | `-g` | **Global Mode**: Routes ALL network traffic (auto-handles gateway to prevent SSH drop) |
| `--tun-route` | | **Split Tunneling**: Route specific CIDRs to TUN (can be repeated) |
| `--tun-nat` | | **NAT Mapping**: Map local subnet to remote subnet (`LocalCIDR:RemoteCIDR`) |
| `--tun-ip` | | Internal IP for the TUN interface (default `10.0.0.1/24`) |

### Usage Examples

**1. Global Mode**

Route all local traffic through the remote server.

> **⚠️ Warning**: Global TUN mode might conflict with other software that modifies routing tables (e.g., Clash, ZeroTier). Use with caution or prefer Split Tunneling.

```bash
# -g automatically enables TUN mode
sudo gotun -g user@server.com
```

**2. Split Tunneling**

Route only specific subnets through the tunnel. For example, only traffic to `10.0.0.0/24` goes via SSH:

```bash
# Traffic to 10.0.0.x goes via SSH, everything else is direct
sudo gotun --tun-route 10.0.0.0/24 user@server.com
```

**3. NAT Mapping**

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

```bash
# Access Local 10.0.0.1 -> Auto-NAT -> Remote 192.168.0.1
sudo gotun --tun-nat 10.0.0.0/24:192.168.0.0/24 user@server.com
```

> **Note**:
> - **Privileges**: TUN mode requires `sudo` (macOS/Linux) or Admin (Windows).
> - **Windows**: `wintun.dll` is auto-extracted on first run; no manual driver installation needed.

**4. RDP Remote Desktop Example**

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.

```bash
# Route traffic for 192.168.2.0/24 through the SSH tunnel
sudo gotun --tun-route 192.168.2.0/24 user@192.168.2.2
```

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.

---
## Troubleshooting

### Connection issues
Expand Down Expand Up @@ -408,10 +477,10 @@ Implemented:
- [x] Rule-based routing
- [x] Shell completion for common shells
- [x] SOCKS5 proxy support
- [x] TUN Mode: L3 VPN support (Global/Split/NAT)

Planned:

- [ ] RDP gateway support
- [ ] Tray/GUI frontend
- [ ] Export/import of configuration profiles
- [ ] Connection pooling and performance tuning
Expand Down
Loading
Loading