mirror of
https://github.com/netbirdio/docs.git
synced 2026-05-01 14:56:37 +00:00
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:
@@ -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?
|
||||
|
||||
Reference in New Issue
Block a user