eric/geth
Watch
1
0
Fork
You've already forked geth
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Implement opt-in overlay TUN runtime

Browse source
This commit is contained in:
Eric Wendland 2026-05-23 02:08:51 +02:00
commit d9728a326d
15 changed files with 2315 additions and 84 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/architecture.md
View file

@ -253,12 +253,26 @@ TUN/Wintun interface are carried over the daemon-owned Iroh endpoint on
with `overlay.join`, `overlay.route`, and `overlay.admin` capabilities. The
prototype exposes `geth overlay status`, `geth overlay plan <name>`,
`geth overlay join <name> --secret <resource-secret>`, and `geth overlay leave
<name>` as planning/control stubs only. They validate names, CIDRs, resource
IDs, capabilities, and security notes, but they do not create host network
interfaces, assign virtual IPs, or route packets yet. Future implementation must
remain explicitly opt-in because TUN/Wintun setup may need platform-specific
privileges. Overlay discovery can use mDNS, peer exchange, and resource
metadata, but discovery remains untrusted and cannot grant overlay access.
<name>`. Join creates or reuses `resource:overlay:<name>`, persists local
membership in `module_state`, assigns a deterministic virtual IP from the CIDR,
and stores only a BLAKE3 fingerprint of the supplied secret. If bearer access
already exists for that overlay resource, join requires the supplied secret to
be a bearer token with `overlay.join`; this lets operators create explicit
resource-scoped overlay invites through `geth secret bearer create`. The
`geth overlay interface-plan` generates Linux, macOS, or Windows host-interface
plans for review. `geth overlay up <name>` is the explicit opt-in that creates a
real L3 TUN/Wintun-style interface through `tun-rs`, assigns the local
deterministic overlay IP, reads IPv4 packets from the interface, maps
destination overlay IPs to imported peer cards, and carries those packets over
the dedicated `/geth/overlay/1` Iroh ALPN. `geth overlay down <name>` stops the
runtime and drops the device handle. The serving daemon validates the signed
peer card against the observed EndpointID and requires `overlay.route` on
`resource:overlay:<name>` before queuing a received packet into the active
interface; if no runtime is active, the packet is persisted for `geth overlay
recv`. Interface setup may require `CAP_NET_ADMIN`, sudo, a preconfigured
`/dev/net/tun`, Wintun availability, or platform-specific network entitlements.
Overlay discovery can use mDNS, peer exchange, and resource metadata, but
discovery remains untrusted and cannot grant overlay access.
`geth-pipe` currently supports `pipe listen/connect/send/recv` against a
daemon-lifetime runtime. `geth pipe connect <name> --node <node-id>` sends an