sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 07:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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
Download Patch File Download Diff File Expand all files Collapse all files

97
src/pages/about-netbird/faq.mdx
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?

206
src/pages/help/troubleshooting-client.mdx
View File

@@ -333,6 +333,212 @@ sudo netbird service stop
sudo bash -c 'PIONS_LOG_DEBUG=all NB_LOG_LEVEL=debug netbird up -F' > /tmp/netbird.log
```
## Host-based firewall issues
NetBird automatically adds firewall rules on all platforms to allow traffic on the NetBird interface (`wt0`).
However, conflicts can occur with other firewall management tools or security software.
### Symptoms
- Peers show as "Connected" in `netbird status` but cannot ping or reach each other
- Connection works on some machines but not others with the same network configuration
- Connection works after disabling the host firewall but fails when re-enabled
- P2P connections work but routed traffic does not
### Understanding the issue
NetBird manages firewall rules directly via iptables/nftables (Linux/macOS) or Windows Firewall APIs.
When another tool also manages firewall rules, conflicts can occur:
| Tool | Conflict Type |
|------|---------------|
| UFW (Linux) | Chain ordering - UFW may evaluate its deny rules before NetBird's allow rules |
| firewalld (Linux) | Zone conflicts - NetBird interface may be in wrong zone |
| Windows Group Policy | Policy may override or remove NetBird's firewall rule |
| Third-party security software | May block traffic independently of OS firewall |
### UFW (Linux)
UFW is a frontend for iptables commonly used on Ubuntu. Its default policy denies all incoming traffic,
which can block NetBird traffic before it reaches NetBird's iptables rules.
**Check UFW status**:
```bash
sudo ufw status verbose
```
If UFW is active with a default deny incoming policy, add a rule for the NetBird interface:
**Allow NetBird interface**:
```bash
sudo ufw allow in on wt0
```
**Verify the rule was added**:
```bash
sudo ufw status | grep wt0
```
Expected output:
```
Anywhere on wt0 ALLOW Anywhere
Anywhere (v6) on wt0 ALLOW Anywhere (v6)
```
**Alternative - Allow specific NetBird subnet**:
If you prefer a more restrictive rule:
```bash
sudo ufw allow in on wt0 from 100.64.0.0/10
```
### firewalld (Linux)
On distributions using firewalld (RHEL, CentOS, Fedora), ensure the `wt0` interface is in a trusted zone:
**Check current zone for wt0**:
```bash
sudo firewall-cmd --get-zone-of-interface=wt0
```
**Add wt0 to trusted zone**:
```bash
sudo firewall-cmd --permanent --zone=trusted --add-interface=wt0
sudo firewall-cmd --reload
```
### Windows Firewall
NetBird creates a Windows Firewall rule automatically that allows traffic on the NetBird IP address
(the `wt0` interface). This covers traffic after WireGuard decryption.
**Check if the NetBird rule exists**:
```powershell
Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*NetBird*" } | Format-List DisplayName, Enabled, Direction, Action
```
**Check if the rule is being applied**:
```powershell
Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*NetBird*" } | Get-NetFirewallAddressFilter
```
**Manually create the rule if missing**:
```powershell
New-NetFirewallRule -DisplayName "NetBird" -Direction Inbound -InterfaceAlias "wt0" -Action Allow
```
**Check for Group Policy overrides**:
If the rule exists but traffic is still blocked, Group Policy may be overriding local firewall rules.
Check with your IT administrator or review:
```powershell
Get-NetFirewallProfile | Format-List Name, Enabled, DefaultInboundAction
```
### Environments without NAT (flat networks, routed VLANs)
In most environments, NAT provides stateful connection tracking. When Peer A sends UDP to Peer B, the
return traffic is allowed because the NAT device tracks it as part of an established connection.
However, in environments **without NAT between peers** (e.g., flat office networks, routed VLANs without
masquerading), Windows Firewall may block incoming WireGuard P2P traffic because:
1. There is no NAT state tracking the "connection"
2. Windows Firewall sees the incoming UDP packets as unsolicited inbound traffic
3. The default NetBird rule only covers traffic on the `wt0` interface (after decryption), not the raw
WireGuard packets arriving on the physical interface
**Symptoms**:
- P2P works when one peer is behind NAT but fails when both peers are on the same flat network
- `netbird status -d` shows connection type as "Relayed" instead of "P2P" for local peers
- P2P works after disabling Windows Firewall
**Solution**: Add a firewall rule to allow inbound UDP for WireGuard P2P traffic, scoped to the NetBird process:
```powershell
New-NetFirewallRule -DisplayName "NetBird P2P" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 49152-65535 -Program "C:\Program Files\Netbird\netbird.exe"
```
This rule:
- Allows inbound UDP on the ephemeral port range (used for WireGuard)
- Is scoped to only the NetBird process for security
- Does not expose any other services
**Note**: This is only needed in environments without NAT between peers. If your peers connect through
NAT (typical for remote access scenarios), the default rules are sufficient.
**Linux in non-NAT environments**: The same principle applies. If UFW or firewalld is blocking inbound
UDP on the physical interface, you may need to allow it. However, Linux cannot scope firewall rules to
a specific process like Windows can. A broader rule would be required:
```bash
# UFW - allows inbound UDP on ephemeral ports (less restrictive than Windows equivalent)
sudo ufw allow in proto udp to any port 49152:65535
```
Consider whether this is acceptable for your security posture, or use NetBird's relay fallback instead.
### Third-party security software
Antivirus and endpoint protection software often includes its own firewall that operates independently
of the OS firewall. Common culprits include:
- Symantec Endpoint Protection
- McAfee
- Kaspersky
- ESET
- CrowdStrike Falcon
If you suspect third-party software is blocking NetBird:
1. Temporarily disable the third-party firewall component (not the entire product)
2. Test NetBird connectivity
3. If it works, add an exception for the NetBird process or the `wt0` interface
The NetBird process locations:
- **Windows**: `C:\Program Files\NetBird\netbird.exe`
- **Linux**: `/usr/bin/netbird`
- **macOS**: `/usr/local/bin/netbird`
### Collecting firewall diagnostics
When reporting firewall-related issues, include a debug bundle with system information:
```bash
netbird debug bundle --system-info
```
The `--system-info` flag captures:
- Network routes
- Interface configuration
- Firewall rules (where accessible)
**Additional diagnostics for Linux**:
```bash
# Current iptables rules
sudo iptables -L -n -v
# nftables rules (if applicable)
sudo nft list ruleset
# UFW status
sudo ufw status verbose
```
**Additional diagnostics for Windows** (run as Administrator):
```powershell
# All firewall rules for wt0
Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*NetBird*" -or $_.DisplayName -like "*wt0*" }
# Firewall profile status
Get-NetFirewallProfile
```
### Quick reference
| Platform | Check Command | Fix Command |
|----------|---------------|-------------|
| UFW (Linux) | `sudo ufw status` | `sudo ufw allow in on wt0` |
| firewalld (Linux) | `sudo firewall-cmd --get-zone-of-interface=wt0` | `sudo firewall-cmd --permanent --zone=trusted --add-interface=wt0 && sudo firewall-cmd --reload` |
| Windows | `Get-NetFirewallRule \| Where-Object { $_.DisplayName -like "*NetBird*" }` | Check Group Policy or third-party software |
| Windows (no NAT) | P2P shows as Relayed for local peers | `New-NetFirewallRule -DisplayName "NetBird P2P" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 49152-65535 -Program "C:\Program Files\Netbird\netbird.exe"` |
## Client login failures
A single machine can only connect to one NetBird account as the same user/login method throughout the lifetime of