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/tcpand modern TLS/HTTP2 profiles with an ordinary web server. Persistentedge → exitconnection 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_PROXYvariables, staticip routehacks, 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
edgenode monitors packet loss and RTT spikes continuously, fails over to the next healthy gateway once loss exceeds 20%, and lazily returns to primary#1after 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 automaticTCPMSS 1280clamping 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-256hashes 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
ClientHelloSNI, HTTPHost, QUICInitial), 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 theedgebefore they reach cloud exit VMs. - Local bypass: private networks (RFC 1918, CGNAT
100.64.0.0/10, loopback) and.local/.landomains 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-relayis 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.