Setuping PI-Hole FTL DNS on a local network

pihole comes with it's own lightweight DNS server called FTL. It's geared towards easy of use. Even so, setting up this feature can be hard. Here are some lessons I've learned.

In this example:

Your network is setup on 192.168.1.0/24
192.168.1.1 is your DHCP server and IP gateway. (usually your router)
192.168.1.254 is the host running pi-hole
192.168.1.2 is a host running Apache.

The goal is to let the acme.lan resolve to 192.168.1.2. When you surf to http://acme.lan you'd see the default Apache welcome page.

Step 1: configure your DHCP server

You'll probably need to log in on your router. Look for the DHCP server settings. The Primary DNS should read 192.168.1.254. Save the settings

This will route all DNS traffic to the pi-hole. As per the installation instructions:

https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245

Step 2: ensure the pi-hole gets a static ip from the DHCP server

In the same settings in your router. You should see something like "address reservation". Add an entry for 192.168.1.254. You will also need the MAC adress of the pi-hole. SSH into the pi-hole and run the ifconfig or ip link command to list the MAC address.

This will ensure that your pi-hole will always keep the same IP address.

Repeat this step for the host running Apache with IP address 192.168.1.2.

Step 3: Add local DNS entries in the pi-hole settings

Go to http://192.168.1.254/admin/. This is the dashboard of your pi-hole. Log into the dashboard. Click the Local DNS > DNS Records tab open. This is where you manage your local DNS records.

Add a new record for acme.lan associated with 192.168.1.2. Save the settings.

Step 4: Test if everything works

When you open up your browser and surf to http://acme.lan, you should see the Apache Welcome page.

Easy, right?

Troubleshooting

The road can be a bit more bumpy then that. At least, my journey was.

That is, you surf to http://acme.lan and all you get is a server not found error in your browser.

Here's a few issues I ran into:

Problem 1: Pi-hole FLT server crashes in the background

You navigate to http://192.168.1.254/admin and you get the pi-hole dashboard. Nothing seems out of the ordinary. However, the DNS server isn't running as an active background daemon. Here's how to troubleshoot:

Running pihole status should yield:

  [✓] DNS service is listening
     [✓] UDP (IPv4)
     [✓] TCP (IPv4)
     [✓] UDP (IPv6)
     [✓] TCP (IPv6)

  [✓] Pi-hole blocking is enabled

However, I got a [✗] DNS service is NOT listening

Start/Restart the server using this command: sudo systemctl restart pihole-FTL

So, why did it crash? Checking the log with cat /var/log/pihole-FTL.log, this is what I get:

[2020-12-22 14:49:50.301 14502/T14507] !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
[2020-12-22 14:49:50.301 14502/T14507] ---------------------------->  FTL crashed!  <----------------------------
[2020-12-22 14:49:50.301 14502/T14507] !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
[2020-12-22 14:49:50.302 14502/T14507] Please report a bug at https://github.com/pi-hole/FTL/issues
[2020-12-22 14:49:50.302 14502/T14507] and include in your report already the following details:
[2020-12-22 14:49:50.302 14502/T14507] FTL has been running for 121 seconds
[2020-12-22 14:49:50.303 14502/T14507] FTL branch: master
[2020-12-22 14:49:50.303 14502/T14507] FTL version: v5.3.2
[2020-12-22 14:49:50.303 14502/T14507] FTL commit: 0790cf7
[2020-12-22 14:49:50.304 14502/T14507] FTL date: 2020-12-02 21:28:39 +0000
[2020-12-22 14:49:50.304 14502/T14507] FTL user: started as pihole, ended as pihole
[2020-12-22 14:49:50.304 14502/T14507] Compiled for armv6hf (compiled on CI) using arm-linux-gnueabihf-gcc (crosstool-NG crosstool-ng-1.22.0-88-g8460611) 4.9.3
[2020-12-22 14:49:50.305 14502/T14507] Process details: MID: 14502
[2020-12-22 14:49:50.305 14502/T14507]                  PID: 14502
[2020-12-22 14:49:50.305 14502/T14507]                  TID: 14507
[2020-12-22 14:49:50.305 14502/T14507]                  Name: database
[2020-12-22 14:49:50.306 14502/T14507] Received signal: Segmentation fault
[2020-12-22 14:49:50.306 14502/T14507]      at address: 0x4
[2020-12-22 14:49:50.306 14502/T14507]      with code:  SEGV_MAPERR (Address not mapped to object)
[2020-12-22 14:49:50.317 14502/T14507] Backtrace:
[2020-12-22 14:49:50.320 14502/T14507] B[0000]: /usr/bin/pihole-FTL(+0x4acc8) [0x4a1cc8]
[2020-12-22 14:49:50.509 14502/T14507] L[0000]: /root/project/src/signals.c:194
[2020-12-22 14:49:50.519 14502/T14507] B[0001]: /lib/arm-linux-gnueabihf/libc.so.6(__default_rt_sa_restorer+0) [0xb6d17130]
[2020-12-22 14:49:50.520 14502/T14507] B[0002]: /usr/bin/pihole-FTL(+0x12d8d0) [0x5848d0]
[2020-12-22 14:49:51.351 14502/T14507] L[0002]: /root/project/src/database/sqlite3.c:160127
[2020-12-22 14:49:51.420 14502/T14507] B[0003]: /usr/bin/pihole-FTL(+0x12e170) [0x585170]
[2020-12-22 14:49:52.214 14502/T14507] L[0003]: /root/project/src/database/sqlite3.c:160231
[2020-12-22 14:49:52.282 14502/T14507] B[0004]: /usr/bin/pihole-FTL(piholeFTLDB_reopen+0x44) [0x4a8ab0]
[2020-12-22 14:49:52.394 14502/T14507] L[0004]: /root/project/src/database/common.c:52
[2020-12-22 14:49:52.405 14502/T14507] B[0005]: /usr/bin/pihole-FTL(FTL_reload_all_domainlists+0x34) [0x4919d4]
[2020-12-22 14:49:52.508 14502/T14507] L[0005]: /root/project/src/datastructure.c:474
[2020-12-22 14:49:52.517 14502/T14507] B[0006]: /usr/bin/pihole-FTL(DB_thread+0x1e0) [0x4aae5c]
[2020-12-22 14:49:52.625 14502/T14507] L[0006]: /root/project/src/database/database-thread.c:81

This has been traced back to a problem with the sqlite3 library which is used to store data persistently. Try upgrading all dependencies to their latest versions. It's a known issue. pi-hole/FTL#97

Problem 2: Client isn't configured correctly

Your machine - laptop, mobile, desktop - doesn't run a DNS server. All it can do is send DNS queries to a known DNS server. Either you manually configure one in your network settings - e.g. 8.8.8.8 if you use Google DNS - or your system will use the primary DNS you've configured in you DHCP server / IP Gateway. In our case, that will be the pi-hole at 192.168.1.2.

On linux, those settings are stored in a file called /etc/resolv.conf where you'd find an entry nameserver 192.168.1.188.

However, that file might be managed by a systemd process called systemd-resolved which will automatically overwrite the file with whatever settings it gets fed elsewhere in your configuration.

Annoyingly, systemd-resolved tends to go with a stub resolv.conf file which has this weird entry: nameserver 127.0.0.53.

As a result, your DNS queries are sent to this non-existent IP address.

On Fedora, the solution is to opt out of systemd-resolved managing this file:

https://fedoraproject.org/wiki/Changes/systemd-resolved#Opting_out_of_.2Fetc.2Fresolv.conf_that_points_to_the_localhost_stub_resolver

You'll need to restart the service with sudo service systemd-resolved restart afterwards. Check if the /etc/resolv.conf file now reflects the nameservers you've configured in step 1.