From e2b6ab1db5f87a0e3e65fd21b74962be1e73e350 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Sun, 21 Dec 2025 21:22:02 +1100 Subject: [PATCH] Add critical NAT Reflection fix for port forwarding and SSL certificate generation --- TROUBLESHOOTING_NAT_REFLECTION.md | 236 ++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 TROUBLESHOOTING_NAT_REFLECTION.md diff --git a/TROUBLESHOOTING_NAT_REFLECTION.md b/TROUBLESHOOTING_NAT_REFLECTION.md new file mode 100644 index 0000000..327f8b7 --- /dev/null +++ b/TROUBLESHOOTING_NAT_REFLECTION.md @@ -0,0 +1,236 @@ +# OPNsense NAT Reflection Fix - Critical Configuration + +**Issue:** Port forwards work from outside network but NOT from inside network, or SSL certificate generation fails with "JSONObject["responsetime"] not found" + +**Solution:** Enable "Automatic outbound NAT for Reflection" + +--- + +## 🎯 The Problem + +When you have port forwards configured in OPNsense (e.g., port 80/443 → Nginx), you may encounter: + +### Symptoms: +- ✅ Port forwards work from OUTSIDE your network (mobile data) +- ❌ Port forwards DON'T work from INSIDE your network +- ❌ SSL certificate generation fails in Nginx Proxy Manager +- ❌ Can't access services using external domain from internal network +- ❌ Firewall logs show: "Default deny / state violation rule" + +### Root Cause: +**NAT Reflection is not properly configured.** + +NAT Reflection allows devices on your internal network (LAN) to access internal services using the external IP address or domain name. Without it, traffic loops back incorrectly and gets blocked. + +--- + +## ✅ The Fix: Enable Automatic Outbound NAT for Reflection + +### Step 1: Navigate to NAT Reflection Settings + +1. **Login to OPNsense:** https://10.0.0.254 + +2. **Navigate to:** System > Settings > Advanced + +3. **Scroll to:** Firewall & NAT section + +--- + +### Step 2: Enable NAT Reflection + +4. **Configure these settings:** + +``` +Reflection for port forwards: + ● Enable (NAT + Proxy) + +Reflection for 1:1: + ● Enable (NAT + Proxy) + +Automatic outbound NAT for Reflection: + ☑ Enable automatic outbound NAT for Reflection ← THIS IS CRITICAL! + +Reflection timeout: 2000 (default) +``` + +5. **Click SAVE** + +6. **Scroll to bottom and click "Apply Changes"** + +--- + +### Step 3: Test Immediately + +**From INSIDE your network:** + +```bash +# Test accessing service via external domain +ping immish.hideawaygaming.com.au +# Should resolve to your public IP + +# Test HTTP +curl -I http://immish.hideawaygaming.com.au +# Should return: HTTP/1.1 200 OK or 301 redirect + +# Test in browser +https://immish.hideawaygaming.com.au +# Should show your service! +``` + +**From OUTSIDE your network (mobile data):** +- Should continue to work as before + +--- + +## 📋 What This Setting Does + +### Without "Automatic outbound NAT for Reflection": + +``` +Internal Client (10.0.0.14) + | + | Request to: immish.hideawaygaming.com.au (120.156.234.95) + v +[OPNsense WAN] + | + | NAT forward: 443 → 10.0.0.55:443 + v +[Nginx 10.0.0.55] + | + | Response to: 10.0.0.14 (direct, bypasses firewall) + v +[Client 10.0.0.14] ❌ BLOCKED - connection state mismatch! + +Result: "Default deny / state violation rule" +``` + +### With "Automatic outbound NAT for Reflection" ENABLED: + +``` +Internal Client (10.0.0.14) + | + | Request to: immish.hideawaygaming.com.au (120.156.234.95) + v +[OPNsense WAN] + | + | NAT forward: 443 → 10.0.0.55:443 + | ALSO creates outbound NAT rule + v +[Nginx 10.0.0.55] + | + | Response goes BACK to OPNsense + v +[OPNsense] + | + | Translates back to original request + v +[Client 10.0.0.14] ✅ SUCCESS - connection states match! + +Result: Traffic flows correctly! +``` + +--- + +## 🔧 Common Scenarios Where This Matters + +### 1. SSL Certificate Generation in Nginx Proxy Manager + +**Without NAT Reflection:** +- Let's Encrypt tries to verify domain +- Request goes to external IP +- Loops back through NAT +- Gets blocked by firewall +- Error: "JSONObject["responsetime"] not found" + +**With NAT Reflection:** +- Let's Encrypt verification works +- Certificate generates successfully ✅ + +--- + +### 2. Internal Access to Services + +**Without NAT Reflection:** +``` +User types: https://plex.yourdomain.com +DNS resolves to: 203.x.x.x (public IP) +Request hits OPNsense WAN +Forwarded to Plex server +Response blocked ❌ +``` + +**With NAT Reflection:** +``` +User types: https://plex.yourdomain.com +DNS resolves to: 203.x.x.x (public IP) +Request hits OPNsense WAN +Forwarded to Plex server +Response properly NAT'd back +User sees Plex! ✅ +``` + +--- + +## 📝 Quick Reference Card + +``` +╔═══════════════════════════════════════════════════════════╗ +║ OPNsense NAT Reflection Quick Fix ║ +╠═══════════════════════════════════════════════════════════╣ +║ ║ +║ Location: System > Settings > Advanced ║ +║ Section: Firewall & NAT ║ +║ ║ +║ Settings: ║ +║ Reflection for port forwards: Enable (NAT + Proxy) ║ +║ Reflection for 1:1: Enable (NAT + Proxy) ║ +║ ☑ Enable automatic outbound NAT for Reflection ║ +║ ║ +║ Purpose: ║ +║ Allows internal devices to access services ║ +║ using external IP/domain names ║ +║ ║ +║ Result: ║ +║ ✅ Port forwards work from anywhere ║ +║ ✅ SSL certificates generate successfully ║ +║ ✅ Single URL works inside and outside network ║ +║ ║ +╚═══════════════════════════════════════════════════════════╝ +``` + +--- + +## 🎯 Related Issues This Fixes + +1. **SSL Certificate Generation Failures** + - Error: "JSONObject["responsetime"] not found" + - Error: "Connection timeout" + - Error: "Domain validation failed" + +2. **Firewall Blocking Internal Requests** + - Log: "Default deny / state violation rule" + - Log: "Connection state mismatch" + - Traffic blocked even with port forwards configured + +3. **Services Not Accessible Internally** + - External domain works from mobile data + - Same domain doesn't work from WiFi + - Different behavior inside vs outside network + +4. **Nginx Proxy Manager Issues** + - Can't generate certificates + - Can't access proxied services internally + - 502 Bad Gateway from internal network + +--- + +**This setting is CRITICAL for proper port forwarding functionality in OPNsense!** + +**Always enable "Automatic outbound NAT for Reflection" when using port forwards for services that need to be accessed both internally and externally.** + +--- + +*Discovered By: jessikitty* +*Date: December 21, 2025* +*Tested On: OPNsense 25.1, Mac mini 2014* +*Location: System > Settings > Advanced > Firewall & NAT*