pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-09-08 07:01:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add basic firewall information

Browse Source
This commit is contained in:
Owen
2026-06-26 09:26:20 -04:00
parent 48ce4ac51a
commit 48a360c929
6 changed files with 254 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs.json
View File

@@ -90,6 +90,15 @@
"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",

62
manage/clients/firewalls/opnsense.mdx Normal file
View File

@@ -0,0 +1,62 @@
---
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
## Option 1: 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.
<Note>
Image description from the source references: the Outbound NAT page showing a UDP rule with static-port translation enabled, created in hybrid mode and applied at the top of the outbound rules list.
</Note>
## Option 2: NAT-PMP
If your environment allows it, NAT-PMP can let clients request temporary UDP mappings dynamically.
1. Open **Services > Universal Plug and Play**.
2. Enable NAT-PMP support.
3. Keep the scope as narrow as your policy allows.
4. Apply changes.
<Warning>
NAT-PMP can improve connectivity, but may broaden mapping behavior. Use restricted ACLs and network segmentation where possible.
</Warning>
<Note>
Image description from the source references: the UPnP/NAT-PMP settings panel with NAT-PMP allowed, indicating dynamic mapping is enabled for LAN clients.
</Note>
## Optional: Running Tailscale plugin on OPNsense
Source material notes that recent OPNsense releases include an `os-tailscale` community plugin. That workflow is specific to Tailscale installations on the firewall itself and is separate from Pangolin client/site tuning.
For Pangolin, prioritize the NAT behavior changes above.
## 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.

57
manage/clients/firewalls/overview.mdx Normal file
View File

@@ -0,0 +1,57 @@
---
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
## Security and performance trade-off
Some changes that improve direct connectivity can also widen inbound mapping behavior. Review each setting with your security team before enabling it globally.
- NAT-PMP or UPnP can increase exposure if left broad
- Static or persistent port translation can improve predictability, but should be scoped to known traffic when possible
## 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)
## Verifying impact
After applying changes:
1. Reconnect the client and site.
2. Check connection status in the Pangolin client JSON view or `pangolin status`.
3. Confirm more sessions are direct and fewer are relayed.
<Note>
Image description from the source references: a summary banner showing that direct peer-to-peer is preferred, with relay as fallback when NAT policies prevent direct UDP paths.
</Note>

64
manage/clients/firewalls/palo-alto.mdx Normal file
View File

@@ -0,0 +1,64 @@
---
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.
<Note>
Image description from the source references: NAT Policy Rule editor on the Translated Packet tab, with Translation Type set to Persistent Dynamic IP and Port.
</Note>
## 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.
<Note>
Image description from the source references: one screen shows a custom UDP service definition with timeout tuning; another shows that service selected in NAT policy match criteria.
</Note>
## 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
<Note>
Image description from the source references: older NAT policy editor where Translation Type is set to Static IP instead of Dynamic IP and Port.
</Note>
## Validate the result
1. Reconnect Pangolin clients and sites.
2. Check whether previously relayed sessions now establish direct paths.
3. Keep monitoring for policy side effects or unintended exposure.

60
manage/clients/firewalls/pfsense.mdx Normal file
View File

@@ -0,0 +1,60 @@
---
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
## Option 1: 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.
<Note>
Image description from the source references: pfSense outbound NAT screen with a UDP rule in hybrid mode and static-port translation enabled.
</Note>
## Option 2: NAT-PMP
For compatible environments, NAT-PMP can allow temporary port mappings for clients.
1. Open **Services > UPnP & NAT-PMP**.
2. Enable NAT-PMP mapping.
3. Limit allowed interfaces and clients where possible.
4. Save and apply changes.
<Warning>
NAT-PMP and UPnP can reduce relay usage but should be scoped carefully to avoid opening unnecessary mapping paths.
</Warning>
<Note>
Image description from the source references: the pfSense UPnP & NAT-PMP settings page with NAT-PMP enabled.
</Note>
## Newer pfSense behavior
The source references newer pfSense builds adding endpoint-independent style outbound NAT options. If available in your version, test these features in a controlled environment before broad rollout.
## Validate the result
1. Reconnect Pangolin clients.
2. Inspect connection mode in client status.
3. Confirm direct sessions increase and relay sessions decrease.

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. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make.
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.
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 tweaks from [Tailscale's firewall guide](https://tailscale.com/kb/1361/firewall) 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/overview) guidance or pin Newt to a static port with `--port` / `PORT` and DNAT that port to Newt on the site host.
</Accordion>
</AccordionGroup>