Jump to content

# Pi-hole

2 languages

- Italiano
- 日本語

From ArchWiki

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-ftlAUR (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-coreAUR 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:

1. Daily data are stored in RAM and are captured in real-time within `/run/log/pihole/pihole.log`
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.

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:

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.

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

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: log2ramAUR 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.

### Nginx instead of Lighttpd

This article or section is being considered for removal.

Reason: Seems unneded since Special:Diff/827503. (Discuss in Talk:Pi-hole)

This is unofficial, community-supported configuration[dead link 2025-03-15—HTTP 404]. Make sure that PHP is set up (see #Set up PHP[broken link: invalid section]) and lighttpd server is inactive.

Install nginx-mainline and php-fpm.

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 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 `fastcgi_pass` directive to the following:

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

Optionally, set `VIRTUAL_HOST` 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 `/usr` (and sub-directories).

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

    /etc/systemd/system/php-fpm.service.d/pihole.conf

    [Service]
    ReadWritePaths = /srv/http/pihole
    ReadWritePaths = /run/pihole-ftl/pihole-FTL.port
    ReadWritePaths = /run/log/pihole/pihole.log
    ReadWritePaths = /run/log/pihole-ftl/pihole-FTL.log
    ReadWritePaths = /etc/pihole
    ReadWritePaths = /etc/hosts
    ReadWritePaths = /etc/hostname
    ReadWritePaths = /etc/dnsmasq.d/01-pihole.conf
    ReadWritePaths = /proc/meminfo
    ReadWritePaths = /proc/cpuinfo
    ReadWritePaths = /sys/class/thermal/thermal_zone0/temp
    ReadWritePaths = /tmp

Then start and enable `nginx.service` and `php-fpm.service`.

### Additional blocklists

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

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

1. Check the interface name with `ip a`. If it is wrong, set `PIHOLE_INTERFACE` to the correct value in `/etc/pihole/setupVars.conf`
2. 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

Category:

- Domain Name System

Hidden categories:

- Pages or sections flagged with Template:Out of date
- Pages or sections flagged with Template:Style
- Sections flagged with Template:Remove
- Pages with dead links
- Pages with broken section links
- Pages or sections flagged with Template:Accuracy