Improvements on unbound's configuration loading

[LucaBarban]

I have recently setup this container on my network, and i wanted to allow DNS rebinds for my domain like already mentioned in issue #139. The proposed solution there doesn't quite work, given that Unbound is configured to load specifically the pi-hole.conf file.

docker-pihole-unbound/docker/custom-entrypoint.sh

Line 9 in a1636aa

/usr/sbin/unbound -d -c /etc/unbound/unbound.conf.d/pi-hole.conf &

This will override the default's Unbound configuration found at /etc/unbound/unbound.conf, especially preventing the line that loads the files under the unbound.conf.d folder from being read (specifically the last one include-toplevel: "/etc/unbound/unbound.conf.d/*.conf").
This means that, in order to allow rebinds for a specific domain, we have to overwrite the pi-hole.conf file completely.

To solve the problem, i adopted the following (lazy) solution:

• Copy over the original configuration in a new file and append the following line:

    private-domain: "your.domain"

• Add the following volume mount to your existing mounts to include the newly created file in the container:

      - <path/to/the/custom/conf/file.conf>:/etc/unbound/unbound.conf.d/pi-hole.conf

If this doesn't work you could try to disable on the PiHole's web UI the setting Never forward reverse lookups for private IP ranges. You can find it under Settings > DNS > Advanced DNS settings after enabling the "Expert" mode by clicking the top right green switch.
In the eventuality that even this doesn't work, you could try mounting a .conf file in the /etc/dnsmasq.d container's path with the following content:

rebind-domain-ok=/your.domain/

[laest]

I came across the same issue and would like to suggest a small change to handle such issues more clean in the future without manipulating the main pi-hole.conf.

In order to do so we will need to update the unbound-pihole.conf. First I would suggest to update the file according to the latest version from the official documentation since we are already changeing the file. In addition to that, we include the following line at the end of the file: include-toplevel: "/etc/unbound/unbound.conf.d/*.conf".

# Config pulled from https://docs.pi-hole.net/guides/unbound/

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 no if you don't have IPv6 connectivity
    do-ip6: yes

    # 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.
    # IP fragmentation is unreliable on the Internet today, and can cause
    # transmission failures when large DNS messages are sent via UDP. Even
    # when fragmentation does work, it may not be secure; it is theoretically
    # possible to spoof parts of a fragmented DNS message, without easy
    # detection at the receiving end. Recently, there was an excellent study
    # >>> Defragmenting DNS - Determining the optimal maximum UDP response size for DNS <<<
    # by Axel Koolhaas, and Tjeerd Slokker (https://indico.dns-oarc.net/event/36/contributions/776/)
    # in collaboration with NLnet Labs explored DNS using real world data from the
    # the RIPE Atlas probes and the researchers suggested different values for
    # IPv4 and IPv6 and in different scenarios. They advise that servers should
    # be configured to limit DNS messages sent over UDP to a size that will not
    # trigger fragmentation on typical network links. DNS servers can switch
    # from UDP to TCP when a DNS response is too big to fit in this limited
    # buffer size. This value has also been suggested in DNS Flag Day 2020.
    edns-buffer-size: 1232

    # 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

    # Ensure no reverse queries to non-public IP ranges (RFC6303 4.2)
    private-address: 192.0.2.0/24
    private-address: 198.51.100.0/24
    private-address: 203.0.113.0/24
    private-address: 255.255.255.255/32
    private-address: 2001:db8::/32

include-toplevel: "/etc/unbound/unbound.conf.d/*.conf"

To make this work properly we also change the Dockerfile and move the pi-hole.conf file from /etc/unbound/unbound.conf.d/pi-hole.conf to /etc/unbound/pi-hole.conf. So we change line 5 of the Dockerfile

FROM: COPY unbound-pihole.conf /etc/unbound/pi-hole.conf
TO: COPY unbound-pihole.conf /etc/unbound/pi-hole.conf

FROM pihole/pihole:2025.08.0

...

COPY unbound-pihole.conf /etc/unbound/pi-hole.conf

...

ENTRYPOINT ["/custom-entrypoint.sh"]

To reflect this change at the startup of unbound we need to change the entrypoint script in line 9 to use the new location of pi-hole.conf.

#!/bin/sh

...

echo "  [i] Starting Unbound"
/usr/sbin/unbound -d -c /etc/unbound/pi-hole.conf &
UNBOUND_PID=$!

...

exec /usr/bin/start.sh

@mpgirro I tested this locally but I do not seem to have permission to create a new branch and open a pull request. It would be gread if we could update this pi-hole.conf to the latest version as well as to implement the suggested configuration change to be able to add custom configuration of unbound without having to change the main pi-hole.conf.

[LucaBarban]

@laest I would close my issue, even if I didn't cover the changes you proposed changes. The thing is that it they could break the current setups that people have if they have something like watchtower updating their stacks, so I think it would be better discussed in a dedicated one.

Also, you should be able clone the repo and open pull requests on your branches, I didn't have any special permissions when I did so with mine.