eric/geth
Watch
1
0
Fork
You've already forked geth
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
geth/docs/overlay-platforms.md

2.8 KiB
Raw Blame History

Overlay Platform Notes

This document captures prototype release guidance for geth overlay up. Overlay packets are always carried over Iroh on /geth/overlay/1; these notes only cover host interface setup for the local TUN/Wintun-style device.

Linux

geth overlay up <name> uses tun-rs to create a layer-3 TUN device and assign the joined overlay virtual IP.

Operational requirements:

  • /dev/net/tun must exist and be usable by the daemon process.
  • The user service must have enough privilege to create/configure the device, commonly CAP_NET_ADMIN, a helper, or a supervised manual setup step.
  • The daemon should run as a user service; do not install geth as a system service just to gain network privileges.

Recovery checks:

  • Run geth overlay interface-plan <name> --platform linux to inspect the intended commands.
  • If activation fails, check /dev/net/tun, user permissions, and whether the service manager strips required capabilities.

macOS

macOS uses utun-style devices. Release builds must document that host network integration may require user approval and network-extension or entitlement-aware packaging depending on the distribution path.

Prototype guidance:

  • Run geth overlay interface-plan <name> --platform macos before activation.
  • Treat geth overlay up failures as host entitlement/setup failures, not as a reason to fall back to another geth transport.
  • Keep the daemon as a LaunchAgent/user service. Do not install a privileged system daemon unless a future signed helper design explicitly requires it.

Release checklist:

  • Document required entitlements or helper setup for the chosen signing method.
  • Document how the LaunchAgent is installed and how users approve networking prompts.
  • Include this document in release archives.

Windows

Windows overlay activation needs a Wintun-compatible adapter path. The release artifact does not silently install kernel drivers.

Prototype guidance:

  • Run geth overlay interface-plan <name> --platform windows before activation.
  • Install or make available Wintun through an operator-approved mechanism before geth overlay up.
  • Keep the daemon as a per-user scheduled task. Do not install geth as a system service for the prototype.

Release checklist:

  • Either package the Wintun DLL/driver according to its license and installation requirements, or clearly point users to an approved Wintun installation path.
  • Document how the per-user scheduled task is installed.
  • Include this document in release archives.

Security Boundary

Discovery and peer-card metadata can suggest candidate endpoints and overlay virtual IPs, but they do not grant access. Packet injection still requires overlay.route on resource:overlay:<name>, and joining through a bearer token must not mutate node identity or grant trust graph permissions.