Overview

Relevant source files

• intra/backend/ipn_proxies.go
• intra/backend/netstat.go
• intra/common.go
• intra/core/connmap.go
• intra/dnsx/alg.go
• intra/dnsx/cacher.go
• intra/dnsx/transport.go
• intra/icmp.go
• intra/ipn/auto.go
• intra/ipn/nop.go
• intra/ipn/proxies.go
• intra/ipn/proxy.go
• intra/ipn/wg/stats.go
• intra/ipn/wgproxy.go
• intra/listener.go
• intra/netstack/netstack.go
• intra/netstack/stat.go
• intra/protect/protect.go
• intra/settings/config.go
• intra/settings/proxyopts.go
• intra/tcp.go
• intra/tun2socks.go
• intra/tunnel.go
• intra/udp.go
• intra/udpmux.go
• tunnel/tunnel.go

Purpose and Scope

Firestack is a Go-based VPN/tunnel system that provides DNS resolution, proxy management, and anti-censorship capabilities through a userspace network stack. The system intercepts network traffic via a TUN device, processes it through a gVisor-based TCP/IP stack, and routes connections through configurable DNS resolvers and proxy chains.

This document provides an architectural overview of the entire firestack system, introducing the major components and their interactions. For detailed information about specific subsystems, see:

• DNS resolution architecture: DNS Resolution System
• Proxy management and routing: Proxy Management System
• Network stack and TUN device handling: Network Stack and Tunnel
• Anti-censorship techniques: Connection Management and Anti-Censorship

---

System Architecture

Firestack is organized into several layers that work together to provide a programmable network stack:

Layer Overview

Layer	Components	Primary Responsibilities
Application Interface	Tunnel, Resolver, Proxies	External API, system lifecycle management
DNS Resolution	Gateway, Transport, Cacher	DNS query processing, ALG translation, caching
Proxy Management	Proxifier, WgProxy, socks5, http1, auto	Proxy selection, health monitoring, routing
Network Stack	gtunnel, netstack.GConnHandler	gVisor TCP/IP stack, packet forwarding
Connection Handling	baseHandler, tcpHandler, udpHandler, icmpHandler	Flow evaluation, policy enforcement, NAT
Operating System	protect.Controller, TUN device	Socket protection, device I/O

Sources: intra/tun2socks.go1-250 intra/tunnel.go1-150 tunnel/tunnel.go1-250

---

Core Architecture Diagram

Description: This diagram shows the core architecture using actual struct and interface names from the codebase. The Tunnel interface is implemented by rtunnel, which coordinates the gtunnel (network stack), resolver (DNS), and proxifier (proxy routing). The gVisor stack routes packets to protocol-specific handlers (tcpHandler, udpHandler, icmpHandler), which all extend baseHandler for common flow evaluation logic.

Sources: intra/tunnel.go126-138 intra/tcp.go46-49 intra/udp.go44-47 intra/icmp.go25-27 intra/common.go69-86 intra/dnsx/transport.go188-207 intra/ipn/proxies.go229-265 tunnel/tunnel.go68-78

---

Major Components

1. Tunnel Management (rtunnel, gtunnel)

The tunnel subsystem manages the TUN device lifecycle and coordinates between the application layer and the network stack.

Key Types:

• Tunnel interface: Public API for tunnel operations (intra/tunnel.go79-124)
• rtunnel struct: Top-level tunnel coordinator (intra/tunnel.go126-138)
• gtunnel struct: gVisor network stack wrapper (tunnel/tunnel.go68-78)

Responsibilities:

• TUN device file descriptor management
• MTU configuration (separate tunmtu for TUN device, linkmtu for underlying network)
• Network stack initialization and lifecycle
• PCAP packet capture integration

Key Functions:

• NewTunnel(): Creates tunnel with TUN fd, MTU, interface addresses (intra/tunnel.go153-169)
• SetLinkAndRoutes(): Attaches TUN device to network stack (intra/tunnel.go360-440)
• Restart(): Hot-swaps TUN device without stopping services (intra/tunnel.go487-550)

Sources: intra/tunnel.go1-600 tunnel/tunnel.go1-350 intra/tun2socks.go68-120

---

2. DNS Resolution System (resolver, Gateway)

The DNS subsystem provides query processing with Application Level Gateway (ALG) translation, caching, and multiple transport support.

Key Types:

• Resolver interface: Main DNS resolver API (intra/dnsx/transport.go168-186)
• resolver struct: Implements multi-transport DNS resolution (intra/dnsx/transport.go188-207)
• Gateway interface: ALG translation and IP mapping (intra/dnsx/alg.go83-104)
• dnsgateway struct: Implements ALG with three-map system (intra/dnsx/alg.go857-877)

