Skip to content

Commit

Permalink
Merge pull request #14 from apernet/wip-hy2-tun
Browse files Browse the repository at this point in the history 
Add docs for TUN mode
  • Loading branch information
@tobyxdd
tobyxdd authored Mar 23, 2024
2 parents 5f143a6 + 515dd38 commit e89267e
Show file tree
Hide file tree
Showing 4 changed files with 98 additions and 2 deletions.
49 changes: 49 additions & 0 deletions docs/docs/advanced/Full-Client-Config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -311,3 +311,52 @@ Example:
}
}
```

### TUN

TUN mode is a cross-platform transparent proxy solution that creates a virtual network interface in the system and uses the system's routes to capture and redirect traffic. It currently works on Windows, Linux, and macOS.

Unlike traditional L3 VPNs (such as WireGuard and OpenVPN), Hysteria's TUN mode can only handle TCP and UDP and does not support other protocols including ICMP (e.g. ping). It also takes control of the TCP stack to speed up TCP connections.

Compared to Hysteria 1's implementation, Hysteria 2's TUN is based on [sing-tun](https://github.com/SagerNet/sing-tun)'s "system" stack, requiring a /30 IPv4 address and a /126 IPv6 address to be configured on the interface. Hysteria will automatically set up the network interface, addresses, and routes.

```yaml
tun:
name: "hytun" # (1)!
mtu: 1500 # (2)!
timeout: 5m # (3)!
address: # (4)!
ipv4: 100.100.100.101/30
ipv6: 2001::ffff:ffff:ffff:fff1/126
route: # (5)!
ipv4: [0.0.0.0/0] # (6)!
ipv6: ["2000::/3"] # (7)!
ipv4Exclude: [192.0.2.1/32] # (8)!
ipv6Exclude: ["2001:db8::1/128"] # (9)!
```

1. Name of the TUN interface.
2. Optional. The maximum packet size accepted by the TUN interface. The default is 1500 bytes.
3. Optional. UDP session timeout. The default is 5 minutes.
4. Optional. Addresses to use on the interface. Set to any private address that does not conflict with your LAN. The defaults are as shown.
5. Optional. Routing rules. Omitting or skipping all fields means that no routes will be added automatically. In most cases, just having `ipv4Exclude` or `ipv6Exclude` is enough.
6. Optional. IPv4 prefix to proxy. If any other field is configured, the default is `0.0.0.0/0`.
7. Optional. IPv6 prefix to proxy. Due to YAML limitations, quotes are required. If any other field is configured, the default is `::/0`.
8. Optional. IPv4 prefix to exclude. Can be filled with the Hysteria server's address to avoid a loop. If you wish to completely disable IPv4 proxying, you can also add `0.0.0.0/0` here.
9. Optional. IPv6 prefix to exclude. Due to YAML limitations, quotes are required. Can be filled with the Hysteria server's address to avoid a loop. If you wish to completely disable IPv6 proxying, you can also add `"::/0"` here.

Note: On Linux, it is sometimes necessary to disable `rp_filter` to allow an interface to receive traffic from other interfaces.

```bash
sysctl net.ipv4.conf.default.rp_filter=2
sysctl net.ipv4.conf.all.rp_filter=2
```

Known compatibility issues:

| OS | Issue |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS | The name of the TUN interface must be utun followed by a number, for example `utun123`. |
| Windows Server 2022 | Windows Firewall must be disabled for this to work. |
| CentOS 7 | Firewall must be disabled for this to work. For kernels before 4.17, the automatically added routes will not work properly ([reason](https://github.com/torvalds/linux/commit/bfff4862653bb96001ab57c1edd6d03f48e5f035)). Upgrade the kernel to 4.17 or higher, or execute `ip rule del from all goto 9010; ip -6 rule del from all goto 9010` after starting the Hysteria client. |
| FreeBSD | [Not supported](https://github.com/SagerNet/sing-tun/blob/v0.2.4/tun_other.go#L10) |
49 changes: 49 additions & 0 deletions docs/docs/advanced/Full-Client-Config.zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -311,3 +311,52 @@ tcpRedirect:
}
}
```

### TUN

TUN 是一个跨平台的透明代理解决方案，在系统中创建虚拟网卡，利用系统路由功能来捕获及重定向流量。目前兼容 Windows、Linux 和 macOS 平台。

