arch-wiki-md-repo
Version:
All arch-wiki articles in markdown format, updated every two days.
319 lines (204 loc) • 12.4 kB
Markdown
Related articles
* [Dnsmasq](/index.php/Dnsmasq "Dnsmasq")
* [Lighttpd](/index.php/Lighttpd "Lighttpd")
* [Linux_Containers](/index.php/Linux_Containers "Linux Containers")
* [Nginx](/index.php/Nginx "Nginx")
* [OpenVPN](/index.php/OpenVPN "OpenVPN")
[Pi-hole](https://pi-hole.net/) is a [DNS sinkhole](https://en.wikipedia.org/wiki/DNS_sinkhole "wikipedia:DNS sinkhole") that compiles a blocklist of domains known to host advertisements and malware from multiple third-party sources. Pi-hole uses [dnsmasq](/index.php/Dnsmasq "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.
## Contents
* [1 Pi-hole server](#Pi-hole_server)
* [1.1 Installation](#Installation)
* [1.2 Initial configuration](#Initial_configuration)
* [1.2.1 Dnsmasq](#Dnsmasq)
* [1.2.2 Web server](#Web_server)
* [1.2.2.1 Lighttpd](#Lighttpd)
* [1.2.2.2 Nginx](#Nginx)
* [1.2.3 FTL](#FTL)
* [1.3 Making devices use Pi-hole](#Making_devices_use_Pi-hole)
* [1.3.1 Troubleshooting](#Troubleshooting)
* [1.4 Using Pi-hole together with OpenVPN](#Using_Pi-hole_together_with_OpenVPN)
* [1.5 Password-protect web interface](#Password-protect_web_interface)
* [2 Pi-hole Standalone](#Pi-hole_Standalone)
* [2.1 Installation](#Installation_2)
* [2.2 Initial configuration](#Initial_configuration_2)
* [2.2.1 Dnsmasq](#Dnsmasq_2)
* [2.2.2 Configuring host name resolution](#Configuring_host_name_resolution)
* [2.2.2.1 Manually](#Manually)
* [2.2.2.2 Openresolve](#Openresolve)
* [3 Using Pi-hole](#Using_Pi-hole)
* [3.1 Pi-hole DNS management](#Pi-hole_DNS_management)
* [3.2 Forced update of ad-serving domains list](#Forced_update_of_ad-serving_domains_list)
* [3.3 Temporarily disable Pi-hole](#Temporarily_disable_Pi-hole)
* [4 See also](#See_also)
## Pi-hole server
### Installation
[Install](/index.php/Install "Install") the [pi-hole-server](https://aur.archlinux.org/packages/pi-hole-server/) package.
### Initial configuration
#### Dnsmasq
Ensure that the following line in `/etc/dnsmasq.conf` is not commented out:
```
conf-dir=/etc/dnsmasq.d/,*.conf
```
**Note:** If you already use dnsmasq, since Pi-hole FTL version 3.0 the dnsmasq parameter `log-queries=extra` is required.
[Enable](/index.php/Enable "Enable") `dnsmasq.service` and re/start it.
#### Web server
Optionally choose a web server for the Pi-hole web interface.
**Note:** Pi-hole does not strictly require a web interface as many commands are possible via the CLI interface.
Example config files that work out-of-the-box are provided for both [lighttpd](https://www.archlinux.org/packages/?name=lighttpd) and [nginx](https://www.archlinux.org/packages/?name=nginx). Other web servers can also run the WebUI, but are currently unsupported.
Install [php-sqlite](https://www.archlinux.org/packages/?name=php-sqlite) and enable the relevant extensions detailed here:
`/etc/php/php.ini`
```
[...]
extension=pdo_sqlite
[...]
extension=sockets
extension=sqlite3
[...]
```
For security reasons, one can populate the [PHP open_basedir](/index.php/PHP#Configuration "PHP") 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
```
##### Lighttpd
[Install](/index.php/Install "Install") [lighttpd](https://www.archlinux.org/packages/?name=lighttpd) and [php-cgi](https://www.archlinux.org/packages/?name=php-cgi).
Copy the package provided default config for Pi-hole:
```
# cp /usr/share/pihole/configs/lighttpd.example.conf /etc/lighttpd/lighttpd.conf
```
[Enable](/index.php/Enable "Enable") `lighttpd.service` and re/start it:
##### Nginx
[Install](/index.php/Install "Install") [nginx-mainline](https://www.archlinux.org/packages/?name=nginx-mainline) and [php-fpm](https://www.archlinux.org/packages/?name=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](/index.php/Enable "Enable") `nginx.service` `php-fpm.service` and re/start them.
#### FTL
The [Pi-hole FTL engine](https://github.com/pi-hole/FTL) ([pi-hole-ftl](https://aur.archlinux.org/packages/pi-hole-ftl/)) is a dependency of the web interface.
FTL is 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:
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.
**Tip:** If Pi-hole is running on a [Solid State Drive](/index.php/Solid_State_Drive "Solid State Drive") (single-board computers SD, SSD, M.2/NVMe device, etc...) it is recommended to set the `DBINTERVAL` value to at least 60.0 to minimize writes to the database.
See [the GitHub Readme](https://github.com/pi-hole/FTL#ftls-config-file) for how to configure FTL.
`pi-hole-ftl.service` is statically enabled; re/start it.
### Making devices use Pi-hole
[The upstream documentation](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245) documents four different methods:
1. Define Pi-hole's IP address as the only DNS entry in the router
2. Advertise Pi-hole's IP address via dnsmasq in the router (if supported)
3. Manually configure each device to use the Pi-hole as their DNS server
4. [Use Pi-hole's built-in DHCP server](https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to/3026)
#### Troubleshooting
* If you setup a DHCP-based method and ad blocking does not work on a device, it might still have an outdated DHCP lease. If you do not know how to renew your DHCP lease, try restarting the device.
* A simple check to see that the router is setup correctly is to first renew a DHCP lease, then inspect the contents of `/etc/resolv.conf` on a Linux client. One should see the IP address of the Pi-hole box, not the IP address of the router.
* If you are having problems with method 2, try disabling the `dns-rebind` feature on the router (if present).
* If `pihole -g` or updating lists from the web UI fail with `DNS Resolution is Currently Unavailable`, adding `127.0.0.1 pi.hole` to `/etc/hosts` [may fix it](https://github.com/pi-hole/pi-hole/issues/1800)
### Using Pi-hole together with OpenVPN
An [OpenVPN](/index.php/OpenVPN "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`.
### Password-protect web interface
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.
## Pi-hole Standalone
The Archlinux Pi-hole Standalone variant is born from the need to use Pi-hole services in a mobile context. [Sky-hole article](http://dlaa.me/blog/post/skyhole) was inspirational.
### Installation
[Install](/index.php/Install "Install") the [pi-hole-standalone](https://aur.archlinux.org/packages/pi-hole-standalone/) 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](/index.php/Edit "Edit") it or preventing from being executed by [masking](/index.php/Systemd#Using_units "Systemd") it. You need to manually start `pi-hole-gravity.timer` or simply reboot after your configuration is finished.
### Initial configuration
#### Dnsmasq
Ensure that the following line in `/etc/dnsmasq.conf` is uncommented:
```
conf-dir=/etc/dnsmasq.d/,*.conf
```
[Enable](/index.php/Enable "Enable") `dnsmasq.service` and 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.
##### Manually
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`:
`/etc/resolv.conf`
```
[...]
nameserver 127.0.0.1
```
**Note:** No other `nameserver` items need to be present in the config file.
##### Openresolve
It is likely that is the [openresolv](https://www.archlinux.org/packages/?name=openresolv) service to handle `/etc/resolv.conf` if you use a network connection manager such as [netctl](/index.php/Netctl "Netctl") or [NetworkManager](/index.php/NetworkManager "NetworkManager"). If it is your case, you must force [openresolv](https://www.archlinux.org/packages/?name=openresolv) to use **localhost** as name server.
Edit `/etc/resolvconf.conf` to uncomment the name_servers line:
`/etc/resolvconf.conf`
```
[...]
name_servers=127.0.0.1
```
and update resolvconf:
```
# resolvconf -u
```
## Using Pi-hole
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](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](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](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*.
## See also
* [Pi-hole homepage](https://pi-hole.net/)
* [Pi-hole GitHub page](https://github.com/pi-hole/pi-hole)
* [Pi-hole FTL GitHub page](https://github.com/pi-hole/FTL)
* [Sky-Hole, the basic idea under Pi-hole standalone](http://dlaa.me/blog/post/skyhole)