Split-Horizon DNS for Multi-Site Networks

Simple, persistent split-horizon DNS configuration for OpenWrt/Gargoyle and Ubiquiti UDM Pro

---

The Problem: Port Forwarding Works from Outside, But Not Inside

You've set up port forwarding to access your NVR, cameras, or servers from the internet - and it works perfectly from outside your network. But when you try to use the same URL from inside your local network, it fails. This is called the "Hairpin NAT" problem (also known as NAT loopback or NAT reflection).

What's Happening (The Hairpin NAT Problem)

Your Setup:

• NVR on local network: 192.168.55.19
• Public IP: 203.0.113.39
• Port forwarding: External 8000 → Internal 80
• External DNS: nvr8000.factory.example.com → 203.0.113.39

From Outside (Works ✅):

1. You visit: http://nvr8000.factory.example.com:8000
2. DNS resolves to: 203.0.113.39 (public IP)
3. Router forwards port 8000 to 192.168.55.19:80
4. Connection successful!

From Inside Your Network (Fails ❌):

1. You visit: http://nvr8000.factory.example.com:8000
2. DNS resolves to: 203.0.113.39 (same public IP)
3. Traffic goes OUT to router's WAN interface
4. Router tries to "hairpin" traffic back inside
5. FAILS - Most routers don't support hairpin NAT!

Why Most Routers Don't Support Hairpin NAT

When you're inside your network trying to reach your own public IP, the router needs to perform "hairpin NAT" - receiving traffic from inside and looping it back inside. This feature is:

• ❌ Not supported by most consumer routers (TP-Link, Netgear, Asus, Linksys)
• ❌ Not supported by many Gargoyle configurations
• ❌ Not supported by some UDM Pro configurations
• ⚠️ Inconsistent - May work on some firmware versions, fail on others
• ⚠️ Wasteful - Even if it works, it wastes bandwidth and doubles latency

Visual Example:

Inside Factory (Hairpin NAT Required):
┌─────────────┐
│  Your PC    │  "Connect to nvr8000.factory.example.com:8000"
│ 192.168.55.5│  DNS says: 203.0.113.39
└──────┬──────┘
       │ Traffic goes OUT...
       ▼
┌─────────────┐
│   Router    │  ❌ "Hairpin NAT not supported!"
│ WAN: 203.   │     Traffic trying to loop back
│ LAN: 192.   │     Connection FAILS
└─────────────┘

