From 0749bbca4ed2f960d7035520dd0716b535b0eb6c Mon Sep 17 00:00:00 2001
From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
Date: Fri, 12 Dec 2025 12:30:57 +0100
Subject: [PATCH] docs: add firewall troubleshooting guide for pfSense and
 OPNsense (#515)

---
 src/pages/get-started/install/opnsense.mdx | 29 ++++++++++++++++++++++
 src/pages/get-started/install/pfsense.mdx  | 29 ++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/src/pages/get-started/install/opnsense.mdx b/src/pages/get-started/install/opnsense.mdx
index 85653115..33e031dc 100644
--- a/src/pages/get-started/install/opnsense.mdx
+++ b/src/pages/get-started/install/opnsense.mdx
@@ -111,6 +111,35 @@ This ensures traffic flows freely, while NetBird’s own policies (ACLs) govern
     <img src="/docs-static/img/get-started/opnsense/firewall_rules.png" alt="firewallRules" className="imagewrapper-big"/>
 </p>
 
+### Config for Troubleshooting Relayed Connections
+
+By default, OPNsense uses automatic outbound NAT which randomizes source ports. This can cause issues with NetBird's NAT traversal (hole punching). To ensure reliable direct connections, you must configure a Static Port mapping.
+
+1.  **Change Outbound NAT Mode**:
+    -   Navigate to `Firewall` > `NAT` > `Outbound`.
+    -   Select `Hybrid outbound NAT rule generation`.
+    -   Click `Save`.
+
+2.  **Add Static Port Rule**:
+    -   Click `+` to add a new rule.
+    -   **Interface**: `WAN`
+    -   **TCP/IP Version**: `IPv4`
+    -   **Protocol**: `UDP`
+    -   **Source address**: `Single host or Network` (enter the IP address of your NetBird host)
+    -   **Destination address**: `any`
+    -   **Translation / Static-port**: Check `Static-port` box
+    -   **Description**: `NetBird Static Port`
+    -   Click `Save` and then `Apply changes`.
+
+3.  **Reset States**:
+    -   Go to `Firewall` > `Diagnostics` > `States`.
+    -   Filter by the NetBird host IP.
+    -   Delete the states.
+
+4.  **Restart NetBird**:
+    -   Run `netbird service restart` on the device.
+    -   Run `netbird status -d` to verify the connection.
+
 ## Get started
 <p float="center" >
     <Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
diff --git a/src/pages/get-started/install/pfsense.mdx b/src/pages/get-started/install/pfsense.mdx
index 6b08cfb4..34ecb4cc 100644
--- a/src/pages/get-started/install/pfsense.mdx
+++ b/src/pages/get-started/install/pfsense.mdx
@@ -110,6 +110,35 @@ Create rules to control traffic coming from your NetBird network into pfSense an
 
 <p><img src="/docs-static/img/get-started/pfSense/firewall_rules.png" alt="firewallRules" className="imagewrapper-big"/></p>
 
+### Config for Troubleshooting Relayed Connections
+
+By default, pfSense uses automatic outbound NAT which randomizes source ports. This can cause issues with NetBird's NAT traversal (hole punching). To ensure reliable direct connections, you must configure a Static Port mapping.
+
+1.  **Change Outbound NAT Mode**:
+    -   Navigate to `Firewall` > `NAT` > `Outbound`.
+    -   Select `Hybrid Outbound NAT rule generation`.
+    -   Click `Save`.
+
+2.  **Add Static Port Rule**:
+    -   Click `Add` (Up arrow) to create a new rule at the top of the list.
+    -   **Interface**: `WAN`
+    -   **Address Family**: `IPv4`
+    -   **Protocol**: `UDP`
+    -   **Source**: `Network` (enter the IP address of your NetBird host)
+    -   **Destination**: `Any`
+    -   **Translation / Static Port**: Check `Static Port` box
+    -   **Description**: `NetBird Static Port`
+    -   Click `Save` and then `Apply Changes`.
+
+3.  **Reset States**:
+    -   Go to `Diagnostics` > `States`.
+    -   Filter by the NetBird host IP.
+    -   Click `Kill`.
+
+4.  **Restart NetBird**:
+    -   Run `netbird service restart` on the device.
+    -   Run `netbird status -d` to verify the connection.
+
 ## Uninstallation
 
 From a shell on your pfSense system, run: