How to install and configure Pi-hole

Install Pi-hole a network-wide ad blocking on your own Linux hardware. I have used it on Debian Stretch at first, but then moved to a small Raspberry Pi which now acts as DNS and DHCP server.

pi-hole application
pi-hole application

Install operation system

Download Raspbian Stretch Lite a minimal image based on Debian Stretch.

Unzip downloaded archive.

$ unzip 2017-09-07-raspbian-stretch-lite.zip

Write image to SD Card.

$ sudo dd if=2017-09-07-raspbian-stretch-lite.img of=/dev/mmcblk0

Connect device to the external monitor and boot it to perform initial configuration.

Log in as pi user using raspberry password.

Change default password.

$ passwd
Changing password for pi.
(current) UNIX password: raspberry
Enter new UNIX password:  ***********
Retype new UNIX password: ***********
passwd: password updated successfully

Configure static IP address.

$ cat << | sudo tee -a /etc/network/interfaces.d/eth0 
auto eth0
iface eth0 inet static
  address 192.168.1.252
  netmask 255.255.255.0
  gateway 192.168.1.1
EOF

Start and enable at boot OpenSSH service.

$ sudo systemctl start ssh
$ sudo systemctl enable ssh

Device is ready, so you can cannect it to the network.

Upgrade installed packages

Update package index.

$ sudo apt-get update

Upgrade packages.

$ sudo apt-get upgrade

Install Pi-hole

Install git and net-tools packages.

$ sudo apt-get install git net-tools

Clone pi-hole repository.

$ git clone --depth 1 https://github.com/pi-hole/pi-hole.git pi-hole

Execute installation script.

$ sudo bash pi-hole/automated\ install/basic-install.sh 

Installation process will start immidiately.

Choose DNS upstream provider.

Choose supported protocols - IPv4, IPv6 protocol or both.

Choose to install admin interface.

Choose to log queries to display graphs in web-interface.

Choose to use static IPv4 address.

Provide IPv4 address.

Provide IPv4 default gateway.

Confirm network configuration provided in the last three steps.

Installation is complete.

Change admin password using terminal.

$ pihole -a -p
Enter New Password (Blank for no password): **********
Confirm Password:                           **********
New password set

pihole utility

Use pihole utility to perform maintance tasks.

View live output of the Pi-hole log.

$ pihole -t
Press Ctrl-C to exit
Oct 21 13:41:33 dnsmasq[27682]: forwarded www.google.com to 8.8.8.8
Oct 21 13:41:33 dnsmasq[27682]: reply www.google.com is 172.217.20.196
Oct 21 13:41:36 dnsmasq[27682]: query[A] play.google.com from 192.168.1.149
Oct 21 13:41:36 dnsmasq[27682]: forwarded play.google.com to 8.8.4.4
Oct 21 13:41:36 dnsmasq[27682]: reply play.google.com is 
Oct 21 13:41:36 dnsmasq[27682]: reply play.l.google.com is 172.217.20.174
Oct 21 13:41:36 dnsmasq[27682]: query[A] play.l.google.com from 192.168.1.149
Oct 21 13:41:36 dnsmasq[27682]: cached play.l.google.com is 172.217.20.174
Oct 21 13:41:37 dnsmasq[27682]: query[A] blog.sleeplessbeastie.eu from 192.168.1.149
Oct 21 13:41:37 dnsmasq[27682]: cached blog.sleeplessbeastie.eu is 84.16.240.28
...

Reconfigure Pi-hole to change IP address or other settings defined during installation process.

$ pihole -r

List whitelisted domains.

$ pihole -w -l
Displaying gravity resistant domains:

1: raw.githubusercontent.com
2: mirror1.malwaredomains.com
3: sysctl.org
4: zeustracker.abuse.ch
5: s3.amazonaws.com
6: hosts-file.net

Add domain to the whitelist.

$ pihole -w example.com

Remove domain from the whitelist.

$ pihole -w -d example.com

List blacklisted domains.

$ pihole -b -l
Displaying domains caught in the sinkhole:

Add domain to the blacklist.

$ pihole -b example.com

Remove domain from the blacklist.

$ pihole -b -d example.com

pihole usage information.

$ pihole
Usage: pihole [options]
Example: 'pihole -w -h'
Add '-h' after specific commands for more information on usage

Whitelist/Blacklist Options:
  -w, whitelist       Whitelist domain(s)
  -b, blacklist       Blacklist domain(s)
  -wild, wildcard     Blacklist domain(s), and all its subdomains
                        Add '-h' for more info on whitelist/blacklist usage

Debugging Options:
  -d, debug           Start a debugging session
                        Add '-a' to enable automated debugging
  -f, flush           Flush the Pi-hole log
  -r, reconfigure     Reconfigure or Repair Pi-hole subsystems
  -t, tail            View the live output of the Pi-hole log

Options:
  -a, admin           Admin Console options
                        Add '-h' for more info on admin console usage
  -c, chronometer     Calculates stats and displays to an LCD
                        Add '-h' for more info on chronometer usage
  -g, updateGravity   Update the list of ad-serving domains
  -h, --help, help    Show this help dialog
  -l, logging         Specify whether the Pi-hole log should be used
                        Add '-h' for more info on logging usage
  -q, query           Query the adlists for a specified domain
                        Add '-exact' AFTER a specified domain for exact match
  -up, updatePihole   Update Pi-hole subsystems
  -v, version         Show installed versions of Pi-hole, Admin Console & FTL
                        Add '-h' for more info on version usage
  uninstall           Uninstall Pi-hole from your system
  status              Display the running status of Pi-hole subsystems
  enable              Enable Pi-hole subsystems
  disable             Disable Pi-hole subsystems
                        Add '-h' for more info on disable usage
  restartdns          Restart Pi-hole subsystems
  checkout            Switch Pi-hole subsystems to a different Github branch
                        Add '-h' for more info on checkout usage

Additional notes

Remember to create and configure self signed SSL certificate.

About Milosz Galazka

Milosz is a Linux Foundation Certified Engineer working for a successful Polish company as a system administrator and a long time supporter of Free Software Foundation and Debian operating system. He is also open for new opportunities and challenges.