Common Workarounds (And Why They're Not Ideal)

❌ Use Public IP from Outside, Local IP from Inside

• Requires two different bookmarks
• Confusing for users
• Easy to use the wrong one
• More documentation needed

❌ Set Up a VPN

• Complex setup
• Requires VPN client software
• Always-on VPN slows down internet
• Costs money (or significant setup time)
• Overkill for simple device access

❌ Use Reverse Proxy (Nginx, Traefik)

• Only works for HTTP/HTTPS
• Doesn't help local LAN users
• Adds complexity
• Single point of failure

❌ Just Deal With Different URLs

• Internal: nvr.local or 192.168.55.19
• External: nvr.factory.example.com:8000
• Users must remember which to use where!

The Solution: Split-Horizon DNS

Split-horizon DNS (also called split-brain DNS) solves the hairpin NAT problem by making the same URL work everywhere - it gives different answers depending on where you ask from:

• External queries (from the internet) → Public IP addresses
• Internal queries (from local network) → Private IP addresses

How Split-Horizon DNS Fixes Your Problem

Same URL, Different Destinations:

From Outside Your Network:

1. You visit: http://nvr8000.factory.example.com:8000
2. External DNS resolves to: 203.0.113.39 (public IP)
3. Port forwarding: 8000 → 192.168.55.19:80
4. ✅ Works perfectly!

From Inside Your Network:

1. You visit: http://nvr8000.factory.example.com:8000
2. Local DNS override resolves to: 192.168.55.19 (local IP!)
3. Direct local connection - no routing needed
4. ✅ Works perfectly!

Visual Example:

With Split-Horizon DNS:
┌─────────────┐
│  Your PC    │  "Connect to nvr8000.factory.example.com:8000"
│ 192.168.55.5│  LOCAL DNS says: 192.168.55.19 (not the public IP!)
└──────┬──────┘
       │ Direct connection...
       ▼
┌─────────────┐
│     NVR     │  ✅ Direct connection!
│ 192.168.55.19│    Fast, no routing needed
└─────────────┘

Why Split-Horizon DNS is Better

✅ Single URL everywhere - Same bookmark/link works at office and remotely ✅ No VPN required - Works automatically for basic access ✅ Fast local access - Direct connection to devices on your LAN ✅ No hairpin NAT needed - Bypass the router limitation entirely ✅ Reduced bandwidth - Internal traffic stays internal ✅ Free to implement - No subscription fees or additional hardware ✅ Simple configuration - Set up once per location ✅ User-friendly - Users don't need to think about network location

Who Needs This?

You need split-horizon DNS if:

• ✅ You have port forwarding set up for remote access
• ✅ It works from outside your network but fails from inside
• ✅ You want to use the same URL everywhere
• ✅ You have multiple sites (offices, warehouses, factories)
• ✅ You access NVRs, cameras, servers, or services remotely
• ✅ You don't want to set up a VPN for every user

Common scenarios:

• Security camera/NVR systems at multiple locations
• Small business with branch offices
• Home lab with remote access
• Multi-site infrastructure management
• Any device with port forwarding that needs to work locally too

Real-World Example

Without split-horizon DNS:

You @ Office → nvr.office.example.com → Internet → Router → ❌ FAILS (hairpin NAT)
You @ Home   → nvr.office.example.com → Internet → Router → ✅ Works

Problem: Same URL doesn't work everywhere!

With split-horizon DNS:

You @ Office → nvr.office.example.com → Direct local connection → ✅ Works (fast!)
You @ Home   → nvr.office.example.com → Internet → Router → ✅ Works

Solution: Same URL works everywhere, automatically!

---

⚠️ Is This Right For You?

What You'll Need (Required)

This is a semi-advanced solution that requires:

1. ✅ A Domain Name You Own

   • You must purchase and control a domain (e.g., example.com)
   • Costs: ~$10-15/year from registrars like Namecheap, GoDaddy, Cloudflare
   • OR use a subdomain if you already own one
   • Alternative: Free dynamic DNS services (DuckDNS, No-IP) work but have limitations

2. ✅ Root/SSH Access to Your Router

   • Must be able to SSH into your router as root/admin
   • Requires command-line access (not just web interface)
   • Your router must support SSH (most prosumer/enterprise routers do)

3. ✅ Command-Line Knowledge

   • Comfortable using SSH and basic Linux commands
   • Able to edit text files via command line (vi, nano)
   • Understand concepts like IP addresses, DNS, port forwarding

4. ✅ Router Compatibility

   • UDM Pro, OpenWrt, Gargoyle, or similar router with SSH access
   • Consumer routers (most TP-Link, Netgear, Asus) typically won't work

Skill Level: Intermediate

You'll be comfortable with this if you:

• ✅ Have set up port forwarding before
• ✅ Know how to SSH into a Linux server or router
• ✅ Understand what DNS is and how it works
• ✅ Can follow command-line instructions carefully

This might be too advanced if you:

• ❌ Have never used SSH or command line before
• ❌ Don't own a domain name and don't want to purchase one
• ❌ Only have a basic consumer router without SSH access
• ❌ Are uncomfortable editing configuration files

Alternative Solutions (If This Isn't For You)

If this seems too complex, consider:

Solution	Complexity	Cost	Best For
VPN (Tailscale, ZeroTier)	Easy	Free tier available	Beginners, small setups
Cloud Relay (Cloudflare Tunnel)	Medium	Free tier available	Web services only
Separate URLs	Very Easy	Free	Small setups, willing to remember 2 URLs

If you're ready to proceed and have the requirements above, continue reading!

---

🔒 Security Warning: Port Forwarding Risks

⚠️ CRITICAL: Understand the Security Implications

Split-horizon DNS itself is just a DNS configuration technique - it doesn't create security risks. However, this guide assumes you're using port forwarding to access devices remotely, which DOES expose your devices to the entire internet.

The Security Risk

When you port forward to access your NVR, cameras, or servers remotely:

What You're Doing:

Internet (Anyone in the world)
    ↓
Your Public IP:8000
    ↓
Your NVR (now accessible to everyone)

The Risks:

• 🔴 Exposed login pages - Attackers can attempt to brute-force your passwords
• 🔴 Vulnerable devices - Many NVRs/cameras have known security vulnerabilities
• 🔴 Botnet recruitment - Compromised devices can be used in DDoS attacks
• 🔴 Data theft - Attackers could access your camera feeds, recordings, data
• 🔴 Network entry point - Compromised device could be used to attack your network
• 🔴 Unencrypted traffic - HTTP connections can be intercepted

🛡️ More Secure Alternative: Use a VPN Instead

The MOST SECURE approach is to NOT use port forwarding at all:

VPN Approach (Recommended for Security):

You → VPN → Appears on local network → Direct access to devices

Why VPN is more secure:

• ✅ No ports exposed to internet
• ✅ Encrypted tunnel
• ✅ Authentication required before any access
• ✅ No direct device exposure
• ✅ Can access ALL devices, not just specific ports

VPN Options:

• Tailscale (easiest) - Free for personal use, works with UDM Pro
• WireGuard (fast) - Free, built into many routers
• OpenVPN - Free, widely supported
• Built-in VPN - UDM Pro has built-in VPN server

If You Still Choose Port Forwarding

If VPN isn't feasible for your use case, implement these security measures:

1. Use Strong Authentication

• ❌ NEVER use default passwords (admin/admin, admin/12345, etc.)
• ✅ Use complex passwords: 16+ characters, mix of letters/numbers/symbols
• ✅ Enable two-factor authentication (2FA) if available
• ✅ Disable or rename default admin accounts

2. Use HTTPS Only

• ❌ Don't use HTTP (unencrypted)
• ✅ Use HTTPS with valid SSL/TLS certificates
• ✅ Consider Let's Encrypt for free certificates
• ✅ Force HTTPS redirects

3. Limit Access

• ✅ Use firewall rules to restrict access by IP address/country
• ✅ Only allow access from known IPs if possible
• ✅ Block countries you don't need access from
• ✅ Use non-standard ports (not 8000, 8080, etc.) - helps avoid automated scans

4. Network Segmentation

• ✅ Put cameras/NVRs on isolated VLAN
• ✅ Prevent compromised devices from accessing main network
• ✅ Firewall rules between VLANs

5. Keep Firmware Updated

• ✅ Regularly update device firmware
• ✅ Subscribe to security advisories for your devices
• ✅ Replace devices that no longer receive updates

6. Monitor Access Logs

• ✅ Regularly review login attempts
• ✅ Set up alerts for failed login attempts
• ✅ Use fail2ban or similar to block brute-force attacks

7. Consider Additional Security Layers

• ✅ Cloudflare Tunnel - Protects web-based services
• ✅ Reverse Proxy - Add authentication layer (Authelia, etc.)
• ✅ Port Knocking - Hide ports until specific sequence

Risk Assessment Table

Approach	Security Level	Convenience	Complexity
VPN Only	🟢 Very High	Medium	Medium
Cloudflare Tunnel	🟢 High	High	Medium
Port Forward + Security Best Practices	🟡 Medium	High	Low-Medium
Port Forward + Weak Passwords	🔴 Very Low	High	Low
Port Forward + Default Credentials	🔴 Critical Risk	High	Low

💡 Our Recommendation

For home users:

1. Best: Set up VPN (Tailscale is easiest) - use split-horizon DNS internally only
2. Good: Port forwarding with ALL security best practices above
3. Acceptable: Port forwarding for non-sensitive devices only (not cameras in private areas)

For businesses:

1. Required: VPN or zero-trust solution (Cloudflare Access, etc.)
2. Minimum: Port forwarding only with corporate security policies enforced

The Bottom Line

Split-horizon DNS is a useful DNS technique, but:

• ✅ Use it WITH a VPN for maximum security
• ⚠️ Use it WITH port forwarding only if you implement security best practices
• ❌ NEVER expose devices with default passwords or unencrypted HTTP

Remember: Every open port is a potential entry point for attackers. The question isn't "if" but "when" automated scanners will find your exposed ports.

---

Supported Hardware

This guide supports:

• ✅ Ubiquiti UniFi Dream Machine Pro (UDM Pro) - Firmware 4.x+
• ✅ OpenWrt - 21.x, 22.x, 23.x
• ✅ Gargoyle - 1.13.x, 1.14.x, 1.15.x (OpenWrt-based)

---

Quick Start

Prerequisites

• Control of your external DNS (registrar or DNS provider)
• SSH access to your router
• Basic command-line knowledge
• Static or DHCP-reserved IPs for your devices

Overview of Steps

1. Configure external DNS - A records pointing to public IPs
2. Configure internal DNS - Local overrides on each router
3. Make configuration persistent - Survives reboots and firmware updates
4. Test and verify - Ensure it works locally and remotely

Choose Your Router

Select the guide for your hardware:

📘 UDM Pro Setup Guide - For Ubiquiti Dream Machine Pro 📗 OpenWrt/Gargoyle Setup Guide - For OpenWrt and Gargoyle routers

Important best practice:

💡 Port-in-Name Convention Guide - Recommended! Include the port number in your domain name (e.g., nvr8000.factory.example.com means external port 8000). This makes your configuration self-documenting and prevents mistakes.

---

Example Use Cases

Home Lab

Access your home servers, NAS, and services using clean domain names both at home and remotely.

Example:

• nas443.home.example.com → 192.168.1.100 (local) / 203.0.113.50:443 (external)
• plex32400.home.example.com → 192.168.1.101 (local) / 203.0.113.50:32400 (external)

Note: Port numbers in domain names (like 443, 32400) indicate the external port for remote access. See Port-in-Name Convention.

Small Business Multi-Site

Consistent URLs across office locations for cameras, servers, and infrastructure.

Example:

• nvr8000.factory.example.com → 192.168.55.19 (local) / 203.0.113.39:8000 (external)
• nvr8001.factory.example.com → 192.168.55.124 (local) / 203.0.113.39:8001 (external)
• alarm8002.factory.example.com → 192.168.55.95 (local) / 203.0.113.39:8002 (external)

Security Systems

Centralized access to NVRs, cameras, and alarm systems across multiple locations - perfect use case for port-in-name convention!

Example (Factory Setup):

• nvr8000.factory.example.com → External port 8000, Local IP 192.168.55.19
• nvr8001.factory.example.com → External port 8001, Local IP 192.168.55.124
• alarm8002.factory.example.com → External port 8002, Local IP 192.168.55.95

Benefits: Domain name tells you exactly which port to use remotely - no documentation needed!

---

Naming Best Practices

Include External Port in Domain Name

Recommended approach:

nvr8000.office.example.com  → Use port 8000 externally
nvr8001.office.example.com  → Use port 8001 externally
server443.office.example.com → Use port 443 externally

Why this is better:

• ✅ Self-documenting - no need to look up which port to use
• ✅ Clear and consistent
• ✅ Prevents configuration errors
• ✅ Easy to remember

Avoid:

nvr1.office.example.com  → Which port? Need to look it up!
nvr2.office.example.com  → Is this 8000? 8001? 8080?

How it works:

• Locally: Domain resolves directly to device, no port needed
• Externally: Domain name tells you which port to use

---

How It Works

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    External DNS Provider                     │
│  (GoDaddy, Cloudflare, Route53, etc.)                       │
│                                                              │
│  nvr.office.example.com  →  203.0.113.10 (Public IP)        │
└─────────────────────────────────────────────────────────────┘
                              ▲
                              │
                   External Query (from internet)
                              │
┌─────────────────────────────┴─────────────────────────────┐
│                    Your Office Router                      │
│  (UDM Pro / OpenWrt / Gargoyle)                           │
│                                                            │
│  Internal DNS Override (dnsmasq):                         │
│  nvr.office.example.com  →  192.168.1.100 (Local IP)      │
└─────────────────────────────┬──────────────────────────────┘
                              │
                   Internal Query (from LAN)
                              │
                              ▼
                    ┌──────────────────┐
                    │   NVR Device     │
                    │  192.168.1.100   │
                    └──────────────────┘

DNS Query Flow

Internal user on LAN:

1. Client queries: nvr.office.example.com
2. Router's dnsmasq intercepts
3. Local override returns: 192.168.1.100
4. Client connects directly to device on LAN ✅

External user on internet:

1. Client queries: nvr.office.example.com
2. External DNS provider responds: 203.0.113.10
3. Client connects through internet to public IP ✅

---

Features

UDM Pro Implementation

• ✅ Persistent across firmware updates - Uses on-boot-script
• ✅ Automatic restart - dnsmasq auto-restarts after config change
• ✅ Clean integration - Doesn't interfere with UniFi settings
• ✅ Easy to maintain - Simple script in /data partition

OpenWrt/Gargoyle Implementation

• ✅ Persistent across reboots - Uses /etc/rc.local
• ✅ Simple configuration - Just edit dnsmasq.conf
• ✅ Easy to restore - Quick SSH command to re-apply
• ⚠️ May need reapplication after major firmware updates

---

Documentation Structure

split-horizon-dns/
├── README.md (this file)
│
├── docs/
│   ├── udm-pro-guide.md         # Complete UDM Pro setup
│   ├── openwrt-gargoyle-guide.md # Complete OpenWrt/Gargoyle setup
│   ├── troubleshooting.md        # Common issues and fixes
│   └── examples.md               # Real-world examples
│
└── scripts/
    ├── udm-pro/
    │   └── 10-custom-dns.sh      # Template boot script
    └── openwrt/
        └── rc.local-snippet.sh   # Template rc.local addition

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Ways to contribute:

• Report issues or bugs
• Improve documentation
• Add examples for different use cases
• Test on different firmware versions
• Share your success stories

---

Tested Configurations

This guide has been tested on:

Hardware	Firmware Version	Status
UDM Pro	4.4.6	✅ Working
Gargoyle	1.15.x	✅ Working
OpenWrt	23.05.x	✅ Working
OpenWrt	22.03.x	✅ Working

Have you tested on other configurations? Please open an issue to let us know!

---

Troubleshooting

Common issues? Check the Troubleshooting Guide.

Quick links:

• DNS not resolving locally
• Configuration lost after update
• External DNS not propagating

---

Alternative Solutions

Why not just use a VPN?

VPN Approach:

• ❌ More complex setup
• ❌ Always-on VPN client required
• ❌ Performance overhead
• ❌ Can interfere with local networking

Split-Horizon DNS:

• ✅ No client configuration needed
• ✅ Works automatically
• ✅ Zero performance impact
• ✅ Simple and elegant

Why not use Pi-hole or AdGuard Home?

You can! These solutions work great with split-horizon DNS. In fact, you can run Pi-hole/AdGuard and implement split-horizon DNS in them instead of on the router.

This guide focuses on router-level implementation for:

• Simpler architecture (no additional hardware/containers)
• Works even if Pi-hole/AdGuard fails
• Good for those who don't run separate DNS servers

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• unifios-utilities - For the excellent on-boot-script for UDM Pro
• OpenWrt community - For the robust dnsmasq implementation
• Gargoyle project - For the user-friendly OpenWrt fork

---

Support

• 🐛 Found a bug? Open an issue
• 💡 Have a suggestion? Start a discussion
• ⭐ Find this useful? Give it a star!

---

Changelog

v1.0.0 (2025-12-13)

• Initial release
• UDM Pro guide
• OpenWrt/Gargoyle guide
• Troubleshooting documentation
• Example scripts

---

Ready to get started? Choose your guide:

📘 UDM Pro Setup Guide →
📗 OpenWrt/Gargoyle Setup Guide →