ALG Translation System: The ALG system generates fake IPs (RFC6598 100.64.x.x for IPv4, RFC8215a for IPv6) to enable per-domain routing policies. Three maps maintain bidirectional translations:

• alg map: domain+qtype → algans (fake IP answers)
• nat map: algip → baseans (fake → real IP)
• ptr map: realip → baseans (real IP → domains)

Key Functions:

• q(): Queries primary/secondary transports, performs ALG translation (intra/dnsx/alg.go1142-1320)
• X(): Undoes ALG translation, returns real IPs (intra/dnsx/alg.go1481-1558)
• PTR(): Reverse lookup from IP to domain names (intra/dnsx/alg.go1562-1613)

Sources: intra/dnsx/alg.go1-2500 intra/dnsx/transport.go188-1100 intra/dnsx/cacher.go1-500

---

3. Proxy Management (Proxifier, Proxy implementations)

The proxy subsystem selects and manages connections through various proxy types with health monitoring and automatic failover.

Key Types:

• Proxies interface: Proxy provider API (intra/ipn/proxies.go217-228)
• proxifier struct: Manages proxy pool and selection (intra/ipn/proxies.go229-265)
• Proxy interface: Common proxy interface (intra/ipn/proxies.go167-188)
• Implementations: wgproxy, socks5, http1, auto, exit, base (intra/ipn/proxies.go155-166)

Connection Pinning: The system uses two Sieve caches for intelligent routing:

• ipPins: Maps netip.AddrPort → proxyid (per-destination pinning)
• uidPins: Maps uid+dst → proxyid (per-app pinning)

Pins expire after 10 minutes (pintimeout) unless refreshed by successful connections.

Proxy Types:

• Exit: Direct connection via underlying network (always available)
• Base: May loop back through tunnel (for DNS over VPN)
• Block: Drops all traffic (policy enforcement)
• Auto: Races multiple proxies, selects fastest
• WgProxy: WireGuard with gVisor integration, supports hop chaining
• SOCKS5/HTTP: Standard proxy protocols
• RPN types: Remote proxies (Win, WS, H2, SE)

Key Functions:

• ProxyTo(): Selects proxy for destination, checks pins (intra/ipn/proxies.go453-600)
• Refresh(): Updates proxy health, re-resolves endpoints (intra/ipn/wgproxy.go329-379)
• Ping(): Sends WireGuard keepalive packets (intra/ipn/wgproxy.go255-293)

Sources: intra/ipn/proxies.go1-1300 intra/ipn/wgproxy.go1-1500 intra/ipn/auto.go1-400 intra/ipn/proxy.go1-800

---

4. Network Stack Integration (gtunnel, Protocol Handlers)

The network stack layer bridges the TUN device to the gVisor TCP/IP stack and routes packets to protocol-specific handlers.

Packet Flow:

1. Ingress from TUN: TUN device → endpoint.Attach() → linkDispatcher.dispatch()
2. Distribution: supervisor.distribute() hashes 5-tuple to select processor (0-7)
3. Injection: Processor calls stack.InjectInbound() to gVisor stack
4. Protocol Demux: Stack routes to TCP/UDP/ICMP handlers based on protocol
5. Flow Evaluation: baseHandler.onFlow() performs ALG undo, calls policy listener
6. Proxy Selection: Handler calls proxifier.ProxyTo() to select proxy
7. Connection: Handler dials via selected proxy, pipes data bidirectionally

Key Types:

• GConnHandler: Protocol handler interface (intra/netstack/netstack.go1-200)
• tcpHandler: TCP connection proxy (intra/tcp.go46-49)
• udpHandler: UDP connection proxy with EIM/EIF NAT (intra/udp.go44-47)
• icmpHandler: ICMP echo (ping) handler (intra/icmp.go25-27)
• baseHandler: Common flow evaluation logic (intra/common.go69-86)

Key Functions:

• Proxy(): Main entry point for connection requests (intra/tcp.go241-363 intra/udp.go162-191)
• onFlow(): Performs ALG undo, calls policy listener (intra/common.go133-230)
• judge(): Evaluates flow against policies, returns Mark (intra/common.go264-355)
• Connect(): Selects proxy and establishes connection (intra/udp.go194-386)

Sources: intra/tcp.go1-450 intra/udp.go1-400 intra/icmp.go1-150 intra/common.go1-800 tunnel/tunnel.go1-350

---

5. Policy Engine (SocketListener, Flow Evaluation)

The policy engine determines routing decisions for each connection through a multi-stage evaluation process.

Policy Flow:

