Network Stack and Tunnel

Relevant source files

• intra/netstack/netstack.go
• intra/settings/config.go
• intra/tun2socks.go
• intra/tunnel.go
• tunnel/tunnel.go

The Network Stack and Tunnel system is the core orchestration layer that binds together the gVisor-based network stack, protocol handlers (TCP/UDP/ICMP), DNS resolver, proxy system, and local services. It manages the lifecycle of the tunnel, processes packets from the TUN device, enforces firewall policies, and coordinates traffic routing through the configured proxies.

For DNS resolution architecture, see DNS Resolution System. For proxy management and selection, see Proxy Management System. For connection reliability and anti-censorship features, see Connection Reliability and Anti-Censorship.

Tunnel Architecture

The tunnel system is defined by the Tunnel interface intra/tunnel.go74-119 and its concrete implementation rtunnel intra/tunnel.go121-137 The rtunnel orchestrates all major subsystems: the gVisor network stack, protocol handlers, DNS resolver, proxy provider, and local services.

Core Orchestration Diagram

This diagram maps the high-level rtunnel orchestrator to the specific code entities it manages.

Sources: intra/tunnel.go121-137 intra/tunnel.go155-260 intra/tun2socks.go160-180

Key Components

The rtunnel struct serves as the central manager for the Intra session:

Component	Type	Purpose
t	*core.Volatile[tunnel.Tunnel]	Atomic reference to the gVisor netstack tunnel, allowing hot-swap during Restart() intra/tunnel.go125
ctx	context.Context	Lifecycle context for all subsystems intra/tunnel.go122
handlers	netstack.GConnHandler	Aggregates TCP/UDP/ICMP protocol handlers intra/tunnel.go128
proxies	ipn.Proxies	Proxy provider and manager (proxifier) intra/tunnel.go129
resolver	dnsx.Resolver	DNS resolution orchestrator intra/tunnel.go130
services	rnet.Services	Local services (HTTP/SOCKS servers) intra/tunnel.go131
linkmtu	atomic.Int32	Current link MTU, atomically updated intra/tunnel.go133
closed	atomic.Bool	Shutdown flag intra/tunnel.go135

Sources: intra/tunnel.go121-137

Tunnel Lifecycle

Creation and Initialization

Tunnel creation follows an 8-second timeout bootstrap sequence defined by mktunTimeout intra/tunnel.go51 The NewTunnel2 function handles the orchestration of these components, while Connect variants provide simplified entry points for external callers intra/tun2socks.go160-180

Sources: intra/tunnel.go159-224 intra/tun2socks.go160-180

The initialization sequence includes:

1. Context setup: Creates a context with a timeout using core.EitherOr and mktunTimeout intra/tunnel.go175-190
2. NAT-PT: Initializes x64.NewNatPt2 for ALG/NAT64 translation intra/tunnel.go194
3. Proxies: Creates ipn.NewProxifier with dual-stack support intra/tunnel.go195
4. Default DNS kickstart: Bootstraps default DNS resolver via dtr.kickstart(proxies) intra/tunnel.go205-208
5. DNS Resolver: Creates dnsx.NewResolver and registers various transports intra/tunnel.go212-224
6. Netstack: Initializes gVisor via tunnel.NewGTunnel tunnel/tunnel.go173-221

For details, see Tunnel Management and Lifecycle.

gVisor Netstack and Endpoint Management

The tunnel leverages gVisor's user-space network stack to process IP packets from a TUN device.

Packet Flow and Entities

This diagram maps the packet processing path from the physical device to the protocol handlers.

Sources: tunnel/tunnel.go173-204 intra/netstack/netstack.go30-58

• SeamlessEndpoint: The endpoint implementation allows the network stack to remain active while underlying link details change tunnel/tunnel.go71
• Stack Setup: The stack is initialized as dual-stack by default tunnel/tunnel.go182 netstack.Up attaches the endpoint to a NIC and configures spoofing and promiscuous mode intra/netstack/netstack.go30-88
• Routing: netstack.Route sets the routing table for the stack, typically covering all IPv4/IPv6 traffic via header.IPv4EmptySubnet and header.IPv6EmptySubnet intra/netstack/netstack.go175-209

Statistics and Monitoring

The system provides comprehensive statistics via the Stat() method, which aggregates data from the network stack.

• Caching: Statistics are cached using a core.Barrier with a 30-second TTL (statttl) to reduce overhead intra/tunnel.go126 intra/tunnel.go139
• Implementation: The Stat function in gtunnel extracts counters from the gVisor stack and maps them to Intra's NetStat structure tunnel/tunnel.go65

Sources: intra/tunnel.go121-139 tunnel/tunnel.go65

Protocol Handlers

The tunnel uses specialized handlers for different L4 protocols:

• TCP: Handled via OutboundTCP which provides the stack.TCPForwarder callback intra/netstack/netstack.go55
• UDP: Handled via OutboundUDP which provides the stack.UDPForwarder callback intra/netstack/netstack.go56
• ICMP: Handled via OutboundICMP which provides the stack.ICMPForwarder callback intra/netstack/netstack.go57

For details, see Protocol Handlers (TCP/UDP/ICMP).

Runtime Configuration

Global settings control the behavior of the network stack and tunnel:

• PCAP Support: Support for packet capture to stdout or file via pcapsink. Controlled via SetPcap which manages the pcapio sink tunnel/tunnel.go63 tunnel/tunnel.go223-241
• MTU Management: Tun MTU is managed by Mtu() tunnel/tunnel.go87-93 and SetLinkMtu() intra/tunnel.go101
• Global Settings: Atomic flags in intra/settings/config.go control behaviors like HappyEyeballs, PortForward, and EndpointIndependentMapping intra/settings/config.go33-51

For details, see Runtime Configuration and Settings.

Sources:

• intra/tunnel.go51-260
• tunnel/tunnel.go48-221
• intra/netstack/netstack.go30-212
• intra/settings/config.go15-80
• intra/tun2socks.go160-180