From ArchWiki
Revision as of 12:41, 31 December 2017 by Graysky (talk | contribs) (Preferred method: better readability)
Jump to: navigation, search

Pi-hole is a shell-script based project that manages blocklists of known IP addresses known to host advertisements and malware through a seamless interaction with dnsmasq to simply drop all any bad request. Running it effectively deploys network-wide adblocking without the need to configure individual clients. The package comes with a nice webUI (as well as a CLI interface) and is very lightweight and scaleable.

Pi-hole Server


Install pi-hole-ftlAUR and pi-hole-serverAUR.

Initial configuration


Ensure that the following line in /etc/dnsmasq.conf is uncommented:


Enable dnsmasq.service and re/start it.

Web Server

Optionally choose a web server for the Pi-hole web interface.

Note: Pi-hole does not strictly require a web interface as many commands are possible via the CLI interface.

Example config files that work out-of-the-box are provided for both lighttpd and nginx. Other web servers can also run the WebUI, but are currently unsupported.

Install php-sqlite and enable the relevant extensions detailed here:


For security reasons, one can populate the PHP open_basedir directive however, the Pi-hole administration web interface will need access to following files and directories:


Install lighttpd and php-cgi.

Copy the package provided default config for Pi-hole:

# cp /usr/share/pihole/configs/lighttpd.example.conf /etc/lighttpd/lighttpd.conf

Enable lighttpd.service and re/start it:


Install nginx-mainline and php-fpm.

Edit /etc/php/php-fpm.d/www.conf and change the listen directive to the following:

listen =  

Modify /etc/nginx/nginx.conf to contain the following in the http section:

gzip            on;
gzip_min_length 1000;
gzip_proxied    expired no-cache no-store private auth;
gzip_types      text/plain application/xml application/json application/javascript application/octet-stream text/css;
include /etc/nginx/conf.d/*.conf;

Copy the package provided default config for Pi-hole:

# mkdir /etc/nginx/conf.d
# cp /usr/share/pihole/configs/nginx.example.conf /etc/nginx/conf.d/pihole.conf

Enable nginx.service php-fpm.service and re/start them.


FTL is a database-like wrapper/API that provides long-term storage of requests which users can query through the "long-term data" section of the WebGUI. To be clear, data are collected and stored in two places:

  1. Daily data are stored in RAM and are captured in real-time within /run/log/pihole/pihole.log
  2. Historical data (i.e. over multiple days/weeks/months) are stored on the file system /etc/pihole/pihole-FTL.db written out at a user-specified interval.
Tip: If Pi-hole is running on a solid state device (single-board computers SD, SSD, M.2/NVMe device, etc...) it is recommended to set the DBINTERVAL value at least to 60.0 to minimize writes to the database.

Configure FTL by editing /etc/pihole/pihole-FTL.conf with following parameters (the option shown first is the default):

  • SOCKET_LISTENING=localonly|all (Listen only for local socket connections or permit all connections)
  • TIMEFRAME=rolling24h|yesterday|today (Rolling data window, up to 48h (today + yesterday), or up to 24h (only today, as in Pi-hole v2.x ))
  • QUERY_DISPLAY=yes|no (Display all queries? Set to no to hide query display)
  • AAAA_QUERY_ANALYSIS=yes|no (Allow FTL to analyze AAAA queries from pihole.log?)
  • MAXDBDAYS=365 (How long should queries be stored in the database? Setting this to 0 disables the database altogether)
  • RESOLVE_IPV6=yes|no (Should FTL try to resolve IPv6 addresses to host names?)
  • RESOLVE_IPV4=yes|no (Should FTL try to resolve IPv4 addresses to host names?)
  • DBINTERVAL=1.0 (How often do we store queries in FTL's database [minutes]?)
  • DBFILE=/etc/pihole/pihole-FTL.db (Specify path and filename of FTL's SQLite long-term database. Setting this to DBFILE= disables the database altogether)

pi-hole-ftl.service is statically enabled; re/start it.

Configuration of the router and of Pi-hole

Preferred method

Most users will want the all of the following functionality:

  1. Per-host tracking on Pi-hole (i.e. logging of DNS requests tied to individual machines by their respective hostnames).
  2. The ability to resolve hostnames on the LAN.
  3. Ad blocking/network monitoring provided by Pi-hole.

To achieve all of the above, the router should be configured to advertise Pi-hole's IP address for DNS resolution to clients, but retain the actual DNS resolution itself upstream of the Pi-hole box. Pi-hole should be configured to simply use the router as its sole DNS entry.

On the router, use a custom dnsmasq config entry to advertise the IP of the Pi-hole box. The syntax is:


If Pi-hole is running on a machine whose IP address is, this becomes:


On Pi-hole, login to the web interface (http://pi.hole), select "Settings" and define the IP address of the router as the only upstream DNS server. Do not define any other DNS entries for Pi-hole.

Tip: A simple check to see that the router is setup correctly is to first renew a DHCP lease, then inspect the contents of /etc/resolv.conf on the target client machine. One should see the IP address of the Pi-hole box, not the IP address of the router.
Note: For full network and Pi-hole functionality, one may need to disable the dns-rebind feature if present on the router's firmware.
Note: The above configuration may not be possible on some routers depending on the feature set exposed the firmware. The configuration above is confirmed to work on some popular open-source firmwares such as LEDE/OpenWRT, DD-WRT, and TomatoUSB to name a few.

Fallback method

Users unable to configure the router as directed above are referred to this upstream guide for setup instructions.
For completeness, an overview of the guide will be provided below.
You can follow two methods:

Automatic method: Set Your DNS Server In Your Router's Settings

This is the fastest way to get all of your devices using Pi-hole. If you set this configuration via your router's DHCP options, any device that connects to your network will immediately begin blocking ads.

Tip: Make sure you adjust this setting under your LAN settings and not the WAN.

Go to the DHCP Server section of your router and set your Pi-hole box IP address as your unique DNS server for your LAN.

Warning: If you have existing network devices on your network when you make this change, you will not see ads getting blocked until the DHCP lease is renewed. For simplicity, restart those devices.
Note: Note that your Pi-hole should be the only DNS server set here as Pi-hole already delivers the other upstream servers. If you set another server in your router, it's possible your ad blocking will be negatively affected..
Manual Method: Manual configure DNS entry for your devices

You can manually configure each device to use Pi-hole as their DNS server. You just need the IP address of your Pi-hole and then follow the instructions below for your operating system.

In many of modern Linux Desktop Environment, DNS settings are configured through Network Manager.

  1. Click System > Preferences > Network Connections
  2. Select the connection for which you want to configure
  3. Click Edit
  4. Select the IPv4 Settings or IPv6 Settings tab
  5. If the selected method is Automatic (DHCP), open the dropdown and select Automatic (DHCP) addresses only instead. If the method is set to something else, do not change it.
  6. In the DNS servers field, enter your Pi's IP addresses
  7. Click Apply to save the change
  8. Repeat the procedure for additional network connections you want to change.

If you don't use Network Manager, plese refer to your connection manager instruction for specific DNS manual settings.
If you don't use a connection manager at all your DNS settings are specified in /etc/resolv.conf: edit it to insert the following unique nameserver item:

nameserver <Pi-hole_box_IP>

where <Pi-hole_box_IP> is IP address of the machine that run Pi-hole.


  1. Click Apple > System Preferences > Network
  2. Highlight the connection for which you want to configure DNS
  3. Click Advanced
  4. Select the DNS tab
  5. Click + to replace any listed addresses with, or add, your Pi's IP addresses at the top of the list:
  6. Click Apply > OK
  7. Repeat the procedure for additional network connections you want to change.

DNS settings are specified in the TCP/IP Properties window for the selected network connection.

  1. Go to the Control Panel
  2. Click Network and Internet > Network and Sharing Center > Change adapter settings
  3. Select the connection for which you want to configure
  4. Right-click Local Area Connection > Properties
  5. Select the Networking tab
  6. Select Internet Protocol Version 4 (TCP/IPv4) or Internet Protocol Version 6 (TCP/IPv6)
  7. Click Properties
  8. Click Advanced
  9. Select the DNS tab
  10. Click OK
  11. Select Use the following DNS server addresses
  12. Replace those addresses with the IP addresses of your Pi
  13. Restart the connection you selected in step 3
  14. Repeat the procedure for additional network connections you want to change.

Pi-hole centric method

You can follow another method to configure your LAN. You can set up the machine running Pi-hole as a DHCP server and turn off all network services on your router, relegating it to a simple gateway/natter.

Warning: Dnsmasq should be just installed or you should use the default Pi-hole dnsmasq configuration provided with the package. The following instructions may overwrite your dnsmasq customizations if present.

For semplicity of configuration and exposure, only the method via web interface will be followed:

  • Go to your router configuration interface and turn off DHCP service. Take note of your router IP address.
  • Go to Pi-hole web interface (http://pi.hole)
  • Go to Settings/Pi-hole DHCP Server
  • Check DHCP server enabled
  • Set DHCP range for your LAN valorizing From and To boxes. For example: From To
  • Set your router IP address into Router box. For example:
  • Optional: From Advanced DHCP settings check Enable IPv6 support (SLAAC + RA) if you want IPv6 support and functionality.
  • Optional: If you need some static DHCP lease you can configure them going to DHCP leases/Static DHCP leases configuration section.
  • Save to apply changes.
Warning: If you have existing network devices on your network when you make this change, you will not see ads getting blocked until the DHCP lease is renewed. For simplicity, restart those devices.

Using Pi-hole together with OpenVPN

One can use both OpenVPN (server) together with Pi-hole to effectively route the remote traffic from the clients though Pi-hole's DNS thus dropping ads for the clients. A reduction in cellular data usage is expected since ads are never allowed to load. Make sure /etc/openvpn/server/server.conf contains two key lines as illustrated below replacing the literal "xxx.xxx.xxx.xxx" with the IP address of the box running Pi-hole:

push "redirect-gateway def1 bypass-dhcp"
push "dhcp-option DNS xxx.xxx.xxx.xxx"

If it still doesn't work, try creating a file /etc/dnsmasq.d/00-openvpn.conf with the following contents:


This may be necessary to make dnsmasq listen on tun0.

Pi-hole Standalone

The Archlinux Pi-hole Standalone variant is born from the need to use Pi-hole services in a mobile context. Sky-hole article was inspirational.


Install the pi-hole-standaloneAUR package.
The Pi-hole standalone package install a statically enabled timer (and relative service) will weekly update Pi-hole blacklisted servers list. If you do not like default timer timings (from upstrem project) you can, of course, edit it or preventing from being executed by masking it.
You need to manually start pi-hole-gravity.timer or simply reboot after your configuration is finished.

Initial configuration


Ensure that the following line in /etc/dnsmasq.conf is uncommented:


Enable dnsmasq.service and re/start it.

Configuring host name resolution

The Pi-hole standalone package to work properly requires that a unique DNS is set on your machine. That DNS address need to be your machine itself.
This can be done in several ways.


If no service on your machine automatically handles the /etc/resolv.conf file, you can easily edit it to insert the following unique item nameserver:

Note: No other nameserver items need to be present in the config file.

It is likely that is the openresolv service to handle /etc/resolv.conf if you use a network connection manager such as netctl or NetworkManager. If it is your case, you must force openresolv to use localhost as name server.
Edit /etc/resolvconf.conf to uncomment the name_servers line:


and update resolvconf:

# resolvconf -u

Using Pi-hole

As previously mentioned, Pi-hole offers the ability to be configured and used both through the command line and through its web interface (server package only).

Pi-hole DNS management

At first installation, Pi-hole is defaulted to use Google DNS for name resolution of your LAN requests. If you want to change servers or simply add others on the machine running Pi-hole you can execute

pihole -a setdns [DNS1],[DNS2],...

followed by a comma separated list of DNS servers you want Pi-hole will use. For example, if in addition to Google's DNS you want to add those of Comodo run

pihole -a setdns,,,

For server package only, you can manage this via web interface (http://pi.hole) going to Settings and adding desired DNS servers in Upstream DNS Servers section. Save to apply changes.

Forced update of ad-serving domains list

If you need to update the blocked domain list, on the machine running Pi-hole you can execute

pihole -g

or, server package only, via web interface (http://pi.hole) go to Tools/Update Lists and execute Update Lists.

Protect web interface access (server package only)

Pi-hole web interface can be password protected to prevent unauthorized use. On the machine running Pi-hole you can execute

pihole -a -p <pwd>

where <pwd> is the password you want to assign. You can leave it blank for tipical *nix password request and confirmation.
To disable password login retype

pihole -a -p

leaving all blank.

Temporarily disable Pi-hole

Pi-hole can be easily paused through its web interface (http://pi.hole): go to Disable and choose the suspension option that best suits your case.
It is possible via CLI too by executing

pihole disable [time]

If you leave time blank disabling will be permanent until later manual reenabling.
time can be expressed in seconds or minutes with syntax #s and #m. For example, to disable Pi-hole for 5 minutes only, you can execute

pihole disable 5m

At any time you can reenable Pi-hole by executing

pihole enable

or, via web interface, clicking on Enable.

See also