DNS for your VPN
Running AdGuard Home or Pi-hole as the DNS for your VPN, so your devices open local names and private apps by name wherever they are, with encrypted lookups and records of your own.
On this page
A DNS server is what turns a name like nextcloud.homeserver.internal into an address. LibrePortal doesn't run one of its own for your household, but it can use AdGuard Home or Pi-hole, both in the App Center, and put it to work for your VPN as well as for your home network.
With one of them installed, a phone on the VPN can open your apps by name from anywhere, your public lookups leave the server encrypted, and you can add names of your own that LibrePortal will never touch.
What it does for you#
- Local names work over the VPN. The same
https://nextcloud.homeserver.internalbookmark opens at home and on the train. - Private apps open by name too. An app set to Private is only reachable from your trusted places, and your VPN devices are one. Over the VPN its name now points at the server's VPN address, so you type a name instead of an address and a port.
- Everything else is looked up encrypted. Names that aren't yours, like a news site, are passed on to a public resolver over an encrypted connection, so the café's Wi-Fi can't read which sites you ask for.
- Your own records stay yours. You can add names that point wherever you like, and LibrePortal never changes or removes them.
What you need first#
Turning local names on doesn't need AdGuard Home or Pi-hole. The on/off switch works without either, and over the VPN your server answers its own names itself. A resolver is what you add for three things: answering the names for devices at home, records of your own, and phones on the VPN. A phone can't be told "only these names go to the server", so it sends every lookup there, and LibrePortal only lets a phone have names while AdGuard Home or Pi-hole is running to answer (and filter) them. Laptops and desktops don't need one. The Local DNS card in the WebUI's config shows which resolver is installed, and offers to install one if neither is. Install only one, because they both want port 53.
If you already have names switched on, nothing changes for devices at home. What this page adds is the part for your VPN devices.
Pointing a device's VPN at it#
A device on the VPN has to be told to ask your server for names. That's the Use this server's names switch when you add a device, or Access on its row afterwards.
- Install AdGuard Home or Pi-hole if the device is a phone and you haven't. On the VPN page, the phone's names switch offers to install AdGuard for you. Laptops and desktops can skip this.
- Turn on Use this server's names for the device.
- Add the DNS line on the device. The DNS server's address is part of the config your device imported, so a device you added before needs one line added. On a phone, open the tunnel in the WireGuard app, tap edit, add a DNS line with the server's VPN address (shown as Devices reach this server at on the VPN page), and save. The key stays the same: there's no need to regenerate anything, scan a new QR code or import a file. Then switch the tunnel off and on. Check that Android's Private DNS is off, or it ignores the line. A laptop only needs the short command the VPN page shows, run once.
Why it's a one-time step
The VPN works on a copy of its settings that lives on each device, and the server can't reach in and change it. Once a device has the right address, later changes, like installing a new app or marking one private, reach it without you doing anything, because they happen on the server.
A phone sends all its lookups to the server while the tunnel is up. That's how phones work, and it's the reason a phone needs AdGuard or Pi-hole: they're what filters adverts out of those lookups for you. A laptop sends only your server's own names. See names over the VPN for the details.
Private apps by name#
Mark an app Private, and LibrePortal adds its name to the VPN's resolver, pointing at the server's VPN address. Install another private app, or make one public again, and the list follows. You don't manage it.
At home, AdGuard Home or Pi-hole answers the same names with your server's address on your home network. LibrePortal only adds names for domains that an installed app is actually using, so a domain you've configured but not used isn't quietly pointed at your server.
Where public lookups go#
For everything that isn't one of your names, AdGuard Home asks an upstream resolver over an encrypted connection (DNS-over-HTTPS). You choose which one with Upstream DNS (encrypted) in AdGuard's settings on its Config tab:
| Choice | Who answers |
|---|---|
| mullvad (the default) | Mullvad's public resolver. |
| quad9 | Quad9, which also blocks known malicious sites. |
| cloudflare | Cloudflare's resolver. |
| custom | Whatever you set yourself in AdGuard's own DNS settings. LibrePortal leaves it alone. |
Before LibrePortal switches AdGuard to a provider it tests that the provider answers, and it reads the setting back afterwards, so a typo or an outage can't leave your network without DNS. It also only changes an upstream nobody chose: one you set by hand is never overwritten. If you run Unbound on the same server, AdGuard uses that instead, and the choice above applies again when you remove it.
Pi-hole picks its own upstream, described on its page.
Your own records#
Sometimes you want a name LibrePortal doesn't know about: nas.home.example for the disk box in the cupboard, or a whole *.lab.home pointing at a machine on your desk. Add it as a record of your own:
Advanced Do this from the command line
sudo -u libreportal libreportal dns records add nas.home.example 192.168.1.20
sudo -u libreportal libreportal dns records add '*.lab.home' 192.168.1.30
sudo -u libreportal libreportal dns records
sudo -u libreportal libreportal dns records remove nas.home.example
New to the command line? How to run LibrePortal commands →
The answer is an IP address; AdGuard also takes another host name. Your records go into AdGuard Home or Pi-hole and into the VPN's resolver, so they work at home and over the tunnel. If one of yours has the same name as something LibrePortal would add, yours wins.
LibrePortal never overwrites your DNS records
It removes only the entries it added itself. A record already in AdGuard's DNS rewrites or Pi-hole's local DNS, whether you typed it there or it's identical to one LibrePortal would have made, is treated as yours and left alone. If LibrePortal can't read AdGuard's list at all, it changes nothing rather than guess.
Checking on it#
Advanced Do this from the command line
sudo -u libreportal libreportal dns status
New to the command line? How to run LibrePortal commands →
shows whether AdGuard Home or Pi-hole is installed and what answers for your apps. libreportal dns sync brings the records up to date straight away; LibrePortal does that for you after every app install, removal and domain change, so you rarely need to.
