Pi-hole is a DNS sinkhole that compiles a blocklist of domains known to host advertisements and malware from multiple third-party sources. Pi-hole uses dnsmasq to seamlessly drop any and all requests for domains in its blocklist. Running it effectively deploys network-wide ad-blocking without the need to configure individual clients. The package comes with a web and a CLI interface.
- 1 Overview
- 2 Pi-hole server
- 3 Pi-hole standalone
- 4 Using Pi-hole
- 5 Tips & Tricks
- 6 Troubleshooting
- 7 See also
There are 2 versions of Pi-Hole available for Arch Linux:
- #Pi-hole server - This is default and well-known Pi-Hole server that most users are looking for. It is designed to be used as a DNS server for other devices on the LAN.
- #Pi-hole standalone - This is alternative lightweight Pi-Hole installation, designed for a mobile context. It is intended to be used on the same device (e.g. laptop), where no external and centralised Pi-Hole server is available. It also has no web interface and automatically updates.
Install the AUR package.
The Pi-hole FTL engine ( AUR) is a dependency of the Pi-hole main project.
FTL is a DNS resolver/forwarder and 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:
- Daily data are stored in RAM and are captured in real-time within
- Historical data (i.e. over multiple days/weeks/months) are stored on the file system
/etc/pihole/pihole-FTL.dbwritten out at a user-specified interval.
pihole-FTL.service is statically enabled; re/start it. See the official documentation to configure FTL.
DBINTERVALvalue to at least
60.0to minimize writes to the database.
conf-dir=/etc/dnsmasq.d/,*.confin the original
/etc/dnsmasq.confis not commented out.
Pi-hole has a very powerful, user friendly, but completely optional web interface. It allows not only to change settings, but analyse and visualise DNS queries performed by other devices.
Install( will be installed automatically) and enable the relevant extensions detailed here:
[...] extension=pdo_sqlite [...] extension=sockets extension=sqlite3 [...]
For security reasons, one can optionally populate the PHP open_basedir directive however, the Pi-hole administration web interface will need access to following files and directories:
/srv/http/pihole /run/pihole-ftl/pihole-FTL.port /run/log/pihole/pihole.log /run/log/pihole-ftl/pihole-FTL.log /etc/pihole /etc/hosts /etc/hostname /etc/dnsmasq.d/02-pihole-dhcp.conf /etc/dnsmasq.d/03-pihole-wildcard.conf /etc/dnsmasq.d/04-pihole-static-dhcp.conf /proc/meminfo /proc/cpuinfo /sys/class/thermal/thermal_zone0/temp /tmp
Set-up web server
Example config files that work out-of-the-box are provided for bothand . Other web servers can also be used, but are currently unsupported.
Install and .
Copy the package provided default config for Pi-hole:
# cp /usr/share/pihole/configs/lighttpd.example.conf /etc/lighttpd/lighttpd.conf
lighttpd.service and re/start it.
Install and .
/etc/php/php-fpm.d/www.conf and change the listen directive to the following:
listen = 127.0.0.1:9000
/etc/nginx/nginx.conf to contain the following in the http section:
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
php-fpm.service and re/start them.
Protect with password
Optionally, you might want to password-protect the Pi-hole web interface. Run the following command and enter your password:
pihole -a -p
To disable the password protection, set a blank password.
Update hosts file
ships with an empty
/etc/hosts file which is known to prevent Pi-hole from fetching block lists. One must append the following to this file to insure correct operation, noting that ip.address.of.pihole should be the actual IP address of the machine running Pi-hole (eg 192.168.1.250) and myhostname should be the actual hostname of the machine running Pi-hole.
127.0.0.1 localhost ip.address.of.pihole pi.hole myhostname
For more, see Issue#1800.
Making devices use Pi-hole
To use Pi-Hole, make sure that your devices use Pi-Hole's IP address as their only DNS server. To accomplish this, there are generally 2 methods to make it happen:
- In router's LAN DHCP settings, set Pi-Hole's IP address as the only DNS server available for connected devices.
- Manually configure each device to use Pi-Hole's IP address as their only DNS server.
More information about making other devices use Pi-Hole can be found at upstream documentation.
Install the AUR 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.
Pi-hole-standalone now uses FTL as hostnames resolver. Since Pi-hole 4.0, a private fork of dnsmasq is integrated in the FTL sub-project. The originalpackage is now conflicting with AUR and will be uninstalled when upgrading from a previous version. It's still possible to use the previous dnsmasq config files.
Ensure that the following line in
/etc/dnsmasq.conf is uncommented:
If you do not have
/etc/dnsmasq.conf file at all, you can use the example conf file within the package (
/usr/share/pihole/configs/dnsmasq.example.conf) that will work out of box.
pihole-FTL.service is statically enabled; 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 127.0.0.1
nameserveritems need to be present in the config file.
It is likely that is the
/etc/resolv.conf if you use a network connection manager such as netctl or NetworkManager. If it is your case, you must force to use localhost as name server.
/etc/resolvconf.conf to uncomment the name_servers line:
and update resolvconf:
# resolvconf -u
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
By default Pi-hole uses the Google DNS server. You can change which DNS servers Pi-hole uses with:
$ pihole -a setdns server
You can specify multiple DNS servers by separating their addresses with commas.
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.
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.
Tips & Tricks
Cloudflared DNS service
proxy-dns: true proxy-dns-upstream: - https://126.96.36.199/dns-query - https://188.8.131.52/dns-query - https://2606:4700:4700::1111/dns-query - https://2606:4700:4700::1001/dns-query proxy-dns-port: 5053 proxy-dns-address: 0.0.0.0 logfile: /var/log/cloudflared.log
Then start and enable
email@example.com. Now you can use
127.0.0.1#5053 as a DNS server in Pi-Hole.
Use with VPN server
Pi-Hole can be used by connected VPN clients.
An OpenVPN server can be configured to advertise a Pi-hole instance to its clients. Add the following two lines to your
push "redirect-gateway def1 bypass-dhcp" push "dhcp-option DNS Pi-Hole-IP"
If it still does not work, try creating a file
/etc/dnsmasq.d/00-openvpn.conf with the following content:
It may be necessary to make
dnsmasq listen on
WireGuard clients can be configured to use Pi-Hole DNS server. In the client configuration file, specify the following line:
DNS = Pi-Hole-IP
See more information in WireGuard#Client config.
Pi-Hole was intended to block ads, but it can also be used to block other unwanted content:
- Tracking domains
- Malware domains
- Piracy sites
- Fake news sites
- Phishing sites
Data loss on reboot
Systems without a RTC such as some ARM devices will likely experience loss of data in the query log upon rebooting. When systems lacking a RTC boot, the time is set after the network and resolver come up. Aspects of Pi-hole can get started before this happens leading to the data loss. An incorrectly set RTC can also cause problems. See: Installation guide#Time zone and System time.
For devices lacking a RTC:
A hacky work-around for this is to use Systemd#Drop-in files against
pihole-FTL.service wherein a delay is built in calling
/usr/bin/sleep x in a
ExecStartPre statement. Note that the value of "x" in the sleep time depends on how long your specific hardware takes to establish the time sync.
Issue#11008 against systemd-timesyncd is currently preventing the use of the time-sync.target to automate this.