Pi-hole

Adam Monsen

Want your very own Pi-hole? Here you go.

I didn't actually include a Pi-hole service with mario because it is more complex than the others, requiring some unrelated and harder-to-explain changes to the server itself and the LAN router. I didn't want to add that complexity to the book--I favored a concise and well-tested set of starter services.

With this commit you can add a Pi-hole service to your server, per chapter 10 section 4 of the book. You can check out that branch in your mario clone to try it out.

Documentation from the commit log message:

This is an example of extending mario with an additional service as mentioned in chapter 10, section 4, Pi-hole.

Before provisioning, you must add additional variables in mario/ansible/config not mentioned in the book.
Here they are, with some hints on the values you should use:

PIHOLE_WEB_PASSWORD ... something secure
LAN_DNS_SERVER_IP ... IP address of the DNS server upstream of your Pi-hole
MARIO_SERVER_IP ... IP address assigned to your server's network device
ETH_DEV_NAME ... name of your server's network device

For PIHOLE_WEB_PASSWORD, maybe just use a long string of random letters and numbers. Beware characters that must be escaped in YAML (I'm not sure if they will be properly escaped by Ansible/jinja2).

LAN_DNS_SERVER_IP is intended to point to something on your LAN that can answer any DNS query. If your Pi-hole doesn't know/own a particular DNS name-to-address mapping (as will likely be the case for most lookups), it will do a query against the DNS server at this IP address (after we configure that in the Pi-hole web UI, below).

You should be able to find MARIO_SERVER_IP by running hostname -I on your server.

You should be able to find ETH_DEV_NAME by running ls -d /sys/class/net/en* on your server. If that output shows multiple names, try ip addr show dev DEVICENAME for each: the one that is UP and has a valid IP address for your LAN is the one to use for ETH_DEV_NAME.

Check out this branch in your shb repo clone, provision your server, then start pihole on your server as you do other mario services.

Pi-hole has a nice web UI. Once it is running, try logging in to the web UI at https://pihole.example.com/admin/ using the password in PIHOLE_WEB_PASSWORD. Once you do, browse to https://pihole.example.com/admin/settings.php?tab=dns and add an upstream DNS server (use the same IP address you entered in LAN_DNS_SERVER_IP).

There's still the step of telling LAN clients to use Pi-hole for DNS lookups. This is out of scope for these instructions but not all that difficult: it is generally done in the router's DHCP config (force use of DNS server at MARIO_SERVER_IP), or by manually setting the mario server as the DNS server for each LAN client.

Note that some clients will still bypass your Pi-hole DNS server. This may be something you can customize. For example, see https://support.mozilla.org/en-US/kb/dns-over-https

Book cover art with title text, author name, and featuring our Steadfast hero in a cartoon fantasy rolling-hills landscape on a partly cloudy day, holding up their hand in triumph with the apps they successfully self-host magically extending into the air. Our hero has brown-skin, a half-shaved head of dark hair, purple cape, teal shoulder puffs, white sleeves, blue gloves, brown shirt, tan equipment strap and belt, red upper leggings, teal lower leggings, and light brown boots.