In this guide, we will cover the installation and usage of pi-hole on Ubuntu 18.04 / Ubuntu 16.04 / Debian and CentOS 7 system. pi-hole is a DNS sinkhole for Internet advertisements which aims to protect your devices from unwanted content, without installing any client-side software.

Are you tired of ads that keep popping up while browsing content on the Internet?, pi-hole is the tool you’re looking for!.

Features of pi-hole ads blacklisting software

Below are top features of pi-hole:

  • It is easy to install: pi-hole has a versatile installer which automates the installation process.
  • No client-side software required
  • Improve Overall Network Performance: Since ads are blocked before they are downloaded, your network will perform better.
  • Robust: It has a command line interface that is quality assured for interoperability
  • Modern: blocks ads over both IPv4 and IPv6
  • Resolute: pi-hole is able to block content in non-browser locations, e.g ad-laden mobile apps, and smart TVs.
  • Free: pi-hole is an open source software which helps ensure you are the sole person in control of your privacy
  • Responsive: With pi-hole you will experience a seamless speed up on daily browsing through its powerful caching of DNS queries
  • Lightweight: pi-hole is very lightweight as it only handles DNS queries and returns a blank HTML file so it doesn’t need much processing power. 53mb disk space and 512mb of ram should be enough.
  • Insightful: pi-hole has a beautiful and responsive Web Interface dashboard from where you can view and control your Pi-hole
  • Versatile: You can also use pi-hole as a DHCP server, ensuring that all your devices are protected automatically
  • Scalable: It is capable of handling hundreds of millions of queries when installed on server-grade hardware
  • Monitor Performance And Statistics: The Web interface shows how many ads were blocked, a query log, and more.

How to install pi-hole on Linux

Pi-hole installation on Ubuntu 18.04 / Ubuntu 16.04 and CentOS 7 system is done through a script

# curl -sSL https://install.pi-hole.net | bash

[✓] Root user check

        .;;,.
        .ccccc:,.
         :cccclll:.      ..,,
          :ccccclll.   ;ooodc
           'ccll:;ll .oooodc
             .;cll.;;looo:.
                 .. ','.
                .',,,,,,'.
              .',,,,,,,,,,.
            .',,,,,,,,,,,,....
          ....''',,,,,,,'.......
        .........  ....  .........
        ..........      ..........
        ..........      ..........
        .........  ....  .........
          ........,,,,,,,'......
            ....',,,,,,,,,,,,.
               .',,,,,,,,,'.
                .',,,,,,'.
                  ..'''.

  [✓] Disk space check

  [✓] Update local cache of available packages

  [✓] Checking apt-get for upgraded packages... 35 updates available
  [i] It is recommended to update your OS after installing the Pi-hole! 

  [i] Installer Dependency checks...
  [✓] Checking for apt-utils
  [i] Checking for dialog (will be installed)
  [✓] Checking for debconf
  [i] Checking for dhcpcd5 (will be installed)
  [✓] Checking for git
  [✓] Checking for iproute2
  [✓] Checking for whiptail

  [✓] Stopping dnsmasq service...

  [✓] Stopping lighttpd service...
  [i] Using Google DNS servers
  [✓] Set IP address to 167.99.175.16
      You may need to restart after the install is complete
  [i] Unable to find IPv6 ULA/GUA address, IPv6 adblocking will not be enabled
  [i] IPv4 address: 167.99.175.16/20
  [i] IPv6 address: 
  [i] Web Interface On
  [i] Logging On.
  [✗] Check for existing repository in /etc/.pihole
  [✓] Clone https://github.com/pi-hole/pi-hole.git into /etc/.pihole

  [✗] Check for existing repository in /var/www/html/admin
  [✓] Clone https://github.com/pi-hole/AdminLTE.git into /var/www/html/admin
...

On a successful installation, you should see IP Address to set on your devices as DNS Server, and login URL for the pi-hole dashboard.

  [✓] Consolidating blocklists
  [✓] Extracting domains from blocklists
  [i] Number of domains being pulled in by gravity: 155633
  [✓] Removing duplicate domains
  [i] Number of unique domains trapped in the Event Horizon: 132404
  [i] Nothing to whitelist!
  [✓] Parsing domains into hosts format
  [✓] Cleaning up stray matter

  [✓] Force-reloading DNS service
  [✓] DNS service is running
  [✓] Pi-hole blocking is Enabled
  [i] Web Interface password: Dtp2AU7k
      This can be changed using 'pihole -a -p'

  View the web interface at http://pi.hole/admin or http://192.168.10.10/admin

  You may now configure your devices to use the Pi-hole as their DNS server
  [i] Pi-hole DNS (IPv4): 192.168.10.10
  If you set a new IP address, please restart the server running the Pi-hole

  [i] The install log is located at: /etc/pihole/install.log
  Installation Complete! 

You can as well download the installer and run it:

wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.sh

How to use pi-hole on Linux

Once the installer has been run, you need to configure your router to have DHCP clients use Pi-hole as their DNS server which ensures that all devices connecting to your network will have content blocked without any further intervention.

If your router does not support setting the DNS server, you can use Pi-hole’s built-in DHCP server; just be sure to disable DHCP on your router first (if it has that feature available). As a last resort, you can always manually set each device to use Pi-hole as their DNS server.

Accessing pi-hole admin interface

You can access its admin web interface using at http://pi.hole/admin or http://192.168.10.10/admin. Replace pi.hole with your hostname or 192.168.10.10 with the correct server IP address.

To log in to the management interface, use the password shown after the installation, the username is not needed. On successful login, an interface like below will be shown:

All management functions can be done from the UI – e.g:

  • View a summary of total queries, blocked queries, domains on a blocklist, top domains, top clients, Top Blocked Domains
  • Adding Whitelist/Blocklist domains
  • Checking audit logs
  • Change Upstream DNS Servers
  • Set DHCP Settings
  • Configure API settings
  • Export your Pi-hole lists as downloadable archive

Using pi-hole CLI

It is also possible to administer pi-hole from cli using pihole command line tool.

# pihole --help
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 '-h' for more info on query usage
  -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

Change/Reset GUI admin password:

# pihole -a -p
Enter New Password (Blank for no password): 
Confirm Password: 
[✓] New password set

Check pi-hole status:

# pihole status
[✓] DNS service is running
[✓] Pi-hole blocking is Enabled

Re-configure pi-hole system:

# pi-hole -r

Uninstall Pi-hole from your system

# pi-hole uninstall

Restart Pi-hole subsystems

# pi-hole restartdns

The example below will whitelist computigngforgeeks.com domain:

# pihole -w computingforgeeks.com
[i] Adding computingforgeeks.com to whitelist...
[i] computingforgeeks.com does not exist in blacklist, no need to remove!
[i] computingforgeeks.com does not exist in wildcard blacklist, no need to remove!

[i] Using cached Event Horizon list...
[i] 132404 unique domains trapped in the Event Horizon
[i] Number of whitelisted domains: 1
[i] Number of blacklisted domains: 0
[✓] Parsing domains into hosts format
[✓] Cleaning up stray matter

[✓] Force-reloading DNS service
[✓] DNS service is running
[✓] Pi-hole blocking is Enabled