Skip to content

Overview

A node in a distributed L3 mesh network. A single process combines client ingress (edge), regional egress (exit), and optional policy coordination (master); active roles and upstream gateway chains are defined by policy — managed either via the desktop admin interface or declaratively in YAML.

What It Solves

  • Policy-driven regional egress. Route traffic by domain suffixes, CIDR prefixes, client subnets, or a cluster default rule. Each rule specifies an ordered failover list of exit nodes serving that class of traffic.
  • Standard HTTPS transport profile. Inter-node relay channels share port 443/tcp and modern TLS/HTTP2 profiles with an ordinary web server. Persistent edge → exit connection pools rotate smoothly in the background (6m ± 60s), migrating live streams and long downloads onto fresh TCP connections well before intermediate NAT or stateful firewall idle timeouts expire.
  • Control-plane independence. Nodes sync policy from the master and persist a local snapshot (policy.snapshot) to disk. If the master goes offline, active forwarding never stops and nodes survive service or OS restarts using the cached policy. You can also run completely masterless via a local YAML file (local_policy) deployed with Ansible.

Infrastructure Value

  • Single source of routing truth. Routing rules live in one policy instead of scattered HTTP_PROXY variables, static ip route hacks, or per-laptop client toggles.
  • Gateway-wide coverage. Deployed once on an office gateway or home router, the policy automatically covers employee VPN sessions, guest Wi-Fi, CI build agents, and backend services calling external regional APIs — zero endpoint agents required.
  • Eliminates human error. Team members cannot “forget to switch regions” before testing a localized checkout flow or hitting a geo-restricted partner API: routing happens transparently at the gateway.
  • Deterministic failure & automatic failover. When multiple exit nodes are listed on a route, the edge node monitors packet loss and RTT spikes continuously, fails over to the next healthy gateway once loss exceeds 20%, and lazily returns to primary #1 after recovery (with hold-down protection against flapping). If all allowed gateways fail, sessions fail explicitly rather than silently leaking from the gateway’s local IP.
  • Incremental scaling. Start with two nodes — an ingress gateway and one regional exit VM. Adding another region means spinning up one light VM and adding a single line to policy, with zero changes on client devices.

Under the Hood

  • L3 capture: multi-queue TUN (ololo0) backed by the gVisor userspace TCP/IP stack (TCP, UDP, ICMP) with automatic TCPMSS 1280 clamping on captured transit interfaces (capture_iifs) to prevent PMTU blackholes in VPN-over-VPN topologies.
  • Inter-node transport: pool of 5 persistent gRPC/HTTP2 connections per peer over modern TLS, with staggered background rotation (6m ± 60s) and lossless in-flight stream migration (ResumeFrame / SwitchLegFrame).
  • Peer authentication: cryptographic Bearer tokens (only SHA-256 hashes are stored in policy) protected by per-node rate limiting and automatic memory banlists.
  • Zero-MITM L7 DPI routing: lightweight Deep Packet Inspection on initial flow packets extracts target hostnames without decrypting payloads (TLS ClientHello SNI, HTTP Host, QUIC Initial), feeds domain suffix and LPM CIDR matching, applies per-client/subnet split routing (client_defaults), and drives >20% packet-loss failover.
  • DPI protocol guard (btguard): built-in signature and behavioral Deep Packet Inspection identifies BitTorrent handshakes, DHT, uTP, trackers, and obfuscated MSE/PE swarms right at the edge before they reach cloud exit VMs.
  • Local bypass: private networks (RFC 1918, CGNAT 100.64.0.0/10, loopback) and .local / .lan domains always stay local without entering the mesh.

What It Is Not

  • Not a commercial consumer VPN subscription. Everything connects exclusively to your own self-hosted mesh — never to third-party shared servers. ololo-relay is routing infrastructure that works equally well behind an existing corporate VPN, WireGuard mesh, or home router.
  • Not a stateful ACL firewall. Relay policy governs egress routing, not packet-level security filtering between internal VLANs.
  • Not a caching CDN. Exit nodes forward TCP/UDP streams transparently without caching or inspecting application payloads.