1. Preflow: Early UID detection, may provide UID hint before full evaluation
2. ALG Undo: Translate fake IPs back to real IPs and domain names
3. Flow: Main policy evaluation, returns *Mark with routing decision
4. Proxy Selection: Use PIDs from Mark to select appropriate proxy
5. PostFlow: Notify listener of final routing decision
6. Connection: Establish connection, pipe data, report summary on close

Mark Structure:

Key Types:

• SocketListener interface: Policy decision callbacks (intra/listener.go1-200)
• Mark: Flow evaluation result with PIDs (intra/common.go1-100)
• SocketSummary: Connection statistics reported on close

Key Functions:

• Preflow(): Early UID detection (intra/common.go165-187)
• Flow(): Main policy evaluation (intra/common.go133-230)
• PostFlow(): Final routing notification
• OnSocketClosed(): Connection summary reporting

Sources: intra/listener.go1-200 intra/common.go1-800

---

Key Concepts

Application Level Gateway (ALG)

ALG translation enables per-domain routing policies by generating fake IP addresses for DNS responses. When a connection is made to a fake IP, the system translates it back to the real IP and associated domain name, allowing the policy engine to make routing decisions based on domain names rather than just IP addresses.

Fake IP Ranges:

• IPv4: 100.64.x.x (RFC6598, Carrier-Grade NAT)
• IPv6: 64:ff9b:1:da19::/96 (RFC8215a, NAT64 prefix variant)

Translation Process:

1. DNS query arrives → gateway.q() queries upstream
2. Real IPs received → translate() generates fake IPs
3. Fake IPs registered in alg, nat, ptr maps
4. Connection to fake IP → X() translates back to real IPs + domains
5. Policy engine uses domains for routing decisions

Sources: intra/dnsx/alg.go857-2500

Connection Pinning

Pinning associates a successful connection with a specific proxy for a duration, avoiding repeated proxy selection overhead and providing stable routing for ongoing sessions.

Pin Types:

• IP pinning: netip.AddrPort → proxyid (destination-based)
• UID pinning: uid+dst → proxyid (per-app + destination)

Pin Lifetime: 10 minutes (configurable via pintimeout)

Use Cases:

• HTTP/2 connection reuse
• WebSocket stability
• Streaming session continuity

Sources: intra/ipn/proxies.go450-600 intra/core/sieve.go1-300

Proxy Health Monitoring

Proxies undergo continuous health monitoring to enable automatic failover and smart selection by the auto proxy.

Health States:

• TOK (OK): Proxy responding normally
• TKO (Not OK): Proxy experiencing errors
• TUP (Up): Proxy initializing
• TNT (Unresponsive): Proxy not responding to keepalives
• TPU (Paused): Proxy temporarily disabled
• END: Proxy stopped

Monitoring Mechanisms:

• Periodic ping/keepalive (every 5 seconds for WireGuard)
• Connection success/failure tracking
• Automatic refresh on failure
• Statistics collection (RTT, packet loss)

Sources: intra/ipn/wgproxy.go255-380 intra/ipn/proxies.go70-93

Hop Chaining (Proxy via Proxy)

WireGuard proxies support hop chaining, where one proxy routes traffic through another. This enables nested VPN scenarios and privacy-preserving proxy chains.

Constraints:

• Only WireGuard proxies can act as "hop" (via) proxies
• Hop proxy must have default routes (0.0.0.0/0, ::/0)
• MTU calculations account for encapsulation overhead
• Origin proxy must have routes to hop proxy's endpoints

MTU Calculation:

origin_mtu = min(
    hop_mtu - wg_overhead - ip_overhead,
    link_mtu
)

Sources: intra/ipn/proxies.go1100-1300 intra/ipn/wgproxy.go800-1000

---

Data Flow Example: HTTPS Request

Step-by-step:

1. Application writes to fake IP 100.64.1.2:443 (ALG address)
2. TUN device delivers packet to gVisor stack
3. Stack routes to tcpHandler.Proxy()
4. baseHandler.onFlow() undoes ALG: fake IP → real IP + domain
5. listener.Flow() evaluates policy, returns routing decision
6. proxifier.ProxyTo() selects WireGuard proxy based on PIDs
7. wgproxy.Dial() establishes connection through WireGuard tunnel
8. Bidirectional data piping between gVisor and proxy
9. On close, listener.OnSocketClosed() receives connection summary

Sources: intra/tcp.go241-450 intra/common.go133-355 intra/dnsx/alg.go1481-1558 intra/ipn/proxies.go453-600

---

Initialization Sequence

Initialization Steps:

