Skip to content

Instantly share code, notes, and snippets.

@fellipec
Last active March 13, 2025 14:02
Show Gist options
  • Save fellipec/a22581a9c1d6faf2402c83c138bce479 to your computer and use it in GitHub Desktop.
Save fellipec/a22581a9c1d6faf2402c83c138bce479 to your computer and use it in GitHub Desktop.
Pi-Hole DHCP configuration guide

Introduction

Pi-Hole's primary function is to be a DNS server with the ability to block domains, usually used for advertising, tracking or other unwanted sites. It also features a built-in DHCP Server.

Usually, your router will also have a built-in DHCP server, pre-configured from factory, and for most users this is perfectly fine. But in some cases you may want to run another DHCP server instead of relying on your router's one. This guide will help you understand how a DHCP server works and how to configure it without disturbing your network.

If you already know the networking basics, you can cut to the chase and read just the configuration part

Understanding the IP Addressing

To understand why we need a DHCP server, we first need to understand how IP addressing works. In a network running the TCP/IP protocol (the internet protocol) each connected machine, also called a network node or host, must have its IP address to communicate with the other machines. In the version 4 (v4) of the TCP/IP protocol, each address is made up 4 numbers up to 8 bits each (in decimal, from 0 to 255) separated by dots:

IP Address : 192.168.0.5

One of the main characteristics of the IP protocol is the ability to interconnect several different networks. To accomplish this, the IP address are organized in subnets. So a part of the address will be the network number or routing prefix and the other part will be the host identifier. To identify each of those parts in the IP address, we need a network mask or subnet mask, that looks just like an IP address, four numbers separated by dots:

IP Address  : 192.168.0.5
Subnet mask : 255.255.255.0

This mask means that the 192.168.0 part is the network number, while the .5 is our host. In another example, 10.0.0.1 with the mask 255.0.0.0 means that 10. is the network number and 0.0.1 is our host. Subnetting is its own rabbit hole, and if you want to learn more about it, there are other guides like this one. For our purposes, what we need to know is that to computers in the same network talk to each other, they must be in the same subnet. Let's consider 3 computers with the following configuration:

Computer A
IP Address  : 192.168.0.5
Subnet mask : 255.255.255.0

Computer B
IP Address  : 192.168.0.42
Subnet mask : 255.255.255.0

Computer C
IP Address  : 172.16.13.21
Subnet mask : 255.255.0.0

The computers A and B could talk to each other without any problem, but the computer C will not be able to join the other two, because it have an IP address belonging to another subnet.

Routing

As we know, in the Internet we can access computers, or hosts in different networks around the world (hence the name, Internet). To accomplish this goal we need a device called router. A router has at a minimum two network interfaces, that means, it is connected at the same time to at least two different networks. Usually in home and small office setups, the router is connected to the local network and to the Internet Service Provider (ISP) network. In large business, ISPs, data-centers, telecoms and other, enterprise-class routers can be connected to dozens, if not hundreds of different networks. All those routers together are the heart of what makes the Internet work.

Inside each router, there is a routing table that is a table describing how it can access the other networks, not only the ones connected directly to itself, but others that are connected to other routers too. Such table can look like this:

Destination Netmask Gateway Interface
0.0.0.0 0.0.0.0 192.168.0.1 192.168.0.35
10.11.12.0 255.255.255.0 10.11.12.4 10.11.12.4
192.168.0.0 255.255.255.0 192.168.0.35 192.168.0.35
192.168.122.0 255.255.255.0 192.168.122.1 192.168.122.1

In fact not only inside each router, but on each network host, there is such table. What matters to us in this guide is the first line. The 0.0.0.0 address means every other network. So when this router doesn't know where to find a network (because is not explicit informed on the routing table) it will foward it to the 192.168.0.1 address in this example, in hope this other router (also called gateway) knows where to find the destination. This router that will deal with anything our machine doesn't knows how to find is our default gateway.

So, a more complete IP configuration will have not only the address and subnet mask, but also a default gateway:

IP Address     : 192.168.0.5
Subnet mask    : 255.255.255.0
Default gateway: 192.168.0.1

DNS

Using only IP address works fine. But we, humans, usually don't want to remember an address like 172.217.29.78, but would have no trouble remembering google.com. The service that translates google.com into 172.217.29.78 is the Domain Name System (DNS). DNS servers have tables matching domain names (the human easy to remember names) to numerical IP address. The Pi-hole is a DNS Server software, with a bonus feature of not working (blocking) with domain names that are involved in ads, tracking or other unwanted behaviors.

We can't simply install the Pi-Hole (or any other DNS server) and expect that the other computers on the network know it is there. We need to inform them somehow that the Pi-Hole machine is a DNS server. To do this we just type its IP Address in the configuration. So a complete configuration for a computer in our example network would be:

