Custom DNS entries (via DNSMasq) + HTTPS with PiHole on Docker

On my home network, I have a very organized set of hostnames for all the servers/computers/devices in my “lab”. With my current Netgear R7000 router, I organize these in DD-WRT using DNSMasq. As I’m preparing to take the plunge from DD-WRT to a Ubiquiti UniFi setup, one of the necessary steps was an alternative DNS server that I could integrate with the UniFi Security Gateway (USG). I decided to give PiHole a try, hoping that it offered an easy way to add custom entries — but alas, none exists as of yet. Rather than bind a list to the hosts file in my Docker container (which some have done), I decided to add to the DNSMasq config because I like the extra configurability. For those looking to accomplish something similar, this is how I did it:

Step 1: Configuring HTTPS

If you haven’t already generated certificates, go ahead and do that now. Don’t even have a certificate authority yet? There are a ton of fantastic resources that can help you get started.

Assuming you have your certificates already, your external.conf config will look something like this:

Save this wherever you want to keep it — we’ll direct Docker to it in step #3. You will need to adjust line 1 (hostname and IP), as well as lines 8 and 9 (path to your certificates). If you want more information, take a look at this post by one of the developers on the PiHole website.

Step 2: Adding DNSMasq Entries

Our additional DNSMasq file can be named whatever you like, and saved wherever you like. My file looks something like this:


…and so on. Just follow that format, and the sky is the limit. The first line isn’t necessary — but if you have a Plex server in your home, take a look at the “DNS Rebinding” section of this for more info as to why I’ve added it.

Step 3: Configuring PiHole on Docker

With somewhere on the order of 3M pulls, diginc’s PiHole Docker image seems to be the most popular. My install is a little different from the recommended config, and I placed it all in a bash script for easy access:

Explanations for those who want them:

  • --net=host
    This allows the container to expose all necessary ports. If you want to use it as a DHCP server, I believe this mode is necessary.
  • -v "/home/pi/pihole/external.conf:/etc/lighttpd/external.conf"
    The path to our extra configuration file for enabling HTTPS.
  • -v "/home/pi/pihole/root.pem:/home/root.pem"
    Path to the CA certificate for HTTPS. Must line up with our external.conf
  • -v "/home/pi/pihole/cert_comb.pem:/home/cert_comb.pem"
    Path to the combined host certificate/key for HTTPS. Also must line up with our external.conf
  • -v "/home/pi/pihole/dnsmasq.conf:/etc/dnsmasq.d/00-additional.conf"
    Path to where I wanted to save my custom DNSMasq entries.
  • -e ServerIP=""
    Your PiHole server’s IP address here.
  • diginc/pi-hole-multiarch:debian_armhf
    The image to pull. If on x86, use diginc/pi-hole:latest

Remember, the order for -v is host:container

And that’s it! Give your Docker/PiHole server a nice looking hostname and enjoy the green locks for days :)

Show Comments