Skip to content

docs: automatic UPnP port forwarding (clearnet + StartTunnel)#93

Open
helix-nine wants to merge 3 commits into
masterfrom
feat/upnp-port-forwarding
Open

docs: automatic UPnP port forwarding (clearnet + StartTunnel)#93
helix-nine wants to merge 3 commits into
masterfrom
feat/upnp-port-forwarding

Conversation

@helix-nine

Copy link
Copy Markdown
Contributor

Companion to Start9Labs/start-os#3306.

StartOS now attempts UPnP automatically when you enable a public address, opening the required port on the gateway (a home router or a StartTunnel) and removing it when the address is disabled/deleted. StartTunnel implements a UPnP IGD over WireGuard, with the security property that a device can only open ports to itself.

  • start-os/src/clearnet.md — "Configure Port Forwarding": document the automatic UPnP attempt + fallback to manual.
  • start-tunnel/src/port-forwarding.md — note automatic, self-scoped UPnP; the manual steps are now "Add a forward manually".
  • start-tunnel/src/architecture.md — mention StartTunnel acts as a UPnP gateway.

@helix-nine helix-nine requested review from Dominion5254 and waterplea and removed request for Dominion5254 and waterplea June 10, 2026 19:16
Dominion5254
Dominion5254 previously approved these changes Jun 12, 2026
Companion to the DNS-injection half of Start9Labs/start-os#3306: a new
'DNS Records' page documenting how trusted devices inject records over
RFC 2136 and how to view/manage them, plus the per-device 'Allow DNS
injection' toggle (default off) noted on the Devices page.
@helix-nine

Copy link
Copy Markdown
Contributor Author

Thanks for the review @Dominion5254! Two notes:

  1. I pushed one more commit (1f0ffc0) so this fully companions start-os#3306: that PR also ships private-domain DNS injection (trusted devices register DNS records over RFC 2136), which wasn't covered here. Added a new DNS Records page + a note on the per-device Allow DNS injection toggle (off by default) on the Devices page. Worth a quick re-glance since it re-touched the PR. The port-forwarding pages already read PCP-first (PCP/NAT-PMP/UPnP), matching the shipped behavior.

  2. Since this documents behavior that isn't released yet, it should merge alongside (or just after) start-os#3306 rather than ahead of it — happy to hold until that lands.

Still to come as their own docs once the code merges: the StartWRT side now also runs this gateway server (start-wrt#66), and the PCP HOSTNAME (SNI-demux) / PORT_SET extensions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants