Setup local domain name with Opnsense

Updated: at 12:36 PM

I want to set up a domain name for my homelab so that I can access my virtual machines/containers using hostname instead of remembering IP address. For example, postgresql.my-awesome-domain.com instead of 192.168.1.xxx. I already have my router running OPNSense, so the setup process is simpler.

OPNSense uses Unbound DNS as its default DNS resolver. However, since Unbound in OPNSense does not allow creating new DNS zones, we’ll need to use BIND alongside it to achieve our goal.

Do the following:

  1. Install BIND plugin

  2. Configure BIND (under Services -> BIND -> Configuration and select the General tab) listening on 127.0.0.1 for IPv4 and ::1 for IPv6. Since port 53 is used by Unbound, choose a non-privileged port (above 1024) - in this example, we’ll use 53530.

  3. Configure BIND ACL to prevent DNS poisoning by restricting access to localhost only. Add an entry under ACLs with the name BIND-LOCALHOST (you can choose any name that suits your needs) and the Network list is 127.0.0.1 and ::1 for IPv4 and IPv6 respectively.

  4. Create a new zone called my-awesome-domain.com with the following entries:

    • my-awesome-domain.com. 86400 IN NS ns.my-awesome-domain.com.
    • ns.my-awesome-domain.com. 86400 IN A <your-opnsense-lan-ip>
    • myhost1.my-awesome-domain.com. 3600 IN A <some-ip-in-your-subnet>

    Note: The TTL values (86400 for NS records, 3600 for host records) can be adjusted based on how frequently you update these records.

  5. Add a new Query Forwarding under Unbound DNS service (Services -> Unbound DNS -> Query Forwarding) with the following details:

    • Domain: my-awesome-domain.com
    • Server: 127.0.0.1
    • Server port: 53530
    • Description: Local BIND forwarding

  6. Restart Unbound DNS

  7. You need to configure your laptops/other machines in your network to use OPNSense Unbound DNS as your DNS server.

Pro tip: Configure OPNSense ISC DHCPv4 to set the DNS server to OPNSense IP address for automatic DNS configuration across your network.

Now test if the setup is working as expected. On macOS:

  1. Flush your DNS cache:

    sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

  2. Test the DNS resolution using either dig or nslookup:

    # Using dig
dig @your-opnsense-ip myhost1.my-awesome-domain.com

# Using nslookup
nslookup myhost1.my-awesome-domain.com your-opnsense-ip

You should see the IP address return in the command output. If resolution fails, check the following:

  1. Verify BIND and Unbound services are running in OPNSense (Services -> BIND -> General and Services -> Unbound DNS)
  2. Check BIND logs in OPNSense (System -> Log Files -> BIND)
  3. Ensure your client is using OPNSense as its DNS server (run scutil --dns on macOS to verify)