73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
|
# 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.
|