Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Pi-Hole - Setting up Pi-hole as a recursive DNS server ======

Unbound, a secure open-source recursive DNS server, will be used to:

  * Listen only for queries from the local Pi-hole installation (on port 5335).
  * Listen for both UDP and TCP requests.
  * Verify DNSSEC signatures, discarding BOGUS domains.
  * Apply a few security and privacy tricks.


<WRAP info>
**NOTE:**  This assumes Pi-hole is already setup.
</WRAP>


----

===== Install Unbound =====


Install the recursive DNS resolver

<code bash>
sudo apt update
sudo apt install unbound
</code>

<WRAP info>
**NOTE:**  This should install the **/var/lib/unbound/root.hints** file automatically too.

The root.hints file, is a list of primary root servers.

If Unbound is **not** installed from a package manager:

  * The root.hints file may not be installed by default.
  * In this case, download the current root hints file by running: <code bash>
wget https://www.internic.net/domain/named.root -qO- | sudo tee /var/lib/unbound/root.hints
</code>
  * If you do this optional step, you will need to uncomment the **root-hints:** line in the Unbound configuration file defined in the next step.
  * This file changes infrequently, but it is recommended to have it updated every six months or so.

</WRAP>


----

===== Configure Unbound =====

<file bash /etc/unbound/unbound.conf.d/pi-hole.conf>
server:
    # If no logfile is specified, syslog is used.
    # logfile: "/var/log/unbound/unbound.log"
    verbosity: 0

    interface: 127.0.0.1
    port: 5335
    do-ip4: yes
    do-udp: yes
    do-tcp: yes

    # May be set to yes if you have IPv6 connectivity.
    do-ip6: no

    # You want to leave this to no unless you have *native* IPv6. With 6to4 and
    # Terredo tunnels your web browser should favor IPv4 for the same reasons.
    prefer-ip6: no

    # Use this only when you downloaded the list of primary root servers!
    # If you use the default dns-root-data package, unbound will find it automatically.
    #root-hints: "/var/lib/unbound/root.hints"

    # Trust glue only if it is within the server's authority
    harden-glue: yes

    # Require DNSSEC data for trust-anchored zones, if such data is absent, the zone becomes BOGUS.
    harden-dnssec-stripped: yes

    # Don't use Capitalization randomization as it known to cause DNSSEC issues sometimes.
    # see https://discourse.pi-hole.net/t/unbound-stubby-or-dnscrypt-proxy/9378 for further details.
    use-caps-for-id: no

    # Reduce EDNS reassembly buffer size.
    # Suggested by the unbound man page to reduce fragmentation reassembly problems.
    edns-buffer-size: 1472

    # Perform prefetching of close to expired message cache entries.
    # This only applies to domains that have been frequently queried.
    prefetch: yes

    # One thread should be sufficient, can be increased on beefy machines.
    # In reality for most users running on small networks or on a single machine, it should be unnecessary to seek performance enhancement by increasing num-threads above 1.
    num-threads: 1

    # Ensure kernel buffer is large enough to not lose messages in traffic spikes.
    so-rcvbuf: 1m

    # Ensure privacy of local IP ranges.
    private-address: 192.168.0.0/16
    private-address: 169.254.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8
    private-address: fd00::/8
    private-address: fe80::/10
</file>

<WRAP info>
**NOTE:**  Unbound will listen on port 5335.

If the **root-hints** file was installed separately in the previous step, then uncomment the **root-hints:** configuration line in this config file.

See [[Networking:DNS:Unbound:Logging|Logging]] about increasing logging verbosity.
</WRAP>




----

===== Restart Unbound =====

<code bash>
sudo service unbound restart
</code>

----

===== Test that Unbound can resolve =====

<code bash>
dig pi-hole.net @127.0.0.1 -p 5335
</code>

<WRAP info>
**NOTE:**  The first query may be quite slow, but subsequent queries should be faster due to caching.
</WRAP>

----

===== Test DNSSEC validation =====


<code bash>
dig sigfail.verteiltesysteme.net @127.0.0.1 -p 5335
dig sigok.verteiltesysteme.net @127.0.0.1 -p 5335
</code>

<WRAP info>
**NOTE:**

  * The first command should give a status report of SERVFAIL and no IP address.
  * The second should give NOERROR plus an IP address.

</WRAP>

----

===== Configure Pi-hole =====

Navigate to **Tools -> Settings -> DNS**.

In **Upstream DNS Servers**:

  * Untick any pre-defined servers.
  * Change the Custom 1 (IPv4) to **127.0.0.1#5335**.
  * Click **Save**.

{{:pi-hole:pi-hole_-_settings_-_dns_-_upstream_dns_servers.png?600|}}

<WRAP info>
**NOTE:**  Pi-Hole should now be passing requests via Unbound.

  * Pi-Hole is listening on port 53.
  * Unbound will be listening on port 5335.

</WRAP>

----

===== Disable resolvconf for unbound (optional) =====

The unbound package can come with a systemd service called **unbound-resolvconf.service** which is enabled by default.  It instructs resolvconf to write unbound's own DNS service at nameserver 127.0.0.1, but without the 5335 port, into the file **/etc/resolv.conf**.

That /etc/resolv.conf file is used by local services/processes to determine configured DNS servers.

If you configured /etc/dhcpcd.conf with a static domain_name_servers= line, these DNS server(s) will be ignored/overruled by this service.

----

Check if **unbound-resolvconf.service** is enabled:

<code bash>
sudo systemctl status unbound-resolvconf.service
</code>

To disable this service if so desired:

<code bash>
sudo systemctl disable unbound-resolvconf.service
sudo systemctl stop unbound-resolvconf.service
</code>

To have the domain_name_servers= in the file **/etc/dhcpcd.conf** activated/propagate:

<code bash>
sudo systemctl restart dhcpcd
</code>

And check with below one if IP(s) on the nameserver line(s) reflects the ones in the /etc/dhcpcd.conf file:

<code bash>
cat /etc/resolv.conf
</code>

----

===== References =====


https://docs.pi-hole.net/guides/dns/unbound/