不同于常规的三层 VPN 技术（如 WireGuard 和 OpenVPN），Hysteria 的 TUN 模式只能处理 TCP 和 UDP 流量，不支持 ICMP 等其它协议（这意味着不支持 ping 等操作）。其会完全接管 TCP 协议栈以加速 TCP 连接。

与 Hysteria 1 的 TUN 实现相比，Hysteria 2 的 TUN 基于 [sing-tun](https://github.com/SagerNet/sing-tun) 的 "system" 栈，需要在虚拟网卡上配置一个 /30 的 IPv4 地址和一个 /126 的 IPv6 地址。Hysteria 会自动完成网卡、地址和路由规则的配置。

```yaml
tun:
name: "hytun" # (1)!
mtu: 1500 # (2)!
timeout: 5m # (3)!
address: # (4)!
ipv4: 100.100.100.101/30
ipv6: 2001::ffff:ffff:ffff:fff1/126
route: # (5)!
ipv4: [0.0.0.0/0] # (6)!
ipv6: ["2000::/3"] # (7)!
ipv4Exclude: [192.0.2.1/32] # (8)!
ipv6Exclude: ["2001:db8::1/128"] # (9)!
```

1. TUN 接口的名称。
2. 可选。TUN 接口接受的单个包大小。默认 1500 字节。
3. 可选。UDP 会话超时时间。默认 5 分钟。
4. 可选。要在接口上使用的地址。设置成任意不和你的 LAN 冲突的私有地址即可。默认值如下所示。
5. 可选。路由规则。省略或者置空所有子项将禁用自动添加路由。<br>绝大部分情况下只需配置 `ipv4Exclude` 或者 `ipv6Exclude` 即可。
6. 可选。要代理的 IPv4 前缀。若配置了任何其它子项则默认 `0.0.0.0/0`。
7. 可选。要代理的 IPv6 前缀。由于 YAML 的限制必须加上引号。若配置了任何其它子项则默认 `::/0`。
8. 可选。要排除的 IPv4 前缀。<br>**可填入 Hysteria 服务端的地址来避免形成环路。**<br>如果你希望完全禁用 IPv4 代理，也可在此项中添加 `0.0.0.0/0`。
9. 可选。要排除的 IPv6 前缀。由于 YAML 的限制必须加上引号。<br>**可填入 Hysteria 服务端的地址来避免形成环路。**<br>如果你希望完全禁用 IPv6 代理，也可在此项中添加 `"::/0"`。

注意：Linux 上有时需要禁用 `rp_filter` 才能让一个网卡接收来自其他网卡的流量。

```bash
sysctl net.ipv4.conf.default.rp_filter=2
sysctl net.ipv4.conf.all.rp_filter=2
```

已知的兼容性问题：

| 操作系统 | 问题 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS | TUN 接口的名称必须是 utun+数字， 例如 `utun123`。 |
| Windows Server 2022 | 需要禁用防火墙才能正常使用。 |
| CentOS 7 | 需要禁用防火墙才能正常使用。<br>对于 4.17 之前的内核，自动添加的路由规则将无法正常工作（[原因](https://github.com/torvalds/linux/commit/bfff4862653bb96001ab57c1edd6d03f48e5f035)）， 可将内核升级到 4.17 或更高版本，或者在 Hysteria 客户端启动后执行 `ip rule del from all goto 9010; ip -6 rule del from all goto 9010` 来解决此问题。 |
| FreeBSD | 无法使用，[不被 sing-tun 支持](https://github.com/SagerNet/sing-tun/blob/v0.2.4/tun_other.go#L10)。 |
1 change: 0 additions & 1 deletion docs/docs/misc/2-vs-1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,3 @@ There are some features present in Hysteria 1.x that have not yet been implement

- **Client-Side ACL**: ACL is only available on the server side for now.
- **FakeTCP Protocol**: FakeTCP has always been a somewhat niche feature and we are still evaluating whether to bring it back.
- **TUN Mode**: Not yet available, but likely to be reintroduced (and reworked) in the future.
1 change: 0 additions & 1 deletion docs/docs/misc/2-vs-1.zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,3 @@ Hysteria 2 尚未实现 Hysteria 1.x 中的一些功能：

- **客户端 ACL**：目前 ACL 只在服务器端可用。
- **FakeTCP 协议**：FakeTCP 一直是相对小众的功能，我们还在评估是否要重新引入。
- **TUN 模式**：目前暂无，但很可能在未来重写、重新引入。

0 comments on commit e89267e

Please sign in to comment.