Categories
SysOps

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, 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 an image to SD Card.

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

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

Log in as pi user using raspberry password.

Change the 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

The 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 https://github.com/pi-hole/pi-hole.git pi-hole

Execute the installation script.

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

The installation process will start immediately.

Choose DNS upstream provider.

Choose supported protocols – IPv4, IPv6 protocol, or both.

Choose to install the admin interface.

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

Choose to use a static IPv4 address.

Provide an IPv4 address.

Provide an IPv4 default gateway.

Confirm network configuration provided in the last three steps.

Installation is complete.

Change the admin password using the 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 the 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 the IP address or other settings defined during the 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 a specific 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 the 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 a self-signed SSL certificate.