A managed AdBock powered by AdGuardHome with DoH & DoT enabled

A managed AdBock powered by AdGuardHome with DoH & DoT enabled

filter ads from DNS

AdGuardHome 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 AdGuardHome on a VPS (preferred Ubuntu 18.04+).

How does AdGuardHome work?

Whenever you navigate to a website using its URL (https://baidu.com, for example), your device needs to know which IP address the domain name refers to. In order to determine the IP address, your device makes a DNS (domain name system1) query to a DNS nameserver which will respond with a 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 DHCP2. 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 ( &, or Cloudflare’s When you setup the AdGuardHome in your network, you can configure your router’s DHCP service to use AdGuardHome’s DNS address as the default DNS nameserver instead. By doing so, AdGuardHome now has carte blanche to device which DNS queries are allowed, and which ones are blocked (filtered).

AdGuardHome 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, AdGuardHome is working at the DNS level that guards your DNS requests with a layer of filtering.

Install AdGuardHome on VPS

This section is originated from AdGuardHome’s official wiki. All commands are adapted to a Ubuntu server.

Initial installation

Install necessary requirement:

sudo apt install bind9-host

Download AdGuardHome’s binaries and unpack it:

wget https://static.adguard.com/adguardhome/release/AdGuardHome_linux_amd64.tar.gz

tar xvf AdGuardHome_linux_amd64.tar.gz

Then, install AdGuardHome as a system service:

cd AdGuardHome

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.

You can also use systemctl to manage the AdGuardHome service:

  • sudo systemctl start AdGuardHome
  • sudo systemctl restart AdGuardHome

After installation, we can access the AdGuardHome’s web interface on port 3000 (by default). For example, Replace 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 want to use the 53 port for AdGuardHome for traditional DNS service, you can get rid of systemd-resolved consuming 53 port safely:

sudo systemctl stop systemd-resolved

sudo nano /etc/systemd/resolved.conf

Set DNS and FallbackDNS in 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 AdGuardHome.

If you have used other port in AdGuardHome during setting up, you can go to AdGuardHome’s folder, edit the port number in AdGuardHome.yaml, then restart AdGuardHome 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 encryption3, so in order to use them, you will need to acquire an SSL certificate for your registered domain name. 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 AdGuardHome:

  1. fullchain.pem – your PEM-encoded SSL certificate
  2. privkey.pem – your PEM-encoded private key

Now, open AdGuardHome’s web interface (your-server-ip:3000, for example) and go to Settings > Encryption settings. Follow the page’s instructions and set 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 .pem files:

  • Set a certificates file path: /etc/letsencrypt/live/domain.example.com/fullchain.pem
  • Set a private key file: /etc/letsencrypt/live/domain.example.com/privkey.pem

Then, don’t forget to Save config.


One of the core functions of AdGuardHome is to filter DNS queries. But that relies on the filters you defined.

AdGuardHome 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/.

Ads by Google

DNSMASQ China list

A recent upgrade of AdGuardHome 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 AdGuardHome with cHVibGljLmRucy5mcmFua2luZGV2LmNvbQ== (base64, double click to reveal the address) to have a taste. Note that query logs are enabled on my side…

Firefox & Chrome

Firefox now supports DoH, we can manually enabling and disabling DNS-over-HTTPS at Preferences > General > Network Setting > Enable DNS over HTTPS.

Change to Custom in the Use Provider and set the query url to the one shown on AdGuardHome’s web interface under Setup guide.

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 this year. As long as the system was upgraded, we can manually enable our AdGuardHome service on Apple devices.

Go to AdGuardHome’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 devices:


There are various ways to install the mobile config:

  1. Share this config file through iCloud, click it directly from Files on iOS, it will say Profile Downloaded.
  2. Email yourself the file and open it from Safari.
  3. Share this file with AirDrop to you iOS device, it will automatic set this file to General -> Profiles.
  4. Upload it to a web server, and then download/open it from Safari.

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.

Go to 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 with your AdGuardHome. 🥳

  1. The Domain Name System (DNS) is a hierarchical and decentralized naming system for computers, services, or other resources connected to the Internet or a private network. Link 

  2. The Dynamic Host Configuration Protocol (DHCP) is a network management protocol used on UDP/IP networks whereby a DHCP server dynamically assigns an IP address and other network configuration parameters to each device on a network so they can communicate with other IP networks. Link 

  3. Transport Layer Security (TLS), and its now-deprecated predecessor, Secure Sockets Layer (SSL), are cryptographic protocols designed to provide communications security over a computer network. Link 

Ads by Google


Frank Lin

Hey, there! This is Frank Lin (@flinhong), one of the 1.41 billion . This 'inDev. Journal' site holds the exploration of my quirky thoughts and random adventures through life. Hope you enjoy reading and perusing my posts.


Setup an IKEv2 server with StrongSwan



Setup an IKEv2 server with StrongSwan

IKEv2, or Internet Key Exchange v2, is a protocol that allows for direct IPSec tunnelling between two points. In IKEv2 implementations, IPSec provides encryption for the network traffic. IKEv2 is natively supported on some platforms (OS X 10.11+, iOS 9.1+, and Windows 10) with no additional applications necessary, and it handles client hiccups quite smoothly.

Hands on IBM Cloud Functions with CLI



Hands on IBM Cloud Functions with CLI

IBM Cloud CLI allows complete management of the Cloud Functions system. You can use the Cloud Functions CLI plugin-in to manage your code snippets in actions, create triggers, and rules to enable your actions to respond to events, and bundle actions into packages.

Setting up snap Nextcloud on Ubuntu



Setting up snap Nextcloud on Ubuntu

Nextcloud, a fork of ownCloud, is a open-source file sharing server that allows you to store your personal content, like documents and pictures, in a centralized location, much like Dropbox. It also returns the control and security of your sensitive data back to you, thus eliminating the use of a third-party cloud hosting service. Here, I'm going to walk through the installing and configurations on Ubuntu 18.04 using the snappy packaging system.