AdGuard

What it's good for#

Every time a device opens a website or an app phones home, it first asks a DNS server where that name lives. AdGuard Home is a DNS server with a long list of advertising and tracking names it simply refuses to look up. The advert never loads, because the device never finds out where it lives. That works for things you can't install a blocker on, like a smart TV or a games console, and it works for every browser on every phone.

It also keeps a log of which device asked for what, which is an eye-opener the first time you look at it, and lets you block or allow names by hand.

On LibrePortal it does one more job: it answers for your own apps. When you have a domain or local names switched on, LibrePortal tells AdGuard to point those names at your server's address on your home network, so they open directly at home instead of going out to the internet and back.

Signing in#

Open AdGuard with the Admin Interface button on its page. LibrePortal finishes AdGuard's setup wizard for you during the install, so you never see it: the account is called admin, and its password is in the Login Details shown when the install finishes. Press Welcome on the app's page to see it again.

If you've given AdGuard a domain, its admin page there also sits behind LibrePortal's website login (the Traefik one), so you'll be asked for that first. Both sets of details are on the same card.

A brand new AdGuard answers with its setup wizard, and whoever finishes the wizard first sets the admin account. So LibrePortal keeps AdGuard reachable from the server only while it fills the wizard in, and opens it up once it has checked the new login works (why). Nobody gets a chance to reach the wizard first.

To change the password, use Reset Admin Password on the Tools tab rather than AdGuard's own settings, so LibrePortal keeps being able to add your local names. Leave the box empty and a strong one is made for you. The new password goes straight onto the Login Details card, and it's printed in the task's output too.

If you reset the password with 0.4.6 or earlier, the card kept showing the old one. The first time AdGuard starts after the update to 0.4.7, LibrePortal checks which password AdGuard really accepts and puts that one on the card. It doesn't change anything in AdGuard itself.

Getting your devices to use it#

AdGuard only filters for devices that ask it. The end of the install tells you where its DNS server is, something like "AdGuard's DNS server is on 192.168.1.50, port 53".

AdGuard's DNS port is for trusted places only: your home network, the addresses you've trusted, and your VPN devices. That's deliberate. A DNS server open to the whole internet gets found within hours and used to attack other people.

When port 53 is taken#

On a stock Ubuntu server, a part of the system called systemd-resolved already sits on port 53, and if Pi-hole is installed it has 53 too. Rather than fail, the install puts AdGuard's DNS on one other port (the same one for TCP and UDP), tells you what's holding 53 and how to free it, and carries on. AdGuard works, but nothing on your network will use it until it has port 53.

Once you've freed port 53 (turned off systemd-resolved's stub listener, or removed Pi-hole), run Use Port 53 for DNS on the Tools tab. It checks 53 really is free, moves AdGuard onto it and redeploys it; DNS through AdGuard pauses for a few seconds while that happens. If something still holds 53, it refuses and says what.

Everyday use#

The first things most people do in AdGuard's own admin page:

• Query Log shows every lookup and which device made it. If a site or app breaks, look here for what was blocked just then, and unblock it from the log entry.

• Filters is where the blocklists live. The defaults are a good start; you can add more, and allow names that a list blocks by mistake.

• Settings → DNS settings is where AdGuard sends the lookups it doesn't block. If you also run Unbound on this server, AdGuard uses it as its upstream by itself: Unbound is offered beside AdGuard under Also install, and whenever it's installed LibrePortal points AdGuard's upstream at it, so your lookups go straight to the internet's own name servers instead of a public resolver. It only ever changes an upstream nobody chose, so if you've set your own it leaves it alone and tells you how to switch to Unbound by hand. Remove Unbound and the default upstream comes back.

  Without Unbound, LibrePortal sets an encrypted upstream (DNS-over-HTTPS): Mullvad's by default, or Quad9 or Cloudflare if you choose that under Upstream DNS (encrypted) on the Config tab. custom leaves AdGuard's own setting alone. See DNS for your VPN.

LibrePortal's own entries show under Filters → DNS rewrites: one wildcard per domain (and one for your local names), pointing at your server. LibrePortal only ever removes entries it added itself, so anything you add there by hand is left alone, even an entry identical to one it would have made. It refreshes them after every app install and every domain change. To add names of your own that survive everything, use libreportal dns records add: see Your own records.

This server's own DNS#

AdGuard filters the devices you point at it. By default the server it runs on is not one of them: it keeps using whatever DNS it was set up with, so AdGuard going down can never leave the server itself unable to look anything up.

You can change that. Route this server's own DNS through AdGuard (in AdGuard's advanced settings on the Config tab) sends the server's own lookups through AdGuard 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 AdGuard, and the server's DNS goes back exactly as it was. LibrePortal points it at AdGuard on the server's own loopback address, never its network address, so a full-tunnel VPN like Mullvad can't pull the answers through the tunnel, and it checks AdGuard really answers before switching anything over.

Refresh Local DNS on the Tools tab is a different thing: it re-applies AdGuard's records for your app names, so they point at the server on your network. It doesn't touch the server's own resolver. You rarely need it; LibrePortal refreshes those records by itself whenever you install an app or change a domain.

Good to know#

• Updates are automatic, with a backup taken first, and it rolls back if the update fails.
• Backups include its settings file and its working data, including the query log and statistics.
• One per server. Devices point at an address, not a port, so a second copy would serve nobody.
• The query log hides full device addresses. The install switches on AdGuard's option to anonymise client addresses, so the log and statistics keep only part of each one. Installs made with 0.4.6 or earlier tried to and it never took, so on an older install check AdGuard's query log settings if that matters to you.
• It can filter on the move, through the VPN. Keep the DNS ports private rather than opening them to the internet. By default the LibrePortal VPN doesn't hand your devices a DNS server, so a phone on the move isn't filtered. But turn on Use this server's names for a phone on the VPN (which is offered only while AdGuard or Pi-hole is installed, exactly so there's something to answer) and all its lookups go through the server, so AdGuard filters it while you're out too. See names over the VPN and DNS for your VPN.