Lyubomir Georgiev x Zippi

OPNsense Migration Guide: Legacy ISC DHCPv4 > Dnsmasq DHCP + Unbound DNS

·

,
batezippi Avatar
batezippi

Repeatable Migration Guide: Legacy ISC DHCPv4 → Dnsmasq DHCP + Unbound DNS (with DNS over TLS, Reverse DNS, and Optional Active Directory Support) OPNsense 26.1

Prerequisites

  • OPNsense 26.1 or newer.
  • Full configuration backup (System > Configuration > Backups).
  • Documented ISC DHCP settings (ranges, static mappings, domain, lease time).
  • Your LAN subnet: 192.168.1.0/24 (based on your PTR zone).
  • Local domain (example: home.lan).
  • For AD environments: Note your Active Directory domain name (e.g., corp.local or ad.example.com) and the IP address(es) of your domain controller(s) that run DNS.

Step 1: Export Static Mappings from ISC DHCPv4

  1. Go to Services > ISC DHCPv4.
  2. Export static mappings.
  3. Save the file.

Step 2: Configure Dnsmasq DNS & DHCP

General Tab

  • Enable: Leave unchecked for now.
  • Interface(s): Select LAN and any other internal interfaces.
  • Listen port (DNS): 53053
  • Do not forward to system defined DNS: Checked
  • DHCP fqdn: Enabled
  • Save.

DHCP Ranges Tab

  • Interface: LAN
  • Range: e.g., 192.168.1.100 – 192.168.1.200
  • Gateway: OPNsense LAN IP
  • DNS servers: Leave blank
  • Lease time: 86400 (or preferred)
  • Domain: home.lan
  • Save.

Hosts Tab (Static Mappings)

  • Import or add entries with MAC, IP, Hostname, and Domain set to home.lan.

Step 3: System Domain Setting

  1. Go to System > Settings > General.
  2. Set Domain to home.lan.
  3. Save.

Step 4: Configure Unbound

Unbound General Tab

  • Services > Unbound DNS > General
  • Enabled: Yes
  • Enable DNSSEC Support: Unchecked
  • Save.

Query Forwarding Tab (Add the following entries)

Forward 1 – Local Domain (A records from Dnsmasq)

  • Domain: .home.lan (leading dot)
  • Server IP: 127.0.0.1
  • Server Port: 53053
  • Save

Forward 2 – Reverse DNS (PTR records)

  • Domain: 1.168.192.in-addr.arpa
  • Server IP: 127.0.0.1
  • Server Port: 53053
  • Save

Optional Step – Active Directory Domain Forwarding (Only perform this if you have an on-premises Active Directory)

Add one or more entries for your AD domain:

  • Domain: .corp.local (or your exact AD domain name, with leading dot)
  • Server IP: IP address of your primary Domain Controller (e.g., 192.168.1.10)
  • Server Port: 53 (standard DNS port)
  • Save

If you have multiple domain controllers for redundancy, add additional forwarding rules for each DC IP.

Important Notes for AD Forwarding:

  • This forwards all queries for the AD domain directly to your domain controllers.
  • Do not forward the AD domain to Dnsmasq (53053) unless your DCs are not handling DNS.
  • If your AD domain is the same as your local home.lan, decide which service is authoritative and forward accordingly.
  • For reverse zones used by AD (e.g., additional in-addr.arpa zones), you may need extra forwarding rules pointing to the DC.

DNS over TLS Tab (Quad9)

Add the four Quad9 entries:

  • 9.9.9.9, 149.112.112.112, 2620:fe::fe, 2620:fe::9 — all on port 853 with Verify CN dns.quad9.net

Save and apply all Unbound changes.

Step 5: Disable ISC DHCPv4 and Enable Dnsmasq

  1. Disable ISC DHCPv4 completely and apply.
  2. Enable Dnsmasq in the General tab and apply.

Step 6: Force DNS through Unbound (Prevent Leaks)

  • Create the Destination NAT rule for port 53 redirect to 127.0.0.1:53 (as previously described).
  • Add the optional Block rule for outbound DNS port 53 on LAN.

Step 7: Final Verification

  1. Restart Unbound.
  2. Test from a client:
    • nslookup mydevice.home.lan → Should resolve via Dnsmasq.
    • nslookup 192.168.1.50 → Should return hostname (PTR).
    • nslookup dc1.corp.local (or any AD resource) → Should resolve via your Domain Controller.
    • nslookup google.com → Should use Quad9 over TLS.
  3. Visit https://on.quad9.net/ to confirm DoT.

Additional Recommendations for Active Directory Environments

  • Ensure your Domain Controllers receive the correct DNS settings via DHCP or static configuration (usually point to themselves or other DCs).
  • If you experience issues with Kerberos, Group Policy, or SRV records, verify that the AD domain forwarding rule is correctly prioritized in Unbound.
  • Consider adding domain-insecure: “corp.local” via a custom Unbound configuration file if you encounter validation problems (advanced).

Other Posts