jessikitty/ha-wirelesscontrol-migration
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

🔥 CRITICAL: OPNsense NAT Reflection Required for Port Forwarding #3

New Issue
Open
opened 2025-12-21 21:22:50 +11:00 by jessikitty · 0 comments
jessikitty commented 2025-12-21 21:22:50 +11:00
Owner
Copy Link

🔥 CRITICAL: OPNsense NAT Reflection Must Be Enabled

Issue Discovered: December 21, 2025
Reporter: jessikitty
Severity: HIGH - Blocks SSL certificate generation and internal service access

🎯 Problem Summary

When setting up OPNsense with port forwards (80, 443) to Nginx Proxy Manager, SSL certificate generation failed with error:

"JSONObject["responsetime"] not found"

Firewall logs showed:

WAN  161.123.172.240:46683  10.0.0.55:443  tcp  Default deny / state violation rule
WAN  198.240.78.237:43939   10.0.0.55:443  tcp  Default deny / state violation rule

✅ Solution

Enable "Automatic outbound NAT for Reflection"

Location:

System > Settings > Advanced > Firewall & NAT

Settings:

Reflection for port forwards: Enable (NAT + Proxy)
Reflection for 1:1: Enable (NAT + Proxy)
☑ Enable automatic outbound NAT for Reflection  ← CRITICAL!

After enabling this single setting:

  • ✅ SSL certificates generate successfully
  • ✅ Services accessible from internal network using external domain
  • ✅ No more "state violation" errors in firewall logs
  • ✅ Single URL works both inside and outside network

📚 Documentation Created

Complete troubleshooting guide: TROUBLESHOOTING_NAT_REFLECTION.md

Also available in: /mnt/user-data/outputs/OPNSENSE_NAT_REFLECTION_FIX.md

What the Guide Covers:

  1. Symptoms to watch for

    • SSL certificate failures
    • Internal access issues
    • Firewall state violations

  2. Step-by-step fix

    • Exact navigation path
    • Settings to enable
    • Verification steps

  3. Technical explanation

    • Why this happens
    • How NAT reflection works
    • Traffic flow diagrams

  4. Common scenarios

    • Nginx Proxy Manager
    • Plex media server
    • Mobile apps using external domains

🎓 Why This Matters

Without NAT Reflection:

Internal device tries to access external domain
    ↓
DNS resolves to public IP
    ↓
Traffic goes to OPNsense WAN
    ↓
NAT forwards to internal service
    ↓
Service responds directly to client
    ↓
Client expects response from public IP, gets internal IP
    ↓
❌ Connection state mismatch → BLOCKED

With NAT Reflection:

Internal device tries to access external domain
    ↓
DNS resolves to public IP
    ↓
Traffic goes to OPNsense WAN
    ↓
NAT forwards to internal service
    ↓
Service responds back through OPNsense
    ↓
OPNsense translates source IP correctly
    ↓
✅ Client sees expected source → CONNECTION SUCCESS

📋 Must Add to Main Guide

This setting should be added to MAC_MINI_OPNSENSE_GUIDE.md at:

Phase 1, after Step 1.7 (Configure DHCP Server)

New Step 1.7b: Enable NAT Reflection

Addendum created: /mnt/user-data/outputs/GUIDE_ADDENDUM_NAT_REFLECTION.md

🔍 Real-World Impact

User Setup:

  • Mac mini 2014 running OPNsense
  • Nginx Proxy Manager on Home Assistant (10.0.0.55)
  • Port forwards: 80 → 10.0.0.55:80, 443 → 10.0.0.55:443
  • Domain: hideawaygaming.com.au

Before NAT Reflection:

  • DNS resolution: ✅ WORKING (120.156.234.95)
  • Port forwards configured: ✅ WORKING
  • External access (mobile data): ✅ WORKING
  • Internal access (WiFi): ❌ BLOCKED
  • SSL certificate generation: ❌ FAILED
  • Firewall logs: ❌ State violations

After Enabling NAT Reflection:

  • Everything above: ✅ ALL WORKING
  • Single setting change
  • Immediate effect
  • No other configuration needed

⚠️ Critical for These Use Cases

This setting is REQUIRED when:

  • ✅ Using Nginx Proxy Manager
  • ✅ Generating Let's Encrypt certificates
  • ✅ Accessing services via external domain from internal network
  • ✅ Using mobile apps that reference external domains
  • ✅ Running Plex or other media servers
  • ✅ Any port forwarding scenario where internal + external access is needed

NOT required when:

  • ❌ Services are internal-only (no port forwards)
  • ❌ Using VPN-only access
  • ❌ Using split-horizon DNS
  • ❌ Never accessing services internally via external domain

🎯 Action Items

  • Document the issue and solution
  • Create comprehensive troubleshooting guide
  • Upload to repository
  • Update main Mac mini guide with this step
  • Add to troubleshooting section
  • Test on fresh OPNsense installation
  • Add to common gotchas list

📊 Configuration Details

Network Setup:

Router: OPNsense @ 10.0.0.254 (Mac mini 2014)
Nginx: Home Assistant @ 10.0.0.55
Public IP: 120.156.234.95
Domain: hideawaygaming.com.au

Port Forwards:
  80 → 10.0.0.55:80 (HTTP)
  443 → 10.0.0.55:443 (HTTPS)

Error Seen:

Nginx Proxy Manager SSL Certificate Generation:
"There is a server found at this domain but it returned 
an unexpected status code JSONObject["responsetime"] not found."

OPNsense Firewall Logs:
"Default deny / state violation rule"
Multiple IPs attempting to connect to 10.0.0.55:443 blocked

Diagnostic Results:

# DNS resolution - CORRECT
nslookup immish.hideawaygaming.com.au
→ 120.156.234.95

# Public IP - CORRECT
curl ifconfig.me
→ 120.156.234.95

# Port forwards - CONFIGURED
Firewall > NAT > Port Forward
→ 80 and 443 forwards present

# Issue - NAT REFLECTION DISABLED
System > Settings > Advanced
→ Automatic outbound NAT for Reflection: UNCHECKED ❌

🚀 Resolution Timeline

19:00 - SSL certificate generation fails
19:15 - Firewall logs show state violations
19:30 - Diagnostic checks (DNS, IP, port forwards all correct)
19:45 - Identified NAT Reflection as root cause
19:50 - Enabled "Automatic outbound NAT for Reflection"
19:51 - SSL certificate generates successfully! ✅
20:00 - Documentation created

Total time to fix: < 5 minutes after identifying correct setting
Total time troubleshooting: ~50 minutes (could have been 5 with proper docs!)

💡 Key Takeaway

ONE checkbox solves:

  • SSL certificate generation failures
  • Internal access issues
  • Firewall state violations
  • Multiple hours of troubleshooting

This should be in EVERY OPNsense port forwarding guide!

📖 References

This is a CRITICAL finding that will save others hours of troubleshooting! 🎉

Credit to @jessikitty for:

  1. Persistent debugging
  2. Finding the exact setting
  3. Sharing the solution
  4. Enabling comprehensive documentation

Everyone using OPNsense with port forwards needs to know about this!

# 🔥 CRITICAL: OPNsense NAT Reflection Must Be Enabled **Issue Discovered:** December 21, 2025 **Reporter:** jessikitty **Severity:** HIGH - Blocks SSL certificate generation and internal service access --- ## 🎯 Problem Summary When setting up OPNsense with port forwards (80, 443) to Nginx Proxy Manager, SSL certificate generation failed with error: ``` "JSONObject["responsetime"] not found" ``` Firewall logs showed: ``` WAN 161.123.172.240:46683 10.0.0.55:443 tcp Default deny / state violation rule WAN 198.240.78.237:43939 10.0.0.55:443 tcp Default deny / state violation rule ``` --- ## ✅ Solution **Enable "Automatic outbound NAT for Reflection"** ### Location: System > Settings > Advanced > Firewall & NAT ### Settings: ``` Reflection for port forwards: Enable (NAT + Proxy) Reflection for 1:1: Enable (NAT + Proxy) ☑ Enable automatic outbound NAT for Reflection ← CRITICAL! ``` **After enabling this single setting:** - ✅ SSL certificates generate successfully - ✅ Services accessible from internal network using external domain - ✅ No more "state violation" errors in firewall logs - ✅ Single URL works both inside and outside network --- ## 📚 Documentation Created **Complete troubleshooting guide:** [TROUBLESHOOTING_NAT_REFLECTION.md](TROUBLESHOOTING_NAT_REFLECTION.md) **Also available in:** `/mnt/user-data/outputs/OPNSENSE_NAT_REFLECTION_FIX.md` ### What the Guide Covers: 1. **Symptoms to watch for** - SSL certificate failures - Internal access issues - Firewall state violations 2. **Step-by-step fix** - Exact navigation path - Settings to enable - Verification steps 3. **Technical explanation** - Why this happens - How NAT reflection works - Traffic flow diagrams 4. **Common scenarios** - Nginx Proxy Manager - Plex media server - Mobile apps using external domains --- ## 🎓 Why This Matters ### Without NAT Reflection: ``` Internal device tries to access external domain ↓ DNS resolves to public IP ↓ Traffic goes to OPNsense WAN ↓ NAT forwards to internal service ↓ Service responds directly to client ↓ Client expects response from public IP, gets internal IP ↓ ❌ Connection state mismatch → BLOCKED ``` ### With NAT Reflection: ``` Internal device tries to access external domain ↓ DNS resolves to public IP ↓ Traffic goes to OPNsense WAN ↓ NAT forwards to internal service ↓ Service responds back through OPNsense ↓ OPNsense translates source IP correctly ↓ ✅ Client sees expected source → CONNECTION SUCCESS ``` --- ## 📋 Must Add to Main Guide This setting should be added to **MAC_MINI_OPNSENSE_GUIDE.md** at: **Phase 1, after Step 1.7 (Configure DHCP Server)** **New Step 1.7b: Enable NAT Reflection** Addendum created: `/mnt/user-data/outputs/GUIDE_ADDENDUM_NAT_REFLECTION.md` --- ## 🔍 Real-World Impact **User Setup:** - Mac mini 2014 running OPNsense - Nginx Proxy Manager on Home Assistant (10.0.0.55) - Port forwards: 80 → 10.0.0.55:80, 443 → 10.0.0.55:443 - Domain: hideawaygaming.com.au **Before NAT Reflection:** - DNS resolution: ✅ WORKING (120.156.234.95) - Port forwards configured: ✅ WORKING - External access (mobile data): ✅ WORKING - Internal access (WiFi): ❌ BLOCKED - SSL certificate generation: ❌ FAILED - Firewall logs: ❌ State violations **After Enabling NAT Reflection:** - Everything above: ✅ ALL WORKING - Single setting change - Immediate effect - No other configuration needed --- ## ⚠️ Critical for These Use Cases **This setting is REQUIRED when:** - ✅ Using Nginx Proxy Manager - ✅ Generating Let's Encrypt certificates - ✅ Accessing services via external domain from internal network - ✅ Using mobile apps that reference external domains - ✅ Running Plex or other media servers - ✅ Any port forwarding scenario where internal + external access is needed **NOT required when:** - ❌ Services are internal-only (no port forwards) - ❌ Using VPN-only access - ❌ Using split-horizon DNS - ❌ Never accessing services internally via external domain --- ## 🎯 Action Items - [x] Document the issue and solution - [x] Create comprehensive troubleshooting guide - [x] Upload to repository - [ ] Update main Mac mini guide with this step - [ ] Add to troubleshooting section - [ ] Test on fresh OPNsense installation - [ ] Add to common gotchas list --- ## 📊 Configuration Details ### Network Setup: ``` Router: OPNsense @ 10.0.0.254 (Mac mini 2014) Nginx: Home Assistant @ 10.0.0.55 Public IP: 120.156.234.95 Domain: hideawaygaming.com.au Port Forwards: 80 → 10.0.0.55:80 (HTTP) 443 → 10.0.0.55:443 (HTTPS) ``` ### Error Seen: ``` Nginx Proxy Manager SSL Certificate Generation: "There is a server found at this domain but it returned an unexpected status code JSONObject["responsetime"] not found." OPNsense Firewall Logs: "Default deny / state violation rule" Multiple IPs attempting to connect to 10.0.0.55:443 blocked ``` ### Diagnostic Results: ```bash # DNS resolution - CORRECT nslookup immish.hideawaygaming.com.au → 120.156.234.95 # Public IP - CORRECT curl ifconfig.me → 120.156.234.95 # Port forwards - CONFIGURED Firewall > NAT > Port Forward → 80 and 443 forwards present # Issue - NAT REFLECTION DISABLED System > Settings > Advanced → Automatic outbound NAT for Reflection: UNCHECKED ❌ ``` --- ## 🚀 Resolution Timeline **19:00** - SSL certificate generation fails **19:15** - Firewall logs show state violations **19:30** - Diagnostic checks (DNS, IP, port forwards all correct) **19:45** - Identified NAT Reflection as root cause **19:50** - Enabled "Automatic outbound NAT for Reflection" **19:51** - **SSL certificate generates successfully!** ✅ **20:00** - Documentation created **Total time to fix:** < 5 minutes after identifying correct setting **Total time troubleshooting:** ~50 minutes (could have been 5 with proper docs!) --- ## 💡 Key Takeaway **ONE checkbox solves:** - SSL certificate generation failures - Internal access issues - Firewall state violations - Multiple hours of troubleshooting **This should be in EVERY OPNsense port forwarding guide!** --- ## 📖 References - **Full Documentation:** [TROUBLESHOOTING_NAT_REFLECTION.md](TROUBLESHOOTING_NAT_REFLECTION.md) - **Guide Addendum:** `/mnt/user-data/outputs/GUIDE_ADDENDUM_NAT_REFLECTION.md` - **Main Guide:** [MAC_MINI_OPNSENSE_GUIDE.md](MAC_MINI_OPNSENSE_GUIDE.md) (needs update) - **OPNsense Docs:** https://docs.opnsense.org/manual/nat.html#reflection --- **This is a CRITICAL finding that will save others hours of troubleshooting!** 🎉 Credit to @jessikitty for: 1. Persistent debugging 2. Finding the exact setting 3. Sharing the solution 4. Enabling comprehensive documentation **Everyone using OPNsense with port forwards needs to know about this!**
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jessikitty
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jessikitty/ha-wirelesscontrol-migration#3
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?