Pi-hole blocks adverts and trackers for every device in your house at once, phones and smart TVs included, with nothing to install on them. You point your network's DNS at it, and it quietly refuses to look up the addresses adverts come from.
On this page
- At a glance
- What it's good for
- Signing in
- Getting it onto port 53
- Pointing your devices at it
- Names for your apps
- Away from home
- The server's own DNS
- Where Pi-hole gets its answers
- Good to know
- Addresses and ports
- Settings
- In its config file
- Tools
- Works with
- Privacy and security
- What leaves this server
- What LibrePortal turns off
- Sources
- Under the hood
Good to know before you install
Turning on 'Route this server's own DNS through Pi-hole' sends the whole server's lookups through Pi-hole, so its filtering and privacy cover the host as well as the devices you point at it. On a machine running a VPN such as Mullvad that manages its own DNS, or one that needs split DNS, it can conflict, so it is best on a dedicated or headless box. It is off by default and turning it off, or uninstalling Pi-hole, puts the server's resolver back exactly as it was.
At a glance#
- What it is
- DNS-based Ad Blocking Networking
- Where it opens
- Admin Interface
On its own port at
http://your-server:port - Updates
- Automatic A backup is taken first, and it rolls back if the update fails
- Backups
- Included Part of the daily backup when that's switched on
- Copies
- One per server
What it's good for#
Every time a device opens a website or an app loads an advert, it first asks a DNS server to turn a name like ads.example.com into an address. Pi-hole is that DNS server. It answers normal questions as usual and gives no useful answer for names on its blocklists, so the advert or tracker never loads. Because it works at the network level, it covers devices you can't install an ad blocker on, like a TV or a games console, and it shows you which devices are asking for what.
It also makes your server's app names work at home. LibrePortal adds a record to Pi-hole for each app's address, so names like nextcloud.example.com or nextcloud.lan.internal lead straight to your server on your own network (more on that below).
Pi-hole or AdGuard Home?
AdGuard Home does the same job, and LibrePortal treats them alike: same port handling, same local names, same DNS updater. Pi-hole has a long history, a big community around its blocklists and a very detailed query log. AdGuard Home is a single program with more built in, such as encrypted DNS options and per-device settings, and LibrePortal can give it one wildcard entry for all your app names where Pi-hole needs one per app. Either is a good choice. Only install one: only one can have port 53.
Signing in#
Pi-hole's admin page has a password and no username. LibrePortal sets it at install, so there's never a moment when the page is open without one. The password is in the Login Details shown when the install finishes, on the PiHole Login card; press Welcome on the app's page to see it again. The Admin Interface button opens the page.
LibrePortal hands Pi-hole its password, and a few other settings, each time it starts, so Pi-hole shows those as fixed in its own settings pages. Use the one from Login Details.
To check: how to change Pi-hole's admin password on LibrePortal: it is set from CFG_PIHOLE_ADMIN_PASSWORD_1 via FTLCONF_webserver_api_password on every start, and is not on the Config tab
Getting it onto port 53#
Devices only ever look for DNS on port 53. A router hands out an address for DNS, never a port, and phones and computers don't take a port in their DNS settings either. So Pi-hole has to have port 53 on your server, or it filters nothing for anyone.
LibrePortal tries to give it 53. If something else already has it, the install doesn't fail: Pi-hole's DNS goes on another port for now, and the install says what holds 53 and how to free it. The usual culprits are:
- On Ubuntu, systemd-resolved. Ubuntu's own local DNS helper sits on port 53. The install's message says how to turn that listener off.
- AdGuard Home, if it's installed. Only one DNS app can have 53; remove the one you don't want.
Once 53 is free, open Pi-hole's Tools tab and run Use Port 53 for DNS. It moves Pi-hole onto 53 and restarts it, which pauses lookups through it for a few seconds. If 53 is still taken, it says who by and changes nothing.
Why DNS is private
Pi-hole's DNS ports are private: only your trusted places and your devices on the LibrePortal VPN can use them. A DNS server on port 53 that answers the whole internet is called an open resolver, and they're found within hours and abused to flood other people's networks. Use Port 53 for DNS makes the DNS ports private on the way even if you'd made them public.
Pointing your devices at it#
The easy way is your router. In its settings, look for the DNS server it hands out (usually under LAN, DHCP or network settings) and set it to your server's address on your network, for example 192.168.1.50. Devices pick it up the next time they reconnect, or when you restart them. The end of Pi-hole's install prints the exact address to use.
If your router doesn't let you change it, set DNS on each device instead, in its Wi-Fi or network settings. Either way, open Pi-hole's admin page afterwards: the query log should fill up with your devices' lookups.
Give the router only Pi-hole
If you put Pi-hole first and a public DNS server second, many devices use both, and adverts slip through the second. Give the router just your server's address. The catch is that when the server is off, name lookups stop working at home. Worth knowing before you restart the server during a family film.
Pi-hole also asks your router for the names of the devices on your network, so the query log can say "Kitchen tablet" rather than just an address. LibrePortal sets that up from your router's address when it installs Pi-hole.
Names for your apps#
With a domain, LibrePortal adds each app's name to Pi-hole, pointing at your server's address on your network. At home, cloud.example.com then goes straight to your server instead of out to the internet and back, which many home routers can't do. With local names switched on, the .lan.internal names are added the same way, and they work on every device that uses Pi-hole with nothing else to set up.
Pi-hole gets one record per app, so LibrePortal updates the list whenever you install or remove one. Anything you add yourself under Pi-hole's own local DNS records is left alone. You can also keep records of your own with libreportal dns records add, and LibrePortal never prunes them: see DNS for your VPN.
Away from home#
By default the LibrePortal VPN doesn't hand your devices a DNS server, so when you're out, your phone keeps using whatever DNS its mobile network or Wi-Fi gives it, and Pi-hole doesn't filter for it. But if you turn on Use this server's names for a phone on the VPN, all its lookups go through the server, and Pi-hole filters it while you're out too. That option is offered only while Pi-hole (or AdGuard) is installed, precisely so there's something to answer. See names over the VPN and DNS for your VPN.
The server's own DNS#
Pi-hole filters for the devices that ask it. By default the server it runs on isn't one of them: it keeps using the DNS it was set up with, so Pi-hole going down can never leave the server itself unable to look anything up.
You can change that. Route this server's own DNS through Pi-hole (in Pi-hole's advanced settings on the Config tab) sends the server's own lookups through Pi-hole too, so the blocking and privacy cover the server, not just your devices. It's off to start with, and reversible: turn it off, or uninstall Pi-hole, and the server's DNS goes back exactly as it was. LibrePortal points it at Pi-hole on the server's own loopback address, never its network address, so a full-tunnel VPN can't pull the answers through the tunnel, and it checks Pi-hole really answers before switching anything over.
Best on a box that does nothing else
Routing the whole server's DNS through Pi-hole can clash with a VPN or with split DNS. So it suits a dedicated or headless box, where Pi-hole is the server's whole job, better than a machine you also use as a desktop. On an everyday machine, leave it off and point your other devices at Pi-hole instead.
Refresh Local DNS on the Tools tab is a different thing: it re-applies Pi-hole's records for your app names. It doesn't touch the server's own resolver, and you rarely need it; LibrePortal refreshes those records by itself whenever you install an app or change a domain.
Where Pi-hole gets its answers#
For names it doesn't block, Pi-hole asks Quad9, a privacy-minded public resolver, and checks the answers with DNSSEC. If you'd rather no outside resolver saw your lookups at all, install Unbound: it looks names up itself, starting from the internet's root servers. Unbound is offered beside Pi-hole under Also install, and Pi-hole's upstream is set to auto, which means Unbound while it's installed and Quad9 when it isn't. So installing Unbound is all it takes, and removing it puts Quad9 back.
Good to know#
- Blocklists, allow lists and groups are all managed in Pi-hole's own admin page. It starts with its default list; add others there.
- DHCP is off. Pi-hole can hand out network addresses instead of your router, but LibrePortal leaves that port switched off. Let your router carry on doing it.
- Updates are automatic, with a backup first. Backups include Pi-hole's settings, lists and query history.
- One per server, and it stays on the main disk: other parts of LibrePortal find it by its folder.
- Pi-hole Web Theme on the Config tab changes how its admin page looks, nothing more.
Addresses and ports#
Pi-hole has 6 ports. LibrePortal picks a free port number for each when you install, so yours will differ from anyone else's. The Config tab's Network section shows them, and the app's Open button uses the right one.
| What it is | Who can reach it | With a domain |
|---|---|---|
| Admin Interface | Trusted places only | Port only |
| DNS Server (TCP) TCP | Trusted places only | Port only |
| DNS Server (UDP) UDP | Trusted places only | Port only |
| HTTPS Interface TCP | Off until you turn it on | Port only |
| DHCP Server (enable to let Pi-hole hand out leases) UDP | Off until you turn it on | Port only |
| Metrics Exporter (sidecar, docker-network only) TCP | Off until you turn it on | Port only |
Settings#
These are Pi-hole's own settings on its Config tab. The settings every app shares, like backups, updates and where its data lives, are explained in App pages and settings.
| Setting | What it does | Starts as |
|---|---|---|
| Pi-hole Web Theme | Visual theme for the Pi-hole web interface Choices: Default Dark, Default Light, Default Auto, High Contrast, High Contrast Dark, High Contrast Light, High Contrast Auto, LCARS, LCARS Color |
default-dark |
In its config file#
A few more aren't on the Config tab yet. They live in the app's config file, described here so you know they exist. How to change them.
| Setting | What it does | Starts as |
|---|---|---|
NameCFG_PIHOLE_DISPLAY_NAME |
What this app is called on your dashboards. Leave empty to use its usual name | Empty |
Show on the LibrePortal DashboardCFG_PIHOLE_SHOW_ON_DASHBOARD |
Whether this app gets a shortcut on the front page of the LibrePortal WebUI, separate from any Dashy dashboard Choices: true, false |
false |
Route this server's own DNS through Pi-hole AdvancedCFG_PIHOLE_HOST_DNS |
Also sends the server's own lookups through Pi-hole, so its blocking and privacy cover the host; best on a dedicated/headless box (see the note). Choices: true, false |
false |
Upstream DNSCFG_PIHOLE_UPSTREAM_DNS |
auto uses the Unbound app when it is installed, else Quad9; or your own, e.g. 1.1.1.1;1.0.0.1 | auto |
Queries and statistics kept forCFG_PIHOLE_STATS_DAYS |
How many days Pi-hole keeps the list of names each device asked for, and the charts built from it. Shorter is more private; the query log is how you see what got blocked. Choices: 1, 7, 30, 91 |
7 |
Tools#
Pi-hole's Tools tab has 2 buttons for jobs you'd otherwise need a terminal for. Each one runs as a task, so you can watch it on the Tasks page and read what it did. More about Tools.
Move Pi-hole's DNS server to port 53, where devices and routers can use it. Only works once nothing else on this server holds port 53.
Re-apply Pi-hole's local DNS rewrites so this server's app names resolve to it on your network. Does not change the server's own DNS resolver.
Works with#
These are the other apps Pi-hole knows how to work with. Once it's installed, its page shows the same list with whether each one is connected. How this works.
- Upstream resolver: Looks names up through Unbound, so no outside resolver sees them. LibrePortal sets this up by itself when both are installed.
- Grafana: Shows dashboards for the apps that have one. works with every app
- Home Assistant: Shows ad-blocking statistics and a switch to pause it.
- Prometheus: Collects metrics from the apps that can export them. works with every app
- Uptime Kuma: Watches your apps and shows when one goes down. works with every app
Privacy and security#
Worth knowing Pi-hole keeps your DNS history on your server. It downloads blocklists weekly, and sends lookups to a public resolver unless Unbound is installed beside it.
What leaves this server#
- Blocklists are downloaded weekly from public sources
- Your lookups go to Quad9 unless Unbound is installed
- Release checks reach GitHub to show update notices
What LibrePortal turns off#
Nothing needed switching off.
Licence: EUPL-1.2. Audited: 21 October 2026. See the privacy of every app and the Promise.
Sources#
Under the hood#
- It runs this image:
pihole/pihole:2026.10.0@sha256:d34134716fc32038b052a8674c7c6879e0ff21f0e6d8af345166fffa2c27c113. - It can sit behind Authelia's sign-in once Authelia is installed.
- Its own project and documentation: github.com/pi-hole/pi-hole
Ports, settings, tools and connections on this page are read from LibrePortal v0.10.97's app catalogue each time the guide is built.
