Pi-hole

Install the package.

Pi-hole's 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. Data are collected and stored in two places:

1. Daily data are stored in RAM and are captured in real-time within
2. Historical data (several days/weeks/months) are stored on the file system /etc/pihole/pihole-FTL.db and written out at a user-specified interval.

pihole-FTL.service is statically enabled; re/start it. For FTL configuration, see upstream documentation.

Pi-hole has a powerful, user-friendly, but completely optional web interface. As well as changing settings, the user can analyse and visualise DNS queries handled by Pi-hole.

Install ( will be installed automatically) and enable the relevant extensions detailed here:

In php 7.0 and newer, the PHP open_basedir directive defaults to empty, meaning PHP can access every directory and file that can be read by the webserver's userid. For greater security, uncomment open_basedir in and add the list of directories and files accessed by the Pi-hole administration web interface. The list is quite long:

The open_basedir directive expects a colon-separated list:

Install and .

Copy the package provided default configuration for Pi-hole:

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

Enable lighttpd.service and start it.

ships with an empty  file which is known to prevent Pi-hole from fetching block lists.  One must append the following to this file to ensure correct operation, noting that ip.address.of.pihole should be the actual IP address of the machine running Pi-hole (e.g. 192.168.1.250) and myhostname should be the actual hostname of the machine running Pi-hole:

For more, see Issue#1800.

To use Pi-hole, devices within the network should use Pi-hole's IP address as their sole DNS server. To accomplish this, there are generally two methods:

1. In the router's LAN DHCP settings, set Pi-hole's IP address as the only DNS server available for connected devices.
2. 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 package.

The Pi-hole standalone package install a statically enabled timer (and relative service) will weekly update Pi-hole blacklisted servers list. The default values can be changed via an edit to the service or it can be prevented from being executed by masking it. Remember to manually start or simply reboot after editing.

See #FTL (Faster Than Light).

Change the computer's network settings so the only DNS server in use is .

If using DHCP to lease IP addresses from an external router, append bind-interfaces to for DNS queries to resolve.

Test DNS queries independently of network-configured nameserver in using .

Go to pi.hole or <Pi-hole IP address>/admin/ to access web interface.

By default Pi-hole uses the Google DNS server. Change which DNS servers Pi-hole uses with:

$ pihole -a setdns server

Specify multiple DNS servers by separating their addresses with commas.

To update the blocked domain list, execute:

$ pihole -g

Pi-hole can be paused via CLI by executing:

$ pihole disable [time]

Leaving the value for blank, the disabling will be permanent until later manual reenabling.

can be expressed in seconds or minutes with syntax #s and #m. For example, to disable Pi-hole for 5 minutes:

$ pihole disable 5m

At any time, reenable Pi-hole by executing:

$ pihole enable

To password-protect the Pi-hole web interface, run the following command and enter the password:

$ pihole -a -p

To disable the password protection, set a blank password.

Pi-hole can be configured to use Cloudflared to achieve DNS over HTTPS functionality.

To make Cloudflared work with Pi-hole, edit file and change settings as per below:

Then restart . Now use as the only DNS server entry in Pi-hole.

If Pi-hole is running on a solid state drive (SD card, SSD etc..) it is recommended to uncomment the value and change it to at least 60.0 to minimize writes to the database:

After changes have been performed, restart pihole-FTL.service.

Both daily and historic data collected by default contain query data that might be considered sensitive.

To disable the query database for historic data, set privacy level to the maximum Anonymous mode either in the web administration (Settings > Privacy) or in the configuration file by editing the line:

PRIVACYLEVEL=3

To also disable the logging for daily data, use the following command:

$ pihole logging off

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 :

push "redirect-gateway def1 bypass-dhcp"
push "dhcp-option DNS Pi-hole-IP"

If it still does not work, try creating a file with the following content:

interface=tun0

It may be necessary to make dnsmasq listen on .

WireGuard clients can be configured to use the Pi-hole DNS server. In the client configuration file, specify the following line:

DNS = Pi-hole-IP

In order for the DNS to be functional from the VPN, Pi-hole has to listen to all local interfaces:

pihole -a -i local

See more information in WireGuard#Client configuration.

This is unofficial, community-supported configuration. Make sure that PHP is set up (see #Set up PHP) and lighttpd server is inactive.

Install and .

Modify 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 configuration for Pi-hole:

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

Edit /etc/nginx/conf.d/pihole.conf and change the directive to the following:

fastcgi_pass  unix:/run/php-fpm/php-fpm.sock;  

Optionally, set to the CNAME of Pi-hole if the intention is to run multiple virtual hosts on Nginx.

fastcgi_param VIRTUAL_HOST "pihole.example.com";

Since version 7.4 php-fpm is hardened by default and revokes read/write access on (and sub-directories).

Create an drop-in file for with the following content:

Then start and enable nginx.service and .

Pi-hole was intended to block ads, but it can also be used to block other unwanted content:

1. Tracking domains
2. Malware domains
3. Piracy sites
4. Fake news sites
5. Phishing sites

There are many sources providing these blocklists. Some examples: firebog.net and oisd.nl.

By default, Pi-hole forwards requests to upstream DNS servers, which might lead to privacy concerns. See upstream documentation for a guide on setting up Unbound locally to resolve DNS requests.

Some strange/unexplained rendering issues in the web GUI can often be fixed by clearing one's browser cache.

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 drop-in files against pihole-FTL.service wherein a delay is built in calling in a statement. Note that the value of "x" in the sleep time depends on how long the 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.

It might be that already occupied port 53, which is required for pihole-FTL.service. To resolve this, disable the stub listener by editing systemd-resolved configuration file:

Then restart and pihole-FTL.service.

For more information, see .

Alternatively, tell dnsmasq to bind to each interface explicitly, instead of the wildcard , by uncommenting the line bind-interfaces in . This will avoid conflicting with which listens on .

Since Pi-hole-FTL 4.0, a private fork of dnsmasq is integrated in the FTL sub-project. The original dnsmasq package is now conflicting with pi-hole-ftl^AUR and will be uninstalled when upgrading from a previous version. It is still possible to use the previous dnsmasq configuration files, just ensure that in the original is not commented out.

The issue, as seen in , is with systemd-sysusers created user http, which is created in expired state. To fix it, run:

# chage --expiredate -1 http

If browsers report "Resolving host" or it just takes longer to load pages than usual, ensure that looks exactly like this:

If it takes very long to load pages, it can be a problem with call in pihole script called through php. Verify it while loading page with: . Kill it and if the page is displayed, replace call in pihole script (there is only one) with: