# 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*