IP Address        : 192.168.0.5
Subnet mask       : 255.255.255.0
Default gateway   : 192.168.0.1
Primary DNS Server: 192.168.0.2

image

So 192.168.0.5 is our computer, 192.168.0.1 is our router and 192.168.0.2 is the Pi-Hole computer (Raspberry Pi or any other machine you decide to install it). You can configure this manually on all your computers on the network, taking care to not repeat the address, and everything will work. But this is tedious and some devices, like smart light bulbs for example, don't have a way to manually configure addresses.

DHCP

The Dynamic Host Configuration Protocol (DHCP) solves this problem. A DHCP server will listen on the network for any hosts asking for an IP address, and the DHCP server will reply, leasing an address, with every other configuration we already discuss, to the asking machine. Any DHCP server will need to know which address it can lease to asking hosts, and the associated configuration, like this:

Start IP Address  : 192.168.0.20
End IP Address    : 192.168.0.90
Subnet mask       : 255.255.255.0
Default gateway   : 192.168.0.1
Primary DNS Server: 192.168.0.2

So, when any computer asks for address, this server will pick any number from 192.168.0.20 to 192.168.0.90 and send, with the rest of the config and will inform how long the computer can use that address. This period of time is the lease time.

When half of the lease time has passed, the computer will ask the DHCP server to renew that lease. If for some reason it can't be renewed (DHCP server is off-line for example) the computer can use the IP until the end of the lease, when it will lose the address. The server also consider that any leased address that was not renewed after the time expires to be available to be leased to other computer.

With a DHCP server in the network, you can configure the addresses at a single point, and all hosts on the network will automatically follow the configuration, making the task way easier, and enabling simpler devices without an user interface to have addresses assigned to them. In home or small office networks usually the router have a DHCP Server pre-configured, making easier for users to use the network.

Using Pi-Hole as the DHCP Server

To the majority of users, the router DHCP server is perfectly fine and convenient. The router is a low-power device that is on all the time that the network is available, and usually have a nice interface that allows the user to change its configuration to fit the needs. But sometimes this is not the case. Some routers have limited configuration options, while others the ISP can lock the configuration, preventing the user to change the DNS server to the Pi-Hole. Or the user just have another reason to prefer not using the router's built-in DHCP function. Pi-Hole has its own DHCP Server, which by default is disabled, in order to not conflict with the existing one.

The first step in using the Pi-Hole as a DHCP server is ensuring its own IP address is manually configured. How to do this depends on the OS, but on Raspberry Pi OS you can find a very comprehensive guide here.

Note that this manual address and subnet mask should be in the same subnet of your router, so the Pi-Hole can talk to it and to the other hosts in the network. Also the default gateway should be your router address. The DNS server if the same IP of the Pi-Hole, so the Pi-Hole machine will use itself to translate domain names into IPs.

Once your Pi-Hole machine have an IP address manually configured and working, you can proceed. To test if your manually configured IP is working, you can type http:// followed by the address and followed by /admin to access the Pi-Hole web interface. In our example it would be http://192.168.0.2/admin.

image

Now you can click on the Settings menu and then on the DHCP tab. Check the box DHCP server enabled and now you can fill in the blanks. The first two fields are the start and end IP address that Pi-Hole should assign to the machines. As a rule of thumb, I start from an address ending in 10, leaving the address from 1 to 9 for the router (which usually ends in 1) the Pi-Hole itself and any other machine you may need to have a manual IP. The end address you can use any larger number, but mind that it should be enough for all your hosts! We often don't count everything, as an example, in a house where live two people, I've counted 2 TVs, 2 cell phones, a stream stick, a smart speaker, a few smart light bulbs and plugs, ebook reader, Wi-Fi enabled printer and of course the computer and a laptop. That is more than 20 hosts! If you want to be safe, the end address could finish in 254 (255 is reserved for broadcasts).

The next field is the Default Gateway, which Pi-Hole kindly labels Router. It can't be more straight foward, you just type the IP address of your router. This is the same IP address you use to enter in the router's configuration, which will be important soon. Finally you have the subnet mask, which Pi-Hole label Netmask. If you leave this field blank, Pi-Hole will just use the same of its own IP address. But you can type it there, if you want.

Note that there is no DNS server to inform. The Pi-Hole assumes that you'll want to use itself as the DNS server and will set this up for you.

There is check box labeled Enable additional IPv6 support (SLAAC + RA). If your network have IPv6 support, checking this box should be enough to make Pi-Hole advertise itself to IPv6 hosts. Note that IPv6 (The next version of the IP protocol) have other addressing configuration schemes that were not discussed in this guide.

You can click in Save and Apply and then click on the Settings menu and System. If you enable the Expert menu on the top right of the screen, you'll see a button to Restart DNS Resolver on the bottom part. Click on it and the Pi-Hole will restart (the Pi-Hole software, not the machine) and the DHCP Server will be active.

Now you'll need to disable the DHCP Server from your router. Each router has a different configuration, but you should look for the LAN settings (Local Area Network) and there you should find the DHCP settings. In this example, I've to click first on Advanced and then Network to find the LAN screen. Check your router manual if you need. Note that this example router have no field to configure the DNS server that its DHCP server will send to the network hosts, being a fine example of where using the Pi-Hole itself is a better solution.

image

Now save the route config and reboot it. For a while nothing will happen, as the computers will still use IPs leased from the router's DHCP server. But when those leases expire, they will have to ask for a new address, and then the Pi-Hole should provide them. You can also force this to happen sooner. In Windows you can use the command:

IPCONFIG /RELEASE
IPCONFIG /RENEW

On Mac, the commands should be

sudo ipconfig set en0 BOOTP
sudo ipconfig set en0 DHCP

On Linux it depends if you use Network Manager, systemd-neworkd, dhclient:

# If using dhclient

sudo dhclient -r
sudo dhclient

# If using Network Manager

sudo nmcli device disconnect eth0
sudo nmcli device connect eth0

# If using systemd-networkd

sudo networkctl renew eth0

# Using ifconfig 

sudo ifconfig eth0 down
sudo ifconfig eth0 up

# All examples assume the interface is eth0

You may want to check the right command for your distribution, or alternatively, in any OS, rebooting the machine should do the trick too.

Monitoring the DHCP server

Scrolling down in the Pi-Hole DHCP tab, you will see the Currently active DHCP leases table. As soon computers start to ask for IP Address, this table will show the address that was leased, the name of the machine, the physical address (also know as MAC Address), and for how long the IP will be leased to that host.

When you see your hosts in that table, you can be sure your Pi-Hole DHCP server to be working well. Congratulations!

Pi-Hole DHCP configuration guide © 2025 by Luiz Fellipe Carneiro is licensed under Creative Commons Attribution 4.0 International. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/

@PHDiniiz
Copy link

Fala, Felipe!

Cara, tentei configurar o servidor DHCP aqui no Pi-Hole mas não vai de jeito nenhum. Quando desativo do roteador e ativo o DHCP no Pi-Hole, atribui IP inválido (169.254.172.225/255.255.0.0) e nem chega no PH. Ele está com ip fixo já (192.168.1.3) onde está rodando um DNS sem problemas. Já coloquei, inclusive, o PH em bridge e nada. Alguma questão que talvez eu tenha esquecido?

Screenshot_1
Screenshot_2

@fellipec
Copy link
Author

Este IP na faixa 169.254.x.x não vem do DHCP do Pi-Hole. Esse é um endereço de auto-configuração que a máquina se dá sozinha quando não encontra um DHCP e quando não tem endereço manual atribuído.

Por esse sintoma, podemos concluir que provavelmente o DHCP não está comunicando-se com a rede por algum motivo. Pode ser duas coisas, ou um firewall, se for o caso você precisa liberar as portas 67 e 68 UDP:

iptables:

# iptables -A INPUT -p udp --dport 67:68 --sport 67:68 -j ACCEPT

ufw:

# ufw allow bootps comment 'Allow 67/UDP'
# ufw allow bootpc comment 'Allow 68/UDP'

ou você pode estar rodando no docker. Aí nesse caso tem que fazer alguma configuração para permitir essas portas também, mas aí eu não conheço de docker.

@marcosvfc
Copy link

Fala, Felipe!

Cara, tentei configurar o servidor DHCP aqui no Pi-Hole mas não vai de jeito nenhum. Quando desativo do roteador e ativo o DHCP no Pi-Hole, atribui IP inválido (169.254.172.225/255.255.0.0) e nem chega no PH. Ele está com ip fixo já (192.168.1.3) onde está rodando um DNS sem problemas. Já coloquei, inclusive, o PH em bridge e nada. Alguma questão que talvez eu tenha esquecido?

Screenshot_1 Screenshot_2

Onde você roda o Pihole? Qual máquina? Está por trás de um Firewall?

@uurf
Copy link

uurf commented Mar 13, 2025

Very informative and thorough.

Maybe it could cover a significant reason to have the pi-hole perform DHCP duties - tying requests to specific hosts on certain systems like Verizon FiOS routers. (In their case you can't specify the pihole IP as an IP to be leased to the devices, so all requests appear to come from the FiOS Router itself).

some spelling corrections:
it's - the contraction of it is
its - possessive form of it

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment