This page documents the settings package and the public control API functions exposed by the intra package that govern the runtime behavior of the firestack engine. It covers the global configuration system, including atomic flags for debug mode, experimental features, network behavior (Endpoint Independent Mapping/Filtering, Port Forwarding, Happy Eyeballs), and proxy modes.
This page focuses on how behavior is configured and observed at runtime. For the tunnel lifecycle itself (connect, restart, disconnect), see 4.1 Tunnel Management and Lifecycle For the anti-censorship dialing strategies that these options configure, see 5.1 Connection Retry and Strategy Selection
settings PackageThe settings package (intra/settings/config.go) provides a centralized set of global variables that control engine behavior. Most are sync/atomic types so they can be written and read from concurrent goroutines without locks.
Defined in intra/settings/config.go
| Flag | Type | Default | Purpose |
|---|---|---|---|
Debug | bool | false | Enables debug-mode behavior intra/settings/config.go19 |
Loopingback | atomic.Bool | false | Adjusts netstack behavior to prevent split dialing intra/settings/config.go23 |
SingleThreaded | atomic.Bool | false | Runs netstack's packet forwarder in single-threaded mode intra/settings/config.go27 |
PortForward | atomic.Bool | false | Enables binding outgoing conns to the same port as incoming conns intra/settings/config.go31 |
HappyEyeballs | atomic.Bool | false | Enables Happy Eyeballs algorithm for dual-stack connections intra/settings/config.go35 |
ExperimentalWireGuard | core.ForeverFlow | false | Enable experimental WireGuard settings intra/settings/config.go39 |
FloodWireGuard | atomic.Bool | false | Floods WireGuard tunnel with randomly sized non-null packets intra/settings/config.go43 |
EndpointIndependentMapping | atomic.Bool | false | Enables UDP EIM as per RFC 4787 intra/settings/config.go47 |
EndpointIndependentFiltering | atomic.Bool | false | Enables UDP EIF as per RFC 4787 intra/settings/config.go51 |
SystemDNSForUndelegatedDomains | atomic.Bool | false | Always use System DNS for undelegated domains intra/settings/config.go55 |
DefaultDNSAsFallback | atomic.Bool | false | Use Default transport as fallback for Preferred transport intra/settings/config.go59 |
SetUserAgent | atomic.Bool | false | Sets User-Agent for DoH and reachability checks intra/settings/config.go63 |
OwnTunFd | atomic.Bool | false | Indicates TUN fd is fully owned by netstack (no dup) intra/settings/config.go79 |
PanicAtRandom | atomic.Bool | false | Testing: triggers random engine panics intra/settings/config.go75 |
Sources: intra/settings/config.go15-80
Defined in intra/settings/tunopts.go These atomic.Int32 variables configure DNS capture, firewall, and NAT64 behavior.
DNSMode)| Constant | Value | Behavior |
|---|---|---|
DNSModeNone | 0 | No DNS redirection intra/settings/tunopts.go21 |
DNSModeIP | 1 | Redirect DNS sent to the VPN's fake DNS IP intra/settings/tunopts.go23 |
DNSModePort | 2 | Redirect all DNS requests on port 53 intra/settings/tunopts.go25 |
BlockMode)| Constant | Value | Behavior |
|---|---|---|
BlockModeNone | 0 | No packet filtering intra/settings/tunopts.go30 |
BlockModeFilter | 1 | Filter on connection establishment intra/settings/tunopts.go32 |
BlockModeSink | 2 | Blackhole all packets intra/settings/tunopts.go34 |
BlockModeFilterProc | 3 | Filter based on owner-uid from procfs intra/settings/tunopts.go37 |
PtMode)| Constant | Value | Behavior |
|---|---|---|
PtModeAuto | 0 | Auto 6to4 protocol translation intra/settings/tunopts.go42 |
PtModeForce64 | 1 | Enforce 6to4 protocol translation intra/settings/tunopts.go44 |
PtModeNo46 | 2 | Disable userspace impl (Android native 464Xlat) intra/settings/tunopts.go46 |
SetTunMode(d, b, pt int32) is used to update these modes atomically intra/settings/tunopts.go99-103
Sources: intra/settings/tunopts.go19-124
Defined in intra/settings/proxyopts.go AutoMode controls the behavior of the intelligent proxy selection logic used by backend.Auto.
| Constant | Value | Meaning |
|---|---|---|
AutoModeLocal | 0 | Use local proxies only (e.g., ipn.Exit) intra/settings/proxyopts.go121 |
AutoModeRemote | 1 | Use remote RPN proxies only intra/settings/proxyopts.go123 |
AutoModeHybrid | 2 | Use both local and remote proxies intra/settings/proxyopts.go125 |
AutoDialsParallel (intra/settings/proxyopts.go165) is an atomic.Bool that instructs the ipn.Auto proxy to dial all available RPN proxies in parallel for faster selection.
Sources: intra/settings/proxyopts.go111-172
The engine uses specific structures to encapsulate connection and resolution parameters.
DialerOpts)The DialerOpts struct (intra/settings/dialeropts.go18-34) defines how the engine should handle outgoing connections, including splitting strategies (Strat), retry logic (Retry), and timeouts. Strategies include SplitAuto, SplitTCPOrTLS, SplitTCP, SplitDesync, and SplitNever intra/settings/dialeropts.go87-99 SetDialerOpts allows runtime updates to these parameters intra/settings/dialeropts.go118-145
DNSOptions)DNSOptions (intra/settings/dnsopts.go23-27) manage the configuration for DNS transports, storing the host/port and resolved IP addresses. The package also defines PlusStrat (intra/settings/dnsopts.go165), an atomic variable that determines the selection strategy for encrypted DNS transports (Safest, Random, Fastest, Robust) intra/settings/dnsopts.go154-163
Sources: intra/settings/dialeropts.go18-151 intra/settings/dnsopts.go23-177
The intra package exposes functions to manipulate these settings from high-level application code (e.g., Android/iOS UI).
Diagram: Public Control API → Settings Mapping
Sources: intra/tun2socks.go191-195 intra/settings/config.go15-80
The LogLevel function updates the global settings.Debug flag intra/tun2socks.go195 The init function in intra/tun2socks.go sets initial Go runtime parameters for the tunnel environment, such as increasing garbage collection frequency (debug.SetGCPercent(50)) and setting memory limits intra/tun2socks.go77-81
Sources: intra/tun2socks.go77-195
NetStatThe system provides detailed runtime statistics via the NetStat struct (intra/backend/netstat.go). This struct aggregates data from the gVisor stack, Go runtime metrics, and settings flags.
Diagram: NetStat Data Sources
Sources: intra/backend/netstat.go9-248 intra/netstack/stat.go24-145
netstack.Stat (intra/netstack/stat.go24-145) populates protocol-specific counters (TCP retransmissions, UDP checksum errors, ICMP unreachable packets) directly from the gVisor stack.Stack object. It also maps NIC information using the default settings.NICID (0x01) intra/netstack/stat.go41 intra/settings/config.go16
The RDNSInfo field within NetStat provides a snapshot of the current global settings, including AutoMode, HappyEyeballs, EIMEIF status, and the current DialerOpts intra/backend/netstat.go148-193
The system provides a comprehensive view of the Go runtime's state. GoStat intra/backend/netstat.go196-238 defines traditional memory stats such as heap allocation, GC runs, and goroutine counts, allowing for remote diagnostics of the engine's health.
Sources: intra/backend/netstat.go148-238 intra/netstack/stat.go24-145
Refresh this wiki