1. Context Setup: Create parent context, setup logging and crash handlers
2. DNS64/NAT64: Initialize NatPt for IPv4/IPv6 translation
3. Proxifier: Create proxy manager with built-in proxies (Exit, Base, Block, Auto)
4. Resolver: Create DNS resolver with gateway, ALG, and default transports
5. Services: Initialize reverse proxy and local services
6. Handlers: Create protocol handlers (TCP, UDP, ICMP) with dependencies
7. Network Stack: Create gVisor stack (gtunnel) with handlers
8. TUN Attachment: Attach TUN device fd to endpoint, configure routes
9. Start Processing: Begin reading packets from TUN, processing through stack

Sources: intra/tunnel.go153-280 tunnel/tunnel.go110-250 intra/dnsx/transport.go212-244 intra/ipn/proxies.go285-335

---

Configuration and Runtime Control

Global Settings

The system exposes global atomic flags for runtime configuration:

Setting	Type	Purpose
Debug	bool	Enable verbose debug logging
Loopingback	bool	Allow DNS queries to loop back through tunnel
SingleThreaded	bool	Force single-threaded packet processing
ExperimentalWireGuard	bool	Enable WireGuard reverse proxy features
HappyEyeballs	bool	Enable RFC 8305 Happy Eyeballs for dual-stack
PortForward	bool	Enable UDP port forwarding for peer discovery
BlockMode	int	Firewall mode: None/Sink/Filter/FilterProc
PtMode	int	DNS64/NAT64 mode: Auto/Disabled/Force

Sources: intra/settings/config.go1-100

Dynamic Proxy Management

Proxies can be added, removed, and updated at runtime:

Sources: intra/ipn/proxies.go54-125 intra/ipn/wgproxy.go396-461

DNS Transport Management

DNS transports can be dynamically added and removed:

Sources: intra/dnsx/transport.go306-370 intra/dnsx/transport.go421-464

---

Thread Safety and Concurrency

Firestack uses several concurrency patterns for safe multi-threaded operation:

Lock-Free Atomics

• Global settings via atomic.Bool, atomic.Int32
• Proxy status tracking via atomic.Int64
• Connection state flags via atomic.Bool

Mutex-Protected Maps

• Proxy registry: sync.RWMutex protecting map[string]Proxy
• DNS transport map: sync.RWMutex protecting map[string]Transport
• Connection tracking: sync.RWMutex protecting connection maps

Channels for Coordination

• Summary reporting: Buffered channels for *SocketSummary, *DNSSummary
• Packet distribution: Channels for distributing packets to processor pool
• Lifecycle signals: Context cancellation for graceful shutdown

Barriers and Coalescing

• Request coalescing: core.Barrier for DNS queries (prevents duplicate queries)
• Refresh barriers: core.Barrier for proxy refresh (prevents stampeding)
• Connection pinning: core.Sieve with TTL-based expiration

Sources: intra/core/barrier.go1-300 intra/core/sieve.go1-500 intra/common.go69-103

---

Error Handling and Recovery

Panic Recovery

All goroutines use core.Recover() to catch panics and log stack traces without crashing the entire system:

Graceful Degradation

• DNS: Falls back to secondary transport on primary failure
• Proxy: Falls back to next proxy in list on connection failure
• ALG: Disables translation if unable to generate fake IPs
• Network Stack: Continues with reduced functionality on handler errors

Connection Stalling

Failed connections are "stalled" (delayed close) to prevent rapid retry storms:

• Blocked connections: Stalled for configurable duration (max 10 seconds)
• Failed DNS: Stalled with exponential backoff
• Failed proxy: Tracked in expiring map to prevent immediate retry

Sources: intra/core/recover.go1-200 intra/common.go400-500 intra/ipn/proxies.go800-900

---

Summary

Firestack provides a programmable network stack with three major capabilities:

1. DNS Resolution with ALG: Generates fake IPs for DNS responses, enabling per-domain routing policies while maintaining compatibility with IP-based routing
2. Multi-Proxy Routing: Selects proxies based on connection characteristics (UID, destination, domain), with automatic failover and health monitoring
3. Anti-Censorship: Supports connection retry strategies, TCP/TLS splitting, and WireGuard proxy chaining to circumvent network restrictions

The architecture separates concerns through clear interfaces (Tunnel, Resolver, Proxies) implemented by coordinator structs (rtunnel, resolver, proxifier) that manage lower-level components (gVisor stack, DNS transports, proxy instances). Protocol handlers (tcpHandler, udpHandler, icmpHandler) share common logic through baseHandler, ensuring consistent flow evaluation and policy enforcement across all connection types.

For detailed information about each subsystem, see the respective wiki pages linked at the beginning of this document.