19 KiB
Prerequisites
IP Addressing¶
Pi-hole needs a static IP address to properly function (a DHCP reservation is just fine).
Ports¶
| Service | Port | Protocol | Notes |
|---|---|---|---|
| pihole-FTL | 53 (DNS) | TCP/UDP | If you happen to have another DNS server running, such as BIND, you will need to turn it off in order for Pi-hole to respond to DNS queries. |
| pihole-FTL | 67 (DHCP) | IPv4 UDP | The DHCP server is an optional feature that requires additional ports. |
| pihole-FTL | 547 (DHCPv6) | IPv6 UDP | The DHCP server is an optional feature that requires additional ports. |
| pihole-FTL | 80 (HTTP) 443 (HTTPS) |
TCP | If you have another webserver already listening on port 80/443, then pihole-FTL will attempt to bind to 8080/8443 instead. If neither of these ports are available, pihole-FTL's webserver will be unavailable until ports are configured manually (see configuration option webserver.port) |
| pihole-FTL | 123 (NTP) | UDP | The NTP server is an optional feature that requires an additional port. |
Info
The use of pihole-FTL on ports 67 or 547 is optional, but required if you use the DHCP functions of Pi-hole. The use of port 123 is required when using pihole-FTL as NTP-Server.
Firewalls¶
Below are some examples of firewall rules that will need to be set on your Pi-hole server in order to use the functions available. These are only shown as guides, the actual commands used will be found with your distribution's documentation.
Because Pi-hole was designed to work inside a local network, the following rules will block the traffic from the Internet for security reasons. 192.168.0.0/16 is the most common local network IP range for home users but it can be different in your case, for example other common local network IPs are 10.0.0.0/8 and 172.16.0.0/12.
Check your local network settings before applying these rules.
IPTables¶
IPTables uses two sets of tables. One set is for IPv4 chains, and the second is for IPv6 chains. If only IPv4 blocking is used for the Pi-hole installation, only apply the rules for IP4Tables. Full Stack (IPv4 and IPv6) require both sets of rules to be applied. Note: These examples insert the rules at the front of the chain. Please see your distribution's documentation for the exact proper command to use.
IPTables (IPv4)
iptables -I INPUT 1 -s 192.168.0.0/16 -p tcp -m tcp --dport 80 -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p tcp -m tcp --dport 443 -j ACCEPT
iptables -I INPUT 1 -s 127.0.0.0/8 -p tcp -m tcp --dport 53 -j ACCEPT
iptables -I INPUT 1 -s 127.0.0.0/8 -p udp -m udp --dport 53 -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p tcp -m tcp --dport 53 -j ACCEPT
iptables -I INPUT 1 -s 192.168.0.0/16 -p udp -m udp --dport 53 -j ACCEPT
iptables -I INPUT 1 -p udp --dport 67:68 --sport 67:68 -j ACCEPT
iptables -I INPUT 1 -p udp --dport 123 -j ACCEPT
iptables -I INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
IP6Tables (IPv6)
ip6tables -I INPUT -p udp -m udp --sport 546:547 --dport 546:547 -j ACCEPT
ip6tables -I INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
FirewallD¶
Using the --permanent argument will ensure the firewall rules persist reboots. If only IPv4 blocking is used for the Pi-hole installation, the dhcpv6 service can be removed from the commands below. Finally --reload to have the new firewall configuration take effect immediately.
firewall-cmd --permanent --add-service=http --add-service=https --add-service=dns --add-service=dhcp --add-service=dhcpv6 --add-service=ntp
firewall-cmd --reload
ufw¶
ufw stores all rules persistently, so you just need to execute the commands below.
IPv4:
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 53/tcp
ufw allow 53/udp
ufw allow 67/tcp
ufw allow 67/udp
ufw allow 123/udp
IPv6 (include above IPv4 rules):
ufw allow 546:547/udp
Post-Install
Making your network take advantage of Pi-hole¶
Once the installer has been run, you will need to configure your router to have DHCP clients use Pi-hole as their DNS server which ensures all devices connected to your network will have content blocked without any further intervention.
If your router does not support setting the DNS server, you can use Pi-hole's built-in DHCP server; just be sure to disable DHCP on your router first (if it has that feature available).
As a last resort, you can manually set each device to use Pi-hole as its DNS server.
Making your Pi-hole host use Pi-hole¶
Pi-hole will not be used by the host automatically after installation. To have the host resolve through Pi-hole and your configured blocking lists, you can make the host use Pi-hole as upstream DNS server:
Warning
If your Pi-hole host is using Pi-hole as upstream DNS server and Pi-hole fails, your host loses DNS resolution. This can prevent successful repair attempts, e.g. by pihole -r as it needs a working internet connection.
If your OS uses dhcpcd for network configuration, you can add to your /etc/dhcpcd.conf
static domain_name_servers=127.0.0.1
Adding your local user to the 'pihole' group¶
Pi-hole v6 uses a new API for authentication. All CLI commands use this API instead of e.g. direct database manipulation. If a password is set for API access, the CLI commands also need to authenticate. To avoid entering the password everytime on CLI, Pi-hole allows users which are members of the 'pihole' group to authenticate without manually entering the password (this can be disabled by setting webserver.api.cli_pw to false.)
To add your local user to the 'pihole' group use the following command
For Debian/Ubuntu/Raspberry Pi OS/Armbian/Fedora/CentOS
sudo usermod -aG pihole $USER
For Alpine
sudo addgroup pihole $USER