Overview

Relevant source files

• intra/backend/ipn_proxies.go
• intra/common.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/tcp.go
• intra/tunnel.go
• intra/udp.go
• intra/udpmux.go
• tunnel/tunnel.go

Purpose: Firestack is a VPN and network tunneling system that intercepts device traffic through a TUN device, processes it through a userspace TCP/IP stack (gVisor), and routes it through configurable DNS resolvers and proxy servers. The system provides advanced features including DNS Application Layer Gateway (ALG), NAT64, multiple proxy types (WireGuard, SOCKS5, HTTP), intelligent routing, and connection retry mechanisms.

Scope: This page provides a high-level architectural overview of the firestack codebase. For detailed information about specific subsystems, see:

• Build system and CI/CD pipeline: Build System and Deployment
• DNS resolution architecture: DNS Resolution System
• Proxy management: Proxy Management System
• Tunnel implementation: Core Tunnel Architecture
• Connection resilience: Connection Management and Resilience
• Supporting infrastructure: Supporting Infrastructure

---

System Architecture

Firestack implements a layered architecture where network traffic flows from the TUN device through the gVisor netstack to protocol handlers, which then consult DNS resolvers and proxy systems before establishing connections:

Overall Architecture Diagram

Sources: intra/tun2socks.go intra/tunnel.go126-137 tunnel/tunnel.go68-78 intra/common.go69-103 intra/tcp.go47-50 intra/udp.go44-47 intra/icmp.go25-27 intra/udpmux.go69-82 intra/dnsx/transport.go184-203 intra/dnsx/alg.go855-874 intra/dnsx/cacher.go92-108 intra/ipn/proxies.go227-263 intra/ipn/wgproxy.go98-151 intra/ipn/auto.go28-43

---

Core Components

Core Components

Firestack is composed of six major subsystems, each with well-defined responsibilities:

1. Application Interface

Entry Point: intra/tun2socks.go

The Connect() function in tun2socks.go serves as the main API, initializing:

• NewTunnel() or NewTunnel2() for tunnel creation
• Bridge interface implementation for callbacks
• Default DNS configuration

Key Functions:

• Connect(fd, mtu, ifaddrs, fakedns, dtr, bdg) - Primary initialization
• LogLevel(), SetDnsMode(), ExperimentalWireGuard() - Runtime configuration

Sources: intra/tun2socks.go intra/tunnel.go153-157

---

2. VPN Tunnel Layer

Implementation: Two-tier abstraction

High-Level Orchestrator (rtunnel struct):

• Defined in intra/tunnel.go126-137
• Coordinates dnsx.Resolver, ipn.Proxies, and rnet.Services
• Manages lifecycle via SetLinkAndRoutes(), Restart(), CloseConns()
• Holds references to protocol handlers

Low-Level Tunnel (gtunnel struct):

• Defined in tunnel/tunnel.go68-78
• Integrates with gVisor's stack.Stack
• Manages SeamlessEndpoint for TUN ↔ netstack bridging
• Handles MTU updates, PCAP output, and statistics

Key Types:

rtunnel struct {
    t        *core.Volatile[tunnel.Tunnel]
    handlers netstack.GConnHandler
    proxies  ipn.Proxies
    resolver dnsx.Resolver
}

gtunnel struct {
    stack  *stack.Stack
    ep     netstack.SeamlessEndpoint
    hdl    netstack.GConnHandler
}

Sources: intra/tunnel.go126-137 tunnel/tunnel.go68-78 intra/netstack/netstack.go30-55

---

3. Protocol Handlers

Architecture: Shared base + protocol-specific implementations

Protocol Handler Flow

baseHandler (intra/common.go69-103):

• onFlow(src, dst) - Calls gateway.X() to undo ALG, retrieves domains/IPs
• onInflow(to, from) - Handles reverse proxy flows
• judge(res) - Determines cid, uid, fid, pids from policy marks
• isDNS(target) - Checks if target is a fake DNS address
• dnsOverride(gconn, uid) - Redirects DNS queries to resolver.Serve()
• processSummaries() - Forwards SocketSummary to listener.OnSocketClosed()

tcpHandler (intra/tcp.go47-50):

• Proxy(gconn, src, target) - Main TCP connection handler
• handle(px, gconn, src, dst, ...) - Dials via proxy with retrier
• forward(gconn, remote, smm) - Bidirectional data copy with stats
• Maintains tcpNat for port mapping tracking

udpHandler (intra/udp.go44-47):

