Max/LorenEteval_Furious
1
0
Fork 0
mirror of https://github.com/LorenEteval/Furious.git synced 2026-10-10 00:08:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite TUN mode documentation 

Signed-off-by: Loren Eteval <loren.eteval@proton.me>
Loren Eteval
2026-08-28 20:14:07 +08:00
parent 29175f3582
commit 2a1eaca39b
1 changed files with 91 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TUN-Mode.md
+91 -62
@@ -1,93 +1,122 @@
# Supported platform
# TUN Mode
* Windows
* macOS
* Linux (since version **0.6.0**)
TUN mode routes system traffic through the active Furious connection. Depending on the selected profile, Furious either lets the proxy core provide its own TUN interface or starts its application-managed Tun2socks service.
# How to use
## Supported platforms
## Windows
| Platform | Release architectures | Permission model |
| --- | --- | --- |
| Windows 7 | AMD64 | Furious must run as Administrator. |
| Windows 10 or later | AMD64 and ARM64 | Furious must run as Administrator. |
| macOS | Intel and Apple silicon | Furious must run as Superuser. |
| Linux | AMD64 and ARM64 | Application Tun2socks requests privileges through `pkexec`; native core TUN may require the whole application to run as root. |
* Download `wintun.dll` from [here](https://www.wintun.net/) and put it in `C:\Windows\System32\`.
* Launch application with Adminstrator privilege. Enable `TUN Mode` in settings.
> [!IMPORTANT]
> TUN mode is disabled in the Flatpak build.
## How TUN mode works
Turn on **Settings > General > TUN Mode** to request TUN for future connections. Changing this setting does not rebuild an active connection; disconnect and reconnect when prompted. Turn it off and reconnect to return to proxy-only operation, except for an explicit TUN configuration described below.
Furious selects one TUN owner for the active profile:
| Profile | TUN implementation |
| --- | --- |
| Xray-core | Xray native TUN when **Use Xray-core TUN** is enabled or the configuration already contains a TUN inbound; otherwise application Tun2socks. |
| Hysteria 2 | Hysteria 2 native TUN when **Use Hysteria2 TUN** is enabled or the configuration already contains a `tun` block; otherwise application Tun2socks. |
| Hysteria 1 | Application Tun2socks. |
| External Core | Application Tun2socks only when that profile enables **Use Application Tun2socks**. Its **TUN Remote Address** supplies the upstream address used for route-loop prevention. |
The native Xray-core and Hysteria 2 choices are under **Settings > Plugin Settings**. Their native-TUN settings are configured there as well. These native options default to enabled on Windows and macOS and disabled on Linux.
> [!NOTE]
> The Windows release is **amd64 (x64)** only. The [official Wintun](https://www.wintun.net/) package ships **one `wintun.dll` per CPU architecture** under `wintun\bin\` (for example `amd64`, `arm`, `arm64`, and `x86`).
>
> You must use the DLL from **`wintun\bin\amd64\wintun.dll`**. Loading a DLL from another architecture (for example `arm64` or `x86`) can **crash TUN mode**.
> A TUN inbound/block already embedded in an Xray-core or Hysteria 2 configuration remains part of that configuration even when the global **TUN Mode** switch is off. Remove the explicit TUN configuration if the core should not start it.
> [!NOTE]
> Since version **0.6.0**:
>
> You can use built-in **"Restart The Application As Administrator"** entry in **"Tools"** menu which is much more convenient.
## Requirements
## macOS
### Windows
* No other dependency required. Launch application via `sudo Furious-GUI`. Enable `TUN Mode` in settings.
1. Download the official [Wintun package](https://www.wintun.net/).
2. Copy the `wintun.dll` matching the Furious build next to `Furious.exe`:
- AMD64 build: `wintun\bin\amd64\wintun.dll`
- ARM64 build: `wintun\bin\arm64\wintun.dll`
3. Open **Settings > General** and select **Restart The Application As Administrator**.
4. After the elevated instance opens, enable **TUN Mode** and connect.
> [!NOTE]
> Since version **0.6.0**:
>
> You can use built-in **"Restart The Application As Superuser"** entry in **"Tools"** menu which is much more convenient.
Furious loads Wintun only from the application directory or `C:\Windows\System32`. A DLL built for the wrong CPU architecture cannot be loaded and may crash the TUN backend.
The Windows 7 release is AMD64-only. Its automatic primary-interface-name lookup uses a PowerShell command unavailable on Windows 7; if detection fails, set **Primary Adapter Interface Name** in **Customize Tun2socks Settings...**.
### macOS
Open **Settings > General** and select **Restart The Application As Superuser**, then enable **TUN Mode** and connect. This preserves the packaged application launch path and is preferred over starting `Furious-GUI` manually with `sudo`.
Application Tun2socks currently uses `en0` as its underlying network interface. Systems whose active uplink is not `en0` may not work with this backend; use a supported native-core TUN path where possible.
### Linux
Application Tun2socks requires `bash`, `ip` from `iproute2`, and `pkexec` from a PolicyKit implementation. Furious may run as a normal user; approve the privilege prompt shown during connection setup.
Native Hysteria 2 TUN cannot use that helper and requires Furious itself to run as root. Native Xray-core TUN likewise needs whatever TUN and route permissions Xray requires on the host. The Linux defaults therefore use application Tun2socks unless a native option is enabled explicitly.
## Routing and loop prevention
Application Tun2socks sends the active proxy server's IP addresses through the original physical gateway before installing its TUN route. If the server address is a hostname, Furious resolves it first. This bypass keeps the core's own connection from returning to the TUN interface.
> [!WARNING]
> After launching the application as Superuser on macOS, some shortcuts are not working, e.g. copy & paste config.
> When application Tun2socks is used, core routing rules that send traffic directly can feed that traffic back into the system TUN interface and create a loop. Use **Global** routing unless every direct path is known to bypass the TUN interface.
## Linux (since version **0.6.0**)
For the built-in **Bypass Mainland China** option, Xray-core without native TUN and Hysteria 1 offer to switch to **Global** and reconnect. Custom routing rules are not inspected automatically.
* TUN mode is available in non-superuser mode, but requires privileged script execution during connection process. You need to enter the superuser password as prompted to connect successfully in TUN mode.
This blanket restriction does not apply to a native core TUN configured to manage its own routing. Furious adds the resolved Hysteria 2 server addresses to its native TUN exclusions; managed Xray-core TUN uses Xray's automatic routing and outbound-interface settings.
# Choose Routing Option
## Platform behavior
> [!WARNING]
> Under `TUN mode`, current routing option **should not** contain direct rules, otherwise a connection loop would occur:
>
> `traffic -> TUN -> Core -> direct rules -> TUN -> Core -> direct rules -> ...`
For application Tun2socks, Furious performs the following host setup:
You can use:
| Platform | Interface and routes | DNS |
| --- | --- | --- |
| Windows | Creates the Wintun adapter named `Furious`, installs the TUN default route, and adds upstream-server bypass routes through the physical gateway. | Configures the TUN adapter DNS; by default it also points the primary adapter at `127.0.0.1` during the connection and flushes the DNS cache. |
| macOS | Starts `utun777`, assigns its gateway, installs the system route ranges, and adds upstream-server bypass routes. | Saves each network service's DNS configuration, applies the TUN DNS, and restores the saved values on normal cleanup. |
| Linux | Creates `utun777`, assigns `10.10.10.10/24`, adds a metric-5 default route, and adds upstream-server bypass routes through the detected interface. | Does not change host DNS settings. |
* Built-in `Global` routing option, meaning it does not have direct rules and will proxy all traffic.
Native Xray-core and Hysteria 2 TUN use their own interface, address, route, and DNS settings instead of **Customize Tun2socks Settings...**.
> [!NOTE]
> Since version **0.6.0**:
>
> The application will ask if you want to switch to global mode and reconnect.
## Custom Tun2socks settings
# Verify
Open **Settings > Connection and Interface > Customize Tun2socks Settings...**. These settings affect only application Tun2socks, not native Xray-core or Hysteria 2 TUN.
To verify that `TUN mode` is working properly, try initiating direct connection from your apps or games.
Leave the basic fields empty unless automatic detection fails:
Here are some basic examples using `curl`:
- **Primary Adapter Interface Name** overrides Windows interface-name detection. This is the usual Windows 7 workaround.
- **Primary Adapter Interface IP** and **Default Primary Gateway IP** must be provided together to override gateway detection. Prefer automatic detection on Linux, where the route commands require an interface name rather than the IP-oriented field shown by this shared editor.
- **Tun2socks Adapter Interface DNS** overrides the default TUN DNS on Windows and macOS.
- **Bypass Tun2socks Adapter Interface IP** accepts comma-separated literal IPv4 or IPv6 addresses. When set, these replace automatic upstream-address resolution for bypass routes.
- **Disable Primary Adapter Interface DNS** applies only to Windows and mitigates DNS leaks while connected.
## Example A
The memory section exposes bounded TCP send/receive buffer sizes and receive-buffer auto-tuning. No separate tun2socks memory-optimization procedure is required.
```
curl icanhazip.com
## Verifying TUN mode
For a strict test, select **Do Not Change System Proxy** in Settings or use a client that ignores proxy settings. Then connect and run:
```shell
curl --noproxy "*" https://icanhazip.com
```
Verify that you get your server IP as response.
The result should be the proxy server's public exit address. Also check the **Log** page: application Tun2socks has a separate log category, while native TUN messages appear in the core log.
# Customize TUN Settings
## Cleanup and troubleshooting
Prior to version 0.5.0, the TUN settings needed to properly configure the system were automatically set by the application in a hard-coded manner. Now, I have designed them to be configurable through a GUI window to provide more flexibility.
Connection startup is staged. If the core, native TUN preparation, Tun2socks, DNS, or route setup fails, Furious stops and disposes the runtimes acquired by that attempt. Normal disconnect, reconnect, and application shutdown also request route, DNS, interface, and process cleanup.
> [!NOTE]
> In most cases the automatic settings will work just fine
Cleanup is best effort. A forced termination, power loss, failed platform command, or privilege loss can leave host state behind.
However, there are some situations that the automatic settings cannot handle. I will list some of them below:
- **No Wintun adapter on Windows:** verify that `wintun.dll` is beside `Furious.exe`, matches the release architecture, and that Furious is elevated.
- **More than one default route:** automatic gateway detection requires one unambiguous default gateway. Supply the Windows gateway/interface values manually, or disable competing adapters temporarily.
- **Windows static DNS:** the default DNS-leak mitigation restores the primary adapter to DHCP DNS on cleanup, not to a previous static DNS value. Disable that option if the adapter must retain static DNS, or restore the static setting afterward.
- **Linux privilege prompt fails:** verify that `pkexec`, PolicyKit, `bash`, and `ip` are available.
- **Linux leaves `utun777` after an interrupted or unprivileged cleanup:** disconnect cleanly when possible. Remove a stale interface with `sudo ip tuntap del mode tun dev utun777` before reconnecting.
- **External Core reports a missing TUN remote address:** enable application Tun2socks only after setting the profile's actual upstream hostname or IP; the executable path and local proxy listeners are not remote addresses.
## Multiple network cards installed
You have more than one network card installed on your computer and the application cannot determine which one should be used as the primary interface. In this case, you need to provide the correct settings manually.
## Automatic settings failed
The automatic settings will fail on some older operating systems, such as Windows 7. By manually providing the TUN settings, I was able to run TUN mode successfully during win7 testing.
## Example custom settings
![image](https://github.com/user-attachments/assets/4a254ee8-074e-4942-9027-ec53fafe2454)
## Memory Optimization
Optimize the memory usage for best performance. See https://github.com/xjasonlyu/tun2socks/wiki/Memory-Optimization
If setup still fails, open the **Log** page and inspect **Application** and either **Tun2socks** or **Core** messages for the first failed stage.