diff --git a/src/pages/about-netbird/faq.mdx b/src/pages/about-netbird/faq.mdx index b0b79a4d..6a325183 100644 --- a/src/pages/about-netbird/faq.mdx +++ b/src/pages/about-netbird/faq.mdx @@ -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 JSON format. +## 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? diff --git a/src/pages/help/troubleshooting-client.mdx b/src/pages/help/troubleshooting-client.mdx index f7f31675..12abc84b 100644 --- a/src/pages/help/troubleshooting-client.mdx +++ b/src/pages/help/troubleshooting-client.mdx @@ -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