AdGuard Home is a network-wide ad-and-tracker blocking DNS server. Its purpose is to let you control your entire network and all your devices, and it does not require using a client-side program. It is a fully-fledged server application which runs on a separate machine (your home router or even a remote VPS), and provide cross-device protection over your network with a mechanism to actively block certain requests from the websites you visit. In this short guide, I will show you how to setup your own AdGuard Home on a VPS (preferred Ubuntu 18.04+).
How does AdGuard Home work?
Whenever you navigate to a website using its URL (https://frankindev.com, for example), your device needs to know which IP address the domain name links to. In order to determine the IP address, your device makes a DNS (domain name system) query to a DNS nameserver which will respond with the DNS record for that particular domain, containing its IP address(es) and associated information.
But how does your device know which DNS server to call for each request? Well, it’s generally the job of your router’s DHCP. It is entirely possible to override the DNS server on the router, but for most people won’t do that and leave the one configured by your ISP (Internet service provider).
There are thousands of public DNS servers out in the world. Like Google’s public DNS servers (18.104.22.168 & 22.214.171.124), or Cloudflare’s 126.96.36.199. When you setup the AdGuard Home in your network, you can configure your router’s DHCP service to use AdGuard Home’s DNS address as the default DNS nameserver instead. By doing so, AdGuard Home now has carte blanche to devices which DNS queries are allowed, and which ones are blocked (filtered).
AdGuard Home is effectively a DNS proxy, whereby it acts as your network’s primary DNS nameserver, filter requests, then relays the requests that satisfy your configured filters to certain “upstream” DNS nameservers, which does the real DNS resolution.
So, AdGuard Home is working at the DNS level that guards your DNS requests with a layer of filtering.
Install AdGuard Home on VPS
This section is originated from AdGuard Home’s official wiki. All commands are adapted to a Ubuntu server.
Install necessary requirement:
sudo apt install bind9-host
Then, choose one of the following methods to install the AdGuard Home service.
Automated install (Linux & Mac)
Run the following command in your terminal:
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
This installation script also accepts following options:
-c <channel> to use specified channel, such as
-r to reinstall AdGuard Home
-u to uninstall AdGuard Home
-v for verbose output
The program will be installed at
/opt/AdGuardHome/AdGuardHome by default.
Or, you can download AdGuard Home’s binaries and manually set it:
tar xvf AdGuardHome_linux_amd64.tar.gz
Then, install AdGuard Home as a system service:
sudo ./AdGuardHome -s install
If no errors prompt, AdGuardHome is now running on the server.
Here are some other commands you might need to control the service.
sudo ./AdGuardHome -s uninstall - uninstall the AdGuardHome service.
sudo ./AdGuardHome -s start - start the service.
sudo ./AdGuardHome -s stop - stop the service.
sudo ./AdGuardHome -s restart - restart the service.
sudo ./AdGuardHome -s status - check the status of the service.
Configure system/web service
You can also use
systemctl to manage the
sudo systemctl start AdGuardHome
sudo systemctl restart AdGuardHome
After installation, we can access the AdGuard Home’s web interface via port
3000 (by default). For example,
188.8.131.52 with the public IP address of your VPS, or a bound domain name.
Follow the instructions on the web interface to finish the setup.
Some ports maybe used by other programs on the same server, just replace them with desired ones and allow traffics of these ports via your firewall. I have set the default web interface port to
3000 instead of
80, which is already consumed by Nginx.
If you need to use the
53 port (normal DNS port via UDP), just follow up the following section.
Getting rid of systemd-resolved consuming port 53
This section is based on Getting rid of systemd-resolved consuming port 53.
In case the
53 port is used by systemd-resolved, and you still need the
53 port for serve traditional DNS service with AdGuard Home, you can get rid of
53 port safely:
sudo systemctl stop systemd-resolved
sudo nano /etc/systemd/resolved.conf
resolved.conf, and comment out & set
DNSStubListener=no. For example:
Then, we need to link the configured file:
sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved
Now, it’s safe to configure the
53 port in AdGuard Home.
If you have used other port in AdGuard Home during setting up (check listening ports of your server by
sudo netstat -plunt), you can go to AdGuard Home’s folder, edit the port number in
AdGuardHome.yaml, then restart AdGuard Home service to make it effect.
Enable DNS-over-HTTPS & DNS-over-TLS
Both DNS-over-HTTPS (DoH) and DNS-over-TLS (DoH) are based on TLS encryption, thus an SSL certificate for your registered domain name is required. You can get the certificate for free from Let’s Encrypt, and follow the steps in a previous post to get a certificate with Nginx.
Here’s another example to get an SSL certificate manually using DNS challenge instead of using Nginx:
sudo apt install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt update
sudo apt install certbot
sudo certbot certonly --manual --preferred-challenges=dns
In the end, you’ll get two
.pem files that required by AdGuard Home:
fullchain.pem – your PEM-encoded SSL certificate
privkey.pem – your PEM-encoded private key
Now, open AdGuard Home’s web interface (
<your-server-ip>:3000, for instance) and go to
Settings > Encryption settings. Follow the page’s instructions and set the Server name to your desired domain name and configure a port number for HTTPS port (yes, you can use ports other than
443). Leave the default port number
853 for DNS-over-TLS port.
In the Certificates section, set the file path refer to the
- Set a certificates file path:
- Set a private key file:
Then, don’t forget to Save config.
Alternatively, you can use ZeroSSL certs with
Steps follow my note at: Free ZeroSSL wildcard SSL certificates with acme.sh DNS API.
One of the core functions of AdGuard Home is to filter DNS queries. But that relies on the filters of your choice.
AdGuard Home offers you a list of filters to choose, just tick the ones you needed.
More available ad-filters can be found at https://filterlists.com/.
DNSMASQ China list
A recent upgrade of AdGuard Home enables us to specify DNS upstream for specific domain(s), syntax like:
So, I’ve created a script - see this gist - to generate a
upstream_dns_file that adapts the https://github.com/felixonmars/dnsmasq-china-list.
The same idea can be adopted to other countries or regions. But I’m not really into this manner since load-balancing is not working on the specific domain(s).
Configure in multiple devices
Please note that encrypted DNS protocols are supported only on Android 9 and above.
To configure it, go to
Setting > Network & internet > Advanced > Private DNS and enter your domain name there.
On my OnePlus phone (OxygenOS 9.0.9), it’s
Settings > WiFi & Internet > Private DNS.
You can try my DoT with cHVibGljLmRvdC5mcmFua2luZGV2LmNvbQ== (base64, double click to reveal the address) to have a taste, which proxying by fly.io.
Firefox & Chrome
Firefox now supports DoH, we can manually enabling and disabling DNS-over-HTTPS at
Preferences > General > Network Setting > Enable DNS over HTTPS.
Custom in the Use Provider and set the query url to the one shown on AdGuard Home’s web interface under
The same to Chrome’s settings, but I haven’t use Chrome for a long time. This post may help for Chrome users: https://techcodex.com/how-to-enable-dns-over-https-doh-in-firefox-and-chrome/.
Also, there’s a long list of available DoH server you can choose: https://github.com/curl/curl/wiki/DNS-over-HTTPS. Some of them also configured with AdBlock filters.
It seems that we can also specify the DoH on Firefox for Android, details are discussed here: https://android.stackexchange.com/questions/214574/how-do-i-enable-dns-over-https-on-firefox-for-android. If you’re using older Android versions, worth to try DoH inside a browser.
iOS 14 & macOS Big Sur
Apple natively supports encrypted DoH & DoT starting from iOS 14 and macOS Big Sur. As long as the system was upgraded, we can manually enable our AdGuard Home service on Apple devices.
Go to AdGuard Home’s web interface, under
Setup guide panel you can download the iOS and macOS configuration file in the
DNS Privacy section. Of course, you can set up “Client ID” for more detailed configurations for different identified clients.
After you get the
*.mobileconfig config file, see below to continue configs on each devices.
You can test with my public DoH by downloading this doh.mobileconfig file…
There are various ways to install the mobile config:
- Share this config file through iCloud, click it directly from
Files on iOS, it will say
- Share this file with AirDrop to you iOS device, it will automatic set this file to
General -> Profiles.
After you receive the profile file, go to
Settings -> General -> Profiles, you’ll see there’s a downloaded profile item. Tap on it, check if everything is right, and then install it.
Settings -> General -> VPN & Network -> DNS. There you will find all installed DNS servers, just select one.
macOS Big Sur:
Double-click the resulting
adg.mobileconfig file in Finder. You will receive a notification that a profile is installed and waiting for review (
System Preferences -> Profiles). Approve the new profile, the service will automatically start.
It will warn that the file is unsigned, but this just means it was not cryptographically signed and distributed, which is standard for DIY configuration profiles…
Cheers, now you enabled encrypted DNS powered by your AdGuard Home. 🥳