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

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

Start and enable at boot OpenSSH service.

$ sudo systemctl start ssh
$ sudo systemctl enable ssh

Device is ready, so you can connect 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 pi-hole

Execute installation script.

$ sudo bash pi-hole/automated\ install/ 

Installation process will start immediately.

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 maintenance tasks.

View live output of the Pi-hole log.

$ pihole -t
Press Ctrl-C to exit
Oct 21 13:41:33 dnsmasq[27682]: forwarded to
Oct 21 13:41:33 dnsmasq[27682]: reply is
Oct 21 13:41:36 dnsmasq[27682]: query[A] from
Oct 21 13:41:36 dnsmasq[27682]: forwarded to
Oct 21 13:41:36 dnsmasq[27682]: reply is 
Oct 21 13:41:36 dnsmasq[27682]: reply is
Oct 21 13:41:36 dnsmasq[27682]: query[A] from
Oct 21 13:41:36 dnsmasq[27682]: cached is
Oct 21 13:41:37 dnsmasq[27682]: query[A] from
Oct 21 13:41:37 dnsmasq[27682]: cached is

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:


Add domain to the whitelist.

$ pihole -w

Remove domain from the whitelist.

$ pihole -w -d

List blacklisted domains.

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

Add domain to the blacklist.

$ pihole -b

Remove domain from the blacklist.

$ pihole -b -d

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

  -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.