docs: add corporate firewalls table to Ports & Firewalls - #908
Conversation
Add a "Corporate firewalls" section covering common enterprise firewall and SASE products (Palo Alto, Fortinet, Cisco, Check Point, Zscaler, Netskope, Cloudflare Gateway, Sophos, SonicWall, Barracuda). It explains how NetBird behaves through a corporate firewall, that it falls back to the TCP/443 relay when direct peer-to-peer is blocked so peers stay connected, and what to allow per product, including which TLS inspection feature to exclude the NetBird domains from. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
@emrcbrn is attempting to deploy a commit to the NetBird GmbH Team on Vercel. A member of the Team first needs to authorize it. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThe documentation updates relay endpoint terminology and details. They add corporate firewall configuration guidance, including allowlisting, inspection exclusions, NAT, and UDP timeouts. Troubleshooting content distinguishes controllable enterprise NAT from external NAT and links to the new guidance. ChangesCorporate firewall and relay guidance
Estimated code review effort: 2 (Simple) | ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
src/pages/about-netbird/ports-and-firewalls.mdxOops! Something went wrong! :( ESLint: 9.39.5 TypeError: Converting circular structure to JSON Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/pages/about-netbird/ports-and-firewalls.mdx`:
- Line 76: Update the allowlist guidance in the ports-and-firewalls
documentation to distinguish endpoint roles: describe STUN as enabling direct
P2P connectivity and TURN as providing relay fallback. Remove the claim that
allowing TURN keeps connections direct or low latency, while preserving the
existing endpoint examples and cross-reference.
- Line 74: Update the explanatory paragraph near “Two settings cover most
products” to distinguish the outcomes: UDP blocking should be described as
normally triggering the TCP/443 relay fallback, while TLS/SSL or deep packet
inspection should be described as potentially preventing the session from
connecting.
- Line 83: Update the Palo Alto Networks firewall guidance in the
ports-and-firewalls table to explicitly exclude relay endpoints by adding
relay.netbird.io and *.relay.netbird.io alongside *.netbird.io in the SSL
Decryption bypass instructions, including the corresponding entries referenced
by the comment.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f48245e1-4cb8-4023-8058-6d350e8cd3f3
📒 Files selected for processing (1)
src/pages/about-netbird/ports-and-firewalls.mdx
…hooting Address review feedback on the new Corporate firewalls section: - Distinguish the two firewall failure modes. Blocking outbound UDP falls back to the TCP/443 relay, but TLS/DPI inspection of the control plane can prevent connecting at all. - Correct the STUN vs TURN roles. STUN enables direct connections, while TURN and the relay service are the fallback, not a way to keep connections direct. - Make the relay domains explicit in the inspection-bypass guidance, since a *.netbird.io wildcard does not match the deeper *.relay.netbird.io hosts. Cross-link the section from the relayed-connections guide (Step 3) and the troubleshooting hub, since a corporate firewall blocking UDP is a common cause of relayed connections. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…y escalation Corporate firewalls: note that some enterprise firewalls apply per-destination (symmetric) source NAT, which defeats hole punching and forces the relay. Add the port-preserving fix, with Palo Alto's Persistent Dynamic IP And Port mode in its row and a general note covering the pattern and UDP session timeouts. Relayed connections: the symmetric-NAT cause is often a corporate firewall the operator controls, so reference the Corporate firewalls section at the final escalation step, and scope the earlier "no firewall tuning will change that" claim to mobile and cloud NAT where it actually holds. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/pages/about-netbird/ports-and-firewalls.mdx`:
- Around line 79-81: Update src/pages/about-netbird/ports-and-firewalls.mdx
lines 79-81 to state that direct P2P requires outbound UDP access to dynamically
discovered peer addresses, not only NetBird service endpoints; document relay as
the expected behavior when UDP is restricted to STUN, TURN, and relay
destinations. Update src/pages/help/troubleshooting-relayed-connections.mdx line
173 to replace the unqualified “proven by elimination” conclusion with a
qualified symmetric-NAT conclusion that requires checking for
destination-specific UDP filtering.
- Line 74: Update the control-plane firewall paragraph in the
ports-and-firewalls documentation to replace the two-outcome framing with
“common causes include.” Explicitly include outbound TCP/443 denial, HTTPS proxy
requirements, and strict destination egress restrictions alongside UDP blocking
and TLS inspection, while preserving the existing fallback and connection-impact
details.
In `@src/pages/help/troubleshooting-relayed-connections.mdx`:
- Line 173: Update the troubleshooting guidance around the “every check passes”
condition to describe symmetric NAT as the leading remaining cause, not proof.
Add a final check of the peer’s UDP policy, including destination-specific
filtering or DPI, before accepting that the connection must be relayed; preserve
the existing corporate-firewall and uncontrollable-NAT guidance.
- Line 151: Update the troubleshooting guidance in the documented endpoint
paragraph to distinguish the transport reported by netbird status -d: recommend
STUN UDP ports 3478 and 5555, TURN UDP ports 80 and 443, and TURN TCP ports
443–65535. Ensure each failure points users to the matching endpoint and exact
ports instead of treating every turn: failure as UDP.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 035d6b4c-3f09-4672-93f2-928502961f12
📒 Files selected for processing (3)
src/pages/about-netbird/ports-and-firewalls.mdxsrc/pages/help/troubleshooting-relayed-connections.mdxsrc/pages/help/troubleshooting.mdx
- Broaden the firewall failure modes beyond UDP blocking and TLS inspection to include blocked or proxied outbound TCP/443 and strict destination egress, which break the control plane before any inspection. - Note that reaching the NetBird service endpoints does not by itself prove a direct peer path, since a firewall can allow STUN/TURN yet block UDP to peer addresses. Qualify the relayed-connections conclusion accordingly. - Match the STUN/TURN fix to the transport that netbird status reports: STUN is UDP 80/443/3478/5555, TURN is UDP 80/443 plus TCP 443-65535, rather than applying STUN's UDP ports to TURN. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Refer to the outbound relay endpoints as "relay" rather than "STUN/TURN" and "Relay (TURN)" in the Corporate firewalls section, in line with NetBird's relay terminology. Endpoint hostnames are unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
TURN is legacy in NetBird, so the user-facing docs now call it the relay service: - Ports & Firewalls: rename the "Relay (TURN) service" endpoint and split the two relay endpoints by transport (UDP/TCP and TCP) to keep them distinct, and drop TURN from the notes and the JSON-download line. - Relayed-connections and troubleshooting hub: drop TURN from the status and rollout wording and the connectivity chip label. - Zero Trust use case: describe STUN and relay instead of STUN/TURN. Endpoint hostnames (turn.netbird.io) and the netbird status output are unchanged. Self-hosted coturn documentation is intentionally left as-is, since there TURN refers to the actual legacy software. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…nections Revert the TURN wording in the troubleshooting hub chip and the Zero Trust use case, keeping the TURN-to-relay rename limited to the Ports & Firewalls and relayed-connections docs for now. The corporate-firewalls cross-link chip in the hub stays. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Order the firewall and SASE rows alphabetically by product (Barracuda through Zscaler) so readers can scan for their vendor. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add pfSense and OPNsense rows, each linking to its existing NetBird setup section for keeping connections direct (Static Port outbound NAT, or Endpoint-Independent NAT / EIM-NAT beta on pfSense). Broaden the table intro from "enterprise" firewalls since these are open-source firewalls. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2 participants
What
Adds a Corporate firewalls section to the Ports & Firewalls page covering common enterprise firewall and SASE products.
It covers:
Placement: new section between "Network firewall ports" and "Host-based firewalls".
Notes for review
This is a first draft. The endpoints to allow are exact (they reuse the existing "Network firewall ports" list), but the per-product rows are derived from NetBird's architecture and each vendor's inspection-feature names, not from lab testing of each firewall. Treat them as a starting point to validate against real support experience. Additional vendors (WatchGuard, Meraki MX, Cato Networks, and so on) can be added on request.
Validated with
npm run build.🤖 Generated with Claude Code
Summary by CodeRabbit