This document describes the proxy management system within firestack, centered on the proxifier component that orchestrates multiple proxy types, selects appropriate proxies for connections, manages proxy health, and supports proxy chaining (hops). The system provides transparent proxy selection for applications, automatic failover, and intelligent routing decisions.
For DNS-specific proxy integration, see DNS Transport Implementations. For WireGuard proxy implementation details including gVisor netstack integration, see WireGuard Proxy Implementation. For proxy lifecycle and health monitoring details, see Auto Proxy and Health Monitoring.
The proxy system is built around a core Proxy interface with multiple concrete implementations, organized into fixed (immutable) and dynamic (user-added) proxies.
Sources: intra/ipn/proxies.go170-191 intra/backend/ipn_proxies.go207-234
| Proxy ID | Type | Purpose | Mutability |
|---|---|---|---|
Block | NOOP | Blocks all traffic | Fixed |
Base | NOOP | Routes via underlying network (may use TUN) | Fixed |
Exit | INTERNET | Always routes via underlying network (never TUN) | Fixed |
Auto | RPN | Races multiple proxies, auto-selects best | Fixed |
Rpn64 | NAT64+RPN | Exit via public NAT64 gateways | Fixed |
RpnWin | WG+RPN | Windscribe WireGuard (multi-country) | Dynamic/RPN |
RpnWs | PIPWS | Nile WebSocket Proxy | Dynamic |
RpnH2 | PIPH2 | Nile HTTP/2 Proxy | Dynamic |
wg* | WG | User WireGuard configs | Dynamic |
OrbotS5 | SOCKS5 | Tor SOCKS5 proxy | Dynamic |
OrbotH1 | HTTP1 | Tor HTTP proxy | Dynamic |
| Custom | SOCKS5/HTTP1 | User-defined proxies | Dynamic |
Sources: intra/ipn/proxies.go34-55 intra/backend/ipn_proxies.go19-68
The proxifier struct is the central orchestrator that manages all proxies, handles proxy selection, and maintains connection state. It implements the Proxifier interface and manages both standard and Rethink Private Network (RPN) proxies.
Sources: intra/ipn/proxies.go231-267 intra/ipn/proxy.go54-126
The ProxyTo method is the core routing decision engine that selects which proxy to use for a given connection based on proxy IDs, health, routes, and connection history.
Key Features:
ipPins and uidPins Sieves to reuse recently successful proxies intra/ipn/proxies.go490-514healthy() and hasroute() before pinning intra/ipn/proxies.go559-575ExpMap to track failing destinations and introduce backoff delays intra/ipn/proxies.go583-587minWaitPeriodSec (3s) for missing proxies to be added intra/ipn/proxies.go610-620Sources: intra/ipn/proxies.go452-641
Firestack supports "PIP" (Private Internet Proxy) variants that use modern web protocols to tunnel traffic.
piph2)The piph2 implementation uses HTTP/2 streams to tunnel TCP data.
dialers.SplitDial for outbound connectivity and wraps streams in a pipconn struct intra/ipn/piph2.go63-176pipws)The pipws implementation tunnels binary data over WebSockets (wss://).
x-nile-pip-claim and x-nile-pip-mac headers intra/ipn/pipws.go104-113Sources: intra/ipn/piph2.go35-233 intra/ipn/pipws.go36-220
rnet)Firestack can run local proxy servers to allow other apps to route traffic through Firestack's managed tunnels.
The rnet.socks5 server provides a local SOCKS5 endpoint using github.com/txthinking/socks5.
ipn.Proxy. When a hop is set, the local server's internal dialer is swapped to the target proxy's dialer intra/rnet/socks5.go104-125ServerListener to perform service-level routing decisions (SvcRoute) intra/rnet/socks5.go240-242The rnet.httpx server provides a local HTTP proxy using github.com/elazarl/goproxy.
ipn.Proxy by overriding the http.Transport.DialContext intra/rnet/http.go71-72Sources: intra/rnet/socks5.go28-151 intra/rnet/http.go28-107
| Status | Value | Meaning |
|---|---|---|
TOK | -1 | Proxy OK, actively working |
TKO | -2 | Proxy OK but erroring out |
TZZ | 1 | Proxy idle, no recent traffic |
TUP | 0 | Proxy up but not yet OK |
TNT | 2 | Proxy unresponsive (timeout) |
TPU | 3 | Proxy paused by user |
END | -3 | Proxy stopped/ended |
Sources: intra/ipn/proxies.go57-92 intra/backend/ipn_proxies.go70-86
The hop system allows proxies to route through other proxies, creating proxy chains.
Hop Validation Rules:
Sources: intra/ipn/proxies.go814-881 intra/ipn/wgproxy.go627-644
The system includes a proxyClient to fetch geolocation and IP metadata through specific proxies.
The fetchIPMetadata function intra/ipn/pxclient.go124-181 attempts to resolve the proxy's external IP by querying multiple providers in sequence:
https://dl.rethinkdns.com/ip intra/ipn/pxclient.go33https://api.windscribe.net/GeoGreet intra/ipn/pxclient.go34https://sky.rethinkdns.com/cdn-cgi/trace intra/ipn/pxclient.go35https://redir.nile.workers.dev/p/warp intra/ipn/pxclient.go36Fetched metadata is cached in an ExpiringMap keyed by proxy ID and network type intra/ipn/pxclient.go71-102
Sources: intra/ipn/pxclient.go66-181
Refresh this wiki