Tunnel Management and Lifecycle

Relevant source files

• intra/netstack/dispatchers.go
• intra/netstack/fdbased.go
• intra/netstack/forwarders.go
• intra/netstack/netstack.go
• intra/netstack/seamless.go
• intra/netstack/snooper.go
• intra/netstack/waitgroup_test.go
• intra/tunnel.go
• tunnel/dialer.go
• tunnel/sink.go
• tunnel/tunnel.go

Purpose and Scope

This document covers the lifecycle management of the core tunnel system in Firestack, specifically focusing on the rtunnel implementation which orchestrates the gvisor-based network stack and all subsystems. The tunnel is the top-level abstraction that brings together the DNS resolver, proxy system, protocol handlers, and network stack into a cohesive unit.

This page documents:

• Tunnel creation and initialization with an 8-second timeout protection.
• Component bootstrapping (NAT-PT, proxies, services, DNS resolver, protocol handlers).
• The SeamlessEndpoint architecture allowing for "hot" FD swapping.
• Dynamic reconfiguration of MTU, link properties, and IP protocol support.
• Tunnel restart and cleanup procedures.
• Statistics collection via Stat() with KeyedBarrier caching.

Sources: intra/tunnel.go1-123 tunnel/tunnel.go1-66

---

Tunnel Interface and Implementation

The tunnel system is built around the Tunnel interface which extends the base tunnel.Tunnel interface with Firestack-specific capabilities. The concrete implementation is rtunnel, which manages all subsystem lifecycles and coordinates their interactions.

Tunnel Interface

The Tunnel interface intra/tunnel.go74-119 defines the contract for an Intra session, including component accessors and lifecycle management methods.

The rtunnel struct intra/tunnel.go121-137 maintains references to all major subsystems:

Sources: intra/tunnel.go59-137 tunnel/tunnel.go49-66

---

Tunnel Creation and Initialization

Creation Functions

Firestack provides multiple entry points for tunnel creation. The high-level NewTunnel functions are the primary way to instantiate the rtunnel orchestrator.

Function	File	Description
NewTunnel	intra/tunnel.go155	Helper that calls NewTunnel2 using the same value for linkmtu and tunmtu.
NewTunnel2	intra/tunnel.go159	Core initialization sequence with distinct control over TUN device MTU vs. physical link MTU.
NewGTunnel	tunnel/tunnel.go173	Low-level gvisor stack and SeamlessEndpoint initialization.

Sources: intra/tunnel.go155-162 tunnel/tunnel.go173-221

Initialization Sequence

The initialization process is protected by an 8-second timeout (mktunTimeout) intra/tunnel.go51 to prevent indefinite hangs. The sequence follows a strict order to ensure proper dependency resolution.

Initialization Sequence Diagram

Key Implementation Details:

1. Timeout Protection: Uses core.EitherOr intra/tunnel.go190 to race between completion and mktunTimeout intra/tunnel.go51
2. DNS Kickstart: dtr.kickstart(proxies) intra/tunnel.go205 ensures the bootstrap resolver is ready, which may involve waiting for proxy availability.
3. Netstack Initialization: tunnel.NewGTunnel tunnel/tunnel.go173-221 creates the gvisor stack and attaches protocol handlers. It utilizes netstack.NewEndpoint tunnel/tunnel.go184 for the link layer.
4. Endpoint Settle: The gtunnel starts a waitForEndpoint goroutine tunnel/tunnel.go95-146 to monitor the health of the SeamlessEndpoint. It checks if the endpoint stays up for at least 3 seconds (uptimeThreshold) tunnel/tunnel.go100

Sources: intra/tunnel.go155-269 tunnel/tunnel.go95-146 tunnel/tunnel.go173-221

---

Dynamic Reconfiguration

The tunnel supports runtime reconfiguration without full teardown, enabling adaptation to network changes (e.g., switching from WiFi to LTE).

Seamless Endpoint Swapping

The magiclink implementation of SeamlessEndpoint intra/netstack/seamless.go68-77 allows swapping the underlying file descriptor (TUN device) without destroying the network stack.

Swap Logic intra/netstack/seamless.go158-213:

1. Attempts to call Swap(fd, mtu) on the existing endpoint intra/netstack/seamless.go163
2. If the existing endpoint cannot be swapped (e.g., if it needs a new instance), it creates a new fdbasedInjectableEndpoint via newFdbasedInjectableEndpoint intra/netstack/seamless.go180
3. Attaches the new endpoint to the existing NetworkDispatcher intra/netstack/seamless.go192
4. Uses Tango (atomic swap) to replace the old endpoint with the new one intra/netstack/seamless.go198
5. Closes and waits for the old endpoint in a separate goroutine intra/netstack/seamless.go203-206

The underlying endpoint intra/netstack/fdbased.go70-112 handles the actual packet dispatching from the TUN FD to the network stack via a linkDispatcher intra/netstack/dispatchers.go174-180

Sources: intra/netstack/seamless.go68-77 intra/netstack/seamless.go158-213 intra/netstack/fdbased.go70-112 intra/netstack/dispatchers.go174-180

MTU Management

Firestack distinguishes between the TUN device MTU and the underlying Link MTU.

SetLinkMtu intra/tunnel.go101 updates the link MTU hint used by proxies (e.g., WireGuard). It uses an atomic.Int32 intra/tunnel.go133 to track changes and returns didchange if the value was updated.

Sources: intra/tunnel.go101 intra/tunnel.go133

Tunnel Restart

Restart intra/tunnel.go107 performs a complete swap of the gvisor netstack while preserving higher-level subsystems (Resolver, Proxies). This is typically used when the TUN file descriptor changes significantly and a seamless swap is not desired.

Restart Workflow:

1. Old Stack Teardown: Calls old.Disconnect() which invokes t.stack.Destroy() tunnel/tunnel.go155
2. New Stack Creation: Creates a new gtunnel with the new file descriptor via NewGTunnel tunnel/tunnel.go173
3. Atomic Swap: Replaces the tunnel instance in the rtunnel's volatile storage t intra/tunnel.go125

Sources: intra/tunnel.go107 tunnel/tunnel.go148-158 tunnel/tunnel.go173-221

---

Statistics Collection and Caching

The tunnel provides detailed metrics through Stat(). To minimize the performance impact of collecting metrics from the gvisor stack and Go runtime, results are cached.

Stat() and Barrier

The tunnel uses a core.Barrier named bar intra/tunnel.go126 with a 30-second TTL (statttl) intra/tunnel.go139

Stat Collection Flow:

• Calls tunnel.Stat() tunnel/tunnel.go65 to get low-level netstack metrics.
• Aggregates metrics for NIC, IP, TCP, UDP, and ICMP intra/tunnel.go118
• The barrier prevents redundant collection under load by returning cached results if within the TTL.

Sources: intra/tunnel.go118-126 intra/tunnel.go139 tunnel/tunnel.go65

---

Bridge to Code Entities

The following diagram maps the logical components of tunnel management to their specific code identifiers and file locations.

Sources: intra/tunnel.go121-137 tunnel/tunnel.go68-78

Link Layer Endpoint Architecture

This diagram illustrates the relationship between the gtunnel and the magiclink (SeamlessEndpoint) which wraps the underlying gVisor link endpoint.

Sources: tunnel/tunnel.go68-78 intra/netstack/seamless.go68-77 intra/netstack/seamless.go158-213