• Proxy(gconn, src, dst) and ProxyMux(gconn, src, dst, dmx) - UDP handlers
• Connect(gconn, src, target, dmx) - Establishes UDP association
• forward(gconn, remote, smm) - Handles datagram forwarding
• Integrates with muxTable for endpoint-independent mapping

icmpHandler (intra/icmp.go25-27):

• Ping(msg, source, target) - Handles ICMP echo requests
• Uses unprivileged ICMP sockets (UDP-based on Android)

UDP Multiplexing (intra/udpmux.go69-82):

• muxTable - Maps local endpoints to proxy IDs
• muxer - Multiplexes connections over net.PacketConn
• demuxconn - Demultiplexed per-remote connection

Sources: intra/common.go69-103 intra/tcp.go47-127 intra/udp.go44-89 intra/icmp.go25-40 intra/udpmux.go69-223

---

4. DNS Resolution System

Core Architecture:

Component	File	Purpose
resolver	dnsx/transport.go184-203	Transport orchestrator, handles Add(), Remove(), forward()
dnsgateway	dnsx/alg.go855-874	ALG/NAT64 engine, synthetic IP generation
ctransport	dnsx/cacher.go92-108	Per-transport caching with TTL extension
Transport types	Various	DoH, DoT, DNS53, DNSCrypt, ODoH, mDNS implementations

resolver struct key methods:

• forward(q, uid, chosenids...) - Main query processing
• Add(dt DNSTransport) - Registers new transport
• Serve(proto, conn, uid) - Handles TCP/UDP DNS queries
• determineTransport(id) - Selects transport by ID

dnsgateway struct key methods:

• q(t1, t2, preset, network, uid, q, smm) - Dual-transport query with ALG
• X(maybeAlg, uid, tids...) - Undoes ALG translation
• PTR(maybeAlg, uid, tid, force) - Reverse lookup
• RESOLV(domain, uid, tid) - Forward lookup

Synthetic IP Ranges:

• IPv4: 100.64.0.0/10 (RFC 6598)
• IPv6: 64:ff9b:1:da19::/96 (RFC 8215a variant)

Sources: intra/dnsx/transport.go184-242 intra/dnsx/alg.go855-949 intra/dnsx/cacher.go92-178

---

5. Proxy Management System

Core Orchestrator: proxifier struct (intra/ipn/proxies.go227-263)

Proxy Type Hierarchy

proxifier struct manages:

• p map[string]Proxy - All registered proxies
• rp map[string]RpnProxy - Main RPN proxies
• hp map[string][]string - Hop relationships (proxy chaining)
• ipPins *core.Sieve - IP → proxyid pinning
• uidPins *core.Sieve2K - uid → [dst → proxyid] pinning

Key Methods:

• ProxyTo(ipp, uid, pids) - Selects proxy based on pinning, health, routes
• AddProxy(id, txt) - Registers new proxy from configuration
• Hop(via, origin) - Sets up proxy chaining
• RefreshProto(l3, mtu, force) - Broadcasts link property changes

auto proxy (intra/ipn/auto.go28-43) implements intelligent selection:

• Races multiple proxies in parallel
• Pins successful proxy for 30s TTL
• Falls back to exit or RPN proxies

Sources: intra/ipn/proxies.go227-333 intra/ipn/wgproxy.go98-172 intra/ipn/auto.go28-115 intra/ipn/proxy.go43-155

---

6. Connection Management

Key Components:

Component	Location	Responsibility
retrier	intra/dialers/	Transparent retry with TCP splitting/desync
IPMap/IPMapper	intra/protect/ipmap/	Hostname→IP caching with confirmation
protect.Controller	intra/protect/	Network binding, socket protection
dialers.RDialer	intra/dialers/	Dialer abstractions with retry

Connection Retry Flow:

1. retrier attempts initial connection
2. On failure, applies TCP splitting or desynchronization
3. IPMap.Disconfirm() invalidates failed IP
4. Re-resolves via DNS and retries with different IP
5. IPMap.Confirm() validates successful IP

Sources: intra/dialers/ intra/protect/ipmap/ intra/protect/

---

Network Traffic Flow

The following diagram traces a typical connection from application to internet:

Key decision points:

1. DNS Override (baseHandler.isDNS() + baseHandler.dnsOverride()): Intercepts DNS queries to tunnel's fake DNS addresses
2. Policy Check (listener.Preflow() + listener.Flow()): Determines blocking/routing rules based on UID, source, destination
3. Proxy Selection (proxifier.ProxyTo()): Chooses proxy based on pinning, health, and configuration
4. IP Resolution (dialers.ResolveFor() + gateway.X()): Resolves hostnames and undoes ALG translations
5. Connection Retry (retrier): Implements TCP splitting and retry strategies

