Firestack is a Go-based network tunneling and privacy-focused system designed for Android and other platforms. It acts as a userspace TCP/UDP connection monitor, firewall, and DNS resolver, built specifically to power the Rethink DNS + Firewall + VPN application. By utilizing a hard-fork of Google's outline-go-tun2socks and integrating the gVisor/netstack TCP/IP stack, Firestack provides a SOCKS-like interface for traffic intercepted via a TUN device README.md1-7
The system is designed to provide:
This page provides a high-level architectural overview. For deep technical details, refer to the child pages:
Sources: README.md1-23 intra/tunnel.go74-119
Firestack is organized into several interacting layers that bridge the gap between the Android VpnService (or OS network interface) and the internet.
Description: The rtunnel struct coordinates the entire lifecycle. It initializes the gVisor stack.Stack, which pulls packets from the TUN file descriptor. Protocol-specific handlers then consult the Resolver for DNS logic (including ALG translation) and the Proxifier to determine which proxy (e.g., WireGuard) should handle the outbound connection intra/tunnel.go121-137 intra/tunnel.go194-212
Sources: intra/tunnel.go121-212 tunnel/tunnel.go68-78
The tunnel system orchestrates the gVisor-based network stack and protocol handlers. The primary entry point for external callers is typically a variant of Connect or NewTunnel intra/tun2socks.go149-182
rtunnel: The main implementation of the Tunnel interface, managing the resolver, proxies, and network stack state intra/tunnel.go121-137gtunnel: Wraps the gVisor stack.Stack and handles the raw SeamlessEndpoint interaction with the TUN device tunnel/tunnel.go68-78tunmtu (for the device) and linkmtu (for the underlying network) to optimize performance for protocols like WireGuard intra/tunnel.go92-107Firestack features a complex DNS subsystem that supports modern encrypted protocols and an Application Level Gateway (ALG).
dnsx.Resolver: The central orchestrator for DNS queries, initialized during tunnel setup intra/tunnel.go212The proxy system manages various outbound tunnels and intelligent routing.
ipn.Proxifier: Manages a registry of proxies and handles selection logic intra/tunnel.go195wgproxy: A userspace WireGuard implementation using wireguard-go and gVisor README.md13-18Traffic intercepted by gVisor is processed by protocol handlers that implement firewall policies and proxying logic.
GConnHandler: Interface for TCP, UDP, and ICMP processing tunnel/tunnel.go41NewGTunnel: Function that attaches the SeamlessEndpoint to the stack.Stack and initializes protocol handlers tunnel/tunnel.go173-221Route: Configures the gVisor routing table for IPv4/IPv6 based on settings like IP46 intra/netstack/netstack.go175-212Firestack exposes extensive runtime configuration and observability through global settings and structured statistics.
Global flags in the settings package control the behavior of the network stack, DNS resolver, and proxies:
settings.Debug: Enables verbose logging and debug behavior intra/settings/config.go19settings.NICID: The identifier used for the virtual NIC within the gVisor stack, default 0x01 intra/settings/config.go16settings.HappyEyeballs: Global flag to enable the Happy Eyeballs algorithm for dual-stack connections intra/settings/config.go35settings.EndpointIndependentMapping: Enables EIM for UDP as per RFC 4787 intra/settings/config.go47Description: The NetStat struct provides a unified view of the system's health, aggregating data from the gVisor stack and the tunnel's own state. Statistics are collected via the Stat() method on the Tunnel interface intra/tunnel.go118 tunnel/tunnel.go65
Sources: intra/tunnel.go118 tunnel/tunnel.go65 intra/settings/config.go15-80
Firestack uses a cross-platform build system to produce artifacts for multiple operating systems, with a primary focus on Android.
| Platform | Artifact Type | Build Tool |
|---|---|---|
| Android | .aar (Library) | gomobile bind, make intra Makefile65-71 |
| iOS/macOS | .xcframework | gomobile bind Makefile91-92 |
| Linux | Binary | xgo (Docker-based) Makefile82-84 |
| Windows | .exe | xgo (Docker-based) Makefile86-88 |
The build process includes a unique runtime patching mechanism using go-patch-overlay to apply patches to the Go runtime, such as modifying runtime.writeErr for Android Makefile78-80 Additionally, Firestack uses go:linkname (via -checklinkname=0 LDFLAGS) to modify runtime internals to improve diagnostics and bypass secure mode restrictions on Android Makefile13-16
For details, see Build System and Deployment.
Sources: README.md71-118 Makefile54-90 intra/tun2socks.go75-95
The project employs a robust CI/CD pipeline via GitHub Actions, focusing on supply chain security and automated publication.
For details, see CI/CD and Release Workflows.
Sources: README.md27-31
Refresh this wiki