Pi-hole - ArchWiki

# Pi-hole

From ArchWiki
Jump to navigation Jump to search

Related articles

- dnsmasq
- Domain name resolution
- lighttpd
- Linux Containers
- nginx
- 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 (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 and a CLI interfaces.

Note: Pi-hole on Arch Linux is not officially supported by the Pi-hole project.

## Overview

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.

## Pi-hole server

### Installation

Install the pi-hole-serverAUR package.

### Configuration

#### FTL

It 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 (i.e. over multiple days/weeks/months) are stored on the file system `/etc/pihole/pihole-FTL.db` written out at a user-specified interval.

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

Note: Starting `pihole-FTL.service` is likelly going to fail. See #Failed to start Pi-hole FTLDNS engine.

#### Web interface

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.

##### Set-up PHP

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

    /etc/php/php.ini

    [...]
    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 lighttpd

Tip: You can use Nginx web server instead. See #Nginx instead of Lighttpd.

Install lighttpd and php-cgi.

Copy the package provided default config for Pi-hole:

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

Enable `lighttpd.service` and re/start it.

#### Update hosts file

The factual accuracy of this article or section is disputed.

Reason: Wouldn't it be the same result if you simply change from `127.0.0.1 localhost` to `127.0.0.1 localhost pi.hole`? More explanation about it here. (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 (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:

1. In 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 to change LAN DNS settings, so you might want to disable router's DHCP server and use Pi-Hole's built in DHCP server instead, as it is automatically configured to use Pi-Hole.

More information about making other devices use Pi-Hole can be found at upstream documentation.

Tip: Pi-Hole hosting device can also make use of Pi-Hole. Just change DNS settings to only IP address `127.0.0.1`.

## Pi-hole standalone

### Installation

Install the pi-hole-standaloneAUR package.

### Configuration

#### Timer

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.

#### FTL

See #FTL.

### Usage

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

## Usage

Both standalone and server versions can be controlled via CLI, but only server version can be controlled via web interface.

Note: Web interface is so powerful that you don't need CLI at all.

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

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

#### Temporarily disable Pi-hole

Pi-hole can be paused via CLI 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

## Tips & Tricks

### Password-protected web interface

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.

### Cloudflared DOH

Pi-Hole can be configured to use privacy-first DNS 1.1.1.1 by Cloudflare over HTTPS (DOH). Install cloudflared-binAUR and create the following file:

    /etc/cloudflared/cloudflared.yml

    proxy-dns: true
    proxy-dns-upstream:
     - https://1.0.0.1/dns-query
     - https://1.1.1.1/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

Then start and enable `cloudflared@cloudflared.service`. Now you can use `127.0.0.1#5053` as a DNS server in Pi-Hole.

### Optimise for solid state drives

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

    /etc/pihole/pihole-FTL.conf

    ...

    ## Database Interval
    ## How often do we store queries in FTL's database -minutes-?
    ## See: https://docs.pi-hole.net/ftldns/database/
    ## Options: number of minutes
    DBINTERVAL=60.0

    ...

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

### 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 your `/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 Pi-Hole DNS server. In the client configuration file, specify the following line:

    DNS = Pi-Hole-IP

See more information in WireGuard#Client config.

### Nginx instead of Lighttpd

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

Install nginx-mainline and php-fpm.

Edit `/etc/php/php-fpm.d/www.conf` and change the listen directive to the following:

    listen = 127.0.0.1:9000

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.

### 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: hosts-file.net, firebog.net and dbl.oisd.nl.

## Troubleshooting

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

### Failed to start Pi-hole FTLDNS engine

It might be that `systemd-resolved.service` already occupied port 53, which is required for `pihole-FTL.service`. To resolve this, stop and disable `systemd-resolved.service` and restart `pihole-FTL.service`.

### 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's still possible to use the previous dnsmasq config files, just ensure that `conf-dir=/etc/dnsmasq.d/,*.conf` in the original `/etc/dnsmasq.conf` is not commented out.

## See also

- Pi-hole homepage
- Pi-hole GitHub page
- Pi-hole FTL GitHub page
- Sky-Hole, the basic idea under Pi-hole standalone

Category:

- Domain Name System

Hidden category:

- Pages or sections flagged with Template:Accuracy