Add documentation for how NetBird interacts with host-based firewalls (#521)

* This PR adds documentation explaining how NetBird interacts with host-based firewalls (Windows Firewall, UFW, iptables) and how to troubleshoot conflicts.

* Fix markdown formatting in troubleshooting-client.mdx

* Add sections for flat networks and routed VLANs without NAT

* Fix typo in UFW conflicts section

* Fix typo in UFW description in troubleshooting guide
This commit is contained in:
Jack Carter
2025-12-19 10:40:31 +01:00
committed by GitHub
parent fe2f159f74
commit f4aa3310a0
2 changed files with 302 additions and 1 deletions

View File

@@ -2,7 +2,11 @@ import {Note} from "@/components/mdx";
export const title = 'FAQ'
## What firewall ports should I open to use NetBird?
## What firewall ports should I open to use NetBird (Network Firewalls)?
This section covers **network/perimeter firewall** requirements (e.g., Fortigate, pfSense, cloud security groups).
For host-based firewalls (Windows Firewall, UFW, iptables), see
[How does NetBird interact with host-based firewalls?](#how-does-net-bird-interact-with-host-based-firewalls)
### Incoming ports
NetBird's agent doesn't require any incoming port to be open; It negotiates the connection with the support of the signal and relay services.
@@ -59,6 +63,97 @@ Below is the list of NetBird hosted endpoints and ports they listen to:
Download the full list of NetBird Cloud STUN/TURN/Relay endpoints and port requirements in <a href="/docs-static/files/netbird-cloud-endpoints.json" download>JSON format.</a>
</Note>
## How does NetBird interact with host-based firewalls?
NetBird automatically manages host-based firewall rules to allow traffic on the NetBird interface (`wt0`).
This is separate from your network/perimeter firewall, which requires no inbound port configuration.
### Platform behavior
| Platform | Firewall Manager | Automatic Rule |
|----------|------------------|----------------|
| Windows | Windows Firewall | Allows all traffic on NetBird interface |
| Linux | iptables/nftables | Adds rules for NetBird traffic |
### Network firewall vs. host-based firewall
It is important to understand the distinction:
- **Network/perimeter firewall** (Fortigate, pfSense, cloud security groups): Controls traffic entering
and leaving your network. NetBird requires **no inbound ports** on these devices. All connections are
initiated outbound using ICE/STUN for NAT traversal.
- **Host-based firewall** (Windows Firewall, UFW, iptables): Controls traffic on the individual machine.
NetBird automatically adds rules to allow traffic on the `wt0` interface.
### UFW conflicts on Linux
[UFW](https://wiki.ubuntu.com/UncomplicatedFirewall) (Uncomplicated Firewall) is a popular frontend for
iptables on Ubuntu and other Linux distributions. When you enable UFW, its default policy is:
- **Incoming**: Deny all
- **Outgoing**: Allow all
This can conflict with NetBird because both UFW and NetBird manage iptables rules. The conflict is about
**chain evaluation order**, not about opening ports to the internet:
1. WireGuard UDP packets arrive via hole punching (no inbound port needed on your router)
2. NetBird decrypts them and presents traffic on the `wt0` interface
3. UFW may evaluate its deny rules before NetBird's allow rules
4. Result: Traffic blocked at the host level despite successful hole punching
**Solution**: Allow traffic on the NetBird interface:
```bash
sudo ufw allow in on wt0
```
This does **not** open any ports to the internet. It allows traffic on the virtual `wt0` interface, which
only carries already-authenticated, already-encrypted NetBird traffic.
**Verify the rule**:
```bash
sudo ufw status | grep wt0
```
### Windows Firewall
NetBird creates a Windows Firewall rule automatically during installation/connection. This rule allows
traffic on the NetBird IP address (the `wt0` interface after decryption).
If traffic is blocked despite NetBird showing peers as connected, check for:
- Group Policy overriding the NetBird rule
- Third-party security software (antivirus, endpoint protection) with its own firewall
- The rule failing to apply due to permissions
**Check if the NetBird rule exists**:
```powershell
Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*NetBird*" }
```
#### Environments without NAT
In flat office networks or routed VLANs without NAT, an additional firewall rule may be needed for P2P
to work. This is because Windows Firewall sees incoming WireGuard UDP packets as unsolicited traffic
when there is no NAT state tracking the connection.
```powershell
New-NetFirewallRule -DisplayName "NetBird P2P" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 49152-65535 -Program "C:\Program Files\Netbird\netbird.exe"
```
See [Environments without NAT](/help/troubleshooting-client#environments-without-nat-flat-networks-routed-vlans)
for details.
### Troubleshooting
If you suspect host-based firewall issues, capture a debug bundle:
```bash
netbird debug bundle --system-info
```
The `--system-info` flag includes network routes and interface configuration, which helps identify
firewall-related issues. See [Host-based firewall issues](/help/troubleshooting-client#host-based-firewall-issues)
for detailed troubleshooting steps.
## Why and what are the anonymous usage metrics?
### Why did we add metrics collection?