pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-07-16 10:59:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add firewall notes

Browse Source
This commit is contained in:
Owen
2026-06-26 14:37:59 -04:00
parent 11e92b8bec
commit 489bec128a
7 changed files with 141 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs.json
View File

@@ -90,21 +90,13 @@
"pages": [
"manage/clients/understanding-clients",
"manage/clients/nat-traversal",
{
"group": "Firewall Integrations",
"pages": [
"manage/clients/firewalls/overview",
"manage/clients/firewalls/opnsense",
"manage/clients/firewalls/pfsense",
"manage/clients/firewalls/palo-alto"
]
},
"manage/clients/install-client",
"manage/clients/configure-client",
"manage/clients/update-client",
"manage/clients/credentials",
"manage/clients/fingerprinting",
"manage/clients/archiving-blocking"
"manage/clients/archiving-blocking",
"manage/clients/firewalls"
]
},
"manage/domains",

137
manage/clients/firewalls.mdx Normal file
View File

@@ -0,0 +1,137 @@
---
title: "Firewall Quirks"
description: "Improve Pangolin direct-connect success behind restrictive firewalls"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Most of the time, Pangolin works with existing firewall policies without any special tuning. Newt and Pangolin clients attempt NAT traversal first so traffic can flow directly between client and site. When direct connectivity cannot be established, traffic falls back to relaying through Gerbil. You can [learn more about how holepunching works here](https://pangolin.net/news/nat-holepunching).
For background on direct vs relayed paths and how to verify connection type, see [NAT Traversal](/manage/clients/nat-traversal).
## Firewall compatibility and workarounds
The table below summarizes common behavior and practical mitigations reported by users.
| Firewall platform | Typical behavior with Pangolin | Practical workaround |
| --- | --- | --- |
| Barracuda | Often relayed | Increase available UDP session capacity; optionally allow a dedicated inbound Newt port |
| Check Point | Usually direct | No workaround typically required |
| Cisco | Often relayed | Allow required UDP flows and, if needed, open a fixed Newt listening port |
| Cisco Umbrella Endpoint Security | Usually relayed | Endpoint filtering commonly prevents direct paths |
| Fortinet | Often connects directly | No workaround typically required |
| OPNsense | Often relayed by default | Disable hard NAT |
| pfSense | Often relayed by default | Disable hard NAT |
| Palo Alto Networks | Mixed; may relay without NAT tuning | Use persistent NAT behavior to stabilize UDP mappings |
| Sophos | Commonly direct | No workaround typically required |
| UniFi Gateways (threat detection on) | Often relayed when threat detection is on | Allow peer-to-peer traffic categories |
If your firewall is not listed and connections are consistently relayed, start with:
1. Confirm current path with `pangolin status` (CLI) or client status JSON (`isRelay`).
2. Keep relaying enabled for reliability while testing firewall adjustments.
3. If needed, pin Newt to a fixed listening port with `--port` / `PORT` and forward that port to the Newt host.
## Platform notes
### Barracuda
Barracuda environments commonly struggle with simultaneous UDP flows from multiple clients, which can push connections to relay mode.
What helps:
- Increase the firewall's maximum UDP session capacity [by increasing the max udp parameter](https://campus.barracuda.com/product/cloudgenfirewall/doc/95258827/general-firewall-configuration/?sl=AX5zwzvyOBUvMAhoTe4U&so=2)
- If direct connectivity is still inconsistent, use a fixed Newt listening port and forward it explicitly.
### Check Point
Check Point deployments generally allow Pangolin direct connectivity without extra configuration.
### Cisco
Cisco firewalls often require additional policy tuning before direct paths become stable.
#### Cisco Umbrella Endpoint Security
When Cisco Umbrella Endpoint Security is in-path, direct peer connectivity is frequently blocked and relay becomes the normal outcome.
### Fortinet
Fortinet environments are often stable for smaller deployments but may shift heavily to relay as concurrent client count grows.
### pfSense
pfSense frequently land in relay mode unless inbound UDP mapping behavior is made explicit. Try the following changes:
By default, pfSense software rewrites the source port on all outgoing connections to enhance security and prevent direct exposure of internal port numbers.
Static port mapping in pfSense involves creating a fixed association between a specific external port number and an internal IP address and port, allowing incoming traffic to be directed to the correct destination within the local network.
Locate the Firewall > NAT, Outbound tab. Select Hybrid Outbound NAT rule generation. Select Save. Select ↑ Add to create a new NAT rule to the top of the list.
Configure the rule: IPv4+IPv6, for Protocol UDP, source address Any. Check Static Port in the Translation section of the page.
Select Save. Select Apply Changes.
### OPNsense
OPNsense frequently land in relay mode unless inbound UDP mapping behavior is made explicit. Try the following changes:
By default, OPNsense software rewrites the source port on all outgoing connections to enhance security and prevent direct exposure of internal port numbers.
Static port mapping in OPNsense involves creating a fixed association between a specific external port number and an internal IP address and port, allowing incoming traffic to be directed to the correct destination within the local network.
Go to Firewall > NAT, Outbound tab. Select Hybrid Outbound NAT rule generation. Select Save. Select ↑ Add to create a new NAT rule to the top of the list.
Configure the rule to match UDP traffic. Note, for each rule, select the appropriate Address Family (IP version), IPv4 for one and IPv6 for the other.
Here is the Markdown table based on the image provided:
| Interface | Source | Source Port | Destination | Destination Port | NAT Address | NAT Port | Static Port | Description |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WAN | LAN net | udp/ * | * | udp/ * | Interface address | * | YES | Pangolin IPv4 |
| WAN | LAN net | udp/ * | * | udp/ * | Interface address | * | YES | Pangolin IPv6 |
Check Static Port in the Translation section of the page. Select Save. Select Apply Changes.
### Palo Alto Networks
Palo Alto deployments can improve direct path reliability by using persistent NAT translation behavior (dynamic IP and port persistence) so UDP mappings do not churn between destinations. [Take a look at the documentation here](https://docs.paloaltonetworks.com/pan-os/10-1/pan-os-new-features/networking-features/persistent-nat-for-dipp).
PAN-OS 11.1.x and later: Persistent Dynamic IP and Port
Ensure stability and performance by referring to the list of preferred releases for PAN-OS.
PAN-OS 11.1.1 contains the translation type for NAT policies, Persistent Dynamic IP and Port. In this translation type, once a client has sent a packet with a particular source port, the same NAT translated port number will be used for all destinations. This lets Tailscale to predict the port number and establish a direct connection.
To use this translation type, go to NAT Policy Rule, select the Translated Packet tab, then select the Translation Type option Persistent Dynamic IP and Port.
Earlier PAN-OS releases: Static IP
With older PAN-OS releases and the Dynamic IP and Port translation type, every UDP stream will translate to a random UDP port. Opening a specific port will not allow traffic through, and Tailscale cannot predict what port number to try for a direct connection.
With older PAN-OS releases it is possible to use the Static IP NAT Policy to enable one device within the protected zone to make direct connections. One might choose a subnet router or other high-traffic node to optimize. In the PAN-OS software create a NAT policy rule with Translation Type set to Static IP, instead of the default setting Dynamic IP And Port. This helps Tailscale figure out how to get packets through the NAT and establish direct connections.
### Sophos
Sophos gateways usually work well with Pangolin's direct-connect flow under default NAT behavior.
If relay usage rises unexpectedly, verify no extra IPS/inspection rule set is rewriting UDP sessions.
### UniFi Gateways
On UniFi networks with threat detection enabled, peer-to-peer categories can interfere with hole punching.
In UniFi Network version 9.0.107 and earlier, select to Settings, Firewall & Security, Edit threat categories, and uncheck P2P.
In UniFi Network version 9.0.108 and later, select to Network, Security, Protection, Peer to Peer and Dark Web, and uncheck P2P.
## Verify improvements
After each firewall change, validate results from a client:
1. Reconnect the site/client pair.
2. Run `pangolin status` (or check JSON status in GUI clients).
3. Confirm `RELAY=false` / `isRelay: false` for sessions expected to be direct.
If direct paths still fail, keep relay enabled and continue iterating with narrower firewall adjustments rather than broad allow-all rules.

35
manage/clients/firewalls/opnsense.mdx
View File

@@ -1,35 +0,0 @@
---
title: "OPNsense"
description: "Tune OPNsense for better Pangolin direct connectivity"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Use this guide if clients behind OPNsense are frequently relayed instead of connecting directly.
## Prerequisites
- OPNsense access with admin rights
- Ability to edit NAT and service settings
- A way to verify Pangolin connection mode after changes
## Static outbound UDP mapping
This approach keeps outbound source ports predictable so UDP hole punching succeeds more often.
1. In OPNsense, open **Firewall > NAT > Outbound**.
2. Switch to **Hybrid Outbound NAT rule generation**.
3. Add a new outbound rule near the top of the list.
4. Configure the rule for UDP traffic used by Pangolin clients/sites.
5. Enable **Static Port** in the translation section.
6. Save and apply changes.
## Validate the result
1. Reconnect a Pangolin client.
2. Check the site entry in client status (`isRelay` in JSON view or `RELAY` column in CLI).
3. Compare before/after to confirm improved direct connectivity.

40
manage/clients/firewalls/overview.mdx
View File

@@ -1,40 +0,0 @@
---
title: "Firewall Integrations"
description: "Improve Pangolin direct-connect success behind restrictive firewalls"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Most Pangolin deployments work without special firewall tuning. In stricter NAT environments, direct client-to-site paths can fail and sessions fall back to relay.
This section covers firewall-side changes that can improve direct connectivity for common enterprise and appliance firewalls.
## Why this matters
Pangolin clients try direct UDP paths first and relay only when needed. If your firewall rewrites UDP source ports aggressively (or blocks port mapping protocols), hole punching becomes less reliable.
Direct paths usually mean:
- Lower latency
- Better throughput
- Less relay traffic on your Pangolin infrastructure
Learn more about how [Pangolin NAT hole punching works](https://pangolin.net/news/nat-holepunching).
## Connection behavior quick guide
| Firewall platform | Typical default behavior | Common fix |
| --- | --- | --- |
| OPNsense | Often relayed in hard-NAT setups | Static outbound UDP mapping or NAT-PMP |
| pfSense | Often relayed in hard-NAT setups | Static outbound UDP mapping or NAT-PMP |
| Palo Alto Networks | Often relayed with random UDP source translation | Persistent Dynamic IP and Port NAT translation |
## Choose your platform
- [OPNsense guide](/manage/clients/firewalls/opnsense)
- [pfSense guide](/manage/clients/firewalls/pfsense)
- [Palo Alto Networks guide](/manage/clients/firewalls/palo-alto)

53
manage/clients/firewalls/palo-alto.mdx
View File

@@ -1,53 +0,0 @@
---
title: "Palo Alto Networks"
description: "Use PAN-OS NAT translation modes that improve Pangolin direct connectivity"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Palo Alto firewalls often default to dynamic source-port translation, which can make UDP hole punching less predictable. This guide focuses on NAT translation settings that improve direct Pangolin paths.
## How this affects Pangolin
When translated source ports change unpredictably per destination, peers cannot reliably discover return paths for direct UDP sessions.
In those cases, clients may connect through relay more often.
## PAN-OS 11.1.x and later
Prefer **Persistent Dynamic IP and Port** for NAT policies handling Pangolin traffic.
1. Open the relevant **NAT Policy Rule**.
2. Go to **Translated Packet**.
3. Set **Translation Type** to **Persistent Dynamic IP and Port**.
4. Commit changes.
This keeps NAT behavior more consistent per client flow and improves direct-connect success.
## Selective policy approach
If you cannot apply persistent translation globally, scope it to Pangolin UDP traffic only.
1. Create a custom service object for Pangolin UDP flow matching.
2. Use that service as match criteria in the NAT rule's **Original Packet** tab.
3. Apply persistent translation only for matching traffic.
4. Commit and test.
## Earlier PAN-OS releases
If your version does not support persistent dynamic translation, a **Static IP** NAT policy can improve direct connectivity for selected high-value nodes (for example, a frequently used subnet or gateway host).
- Create a dedicated NAT policy for the target traffic
- Set Translation Type to Static IP
- Scope rules tightly and test
## Validate the result
1. Reconnect a Pangolin client.
2. Check the site entry in client status (`isRelay` in JSON view or `RELAY` column in CLI).
3. Compare before/after to confirm improved direct connectivity.

36
manage/clients/firewalls/pfsense.mdx
View File

@@ -1,36 +0,0 @@
---
title: "pfSense"
description: "Tune pfSense for better Pangolin direct connectivity"
---
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
<PangolinCloudTocCta />
Use this guide if clients behind pfSense regularly fall back to relay.
## Prerequisites
- pfSense admin access
- Permission to change outbound NAT and service settings
- A test client/site pair to validate results
## Static outbound UDP mapping
Static outbound mapping improves source-port consistency, which helps UDP hole punching.
1. Open **Firewall > NAT > Outbound**.
2. Choose **Hybrid Outbound NAT** mode.
3. Add a new UDP outbound NAT rule and place it near the top.
4. Set matching for Pangolin-relevant source traffic.
5. Enable **Static Port** translation.
6. Save and apply.
## Validate the result
1. Reconnect a Pangolin client.
2. Check the site entry in client status (`isRelay` in JSON view or `RELAY` column in CLI).
3. Compare before/after to confirm improved direct connectivity.

4
manage/clients/nat-traversal.mdx
View File

@@ -95,7 +95,7 @@ Use either view when troubleshooting hole punching or verifying that configurati
Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency.
In some environments, depending on the NAT type and firewall, you may need to tweak settings to get optimal connectivity in the firewall itself. See [Firewall Integrations](/manage/clients/firewalls/overview) for Pangolin-specific guidance for common platforms.
In some environments, depending on the NAT type and firewall, you may need to tweak settings to get optimal connectivity in the firewall itself. See [Firewall Integrations](/manage/clients/firewalls) for Pangolin-specific guidance for common platforms.
Another option is to keep Newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in your firewall to DNAT to Newt. See [Configure Sites](/manage/sites/configure-site) for the full list of Newt flags and environment variables.
@@ -135,6 +135,6 @@ Another option is to keep Newt listening for client connections on a static port
</Accordion>
<Accordion title="Do I need to open firewall ports for hole punching?">
Not always. Many networks hole punch successfully without inbound rules. If punching is unreliable, try [Firewall Integrations](/manage/clients/firewalls/overview) guidance or pin Newt to a static port with `--port` / `PORT` and DNAT that port to Newt on the site host.
Not always. Many networks hole punch successfully without inbound rules. If punching is unreliable, try [Firewall Integrations](/manage/clients/firewalls) guidance or pin Newt to a static port with `--port` / `PORT` and DNAT that port to Newt on the site host.
</Accordion>
</AccordionGroup>