14 years ago I described how to configure ISC BIND and DHCP(v6) Server on FreeBSD to get DHCP with local domain updates working on a dual stack LAN. However, ISC DHCP Server went End of Life on October 5th, 2022, replaced with their new Kea DHCP server. I also wouldn’t recommend running a non-filtering DNS resolver for your LAN any longer.

AdGuard Home

If you’re reading this blog, you’ve almost certainly heard of Pi-hole. However, I’ve found that I prefer AdGuard Home. AdGuard offers paid DNS filtering apps (I happily pay for AdGuard Pro for my iPhone), however their Home product is open source (GPL3) and free. I wont repeat the official Getting started docs, except to point out that AdGuard Home is available in FreeBSD ports so go ahead and install it with pkg install adguardhome.

There are some configuration changes we’re going to make that cannot be done in the web UI and have to be done directly in the AdGuardHome.yaml config file. I wonder cover everything in the file, just the interesting bits.

First, we’re going to be specific about which IPs to bind to, so we don’t accidentally create a public resolver, and also because there are LAN IPs on the router we don’t want to bind to (more on this in just a moment).

http:
  pprof:
    port: 6060
    enabled: false
  address: 172.16.2.1:3000
  session_ttl: 720h
...
dns:
  bind_hosts:
    - 127.0.0.1
    - ::1
    - 172.16.2.1
    - 2001:db8:ffff:aa02::1

Your choice of upstream resolver is of course personal preference, but I wanted a non-filtering upstream since I want to the control and visibility into why requests are passing/failing. I’m also Canadian, so I prefer (but don’t require) that my queries stay domestic. I’m also sending requests for my LAN domains to the authoritative DNS server, which you can see is configured on local host IP 127.0.0.53 and on the similarly numbered alias IPs on my LAN interface (hence why I had to be specific about which IPs I wanted AdGuard to bind to).

  upstream_dns:
    - '# public resolvers'
    - https://private.canadianshield.cira.ca/dns-query
    - https://unfiltered.adguard-dns.com/dns-query
    - '# local network'
    - '[/lan.example.com/]127.0.0.53 172.16.2.53 2001:db8:ffff:aa02::53'
...
  trusted_proxies:
    - 127.0.0.0/8
    - ::1/128
    - 172.16.2.1/32
...
  local_ptr_upstreams:
    - 172.16.2.53
    - 2001:db8:ffff:aa02::53

Lastly, we’re going to configure the webserver for HTTPS and DNS-over-HTTPS (DoH). I use dehydrated to manage my Let’s Encrypt certs, but any tool will do (and is outside the scope of this doc). The important thing to note is that the web UI will now run on port 8453, and will answer DoH queries.

tls:
  enabled: true
  server_name: router.lan.example.com
  force_https: true
  port_https: 8453
  port_dns_over_tls: 853
  port_dns_over_quic: 853
  port_dnscrypt: 0
  dnscrypt_config_file: ""
  allow_unencrypted_doh: false
  certificate_chain: ""
  private_key: ""
  certificate_path: /usr/local/etc/dehydrated/certs/router.lan.example.com/fullchain.pem
  private_key_path: /usr/local/etc/dehydrated/certs/router.lan.example.com/privkey.pem
  strict_sni_check: false

The rest of the configuration should be done to taste in the web UI. Personally, I find this filter list is effective while still having a very low false positive rate:

• AdGuard DNS filter
• AdAway Default Blocklist
• AdGuard DNS popup Hosts filter
• HaGeZi’s Threat Intelligence Feeds
• HaGeZi’s Pro++ Blocklist
• OISD Blocklist Big

More than that and it just becomes unwieldy.

BIND

Good old BIND. It’ll outlive us all. This part is basically unchanged I first described it in 2011, except that I’m going to have BIND listen on 127.0.0.53 and alias IPs I created on my LAN networks (also using the .53 address) by setting this in my /etc/rc.conf:

ifconfig_igb1="inet 172.16.2.1 netmask 255.255.255.0"
ifconfig_igb1_ipv6="inet6 2001:db8:ffff:aa02::1 prefixlen 64"
ifconfig_igb1_aliases="\
  inet 172.16.2.53 netmask 255.255.255.0 \
  inet6 2001:db8:ffff:aa02::53 prefixlen 64"

Next, create an rndc key with rndc-confgen -a -c /usr/local/etc/namedb/rndc.example.com and configure BIND with the following in /usr/local/etc/named/named.conf (don’t remove the logging or zones at the bottom of the default named.conf).

"acl_self" {
  127.0.0.1;
  127.0.0.53;
  172.16.2.1;
  172.16.2.53;
  ::1;
  2001:db8:ffff:aa02::1;
  2001:db8:ffff:aa02::53;
};

acl "acl_lan" {
  10.42.0.0/16;
  10.43.0.0/16;
  172.16.2.0/24;
  2001:db8:ffff:aa02::/64;
  fe80::/10;
};

options {
  directory             "/usr/local/etc/namedb/working";
  pid-file              "/var/run/named/pid";
  dump-file             "/var/dump/named_dump.db";
  statistics-file       "/var/stats/named.stats";
  allow-transfer        { acl_lan; };
  allow-notify          { "none"; };
  allow-recursion       { "none"; };
  dnssec-validation     auto;
  auth-nxdomain         no;
  recursion             no;
  listen-on             { 127.0.0.53; 172.16.2.53; };
  listen-on-v6          { 2001:db8:ffff:aa02::53; };
  disable-empty-zone "255.255.255.255.IN-ADDR.ARPA";
  disable-empty-zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA";
  disable-empty-zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA";
  version "BIND";
};

include "/usr/local/etc/namedb/rndc.example.com";

controls {
  inet 127.0.0.53 allow { "acl_self"; "acl_lan"; } keys { "rndc.example.com";};
  inet 172.16.2.53 allow { "acl_self"; "acl_lan"; } keys { "rndc.example.com";};
  inet 2001:db8:ffff:aa02::53 allow { "acl_self"; "acl_lan"; } keys { "rndc.example.com";};
};

include "/usr/local/etc/namedb/named.zones.local";

The local zones are configured in /usr/local/etc/namedb/named.zones.local:

acl zone "lan.example.com" {
  type master;
  file "../dynamic/lan.example.com";
  update-policy { grant rndc.example.com zonesub ANY; };
};

zone "2.16.172.in-addr.arpa" {
  type master;
  file "../dynamic/2.16.172.in-addr.arpa";
  update-policy { grant rndc.example.com zonesub ANY; };
};

zone "2.0.a.a.f.f.f.f.8.B.D.0.1.0.0.2.ip6.arpa" {
  type master;
  file "../dynamic/2001.0db8.ffff.aa02.ip6.arpa";
  update-policy { grant rndc.example.com zonesub ANY; };
};

Here’s a starter zone for lan.example.com:

$ORIGIN .
$TTL 1200       ; 20 minutes
lan.example.com      IN SOA  ns0.lan.example.com. admin.example.com. (
                                2020138511 ; serial
                                1200       ; refresh (20 minutes)
                                1200       ; retry (20 minutes)
                                2419200    ; expire (4 weeks)
                                3600       ; minimum (1 hour)
                                )
                        NS      ns0.lan.example.com.
                        A       172.16.2.53
                        AAAA    2001:db8:ffff:aa02::53
$ORIGIN lan.example.com.
router                  A       172.16.2.1
                        AAAA    2001:db8:ffff:aa02::1

An IPv4 reverse zone:

$ORIGIN .
$TTL 1200       ; 20 minutes
2.16.172.in-addr.arpa IN SOA ns0.lan.example.com. admin.example.com. (
                                2020051192 ; serial
                                1200       ; refresh (20 minutes)
                                1200       ; retry (20 minutes)
                                2419200    ; expire (4 weeks)
                                3600       ; minimum (1 hour)
                                )
                        NS      ns0.lan.example.com.
$ORIGIN 2.16.172.in-addr.arpa.
1                       PTR     router.lan.example.com.

And an IPv6 reverse zone:

$ORIGIN .
$TTL 1200       ; 20 minutes
2.0.a.a.f.f.f.f.8.B.D.0.1.0.0.2.ip6.arpa IN SOA ns0.lan.example.com. mikemacleod.gmail.com. (
                                2020049273 ; serial
                                1200       ; refresh (20 minutes)
                                1200       ; retry (20 minutes)
                                2419200    ; expire (4 weeks)
                                3600       ; minimum (1 hour)
                                )
                        NS      ns0.lan.example.com.
$ORIGIN 0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.a.a.f.f.f.f.8.B.D.0.1.0.0.2.ip6.arpa.
1.0                     PTR     router.lan.example.com.

Kea DHCP Server

The final piece to this is the Kea DHCP server. It’s still from ISC, but this is a from-scratch implementation of DHCP and DHCPv6 that to use modern designs and tools. We won’t be using many of the new bells and whistles, but there’s a couple things we can do now that we couldn’t with ISC DHCP.

The first thing you’ll notice is that the Kea config files are JSON, and there are four of them. First up is kea-dhcp4.conf, where we configure our IPv4 DHCP options and pool, and also the options necessary to enable dynamic updating of our LAN domain via RFC2136 DDNS updates. Note that because I had an existing zone that had been updated by ISC DHCP and other stuff, I set "ddns-conflict-resolution-mode": "no-check-with-dhcid". You can find more info here.

{
  "Dhcp4": {
    "ddns-send-updates": true,
    "ddns-conflict-resolution-mode": "no-check-with-dhcid",
    "hostname-char-set": "[^A-Za-z0-9.-]",
    "hostname-char-replacement": "x",
    "interfaces-config": {
      "interfaces": [
        "igb1/172.16.2.1"
      ]
    },
    "dhcp-ddns": {
      "enable-updates": true
    },
    "subnet4": [
      {
        "id": 1,
        "subnet": "172.16.2.0/24",
        "authoritative": true,
        "interface": "igb1",
        "ddns-qualifying-suffix": "lan.example.com",
        "pools": [
          {
            "pool": "172.16.2.129 - 172.16.2.254"
          }
        ],
        "option-data": [
          {
            "name": "routers",
            "data": "172.16.2.1"
          },
          {
            "name": "domain-name-servers",
            "data": "172.16.2.1"
          },
          {
            "name": "domain-name",
            "data": "lan.example.com"
          },
          {
            "name": "ntp-servers",
            "data": "172.16.2.1"
          }
        ],
        "reservations": [
          {

            "hw-address": "aa:bb:cc:dd:ee:ff",
            "ip-address": "172.16.2.2",
            "hostname": "foobar"
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp4",
        "output-options": [
          {
            "output": "syslog"
          }
        ],
        "severity": "INFO",
        "debuglevel": 0
      }
    ]
  }
}

The kea-dhcp6.conf file is basically identical, except IPv6 flavoured. One nice thing about Kea is you can set a DHCPv6 reservation by MAC address, which is something you could not do with ISC DHCPv6 Server.

{
  "Dhcp6": {
    "ddns-send-updates": true,
    "ddns-conflict-resolution-mode": "no-check-with-dhcid",
    "hostname-char-set": "[^A-Za-z0-9.-]",
    "hostname-char-replacement": "x",
    "dhcp-ddns": {
      "enable-updates": true
    },
    "interfaces-config": {
      "interfaces": [
        "igb1"
      ]
    },
    "subnet6": [
      {
        "id": 1,
        "subnet": "2001:db8:ffff:aa02::/64",
        "interface": "igb1",
        "rapid-commit": true,
        "ddns-qualifying-suffix": "lan.example.com",
        "pools": [
          {
            "pool": "2001:db8:ffff:aa02:ffff::/80"
          }
        ],
        "option-data": [
          {
            "name": "dns-servers",
            "data": "2001:db8:ffff:aa02::1"
          }
        ],
        "reservations": [
          {
            "hw-address": "aa:bb:cc:dd:ee:ff",
            "ip-addresses": [
              "2001:db8:ffff:aa02::2"
            ],
            "hostname": "foobar"
          }
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp6",
        "output-options": [
          {
            "output": "syslog"
          }
        ],
        "severity": "INFO",
        "debuglevel": 0
      }
    ]
  }
}

Lastly, we have kea-dhcp-ddns.conf, which configures how the zones will actuall be updated. Note that I’m connecting to BIND on 127.0.0.53.

{
  "DhcpDdns": {
    "tsig-keys": [
      {
        "name": "rndc.example.com",
        "algorithm": "hmac-sha256",
        "secret": "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"
      }
    ],
    "forward-ddns": {
      "ddns-domains": [
        {
          "name": "lan.example.com.",
          "key-name": "rndc.example.com",
          "dns-servers": [
            {
              "ip-address": "127.0.0.53",
              "port": 53
            }
          ]
        }
      ]
    },
    "reverse-ddns": {
      "ddns-domains": [
        {
          "name": "2.16.172.in-addr.arpa.",
          "key-name": "rndc.example.com",
          "dns-servers": [
            {
              "ip-address": "127.0.0.53",
              "port": 53
            }
          ]
        },
        {
          "name": "2.0.a.a.f.f.f.f.8.B.D.0.1.0.0.2.ip6.arpa.",
          "key-name": "rndc.example.com",
          "dns-servers": [
            {
              "ip-address": "127.0.0.53",
              "port": 53
            }
          ]
        }
      ]
    },
    "loggers": [
      {
        "name": "kea-dhcp-ddns",
        "output-options": [
          {
            "output": "syslog"
          }
        ],
        "severity": "INFO",
        "debuglevel": 0
      }
    ]
  }
}

Extra Credit: Mobile DNS over HTTPS (DoH)

I mentioned earlier that I pay for AdGuard Pro on my phone. Part of why I do that is it uses the MDM API in iOS to let you force your DNS to a DoH provider, including a custom one. Perhaps one you’re hosting yourself.

I’m already running an nginx reverse proxy on my router, so let’s get mobile DoH setup. This is a simplified configuration and you’ll need to ensure you’ve got HTTPS properly configured, which is (again) outside the scope of this post.

Note that I proxy the request to router.lan.example.com which will resolve to the LAN IP 172.16.2.1 rather than localhost, because we configured AdGuard Home to run it’s HTTP server on 172.16.2.1.

    server {
        listen 443 ssl;
        server_name  dns.example.com;
        location / {
            return 418;
        }
        location /dns-query {
            proxy_pass https://router.lan.example.com:8453/dns-query;
            proxy_set_header X-Real-IP  $proxy_protocol_addr;
            proxy_set_header X-Forwarded-For $proxy_protocol_addr;
        }
    }

Conclusion

That should do it. You’ve now got filtered DNS resolution for the LAN. You’ve got an authoritative LAN domain. You’ve got a modern DHCP service. And you’ve even got filtered DNS resolution when you’re out of the house.