Pi-hole

Related articles
dnsmasq
Domain name resolution
Linux Containers
OpenVPN
WireGuard
Pi-hole
project is a
DNS sinkhole
that compiles a blocklist of domains from multiple third-party sources. Pi-hole uses
pi-hole-ftl
AUR
(a
dnsmasq
fork) 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 an optional web administration interface.
Note
Pi-hole on Arch Linux is not officially supported by the Pi-hole project.
Installation
Install
the
pi-hole-core
AUR
package.
Configuration
This article or section is out of date.
Reason:
Many of the following sections still refer to Pi-hole 5, so are not directly applicable to Pi-hole 6, where many things changed, including an integrated webserver and the move to the .toml config file (Discuss in
Talk:Pi-hole
)
FTL (Faster Than Light)
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:
Daily data are stored in RAM and are captured in real-time within
/run/log/pihole/pihole.log
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.
Note
To disable logging, see
#Disable query logging
.
Starting
pihole-FTL.service
is likely to fail. See
#Failed to start Pi-hole FTLDNS engine
.
pihole-FTL.service
is statically enabled; re/start it. For FTL configuration, see
upstream documentation
.
FTL Integrated Web interface
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.
Update hosts file
This article or section needs language, wiki syntax or style improvements. See
Help:Style
for reference.
Reason:
At least partially duplicates
Network configuration#localhost is resolved over the network
. (Discuss in
Talk:Pi-hole
)
filesystem
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 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:
/etc/hosts
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, devices within the network should use Pi-hole's IP address as their sole DNS server. To accomplish this, there are generally two methods:
In the 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.
Note
Some routers (or even ISPs) do not allow modifications to LAN DNS settings, so disabling the router's DHCP server and using
Pi-hole's built-in DHCP server
might be a solution.
More information about making other devices use Pi-hole can be found at
upstream documentation
.
Tip
The Pi-hole hosting device can also make use of Pi-hole. Just change DNS settings to only IP address
127.0.0.1
.
Usage
Change the computer's network settings so the only DNS server in use is
127.0.0.1
.
If using DHCP to lease IP addresses from an external router, append
bind-interfaces
to
/etc/dnsmasq.conf
for DNS queries to resolve.
Test DNS queries independently of network-configured nameserver in
/etc/resolv.conf
using the
drill
command of
ldns
package with
drill @127.0.0.1 archlinux.org
.
Usage
Both standalone and server versions can be controlled via CLI, but only server version can be controlled via web interface.
Using web interface
Go to
pi.hole
or
<Pi-hole IP address>/admin/
to access web interface.
Using CLI
Pi-hole DNS management
By default Pi-hole uses the Google DNS server. Change which DNS servers Pi-hole uses with:
# pihole-FTL --config dns.upstreams '["
ipaddress#port
"]'
Specify multiple DNS servers by separating their addresses with commas.
Forced update of ad-serving domains list
To update the blocked domain list, execute:
$ pihole -g
Temporarily disable Pi-hole
Pi-hole can be paused via CLI by executing:
$ pihole disable
time
Leaving the value for
time
blank, the 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:
$ pihole disable 5m
At any time, reenable Pi-hole by executing:
$ pihole enable
Tips and tricks
Password-protected web interface
To password-protect the Pi-hole web interface, run the following command and enter the password:
# pihole setpassword
To disable the password protection, set a blank password.
Cloudflare DoH
The factual accuracy of this article or section is disputed.
Reason:
This has been reported as no longer working. From cloudflared: "DNS Proxy is no longer supported." (Discuss in
Talk:Pi-hole
)
Pi-hole can be configured to use
Cloudflared
to achieve
DNS over HTTPS
functionality.
To make
Cloudflared
work with Pi-hole, simply start cloudflared and configure Pi-hole to use it as its DNS entry.
Using the
suggested service file for cloudflared
, that would be:
# systemctl start cloudflared
# pihole-FTL --config dns.upstreams '["127.0.0.1#54"]'
Test that Pi-hole is working with:
$ drill archlinux.org @127.0.0.1 -p 53
Note
The port is the one bound to Pi-hole, not the one bound to cloudflared.
Optimise for solid state drives
If Pi-hole is running on a
solid state drive
(SD card, SSD, etc.), it is recommended to change the
DBinterval
value to at least one hour to minimize writes to the database:
/etc/pihole/pihole.toml
...

[database]

  ...

  # How often do we store queries in FTL's database [seconds]?
  DBinterval = 3600

  ...
Tip
log2ram
AUR
may also be useful on a
RaspberryPi
.
Disable query logging
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 the privacy level to
Anonymous mode
in the web administration (
Settings > Privacy
) or edit the
privacylevel
value in the configuration file:
/etc/pihole/pihole.toml
...

[misc]

  ...

  privacylevel = 3

  ...
To also disable the logging for daily data, use the following command:
# pihole logging off
Warning
Pi-hole will erase all statistics upon executing this command.
Use with VPN server
Pi-hole can be used by connected VPN clients.
OpenVPN
An
OpenVPN
server can be configured to advertise a Pi-hole instance to its clients. Add the following two lines to
/etc/openvpn/server/server.conf
:
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:
interface=tun0
It may be necessary to make
dnsmasq
listen on
tun0
.
WireGuard
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-FTL --config dns.listeningMode LOCAL
See more information in
WireGuard#Client configuration
.
Additional blocklists
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
Note
Pi-hole blocklists must contain
domains
. Some blocklists might contain IP addresses of
127.0.0.1
and domain combination — this format is accepted by Pi-hole.
There are many sources providing these blocklists. Some examples:
firebog.net
and
oisd.nl
.
Block/Allow domains using regex
To add a wildcard domain to the denylist, use the following
pihole
command:
$ pihole --wild yourdomain.com
Note
It will be added as
(\.|^)yourdomain\.com$
entry in the domains list.
To block a domain with a custom regex:
$ pihole --regex '^example\.com$'
To remove the same domain from the denylist, just add
-d
flag to the
pihole
command:
$ pihole --wild -d yourdomain.com
$ pihole --regex -d '^example\.com$'
See also
regex tutorial
.
Use Unbound as upstream DNS server
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.
Troubleshooting
Odd behavior in the web interface after an upgrade
Some strange/unexplained rendering issues in the web GUI can often be fixed by clearing one's browser cache.
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
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
/usr/bin/sleep x
in a
ExecStartPre
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.
Failed to start Pi-hole FTLDNS engine
Tip
Check which process opened port 53 with:
lsof -i :53
as root.
It is possible that
systemd-resolved.service
is already using port 53, which is required for
pihole-FTL.service
.
To resolve this, disable the stub listener by creating a
drop-in snippet
for
systemd-resolved
's configuration file:
/etc/systemd/resolved.conf.d/pi-hole.conf
[Resolve]
DNSStubListener=no
Then
restart
systemd-resolved.service
and
pihole-FTL.service
.
For more information, see
resolved.conf(5)
.
Alternatively, tell dnsmasq to bind to each interface explicitly, instead of the wildcard
0.0.0.0:53
, by uncommenting the line
bind-interfaces
in
/etc/dnsmasq.conf
. This will avoid conflicting with
systemd-resolved
, which listens on
127.0.0.53:53
.
DNSMasq package conflict
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
conf-dir=/etc/dnsmasq.d/,*.conf
in the original
/etc/dnsmasq.conf
is not commented out.
Unknown status and changes not being saved
The issue, as seen in
FS#63704
, is with systemd-sysusers created user
http
, which is created in expired state. To fix it, run:
# chage --expiredate -1 http
Slow loading times
The factual accuracy of this article or section is disputed.
Reason:
This issue seems to pertain to DNS configuration. It might not be a good idea to instruct direct changes to
/etc/resolv.conf
. (Discuss in
Talk:Pi-hole
)
If browsers report "Resolving host" or it just takes longer to load pages than usual, ensure that
/etc/resolv.conf
looks
exactly
like this:
/etc/resolv.conf
nameserver 127.0.0.1
If it takes very long to load pages, it can be a problem with
lsof
call in pihole script
(/usr/bin/pihole)
called through php.  Verify it while loading page with:
ps -ef | grep lsof
. Kill it and if the page is displayed, replace
lsof
call in pihole script (there is only one) with:
ss -lnp '( sport = 53 )'
Prevent DNS resolution issues for other virtual hosts
By default, the DNS service (pihole-FTL) will be bind to the
0.0.0.0
IP address:
# netstat -ltnp | grep 53
tcp        0      0 0.0.0.0:53              0.0.0.0:*               LISTEN      2196/pihole-FTL
tcp6       0      0 :::53                   :::*                    LISTEN      2196/pihole-FTL
This will prevent any other virtual host onto the same machine hosting the pihole instance (such as docker containers) to get DNS resolution.
[1]
[2]
In order to solve this, you need to create a config file in
/etc/dnsmasq.d/
with the following content (where
X.X.X.X
is the IP address of your Pi-hole) :
/etc/dnsmasq.d/99-dns-bind.conf
listen-address=
X.X.X.X
bind-interfaces
Then, you need to
restart
the
pihole-FTL.service
to apply changes.
Tip
To complete this configuration, you may need to activate the online waiting service of your network manager.
Interface not up when pihole starts
If after booting domain name resolution does not work, and the
journal
shows an error message like:
pihole-FTL [...] FATAL ERROR in dnsmasq core: unknown interface wlo1
Then it might be that the interface name is wrong, or the interface is not up when pihole tries to run.
Check the interface name with
ip a
. If it is wrong, set
PIHOLE_INTERFACE
to the correct value in
/etc/pihole/setupVars.conf
If the interface is right, it may not be up when pihole is started (even if the systemd service depends on
After=network-online.target
). Set
DELAY_STARTUP
in
/etc/pihole/pihole-FTL.conf
to a value greater than 0 (expressed in seconds).
Reboot to verify the issue is fixed.
Reference
.
DNS cache evictions greater than zero
Tip
Setting the cache size to zero disables caching.
The cache size should be increased when this number is larger than zero. You can set the cache limit at
/etc/dnsmasq.conf
by uncommenting or adding the following setting with your desired number.
/etc/dnsmasq.conf
cache-size=12345
After changes have been performed,
restart
pihole-FTL.service
.
Note
There is no benefit in increasing this number unless the number of DNS cache evictions is greater than zero.
A larger cache will consume more memory on your node, leaving less memory available for other caches of your Pi-hole. If you push this number to the extremes, it may even be that your Pi-hole gets short on memory and does not operate as expected.
You can not reduce the cache size below 150 when DNSSEC is enabled because the DNSSEC validation process uses the cache.
Reference
.
Missing web GUI after upgrade to version 6
After upgrading from version 5 to 6, you may encounter error
404 Site not found
when accessing the web GUI. Nevertheless, the web GUI is likely still reachable at port
8080
.
Reason: Pi-hole now includes its own web server.
The previous lighttpd server was probably running on port
80
during the upgrade, thus setting
8080
as the default listening port. Also, if another web server was listening on port
8080
during the upgrade, the Pi-hole web GUI would be unavailable completely. See
[3]
.
After resolving the interfering web server, you can reset the web GUI's listening port to
80
by editing the
port
key in
[webserver]
section of
/etc/pihole/pihole.toml
, or through the new web GUI at
Settings > System > turn on Expert mode in the upper right corner > All settings > Webserver and API > webserver.port
.
See also
Pi-hole homepage
Pi-hole GitHub page
Pi-hole FTL GitHub page
Stopping systemd-resolved stub server opening port 53
Unbound performance issue