Difference between revisions of "Pi-hole"

From ArchWiki
Jump to navigation Jump to search
m (Typical configuration: fix file in wiki format)
m (Typical configuration: simplify)
Line 84: Line 84:
# note the search line shown next is optional
search lan

Revision as of 21:29, 29 October 2017

Pi-hole is a shell-script based project that manages blocklists of known advertisements and malware and seamlessly interacts with dnsmasq to simply drop all any request to a known bad-actor. Pi-hole replaces your router as the LAN's DNS so all requests go through it without the need to install anything on the client-side. This setup effectively deploys network-wide adblocking (ie for all connected devices). 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

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

The AUR package provides example config files for both lighttpd and nginx. Other web servers can also run the WebUI, but are currently unsupported.

Any webserver will require the following edit to enable the sockets extension:


For security reason, if you want to populate PHP open_basedir directive, pi-hole administration web interface needs access to following files and directories:


Install lighttpd and php-cgi.

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

Typical configuration

Note: For the purposes of this article, shall be the address of the router and shall be the address of the pihole box.

Pi-hole needs to be the DNS for the LAN in order to work properly. Typical home users rely on their router to resolve DNS queries. The preferred method is to simply redefine the DNS entry on the router to use the IP address of the box running Pi-hole. Configuring the router is outside the scope of this article. An alternative is to manually define the DNS entries for each device connecting to the router although this can be tedious. See, How do I configure my devices to use Pi-hole as their DNS server?

Once the router is serving up the pihole box's IP address as the DNS, log into the pihole webinterface (http://pi.hole/admin), optionally log in if running it with a password, then click "Settings." From there scroll down to the section entitled, "Upstream DNS Servers" and, define the IP address of the router (e.g. as the sole entry, then click "save."

Note: Pi-hole's web interface can configure nearly every aspect of dnsmasq, and execute lots of Pi-hole available commands, control white lists/black lists, and monitor ad filtering.

It may be required to restart the network on any connected clients. As an example, the contents of /etc/resolv.conf on a client should be similar to:



FTL is part of Pi-hole project. It is a database-like wrapper/API providing the frontend to Pi-hole's DNS query log. One can configure FTL in /etc/pihole/pihole-FTL.conf. Read project documentation for details.

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

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.

Initial configuration


Setup is identical to the steps described in #Dnsmasq.


Edit /etc/resolvconf.conf to uncomment the name_servers line:


and update resolvconf:

# resolvconf -u

See also