Document Linux client networking integrations

- Record research on proxy clients, routing libraries, and firewall options
- Recommend rtnetlink with nftnl/mnl for Roentgen

1 files changed, 51 insertions, 0 deletions

diff --git a/docs/research/client-network-integrations.md b/docs/research/client-network-integrations.md
new file mode 100644
index 0000000..07f177d
--- /dev/null
+++ b/docs/research/client-network-integrations.md
@@ -0,0 +1,51 @@
+# Networking libraries in Linux proxy clients
+
+Researched 2026-10-30. This is source research for the technology-stack discussion, not an implementation decision. No routes, firewall rules, services or proxy connections were changed or tested.
+
+## Decision after research
+
+The human chose `rtnetlink` plus `nftnl`/`mnl`, following Mullvad's in-process library approach. The command-backed `nftables` crate remains a researched alternative, not the selected adapter.
+
+The human also clarified that ALT's Xray package has been updated to the latest version; 26.3.27 was only the locally installed version. Target the current distribution core. The [package page](https://packages.altlinux.org/en/sisyphus/srpms/xray-core/) returned an anti-bot page during this follow-up, so current package availability is user-provided evidence. Exact route ownership can now be evaluated against the newer core, while Roentgen retains responsibility for the persistent kill switch.
+
+## Findings
+
+Existing clients use networking libraries, often inside a separate proxy core. A frontend's language does not identify the component that manages Linux routes. Route management, TUN packet handling and firewall policy can belong to different components.
+
+### v2rayN
+
+Inspected revision `57f17d5939e88c8e643ab49b90869d637765e75a`.
+
+Current v2rayN supports native Xray TUN. Its configuration builder supplies `autoSystemRoutingTable`, gateway addresses and outbound-interface settings. Linux additionally enables `autoSystemDnsToGateway`; the WFP leak-blocking option in this code is Windows-specific. These are instructions to the core, rather than C# code implementing Linux routing. See the [Xray inbound builder](https://github.com/2dust/v2rayN/blob/57f17d5939e88c8e643ab49b90869d637765e75a/v2rayN/ServiceLib/Services/CoreConfig/V2ray/V2rayInboundService.cs#L56).
+
+There is also a sing-box path. When legacy protection is enabled, a non-custom configuration using another core can receive a sing-box SOCKS pre-core. The context builder then disables direct TUN handling in the main core. The sing-box inbound builder sets `auto_route`, `strict_route`, interface addresses and route exclusions. This is conditional behavior, not evidence that every current v2rayN TUN session uses sing-box. See [helper selection](https://github.com/2dust/v2rayN/blob/57f17d5939e88c8e643ab49b90869d637765e75a/v2rayN/ServiceLib/Handler/ConfigHandler.cs#L1579), [context construction](https://github.com/2dust/v2rayN/blob/57f17d5939e88c8e643ab49b90869d637765e75a/v2rayN/ServiceLib/Handler/Builder/CoreConfigContextBuilder.cs#L143) and [sing-box inbound construction](https://github.com/2dust/v2rayN/blob/57f17d5939e88c8e643ab49b90869d637765e75a/v2rayN/ServiceLib/Services/CoreConfig/Singbox/SingboxInboundService.cs).
+
+Following the native path into Xray v26.10.29, Linux interface and route operations use `github.com/vishvananda/netlink`, including `LinkSetUp`, `RouteAdd`, `RouteDel` and route subscriptions. DNS automation separately invokes resolver tools. Thus even this core uses a mixture of libraries and commands. See [Linux TUN implementation](https://github.com/XTLS/Xray-core/blob/v26.10.29/proxy/tun/tun_linux.go) and [dependencies](https://github.com/XTLS/Xray-core/blob/v26.10.29/go.mod).
+
+### Throne and sing-tun
+
+Inspected Throne revision `1f30af24e2de13e0735dede240e4592a93e18b64`.
+
+Throne's Go core embeds sing-box components and depends on sing-tun. Its module replacements select Throne forks of sing-box and Xray; quoting only the nominal upstream versions would misidentify the code. See [effective dependencies](https://github.com/throneproj/Throne/blob/1f30af24e2de13e0735dede240e4592a93e18b64/core/go.mod) and [embedded core construction](https://github.com/throneproj/Throne/blob/1f30af24e2de13e0735dede240e4592a93e18b64/core/internal/boxbox/box.go).
+
+The pinned sing-tun revision `611d83b7a57b4719be45581eb674942ff561de6c` uses `github.com/sagernet/netlink` for Linux routes and policy rules. Its nftables redirect implementation uses `github.com/sagernet/nftables`. These are library operations rather than generated `ip` or `nft` command strings in the inspected routines. See [Linux TUN](https://github.com/SagerNet/sing-tun/blob/611d83b7a57b4719be45581eb674942ff561de6c/tun_linux.go), [redirect rules](https://github.com/SagerNet/sing-tun/blob/611d83b7a57b4719be45581eb674942ff561de6c/redirect_nftables.go) and [dependencies](https://github.com/SagerNet/sing-tun/blob/611d83b7a57b4719be45581eb674942ff561de6c/go.mod).
+
+Throne also has its own guard using the Go nftables library. That library opens a `NETLINK_NETFILTER` socket through `mdlayher/netlink`. See the [guard backend](https://github.com/throneproj/Throne/blob/1f30af24e2de13e0735dede240e4592a93e18b64/core/internal/guard/backend_linux.go) and [library connection implementation](https://github.com/sagernet/nftables/blob/55b467739faeff10b431fbc060cba7c5222c85cf/conn.go).
+
+Its guard uses a socket-owned table that the kernel deletes when its owning socket closes. Roentgen must not copy that lifetime for a guard required to survive the controlling process crashing. Library choice alone does not establish kill-switch behavior. The lifetime is explicit in the [guard's arm function](https://github.com/throneproj/Throne/blob/1f30af24e2de13e0735dede240e4592a93e18b64/core/internal/guard/backend_linux.go#L87).
+
+### Mullvad's Rust Linux implementation
+
+Mullvad is a VPN client, not an Xray frontend, but provides a relevant Rust example. Inspected revision `8b7cb0c272f1be5d0f85f250dbfa8d96c688b0e3`.
+
+Its Linux routing code uses `rtnetlink`, including connection creation, route requests and policy-rule operations. Its firewall uses `nftnl` to construct batches and `mnl` to send them over a Netfilter socket. This is library-based in-process integration. See [routing implementation](https://github.com/mullvad/mullvadvpn-app/blob/8b7cb0c272f1be5d0f85f250dbfa8d96c688b0e3/talpid-routing/src/unix/linux.rs), [firewall implementation](https://github.com/mullvad/mullvadvpn-app/blob/8b7cb0c272f1be5d0f85f250dbfa8d96c688b0e3/talpid-core/src/firewall/linux.rs#L199) and [firewall dependencies](https://github.com/mullvad/mullvadvpn-app/blob/8b7cb0c272f1be5d0f85f250dbfa8d96c688b0e3/talpid-core/Cargo.toml).
+
+## Rust options for Roentgen
+
+- `rtnetlink` provides typed operations for interfaces, addresses, routes and policy rules. It is the suitable starting candidate for host routing, without implementing Netlink messages ourselves. See [version 0.23.0 documentation](https://docs.rs/rtnetlink/0.23.0/rtnetlink/).
+- `nftables` provides Rust types for the nftables JSON API. Its helper invokes the `nft` executable, including `nft -j -f -` for updates. It is a library abstraction with a command backend, not an in-process libnftables binding. See [version 0.6.3 helper source](https://docs.rs/nftables/0.6.3/src/nftables/helper.rs.html).
+- `nftnl` wraps C libnftnl and can construct atomic batches. With `mnl`, as used by Mullvad, it offers in-process firewall integration. It is lower level; its own documentation notes incomplete coverage and rough edges. See [version 0.9.4 documentation](https://docs.rs/nftnl/0.9.4/nftnl/).
+
+Recommendation, not an accepted decision: use established libraries. Start with `rtnetlink` for routing. Choose between the typed `nftables` command-backed API and the lower-level `nftnl`/`mnl` approach for firewall management. The former is a reasonable first-release default if invoking system `nft` internally is acceptable. The latter is supported by a substantial Rust VPN example but requires more low-level firewall code and native build dependencies.
+
+The originally observed local Xray 26.3.27 lacks the newer host-routing automation used by current v2rayN. That observation is historical and does not constrain the corrected current-package target above. See the [ALT runtime report](alt-runtime-integration.md). No proposed library replaces Xray's TUN packet handling or proves that Roentgen's required rule expressions and crash recovery work. Those require implementation-specific validation.