Sources: intra/common.go132-227 intra/tcp.go240-364 intra/udp.go168-386 intra/ipn/proxies.go448-637 intra/dialers

---

Key Type Relationships

Handler Type Hierarchy

Handler Interface Structure

Key Methods:

• GBaseConnHandler: onFlow(), judge(), isDNS(), dnsOverride()
• GTCPConnHandler: Proxy(), ReverseProxy(), Error()
• GUDPConnHandler: Proxy(), ProxyMux(), ReverseProxy(), Error(), Connect()
• GICMPHandler: Ping()

Sources: intra/netstack/ intra/common.go69-103 intra/tcp.go47-50 intra/udp.go44-47 intra/icmp.go25-27

---

Proxy Type Hierarchy

Proxy Interface Relationships

Proxy interface required methods (intra/ipn/proxies.go165-186):

• Dial(network, address), DialBind(network, local, remote)
• Announce(network, local), Accept(network, local)
• Hop(p Proxy, dryrun), Refresh(), Ping()
• Status(), Stop(), GetAddr(), onNotOK()

Sources: intra/ipn/proxies.go165-186 intra/ipn/proxy.go43-155 intra/ipn/wgproxy.go160-172 intra/ipn/auto.go28-43

---

DNS Resolver Type Hierarchy

DNS Component Relationships

Key Types:

• resolver struct (dnsx/transport.go184-203): Transport orchestrator
• dnsgateway struct (dnsx/alg.go855-874): ALG/NAT64 engine
• ctransport struct (dnsx/cacher.go92-108): Caching wrapper
• algans struct (dnsx/alg.go796-799): ALG IP → real IPs + domains
• xips struct (dnsx/alg.go194-201): Primary/secondary IP storage

Sources: intra/dnsx/transport.go164-203 intra/dnsx/alg.go83-102 intra/dnsx/alg.go796-874 intra/dnsx/cacher.go65-108

---

Data Flow Example: TCP Connection

Sources: intra/tcp.go240-364 intra/common.go132-311 intra/dnsx/transport.go505-718 intra/ipn/proxies.go448-637 intra/ipn/wgproxy.go189-193

---

Platform Integration

Firestack is designed as a cross-platform library that can be embedded into mobile applications (Android/iOS) and desktop systems (Linux/Windows) through Go Mobile bindings.

Build Artifacts by Platform:

Platform	Artifact Type	Output Path	Build Tool
Android	AAR (Android Archive)	intra/tun2socks.aar	gomobile bind
iOS	XCFramework	Tun2socks.xcframework	gomobile bind
Linux	Binary	tun2socks (ELF)	xgo
Windows	Binary	tun2socks.exe (PE)	xgo

Bridge Interface Contract

The Bridge interface (intra/tunnel.go61-67) defines the integration contract:

Bridge interface {
    Listener    // SocketListener, DNSListener, ServerListener, ProxyListener
    Controller  // protect.Controller for network binding
    Console     // Logging callbacks
}

Listener Callbacks:

• SocketListener (intra/listener.go19-66): OnSocketClosed(summary)
• DNSListener: OnQuery(), OnUpstreamAnswer(), OnResponse()
• ProxyListener: OnProxyAdded(), OnProxyRemoved(), OnProxyStopped()

Controller Methods (intra/protect/):

• Protect(fd) - Exempts socket from VPN routing
• Bind(fd, network) - Binds socket to specific network interface

Sources: Makefile .github/workflows/go.yml intra/tunnel.go61-74 intra/listener.go19-66 intra/protect/

---

State Management

The system maintains several categories of state:

1. Connection State: Tracked in baseHandler.conntracker (connid → [local, remote])
2. Proxy State: Managed by proxifier with maps for proxies, RPN proxies, and hop relationships
3. DNS State: Cached in dnsgateway ALG/NAT/PTR maps and ctransport caches
4. IP State: Maintained in ipmap.IPMap with confirmation/disconfirmation feedback loops

All mutable state uses appropriate synchronization primitives (sync.RWMutex, atomic, core.Volatile).

Sources: intra/common.go99 intra/ipn/proxies.go232-240 intra/dnsx/alg.go856-862 intra/protect/ipmap

---

This overview provides the foundation for understanding firestack's architecture. For detailed information about each subsystem, refer to the linked sections.