Add NAT traversal and firewalls guide - #373
Open
jasikpark wants to merge 5 commits into
Open
Conversation
Deploying docs-nebula with
|
| Latest commit: |
edc39e0
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://64d653e5.docs-nebula.pages.dev |
| Branch Preview URL: | https://nat-traversal-guide.docs-nebula.pages.dev |
jasikpark
force-pushed
the
nat-traversal-guide
branch
from
August 12, 2026 16:54
4d1ebb5 to
010e476
Compare
Answers the network-engineer checklist that existing pages only cover piecemeal: what NAT behavior Nebula needs (endpoint-independent mapping), which behaviors break hole punching (symmetric NAT / per- session DIPP, CGNAT, short UDP timeouts), the mitigation ladder (punchy, advertise_addrs, relays), and how to recognize a relayed tunnel in logs. Slots after host-discovery in the Guides nav; later guides renumbered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016yeo64wtbbMPxtUtmsWRAc
jasikpark
force-pushed
the
nat-traversal-guide
branch
from
August 12, 2026 17:01
010e476 to
bec552f
Compare
jasikpark
marked this pull request as ready for review
August 12, 2026 17:15
Findings applied from a docs-editor review plus a findability quiz run against the live docs: - Restructure: new "NAT types" section defines Public address / Easy NAT (endpoint-independent) / Hard NAT (symmetric NAT, CGNAT) as anchored definitions before the pair table uses them (framing inspired by Tailscale's device-connectivity reference). The old "NAT behaviors that break hole punching" content folds in, with a "Look-alikes" subsection for short UDP timeouts and split-VLAN paths. - Readability: rewritten to roughly 10th-grade level (Flesch-Kincaid 11.1 -> 8.4, 18.9 -> 14.3 words/sentence). Shorter sentences, plainer verbs, same content. - Vocabulary: dropped "dialable" (coined in this PR, used nowhere else in the docs) in favor of "public address". Easy/hard NAT aliases double as search terms. - Correctness: added the RFC 4787 mapping-vs-filtering caveat (mixed pairing is now "usually direct, one-way" with a footnote); port forwards warn to pin listen.port; the relay fallback states its cost (performance, not security); "full-cone" gloss hedged; DPI claim softened to "most". - Cross-links: punchy, relay, and host-discovery now link into this guide (it previously had zero inbound prose links). See-also gains the Managed Nebula architecture "Connectivity and NAT traversal" section. Lighthouse and relay are linked on first use. - Log example: the relay= field is glossed as the relay's Nebula address. Addresses are unchanged and intentional: 203.0.113.9 is RFC 5737 documentation space, 192.168.100.1 matches the example overlay network used across the docs. Build verified with onBrokenLinks/onBrokenAnchors set to throw. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Splits em-dash appositive chains into separate sentences, removes rhetorical pivots and marketing cadence, and keeps the reading level closer to standard technical English throughout the NAT traversal guide and its cross-link sentences. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016yeo64wtbbMPxtUtmsWRAc
Recombines runs of uniformly short sentences so paragraphs read with natural variation, anchors the hole-punching walkthrough hosts in a concrete home/office topology, deep-links both RFC 4787 references (section 4.1 for endpoint-independent mapping, section 5 for filtering), replaces the vendor-specific hard-NAT note with a vendor-neutral description of persistent source-NAT modes, and adds a QUIC comparison to the unknown-UDP guidance. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016yeo64wtbbMPxtUtmsWRAc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
New guide answering the questions a network engineer asks when Nebula hosts sit behind their firewall — the checklist that existing pages (
punchy,relay, host discovery, one paragraph in the DN architecture page) only cover piecemeal:punchykeepalives, inbound only for lighthouses/relayspunchy→ port forward +advertise_addrs→ relays(relayed)suffix on thefromfield in handshake logsPlacement: slots in at position 3, right after How Hosts Find Each Other (its natural sequel); later guides renumbered. Log strings verified against nebula source (
hostmap.goViaSender.String), Managed Nebula punchy defaults verified against generated configs.🤖 Generated with Claude Code
https://claude.ai/code/session_016yeo64wtbbMPxtUtmsWRAc