This post covers how to add DNS entries / mappings to a local network managed with pihole.

There are several ways to do so:

1. The CLI way: /etc/pihole/

Edit /etc/pihole/custom.list, set one mapping per line, just as you would for /etc/hosts:

$ cat /etc/pihole/custom.list

This works because /etc/dnsmasq.d/01-pihole.conf contains addn-hosts=/etc/pihole/custom.list by default.

From Gentoo Wiki:

It is possible to refer to an (additional) hosts file to use as source for DNS queries. To do so, add the -H /path/to/hostsfile (–addn-hosts=/path/to/hostsfile) command line option. It is also possible to pass a directory; in that case, all files inside that directory will be treated as additional hosts files.

2. The CLI way: /etc/dnsmasq.d/

$ cat /etc/dnsmasq.d/03-pihole-custom-dns.conf

From ArchWiki:

In some cases, such as when operating a captive portal, it can be useful to resolve specific domains names to a hard-coded set of addresses. This is done with the address config.

3. The Web way

Navigate to http://pi.hole/admin/dns_records.php and set your DNS records there. From pihole docs:

The order of locally defined DNS records is:

  1. The device’s host name (/etc/hostname) and pi.hole
  2. Configured in a config file in /etc/dnsmasq.d/
  3. Read from /etc/hosts
  4. Read from the “Local (custom) DNS” list (stored in /etc/pihole/custom.list) (the aforementioned ways)

Only the first record will trigger an address-to-name association.

Wrapping up

Then restart pihole to apply changes:

$ pihole restartdns