docs: add corporate firewalls table to Ports & Firewalls (#908)

* docs: add corporate firewalls table to Ports & Firewalls

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>

* docs: refine corporate firewalls section and cross-link from troubleshooting

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>

* docs: add Palo Alto source-NAT guidance and surface firewalls at relay 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>

* docs: address second review pass on corporate firewalls guidance

- 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>

* docs: drop TURN wording from corporate firewalls guidance

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>

* docs: replace TURN wording with relay in user-facing docs

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>

* docs: scope TURN wording changes to Ports & Firewalls and relayed connections

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>

* docs: sort the corporate firewalls table alphabetically

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>

* docs: add pfSense and OPNsense to the corporate firewalls table

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>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bruno Mercier Costa
2026-08-10 18:01:26 +02:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 4061897914
commit ffe10558ec
3 changed files with 46 additions and 10 deletions
@@ -120,7 +120,7 @@ Some networks are known to defeat hole punching, no matter how clean the firewal
- **Cloud NAT gateways** (AWS NAT Gateway, GCP Cloud NAT): symmetric by design for instances without a public IP.
- **Enterprise firewalls in strict mode**: Cisco ASA, Palo Alto, Fortinet and similar devices often default to symmetric NAT, sometimes labeled "strict NAT" in their settings.
If **both** peers sit on networks like these, hole punching can't succeed and no amount of firewall tuning will change that. The relay is the expected outcome, and you can stop here (see [when relay is the right answer](#when-relay-is-the-right-answer)). If only one side does, or you're not sure, keep going: one predictable side is usually enough for P2P.
If **both** peers sit on networks like these, hole punching can't succeed, and for mobile or cloud NAT no firewall tuning will change that. The relay is the expected outcome, and you can stop here (see [when relay is the right answer](#when-relay-is-the-right-answer)). An enterprise firewall you control is the exception: its NAT mode is often tunable, see [Corporate firewalls](/about-netbird/ports-and-firewalls#corporate-firewalls). If only one side is affected, or you're not sure, keep going: one predictable side is usually enough for P2P.
<Note>
A CGNAT tell: the public address your network presents is in `100.64.0.0/10`, a range reserved for carrier-grade NAT. Don't confuse it with your own NetBird IP. NetBird intentionally uses the same range for its overlay network, so only the address your *ISP-facing* connection shows counts.
@@ -139,7 +139,7 @@ Both must succeed. If they don't, fix outbound TCP/443 to these endpoints first,
### Step 3: Is STUN reachable?
Hole punching starts with STUN, and STUN runs over UDP. The best evidence is already in `netbird status -d`. The `Relays:` section near the bottom reports reachability of every STUN, TURN, and relay endpoint:
Hole punching starts with STUN, and STUN runs over UDP. The best evidence is already in `netbird status -d`. The `Relays:` section near the bottom reports reachability of every STUN and relay endpoint:
```
Relays:
@@ -148,7 +148,7 @@ Relays:
[rels://us-nyc-2.relay.netbird.io:443] is Available
```
Any `Unavailable` entry for a `stun:` or `turn:` endpoint means outbound UDP is being dropped on the path, typically by the site's egress firewall. Ask whoever runs it to allow outbound UDP on ports 80, 443, 3478, and 5555 to `stun.netbird.io` and `turn.netbird.io`; the exact list and example rules are in [Ports & Firewalls](/about-netbird/ports-and-firewalls#outgoing-ports).
Any `Unavailable` entry means the reported transport to that endpoint is being dropped on the path, typically by the site's egress firewall. Ask whoever runs it to allow the matching outbound traffic: UDP ports 80, 443, 3478, and 5555 to `stun.netbird.io`, and UDP ports 80 and 443 plus TCP ports 443 to 65535 to `turn.netbird.io`. The exact list and example rules are in [Ports & Firewalls](/about-netbird/ports-and-firewalls#outgoing-ports). If the site runs a named enterprise firewall or SASE product (Palo Alto, Fortinet, Zscaler, and so on), [Corporate firewalls](/about-netbird/ports-and-firewalls#corporate-firewalls) lists what to allow per vendor.
<Warning>
Every fix on this page is an **outbound** firewall rule or an allowance on the host's `wt0` interface. NetBird never needs an inbound port opened on your perimeter firewall.
@@ -170,7 +170,7 @@ Can't shell into the far peer? Administrators can trigger a debug bundle remotel
### Step 6: Conclude, or escalate
If every check passes on both peers and the connection is still relayed, you've proven by elimination that a symmetric NAT is in the path. Accept the relay. It's the [designed behavior for exactly this case](#when-relay-is-the-right-answer), and it costs latency, not security.
If every check passes on both peers and the connection is still relayed, the most likely remaining cause is a symmetric NAT in the path. A firewall that permits outbound UDP only to the NetBird service endpoints, and not to the peers' own discovered addresses, produces the same result and is worth considering. Either way, check whether it is a corporate firewall you control: many enterprise firewalls randomize the source port per destination, or scope outbound UDP too tightly, and both are tunable. [Corporate firewalls](/about-netbird/ports-and-firewalls#corporate-firewalls) has the per-vendor settings. If the NAT is outside your control (mobile, cloud, or someone else's network), accept the relay. It's the [designed behavior for exactly this case](#when-relay-is-the-right-answer), and it costs latency, not security.
If instead something looks wrong but you can't place it, collect evidence and escalate:
@@ -217,7 +217,7 @@ Guides elsewhere sometimes suggest forwarding a UDP port to a peer to force P2P
To keep a whole fleet on direct connections rather than fixing peers one at a time:
- **Allow outbound UDP to STUN/TURN** (`stun.netbird.io`, `turn.netbird.io`, ports 80, 443, 3478, 5555) at every site's egress firewall.
- **Allow outbound UDP to the STUN and relay endpoints** (`stun.netbird.io`, `turn.netbird.io`, ports 80, 443, 3478, 5555) at every site's egress firewall.
- **Wildcard `*.relay.netbird.io` on TCP/443** so the relay fallback survives rotation of the geo-distributed relay pool.
- **Watch the `Relays:` section** of `netbird status -d` during rollout, fix `Unavailable` entries before users report slowness.
- **Bake the `wt0` allowance into host-firewall baselines** (UFW/firewalld/Windows images), so host firewalls never silently block decrypted traffic.
+1
View File
@@ -66,6 +66,7 @@ next to the feature they cover, so nothing here is a copy.
{ label: "Resource connectivity", href: "/help/troubleshooting-resource-connectivity" },
{ label: "Reverse proxy", href: "/manage/reverse-proxy/troubleshooting" },
{ label: "NAT & firewall ports", href: "/about-netbird/ports-and-firewalls" },
{ label: "Corporate firewalls", href: "/about-netbird/ports-and-firewalls#corporate-firewalls" },
{ label: "DNS", href: "/manage/dns/troubleshooting" },
{ label: "Network routes", href: "/manage/network-routes" },
],