From ea1a7bbddf3a4c465e2351d730f7ec5fe2133553 Mon Sep 17 00:00:00 2001 From: Loren Eteval Date: Tue, 6 Oct 2026 22:26:29 +0800 Subject: [PATCH] Update wiki for 0.8.3 Signed-off-by: Loren Eteval --- External-Core.md | 12 +-- Home.md | 8 +- Install-From-PyPI.md | 16 ++- Plugin-Development.md | 16 +-- Quick-Start.md | 12 ++- Release-Artifacts.md | 2 +- Routing.md | 8 +- Server-Profiles-and-Sharing.md | 4 +- TUN-Mode.md | 156 +++++++++++++++-------------- Troubleshooting-and-Diagnostics.md | 24 ++++- 10 files changed, 148 insertions(+), 110 deletions(-) diff --git a/External-Core.md b/External-Core.md index def4d70..f14253c 100644 --- a/External-Core.md +++ b/External-Core.md @@ -42,11 +42,11 @@ Use the browse buttons to avoid path-typing mistakes. Saving through the structu These values do not make the external program create the listeners. Configure the external program itself to listen on the same endpoints. -The HTTP endpoint is used for normal Furious proxy integration and connection operations. The SOCKS endpoint is required when the profile opts into application-managed tun2socks. +The HTTP endpoint is used for normal Furious proxy integration and connection operations. The SOCKS endpoint is required when the profile opts into application TUN, whether sing-tun or tun2socks is selected. -### Application tun2socks +### Application TUN -**Use Application tun2socks** declares that this profile can participate in Furious's application-managed TUN path. +**Use Application tun2socks** declares that this profile can participate in Furious's application-managed TUN path. The existing field label is retained: it permits either engine selected under **Settings > TUN > Application TUN Engine**. It does not force tun2socks. When enabled, **TUN Remote Address** is required. It must be the actual upstream server hostname, IPv4 address, or IPv6 address used for DNS resolution and the remote-server bypass route. @@ -58,7 +58,7 @@ These three values are deliberately separate: Furious never substitutes the executable path or a local listener for the TUN remote address. -Application tun2socks starts only when both the global **TUN Mode** setting and this profile option are enabled. If the profile option is off, a globally enabled TUN setting does not force this External Core profile through Furious's tun2socks path. +The selected application engine starts only when both global **TUN Mode** and this profile option are enabled. If the profile option is off, global TUN does not force this External Core profile through application TUN. ## Arguments and environment @@ -80,7 +80,7 @@ When you click **Connect**, Furious: 2. launches the process directly with the configured working directory and environment; 3. captures stdout and stderr without allowing the child pipes to fill and deadlock; 4. asynchronously probes the configured HTTP endpoint until a TCP connection succeeds, the process exits, or the startup deadline expires; -5. starts application tun2socks only when the global and profile settings both request it; +5. starts the selected application TUN engine only when the global and profile settings both request it; 6. completes the remaining connection setup before reporting **Connected**. The HTTP-listener readiness probe currently has a 2.5-second deadline. A process that stays alive without opening that endpoint fails startup and is cleaned up. TCP acceptance alone does not validate HTTP proxy behavior, authentication, or upstream connectivity; the later network test remains a separate check. No stdout readiness pattern is used. @@ -133,7 +133,7 @@ Clear the field to use the executable's directory, or select an existing absolut ### Process starts but Furious cannot connect -Confirm that the program opens the exact configured HTTP listener before the startup deadline. A successful readiness probe only proves that the endpoint accepts TCP connections. If application tun2socks is enabled, also confirm the SOCKS listener. Inspect the Core log for startup output. +Confirm that the program opens the exact configured HTTP listener before the startup deadline. A successful readiness probe only proves that the endpoint accepts TCP connections. If application TUN is enabled, also confirm the SOCKS listener. Inspect the Core log for startup output. ### Process exits immediately diff --git a/Home.md b/Home.md index 30418ac..581020d 100644 --- a/Home.md +++ b/Home.md @@ -4,6 +4,8 @@ Furious is a cross-platform PySide6 client for Windows, macOS, and Linux. It pro Furious includes official integrations for Xray-core, Hysteria 1, Hysteria 2, and user-configured external core programs. Current protocol support includes VMess, VLESS, Shadowsocks, Trojan, SOCKS, Hysteria 1, and Hysteria 2. +This wiki documents **Furious 0.8.3**. + ## Start here - [Release Artifacts](Release-Artifacts) — choose the correct application download for your platform and CPU architecture. @@ -15,7 +17,7 @@ Furious includes official integrations for Xray-core, Hysteria 1, Hysteria 2, an ## Networking - [Routing](Routing) — choose Global, Bypass Mainland China, or supported custom routing policies. -- [TUN Mode](TUN-Mode) — route system traffic through native TUN or application-managed tun2socks. +- [TUN Mode](TUN-Mode) — route system traffic through native TUN or application-managed sing-tun/tun2socks. - [External Core](External-Core) — run a trusted local executable through Furious's connection lifecycle. ## Help and development @@ -30,7 +32,7 @@ Furious includes official integrations for Xray-core, Hysteria 1, Hysteria 2, an | Page | Purpose | | --- | --- | | **Home** | Profiles, connection controls, routing selection, tests, import, and sharing | -| **Log** | Unified Application, Core, tun2socks, and plugin-provided log categories | +| **Log** | Unified Application, Core, TUN, and plugin-provided log categories | | **Subscription** | Subscription sources, synchronization, filters, and update status | | **Metrics** | Traffic speed, usage history, and optional proxy endpoint information | | **Settings** | Appearance, connection behavior, TUN, system proxy, plugins, diagnostics, and application options | @@ -41,6 +43,6 @@ Furious includes official integrations for Xray-core, Hysteria 1, Hysteria 2, an - **System Proxy** configures supported operating-system proxy settings. It does not route applications that ignore those settings. - **TUN Mode** captures system traffic at the network-interface level and is independent from System Proxy. - **Routing** decides how traffic already handled by a supported core is sent. Available choices depend on the active profile's backend. -- An **External Core** is a trusted local program. Its executable path, local proxy listeners, and optional remote address for application tun2socks are separate settings. +- An **External Core** is a trusted local program. Its executable path, local proxy listeners, and optional remote address for application TUN are separate settings. For the shortest path to a working connection, continue with [Quick Start](Quick-Start). diff --git a/Install-From-PyPI.md b/Install-From-PyPI.md index 463cb31..49b8935 100644 --- a/Install-From-PyPI.md +++ b/Install-From-PyPI.md @@ -49,7 +49,7 @@ You can also launch the installed package directly: python -m Furious ``` -## What pip Installs +## What pip installs `Furious-GUI` declares its runtime dependencies directly. The installation includes: @@ -57,7 +57,8 @@ python -m Furious * `Xray-core` for the Xray backend; * `hysteria` for Hysteria 1; * `hysteria2` for Hysteria 2; -* `tun2socks` for application-managed TUN mode; +* `tun2socks` for one application TUN engine; +* `sing-tun==0.9.7.dev0` for the default application TUN engine; * the remaining cross-platform and platform-specific Python dependencies. There are no core-related optional extras and no separate core-installation step. The native binding wheels contain the @@ -73,7 +74,11 @@ Qt, operating-system, and architecture combination is tested. The current [sourc uses ordinary CPython **3.13** with PySide6 **6.8.3** on Windows, Linux, and macOS. An unpinned PyPI installation may resolve a different Qt release. -Binary availability depends on every dependency. As checked on 2026-09-19, [PySide6 6.11.2](https://pypi.org/project/PySide6/6.11.2/) +The current source also evaluates generic base classes from `collections.abc`, which Python 3.8 does not +support. Do not rely on the metadata lower bound for a Python 3.8 source/PyPI installation; prefer the CI +combination above. The special packaged compatibility builds use a separate toolchain. + +Binary availability depends on every dependency. As checked on 2026-10-06, [PySide6 6.11.2](https://pypi.org/project/PySide6/6.11.2/) requires Python 3.10–3.14 and publishes wheels with these platform tags: | Platform | Architectures | Qt wheel requirement | @@ -106,7 +111,7 @@ Important limits: ## If No Compatible Wheel Is Available When pip finds a matching wheel, installation is a direct download and no compiler is involved. If it prints messages -such as `Building wheel for Xray-core`, `hysteria`, `hysteria2`, or `tun2socks`, then no compatible binary wheel was +such as `Building wheel for Xray-core`, `hysteria`, `hysteria2`, `tun2socks`, or `sing-tun`, then no compatible binary wheel was selected and pip is attempting the exceptional source-build path. You can require wheels and fail immediately instead of compiling: @@ -121,7 +126,7 @@ usually simpler than compiling the bindings. ### Building Native Bindings From Source -Source builds are intended for binding development or environments without matching wheels. All four bindings use a +Source builds are intended for binding development or environments without matching wheels. All five bindings use a native Go archive plus a C++/pybind11 extension. Use the build instructions and Go module requirements from the exact binding release you are compiling; toolchain requirements change independently of Furious. @@ -143,6 +148,7 @@ See the binding repositories for current build details: * [hysteria-python](https://github.com/LorenEteval/hysteria-python) * [hysteria2-python](https://github.com/LorenEteval/hysteria2-python) * [tun2socks-python](https://github.com/LorenEteval/tun2socks-python) +* [sing-tun-python](https://github.com/LorenEteval/sing-tun-python) — Furious 0.8.3 uses [0.9.7.dev0](https://github.com/LorenEteval/sing-tun-python/releases/tag/v0.9.7.dev0) ## Troubleshooting diff --git a/Plugin-Development.md b/Plugin-Development.md index cd67d73..0518064 100644 --- a/Plugin-Development.md +++ b/Plugin-Development.md @@ -2,7 +2,7 @@ Furious uses a capability-based Python plugin system. A plugin is a process-lifetime object that groups one or more independent capabilities; it is not assumed to be a proxy core. -This page documents the current plugin API (version **3**) as implemented by the project. The API is still evolving, so pin and test against the Furious versions you support. +This page documents Furious **0.8.3** and its plugin API (version **3**). The API is still evolving, so pin and test against the Furious versions you support. ## Architecture @@ -112,8 +112,8 @@ Follow Furious's Qt lifetime rules: - give widgets intentional Qt parents; - use the project's reusable window/dialog base classes; -- avoid persistent direct bound-method connections from long-lived objects to transient receivers; -- disconnect or weakly dispatch callbacks where ownership differs; +- use the project's weak connection/dispatch helpers for transient receivers, including signals from their own children where compiled PySide6 retention matters; +- supply the independent sender when its lifetime differs, and release connection handles at the owning boundary; - let the host own and release a returned transient editor. A navigation-page provider is different: the host creates each descriptor's page once and retains it for the application lifetime. @@ -123,10 +123,10 @@ A navigation-page provider is different: the host creates each descriptor's page A `SubscriptionDecoder` declares `decoderId`, `displayName`, and integer `priority`, then implements: ```python -from typing import Optional - from Furious.Plugins import SubscriptionResult +from typing import Optional + def decode(self, data: bytes) -> Optional[SubscriptionResult]: ... @@ -182,6 +182,8 @@ Optional factory hooks include: - `logTimestampPatterns()`; - `afterConnected(httpProxy)`. +The existing `usesApplicationTun2socks(config)` hook name is retained. It reports application-TUN eligibility for either selected engine, not a request to force tun2socks. Native ownership reported by `prepareTUN()` takes priority. Application-engine selection, independent settings, and connection-attempt orchestration belong to Furious. + Do not add backend-name conditionals to shared connection services. Express variation through these capabilities. The runtime implements the `CoreRuntime` contract in `Furious.Interface.Runtime`. Bind its exit callback before starting and keep that event sink stable. Publish a typed `RuntimeExit` exactly once for each execution; interpret raw backend exit codes at the runtime boundary. `isRunning()` must passively report liveness without consuming an exit or emitting callbacks. Exit callbacks may arrive on an implementation worker thread, so UI owners must hand them off to the Qt thread. @@ -202,6 +204,8 @@ Return a `TrafficStatsMonitor` containing a query callable and its target. Its b - `ActionProvider.createActions(...)` returns actions for plugin management. - `NavigationPageProvider.pageDescriptors()` returns `NavigationPageDescriptor` values with an ID, title, icon, order, and factory. +Settings search indexes host-rendered card titles, descriptions, section names, and plugin metadata. Supply accurate descriptors and translation flags; do not build another settings-state authority merely for search. + Navigation pages are sorted by descriptor order and receive IDs namespaced as `plugin::`. For translated bundled UI, follow Furious's static translation-key conventions. Third-party plugins should normally supply their own localized/literal text and mark it non-translatable rather than assuming the host catalog contains their strings. @@ -225,7 +229,7 @@ Do not create an unrelated settings file when the host's configuration model or - Test initialization failure and reverse-order shutdown. - Test repeated editor open/close and runtime connect/disconnect cycles. - Test source execution and an installed wheel, not only an editable checkout. -- Declare runtime data as package data so Nuitka/wheel installations can discover it. +- Declare runtime data as package data and verify its inclusion in wheel and Nuitka builds. An entry point installed into a separate system Python environment is not automatically included in a packaged Furious executable. ## Reference implementations diff --git a/Quick-Start.md b/Quick-Start.md index 4cc7fe4..420cba9 100644 --- a/Quick-Start.md +++ b/Quick-Start.md @@ -84,7 +84,7 @@ System Proxy only affects applications that honor the operating system's proxy c ### TUN Mode -Enable **TUN Mode** when you need interface-level traffic capture, including applications that ignore System Proxy. TUN may require administrative privileges and may use either a backend's native TUN implementation or Furious's application-managed tun2socks path. +Enable **TUN Mode** when you need interface-level traffic capture, including applications that ignore System Proxy. TUN requires host permissions and may use a core's native TUN or an application engine. **Settings > TUN > Application TUN Engine** selects **sing-tun** (the default) or **tun2socks**. Native proxy-core TUN takes priority over this selection. Read [TUN Mode](TUN-Mode) before enabling it, especially if you use custom routing. @@ -96,13 +96,19 @@ Useful checks include: - The status area reports **Connected** and, after the connectivity check, **Network OK**. - On Home, select profiles and open **Tests** to run **Test Ping Latency**, **Test Tcping Latency**, or **Test Download Speed**. Ping and TCP tests measure reachability, not a complete proxy connection. - **Metrics** displays traffic speed and usage when metrics collection is enabled and the active backend exposes statistics. -- **Log** shows application startup, core output, and tun2socks output in filterable categories. +- **Log** shows application startup, core output, and application TUN output in filterable categories. A failed connectivity test can indicate DNS, routing, proxy, or destination reachability problems. Use [Troubleshooting and Diagnostics](Troubleshooting-and-Diagnostics) rather than relying on one status label alone. ## 6. Disconnect cleanly -Click **Disconnect** before changing host networking or terminating a core manually. Furious then unwinds the active connection resources, including the managed runtime, application tun2socks where used, routes, and automatically managed system proxy state. +Click **Disconnect** before changing host networking or terminating a core manually. Furious then unwinds the active connection resources, including the managed runtime, the selected application TUN engine where used, routes, and automatically managed system proxy state. + +## Finding settings + +The search box on **Settings** filters cards by their titles, descriptions, sections, and plugin metadata in English or the current language. Ctrl+F (Command+F on macOS) focuses it. Enter or clearing the query applies immediately. Search does not inspect saved input values or change preferences. + +TUN Mode stays under **General**. Engine selection and both application-engine customization dialogs are grouped under **TUN**; native-core options stay under **Plugin Settings**. ## Next steps diff --git a/Release-Artifacts.md b/Release-Artifacts.md index da11f33..ae3ded9 100644 --- a/Release-Artifacts.md +++ b/Release-Artifacts.md @@ -54,7 +54,7 @@ Current Windows filename patterns are: Use the `windows10` build on Windows 10 and Windows 11. The `windows7` build is a compatibility package for Windows 7 and is published only for x64; there is no Windows 7 ARM64 package. -TUN mode requires a `wintun.dll` that matches the selected architecture. See [TUN Mode](TUN-Mode) before enabling it. +Application **tun2socks** requires an external `wintun.dll` matching the selected architecture. **sing-tun** embeds its Wintun library. All Windows TUN paths require the appropriate host permissions. See [TUN Mode](TUN-Mode) before enabling it. ## macOS diff --git a/Routing.md b/Routing.md index 3a50c21..97b8ff3 100644 --- a/Routing.md +++ b/Routing.md @@ -64,14 +64,14 @@ If the selected named routing is disabled or deleted, Furious persists an availa ## Routing and TUN safety -Application-managed tun2socks sends captured traffic to a local SOCKS listener. A routing rule that sends part of that same captured flow directly through the ordinary host path can feed it back into the TUN interface and create a loop. +Both application engines, sing-tun and tun2socks, send captured traffic to a local SOCKS listener. A routing rule that sends part of that same captured flow directly through the ordinary host path can feed it back into the TUN interface and create a loop. For this reason, Furious rejects unsafe combinations such as: - Xray **Bypass Mainland China** while global TUN is enabled but Xray native TUN is not being used; -- Hysteria 1 **Bypass Mainland China** while global TUN uses application tun2socks. +- Hysteria 1 **Bypass Mainland China** while global TUN uses an application engine. -Use **Global**, use a backend's supported native TUN mode, or redesign the route ownership so direct traffic cannot re-enter application TUN. Do not bypass this validation by manually editing generated runtime data. +Selecting sing-tun does not remove these guards. Use **Global**, use a backend's supported native TUN mode, or redesign the route ownership so direct traffic cannot re-enter application TUN. Do not bypass this validation by manually editing generated runtime data. See [TUN Mode](TUN-Mode) for the complete ownership matrix. @@ -105,7 +105,7 @@ Custom is backend-owned. Xray consumes an Xray routing object; Hysteria 1 consum ### A direct rule fails with TUN enabled -Check whether the connection uses application tun2socks. Direct routing and application-managed TUN can form a loop, so Furious blocks known-unsafe built-in combinations. +Check whether the connection uses application sing-tun or tun2socks. Direct routing and application-managed TUN can form a loop, so Furious blocks known-unsafe built-in combinations. ## See also diff --git a/Server-Profiles-and-Sharing.md b/Server-Profiles-and-Sharing.md index 227a147..118c211 100644 --- a/Server-Profiles-and-Sharing.md +++ b/Server-Profiles-and-Sharing.md @@ -54,7 +54,7 @@ Select one or more rows and use the context menu to: **Duplicate** creates a new independent profile identity. If the source belongs to a subscription, the duplicate becomes a manual profile so a later subscription synchronization does not overwrite it. -**Move To Subscription...** changes group membership, not remote synchronization ownership. A profile moved into a group becomes a local member that survives later subscription updates. Moving a managed profile to another group also removes its former remote ownership. +**Move To Subscription...** changes group membership, not remote synchronization ownership. A manual profile moved into a group becomes a local member that survives later subscription updates. Moving a managed profile to another group removes its former remote ownership. Choosing its existing group leaves membership and remote ownership unchanged. The profile filter above the table can show **All Profiles**, **Manual Profiles**, or profiles belonging to one subscription, including its local members. Search accepts plain text or a regular expression and combines with that filter. Results update as you type; Enter or clearing the box applies immediately. Ctrl+F (Command+F on macOS) focuses the search box and selects the current query. @@ -72,7 +72,7 @@ These actions are no longer in the table context menu. Ping and TCP results do n ## Activation and editing -The active profile is the one used by the next connection attempt. Starting a connection activates the single selected row. Selecting another row while disconnected does not by itself rewrite that profile's data. +The saved activated profile is the default for a connection started without an explicit selection. The connection lifecycle separately owns its running profile and prepared runtime configuration. Starting a connection from Home activates the single selected row; highlighting another row does not switch a running connection. Changing the routing selector while connected requests a controlled reconnection using the new routing mode. Editing connection fields generally takes effect on the next connection. diff --git a/TUN-Mode.md b/TUN-Mode.md index a91a3fe..cb2a4b7 100644 --- a/TUN-Mode.md +++ b/TUN-Mode.md @@ -1,129 +1,135 @@ # TUN Mode -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. It is independent from **System Proxy**, which only configures applications that honor the operating system's proxy settings. +TUN mode routes system traffic through the active Furious connection. Furious uses the proxy core's native TUN when available, otherwise the selected application TUN engine forwards traffic to the core's local SOCKS listener. TUN is independent from **System Proxy**, which only configures applications that honor operating-system proxy settings. -If you have not made a normal proxy connection yet, begin with [Quick Start](Quick-Start). TUN adds interface, route, DNS, and privilege requirements to that working connection. +This page describes Furious **0.8.3**. See [Release Artifacts](Release-Artifacts) for downloads. -## Supported platforms +Begin with a working proxy connection using [Quick Start](Quick-Start). TUN adds interface, route, DNS, and privilege requirements. -| 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; native core TUN may require the whole application to run as root. | +## Selecting an engine -> [!IMPORTANT] -> TUN mode is disabled in the Flatpak build. +1. Turn on **Settings > General > TUN Mode**. +2. Under **Settings > TUN > Application TUN Engine**, choose **sing-tun** or **tun2socks**. The default is **sing-tun**, using its **go** stack. +3. Connect or reconnect to apply the choice. -## How TUN mode works +The engine preference applies to the next connection. It does not change the selected proxy core or replace a running TUN engine in place. The engines have independent settings; switching engines does not copy one engine's settings into the other. -Turn on **Settings > General > TUN Mode** to request TUN for future connections. Changing this setting does not alter a running core in place; accept the reconnection prompt to apply it now, or reconnect later. Turn it off and reconnect to return to proxy-only operation, except for an explicit TUN configuration described below. +**Native proxy-core TUN takes priority over this selector.** Enabling **Use Xray-core TUN**, for example, makes Xray own TUN regardless of the selected application engine. -Furious selects one TUN owner for the active profile: - -| Profile | TUN implementation | +| Profile | TUN owner when global TUN is enabled | | --- | --- | -| 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. See [External Core](External-Core). | +| Xray-core | Native TUN when **Use Xray-core TUN** is enabled or the configuration contains a TUN inbound; otherwise the selected application engine. | +| Hysteria 2 | Native TUN when **Use Hysteria2 TUN** is enabled or the configuration contains a `tun` block; otherwise the selected application engine. | +| Hysteria 1 | The selected application engine. | +| External Core | The selected application engine only when the profile enables **Use Application tun2socks**. This existing label enables application TUN for either engine. See [External Core](External-Core). | -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. +Native options and customization dialogs remain under **Settings > Plugin Settings**. Managed native TUN defaults to enabled on Windows and macOS and disabled on Linux. > [!NOTE] -> 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. +> An explicit Xray TUN inbound or Hysteria 2 `tun` block remains in the profile even when the global TUN switch or corresponding managed native-TUN option is off. Remove the explicit configuration if the core should not start it. -## Requirements +## Platform requirements + +TUN is disabled in **Flatpak**. Use another Linux package format when TUN is required. ### Windows -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. +Run Furious as Administrator. **Settings > General > Restart The Application As Administrator** restarts it with elevation. -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. +**sing-tun embeds its architecture-specific Wintun library**, so it does not require a separately copied `wintun.dll`. See the [binding used by Furious](https://github.com/LorenEteval/sing-tun-python/tree/v0.9.7.dev0/sing-tun-go/internal/wintun). -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...**. +For **tun2socks**, download the official [Wintun package](https://www.wintun.net/) and copy the matching DLL beside `Furious.exe`: + +- AMD64: `wintun\bin\amd64\wintun.dll` +- ARM64: `wintun\bin\arm64\wintun.dll` + +Its Wintun lookup uses the application directory or `C:\Windows\System32`. Match the DLL to the application's architecture. Native core TUN has its own driver handling; an error in one engine does not establish another engine's requirements. + +The Windows 7 package is AMD64-only. If primary-interface-name detection fails, set **Primary Adapter Interface Name** in the selected engine's settings. The legacy tun2socks automatic lookup uses a PowerShell command unavailable on Windows 7. ### 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`. +Use **Settings > General > Restart The Application As Superuser**, then enable TUN and connect. This preserves the packaged application's launch path. -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. +Application tun2socks currently binds its underlying interface to `en0`. If the active uplink has another name, use sing-tun with automatic or explicitly configured SOCKS interface binding, or a suitable native-core TUN configuration. ### 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. +| Engine | Requirements | +| --- | --- | +| sing-tun | Furious itself must run as root. `ip` and `resolvectl` must be available, and systemd-resolved must be active. | +| tun2socks | `bash`, `ip` from iproute2, and `pkexec` with a working PolicyKit implementation. Furious can run as a normal user and request privileges for its helper. | +| Native core TUN | The core needs host permissions to create TUN and routes; the tun2socks helper does not elevate native cores. | -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. +The default sing-tun engine cannot use the legacy privilege helper. If running Furious as root or using systemd-resolved is unsuitable, select **tun2socks**. That engine does not modify Linux DNS settings; arrange a working resolver separately. ## 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. +Furious resolves upstream server addresses and excludes them from application TUN routing so the core can reach the physical network. External Core must supply its actual upstream host/IP in **TUN Remote Address**. > [!WARNING] -> 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. +> Direct/bypass rules can feed traffic back into application TUN. This applies to both engines. Use **Global** unless every direct path is known to bypass TUN safely. -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. +The built-in **Bypass Mainland China** combination is rejected for Xray without native TUN and for Hysteria 1 when global TUN is enabled. Furious offers to switch to Global and reconnect. Selecting sing-tun does not remove that guard. Custom routing rules are not automatically inspected for every possible loop. -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. If required native-TUN preparation fails, the connection fails rather than silently switching to application Tun2socks. Check the first preparation error in the log. +Native cores manage their own TUN routing. Furious adds resolved Hysteria 2 upstream addresses to its native exclusions; managed Xray TUN uses Xray's automatic routing and outbound-interface settings. Required native preparation failures fail the connection rather than silently switching engines. -See [Routing](Routing) for backend routing support, named Xray routing profiles, and the distinction between routing, TUN, and System Proxy. +See [Routing](Routing) for backend-specific choices. -## Platform behavior +## Customize sing-tun settings -For application Tun2socks, Furious performs the following host setup: +Open **Settings > TUN > Customize sing-tun Settings...**. These settings affect only application sing-tun. -| 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. | +| Tab | Settings | +| --- | --- | +| **SOCKS Transit** | Stack, log level, SOCKS interface binding, maximum sessions, connect timeout, SOCKS UDP timeout, and TCP idle timeout. | +| **Interface and Stack** | Device name, MTU, IPv4/IPv6 prefixes, Go TCP congestion control, native UDP/ICMP timeouts, UDP NAT limit, mapping, and filtering. | +| **Host Settings** | Primary adapter overrides, TUN DNS, bypass addresses, and Windows primary-adapter DNS mitigation. | +| **Advanced Options** | Validated native JSON options not represented by ordinary controls. Uses the application's JSON editor. | -Native Xray-core and Hysteria 2 TUN use their own interface, address, route, and DNS settings instead of **Customize Tun2socks Settings...**. +Defaults include the **go** stack, log level **error**, MTU **1500**, IPv4 prefix **198.18.0.1/15**, no IPv6 prefix, and automatic device/interface selection. SOCKS defaults are 1,024 maximum sessions, a 10-second connect timeout, a 60-second UDP timeout, and a 300-second TCP idle timeout. The native stack UDP timeout defaults to **1m**; it is separate from the SOCKS transit timeout. -## Custom Tun2socks settings +Leave host overrides empty unless detection or the default resolver needs adjustment. The physical default gateway is detected automatically. **Bypass TUN Adapter Interface IP (separated by commas)** accepts literal IP addresses for upstream bypass. **Disable Primary Adapter Interface DNS (Mitigating DNS leaks on Windows)** is enabled by default. -Open **Settings > Connection and Interface > Customize Tun2socks Settings...**. These settings affect only application Tun2socks, not native Xray-core or Hysteria 2 TUN. +Advanced JSON uses `tun_options`, `stack_options`, and `host_options` groups with exact native field names. Supported extras include route-address/exclusion lists, `StrictRoute`, `InterfaceScope`, `ForwarderBindInterface`, and `IncludeAllNetworks`. `IncludeAllNetworks: true` requires an explicitly selected **gvisor** stack; `ForwarderBindInterface` is not supported by the go stack. -Leave the basic fields empty unless automatic detection fails: +Furious manages `AutoRoute`, external configuration, and DNS handling. Binding DNS hijacking is disabled; host DNS setup belongs to Furious. Unsupported fields or conflicting values are rejected. This is not a complete sing-box configuration editor. -- **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. +Initially Advanced Options may show `{}`. After saving, empty groups such as `"tun_options": {}` can remain. They add no overrides; missing values use defaults. Ordinary controls and advanced options are merged and validated before saving. Settings take effect on the next connection. -The memory section exposes bounded TCP send/receive buffer sizes and receive-buffer auto-tuning. No separate tun2socks memory-optimization procedure is required. +## Customize tun2socks settings -## Verifying TUN mode +Open **Settings > TUN > Customize Tun2socks Settings...**. These settings affect only application tun2socks. -For a strict test, select **Do Not Change System Proxy** in Settings or use a client that ignores proxy settings. Then connect and run: +- **Primary Adapter Interface Name** overrides Windows name detection. +- **Primary Adapter Interface IP** and **Default Primary Gateway IP** must be supplied together for a manual gateway override. Prefer automatic detection on Linux, where routes need an interface name rather than the IP-oriented field. +- **TUN Adapter Interface DNS** overrides TUN DNS on Windows and macOS. +- **Bypass TUN Adapter Interface IP (separated by commas)** supplies literal upstream bypass addresses instead of automatic resolution. +- **Disable Primary Adapter Interface DNS (Mitigating DNS leaks on Windows)** controls Windows DNS mitigation. +- **Memory Optimization** controls bounded TCP send/receive buffers and receive-buffer auto-tuning. + +## DNS and cleanup + +| Engine | Windows | macOS | Linux | +| --- | --- | --- | --- | +| sing-tun | Applies TUN DNS and optional primary IPv4 DNS mitigation; snapshots and restores the primary adapter's static/DHCP DNS state. | Saves network-service DNS, applies TUN DNS, and restores saved values. | Sets DNS and the `~.` routing domain on the new interface through systemd-resolved; does not edit `/etc/resolv.conf`. | +| tun2socks | Applies TUN DNS and optional primary DNS mitigation; legacy cleanup resets primary DNS to DHCP. | Saves and restores network-service DNS. | Does not modify host DNS. | + +For tun2socks on Windows, disable primary DNS mitigation if static DNS must be retained, or restore it afterward. sing-tun uses its own restoration snapshots; the legacy DHCP-reset limitation does not apply to it. + +Startup, disconnect, reconnect, and shutdown request cleanup of the connection attempt's resources. Failed platform commands, privilege loss, force kills, or power loss can leave host state behind. If sing-tun cleanup cannot prove release, Furious retains ownership and can refuse another connection; a disconnected label alone does not prove that routes or interfaces were removed. + +Use **Application** and **TUN** logs to identify the first failure. Restore only the affected host state; do not remove unrelated routes or processes by name. For a stale legacy Linux `utun777`, only after confirming it belongs to the interrupted Furious connection and is unused, remove it with `sudo ip tuntap del mode tun dev utun777`. + +## Verifying TUN + +Select **Do Not Change System Proxy** or use a client that ignores proxy settings. Connect, then run: ```shell curl --noproxy "*" https://icanhazip.com ``` -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. - -## Cleanup and troubleshooting - -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. - -Cleanup is best effort. A forced termination, power loss, failed platform command, or privilege loss can leave host state behind. - -- **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. After confirming that `utun777` is the stale interface created by this Furious connection and no active connection uses it, remove it 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. - -If setup still fails, open the **Log** page and inspect **Application** and either **Tun2socks** or **Core** messages for the first failed stage. +The result should be the proxy server's public exit address. Application engines share the **TUN** log category, with `[sing-tun]` or `[tun2socks]` source prefixes. Native TUN output stays in **Core**. ## See also diff --git a/Troubleshooting-and-Diagnostics.md b/Troubleshooting-and-Diagnostics.md index 737462e..e90798a 100644 --- a/Troubleshooting-and-Diagnostics.md +++ b/Troubleshooting-and-Diagnostics.md @@ -1,6 +1,6 @@ # Troubleshooting and Diagnostics -Furious separates connection state, application logs, core output, tun2socks output, traffic statistics, and endpoint information. Start with the narrowest signal that corresponds to the failure instead of changing several settings at once. +Furious separates connection state, application logs, core output, application TUN output, traffic statistics, and endpoint information. Start with the narrowest signal that corresponds to the failure instead of changing several settings at once. ## A practical diagnostic sequence @@ -8,19 +8,21 @@ Furious separates connection state, application logs, core output, tun2socks out 2. Note the visible connection state: **Disconnected**, **Connecting**, **Connected**, or **Disconnecting**. 3. Open **Log** and choose **All Logs**. 4. Repeat the action and identify the first relevant error, not only the final cleanup message. -5. Filter by **Application**, **Core**, or **Tun2socks** to isolate its owner. +5. Filter by **Application**, **Core**, or **TUN** to isolate its owner. 6. Disable optional TUN and custom routing temporarily to test the basic proxy path. 7. Re-enable one feature at a time. Do not post an unredacted profile, subscription URL, QR code, complete core configuration, environment block, or credential-bearing log. +Connection failures offer **Copy Error** and **Open Logs**. Copy Error copies the displayed failure and keeps the dialog open. Open Logs closes it and opens the main window's Log page. Review diagnostic text before sharing it. + ## The Log page Furious uses one unified Log page. Every entry belongs to a registered category: - **Application** — Furious Python logging, controllers, services, repositories, UI, and host integration; - **Core** — Xray, Hysteria, Hysteria 2, External Core, and other runtime output; -- **Tun2socks** — Furious's application-managed tun2socks process; +- **TUN** — either application engine, with `[sing-tun]` or `[tun2socks]` prefixes; native proxy-core TUN output remains in **Core**; - plugin-provided categories — added dynamically when installed extensions register them. Choose **All Logs** for chronology or a category for focused inspection. The selected category persists. Search combines with the category and filters text or a regular expression as you type. Enter or clearing the box applies immediately; an invalid regular expression is treated as literal text. Ctrl+F (Command+F on macOS) focuses the search box and selects its query. @@ -106,7 +108,19 @@ See [Quick Start](Quick-Start) and [TUN Mode](TUN-Mode). ### TUN starts, but traffic stops -Return routing to **Global**, disconnect cleanly, and test again. Direct/bypass rules can loop when application tun2socks owns the TUN path. Verify privileges and platform prerequisites in [TUN Mode](TUN-Mode). +Return routing to **Global**, disconnect cleanly, and test again. Direct/bypass rules can loop with either application engine. Verify privileges and platform prerequisites in [TUN Mode](TUN-Mode). + +### sing-tun fails before connecting + +On Linux, sing-tun requires Furious itself to run as root, `ip`, and an active systemd-resolved service accessible through `resolvectl`. The tun2socks PolicyKit helper cannot elevate sing-tun. Select tun2socks if that permission or resolver arrangement is unsuitable. + +On Windows, sing-tun embeds Wintun but still requires Administrator privileges. The separately copied Wintun DLL instructions apply to tun2socks. + +The default sing-tun log level is **error**. Change it in **Customize sing-tun Settings... > SOCKS Transit**, then reconnect if more detail is needed. Engine changes also apply to the next connection; native core TUN takes priority over the application selector. + +### Cleanup reports retained TUN resources + +Inspect the first Application/TUN cleanup error. Furious can retain ownership and refuse a new connection when it cannot verify release. A disconnected status does not prove that host routes, DNS, or interfaces were restored. Correct the reported permission or host-state problem and restore only resources identified as belonging to the affected connection. Restarting the application alone does not guarantee that stale host state is repaired. ### Routing choices are missing @@ -148,7 +162,7 @@ Include: - operating system and CPU architecture; - Python and PySide6 versions for source/PyPI installations; - backend and protocol; -- whether System Proxy, TUN, native TUN, application tun2socks, and custom routing were enabled; +- whether System Proxy, global TUN, native TUN, and custom routing were enabled, plus the selected application TUN engine and sing-tun stack if applicable; - exact reproduction steps; - the smallest relevant redacted log excerpt; - whether the problem reproduces with Global routing and TUN disabled.