How to Install and Use AdGuard on Ubuntu 24.04

There are various ways to block internet advertisements (ads). One of the most popular ones is using a browser extension. But what happens when you want to use ads that run on other apps or even mobile games? In such a case, you need to block ads from their source, that is, directly on the network. This is where AdGuard comes in. With AdGuard, you can block all or most ads by making AdGuard act as an intermediary (a DNS server) that filters content between your network and the internet.

In this article, you will install and set up AdGuard Home on Ubuntu 24.04, enable TLS encryption with automatic renewals, and configure custom DNS settings. You can choose between two installation methods: Docker and the official installation script.

Prerequisites

Before you begin,

• Have access to an Ubuntu 24.04 based server as a non-root user with sudo privileges.
• Create an A record in your domain’s DNS pointing to your server’s IP address. This article uses adguard.example.com, replace it with your own domain.

Understand How AdGuard Home Works

AdGuard Home is a tool that blocks ads and malicious domains across your entire network. It works by acting as your DNS server. When a device on your network tries to access the internet, AdGuard checks whether the requested domain is on a blocklist. If it is, AdGuard stops the connection and prevents the ad or tracker from loading by returning a fake IP address.

Unlike browser extensions that only block ads on one device, AdGuard filters all DNS traffic from every device connected to your network. It also keeps your internet activity private from your internet provider with features like encrypted DNS.

Free Port 53 From systemd-Resolved

Ubuntu 24.04 uses systemd-resolved for local DNS caching and resolution, which binds to port 53 by default. AdGuard Home requires this port for DNS services. Follow the steps below to reconfigure systemd-resolved and free port 53.

1. Create the /etc/systemd/resolved.conf.d directory to store a new config file.

   CONSOLE

   Copy

   $ sudo mkdir -p /etc/systemd/resolved.conf.d

   Explain Code

   Powered by Vultr AgentBeta

2. Create and edit the new config file /etc/systemd/resolved.conf.d/adguardhome.conf.

   CONSOLE

   Copy

   $ sudo nano /etc/systemd/resolved.conf.d/adguardhome.conf

   Explain Code

   Powered by Vultr AgentBeta

   Creating a new config file instead of editing the existing one ensures that the changes are not overwritten during system upgrades.

3. Add the following contents to the file.

   INI

   Copy

   [Resolve]
   DNS=127.0.0.1
   DNSStubListener=no

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file. The above configuration:

   • Explicitly sets the DNS to 127.0.0.1, which is Adguard home.
   • Disables DNSStubListener, which frees up port 53.

4. /etc/resolv.conf is the file most programs read to know which DNS server to use. This file is a symlink to /run/systemd/resolve/stub-resolv.conf, which points to 127.0.0.53. After disabling the DNSStubListener, this config breaks. You need to update the symlink:

   1. Back up the existing resolv.conf file.

      CONSOLE

      Copy

      $ sudo mv /etc/resolv.conf /etc/resolv.conf.backup

      Explain Code

      Powered by Vultr AgentBeta

   2. Create a new symlink pointing to /run/systemd/resolve/resolv.conf.

      CONSOLE

      Copy

      $ sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf

      Explain Code

      Powered by Vultr AgentBeta

      This step ensures that applications now use the DNS server defined in adguardhome.conf. The file /run/systemd/resolve/resolv.conf dynamically reflects the active resolver settings from systemd-resolved, including the override you added in /etc/systemd/resolved.conf.d/adguardhome.conf. Now, all DNS queries get redirected to 127.0.0.1, where AdGuard Home is listening.

   3. Restart systemd-resolved to apply the changes.

      CONSOLE

      Copy

      $ sudo systemctl restart systemd-resolved

      Explain Code

      Powered by Vultr AgentBeta

5. Verify port 53 is free.

   CONSOLE

   Copy

   $ sudo lsof -i :53

   Explain Code

   Powered by Vultr AgentBeta

   The command should return no output.

Set up Firewall Rules

Configure UFW to allow connections to the required AdGuard Home ports before installing and configuring.

1. Allow DNS traffic on port 53.

   CONSOLE

   Copy

   $ sudo ufw allow 53

   Explain Code

   Powered by Vultr AgentBeta

2. Allow DNS-over-TLS and DNS-over-QUIC port 853.

   CONSOLE

   Copy

   $ sudo ufw allow 853

   Explain Code

   Powered by Vultr AgentBeta

   DNS-over-TLS uses TCP protocol, whereas DNS-over-QUIC uses UDP protocol.

3. The initial AdGuard Home setup interface runs on port 3000. Allow it.

   CONSOLE

   Copy

   $ sudo ufw allow 3000/tcp

   Explain Code

   Powered by Vultr AgentBeta

4. Allow HTTP traffic for the web dashboard and certificate verification.

   CONSOLE

   Copy

   $ sudo ufw allow 80/tcp

   Explain Code

   Powered by Vultr AgentBeta

5. Allow HTTPS for the secure web interface and enable DNS-over-HTTPS.

   CONSOLE

   Copy

   $ sudo ufw allow 443/tcp

   Explain Code

   Powered by Vultr AgentBeta

6. Reload UFW to apply the firewall rules.

   CONSOLE

   Copy

   $ sudo ufw reload

   Explain Code

   Powered by Vultr AgentBeta

Install AdGuard Home on Ubuntu 24.04

You can install AdGuard Home using Docker or the official install script. Both methods provide the same functionality.

Generate TLS Certificate

This section covers generating Let's Encrypt certificates for secure HTTPS access to the AdGuard Home dashboard.

1. Install Certbot for certificate generation.

   CONSOLE

   Copy

   $ sudo apt install certbot -y

   Explain Code

   Powered by Vultr AgentBeta

2. Generate a certificate for your domain. Replace adguard.example.com with your actual domain and admin@example.com with your email address.

   CONSOLE

   Copy

   $ sudo certbot certonly --standalone -d adguard.example.com --agree-tos --no-eff-email --email admin@example.com

   Explain Code

   Powered by Vultr AgentBeta

   Output:

   ...
   Successfully received certificate.
   Certificate is saved at: /etc/letsencrypt/live/adguard.example.com/fullchain.pem
   Key is saved at:         /etc/letsencrypt/live/adguard.example.com/privkey.pem
   ...

3. Create a certificate copy script based on your installation method.

   • For Docker installation:

     CONSOLE

     Copy

     $ nano ~/adguardhome/scripts/copy-certs.sh

     Explain Code

     Powered by Vultr AgentBeta

   • For Script installation:

     CONSOLE

     Copy

     $ sudo nano /opt/AdGuardHome/scripts/copy-certs.sh

     Explain Code

     Powered by Vultr AgentBeta

4. Add the certificate copy script content. Replace adguard.example.com with your actual domain.

   • For Docker installation:

     BASH

     Copy

     #!/bin/bash
     
     DOMAIN="adguard.example.com"
     ADGUARD_DIR="/home/YOUR_USERNAME/adguardhome"
     CERT_DIR="$ADGUARD_DIR/certs"
     
     sudo cp /etc/letsencrypt/live/$DOMAIN/fullchain.pem $CERT_DIR/cert.pem
     sudo cp /etc/letsencrypt/live/$DOMAIN/privkey.pem $CERT_DIR/key.pem
     sudo chown YOUR_USERNAME:YOUR_USERNAME $CERT_DIR/*.pem
     chmod 644 $CERT_DIR/cert.pem
     chmod 600 $CERT_DIR/key.pem
     
     if docker ps | grep -q adguardhome; then
         cd $ADGUARD_DIR
         docker compose restart
     fi

     Explain Code

     Powered by Vultr AgentBeta

     Save and close the file. Then, update the script with your actual username. Replace all instances of YOUR_USERNAME with your system username.

     CONSOLE

     Copy

     $ sed -i "s/YOUR_USERNAME/$USER/g" ~/adguardhome/scripts/copy-certs.sh

     Explain Code

     Powered by Vultr AgentBeta

   • For Script installation, add the following content:

     BASH

     Copy

     #!/bin/bash
     
     DOMAIN="adguard.example.com"
     CERT_DIR="/opt/AdGuardHome/certs"
     
     cp /etc/letsencrypt/live/$DOMAIN/fullchain.pem $CERT_DIR/cert.pem
     cp /etc/letsencrypt/live/$DOMAIN/privkey.pem $CERT_DIR/key.pem
     chmod 644 $CERT_DIR/cert.pem
     chmod 600 $CERT_DIR/key.pem
     
     /opt/AdGuardHome/AdGuardHome -s restart

     Explain Code

     Powered by Vultr AgentBeta

5. Make the script executable and run it.

   • For Docker installation:

     CONSOLE

     Copy

     $ chmod +x ~/adguardhome/scripts/copy-certs.sh
     $ ~/adguardhome/scripts/copy-certs.sh

     Explain Code

     Powered by Vultr AgentBeta

   • For Script installation:

     CONSOLE

     Copy

     $ sudo chmod +x /opt/AdGuardHome/scripts/copy-certs.sh
     $ sudo /opt/AdGuardHome/scripts/copy-certs.sh

     Explain Code

     Powered by Vultr AgentBeta

6. Check the certificates.

   • For Docker:

     CONSOLE

     Copy

     $ ls -la ~/adguardhome/certs/

     Explain Code

     Powered by Vultr AgentBeta

   • For Script installation:

     CONSOLE

     Copy

     $ sudo ls -la /opt/AdGuardHome/certs/

     Explain Code

     Powered by Vultr AgentBeta

   You should see cert.pem and key.pem files with the correct permissions.

Configure Automatic Certificate Renewal

Let's Encrypt certificates expire every 90 days. In this section, configure automatic renewal of your TLS certificates.

1. Create a Certbot renewal hook script.

   CONSOLE

   Copy

   $ sudo nano /etc/letsencrypt/renewal-hooks/deploy/adguard-renewal.sh

   Explain Code

   Powered by Vultr AgentBeta

2. Add the renewal script content based on your installation method.

   • For Docker installation:

     BASH

     Copy

     #!/bin/bash
     /home/YOUR_USERNAME/adguardhome/scripts/copy-certs.sh

     Explain Code

     Powered by Vultr AgentBeta

     Note

     Replace YOUR_USERNAME with your username.

   • For Script installation:

     BASH

     Copy

     #!/bin/bash
     /opt/AdGuardHome/scripts/copy-certs.sh

     Explain Code

     Powered by Vultr AgentBeta

   Save and close the file.

3. Make the renewal hook executable.

   CONSOLE

   Copy

   $ sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/adguard-renewal.sh

   Explain Code

   Powered by Vultr AgentBeta

4. To handle port 80 conflicts during renewal (since AdGuard Home binds to port 80 after setup), create stop and start scripts, then add pre-hooks and post-hooks to the Certbot renewal configuration. This temporarily stops AdGuard Home before the renewal attempt and starts it afterward.

   • For Docker installation:

     1. Create a stop script.

        CONSOLE

        Copy

        $ nano ~/adguardhome/scripts/stop-adguard.sh

        Explain Code

        Powered by Vultr AgentBeta

        Add:

        BASH

        Copy

        #!/bin/bash
        docker compose -f /home/YOUR_USERNAME/adguardhome/compose.yml stop > /dev/null 2>&1

        Explain Code

        Powered by Vultr AgentBeta

     2. Create a start script.

        CONSOLE

        Copy

        $ nano ~/adguardhome/scripts/start-adguard.sh

        Explain Code

        Powered by Vultr AgentBeta

        Add:

        BASH

        Copy

        #!/bin/bash
        docker compose -f /home/YOUR_USERNAME/adguardhome/compose.yml start > /dev/null 2>&1

        Explain Code

        Powered by Vultr AgentBeta

     3. Make them executable.

        CONSOLE

        Copy

        $ chmod +x ~/adguardhome/scripts/{stop-adguard.sh,start-adguard.sh}

        Explain Code

        Powered by Vultr AgentBeta

     4. Update the scripts with your actual username.

        CONSOLE

        Copy

        $ sed -i "s/YOUR_USERNAME/$USER/g" ~/adguardhome/scripts/stop-adguard.sh
        $ sed -i "s/YOUR_USERNAME/$USER/g" ~/adguardhome/scripts/start-adguard.sh

        Explain Code

        Powered by Vultr AgentBeta

   • For Script installation:

     1. Create a stop script.

        CONSOLE

        Copy

        $ sudo nano /opt/AdGuardHome/scripts/stop-adguard.sh

        Explain Code

        Powered by Vultr AgentBeta

        Add:

        BASH

        Copy

        #!/bin/bash
        /opt/AdGuardHome/AdGuardHome -s stop > /dev/null 2>&1

        Explain Code

        Powered by Vultr AgentBeta

     2. Create a start script.

        CONSOLE

        Copy

        $ sudo nano /opt/AdGuardHome/scripts/start-adguard.sh

        Explain Code

        Powered by Vultr AgentBeta

        Add:

        BASH

        Copy

        #!/bin/bash
        /opt/AdGuardHome/AdGuardHome -s start > /dev/null 2>&1

        Explain Code

        Powered by Vultr AgentBeta

     3. Make them executable.

        CONSOLE

        Copy

        $ sudo chmod +x /opt/AdGuardHome/scripts/{stop-adguard.sh,start-adguard.sh}

        Explain Code

        Powered by Vultr AgentBeta

5. Edit the Certbot renewal configuration to add the hooks. Replace adguard.example.com with your domain.

   CONSOLE

   Copy

   $ sudo nano /etc/letsencrypt/renewal/adguard.example.com.conf

   Explain Code

   Powered by Vultr AgentBeta

   Add or update under the [renewalparams] section:

   • For Docker installation:

     INI

     Copy

     pre_hook = /home/YOUR_USERNAME/adguardhome/scripts/stop-adguard.sh
     post_hook = /home/YOUR_USERNAME/adguardhome/scripts/start-adguard.sh

     Explain Code

     Powered by Vultr AgentBeta

     Note

     Replace YOUR_USERNAME with your username.

   • For Script installation:

     INI

     Copy

     pre_hook = /opt/AdGuardHome/scripts/stop-adguard.sh
     post_hook = /opt/AdGuardHome/scripts/start-adguard.sh

     Explain Code

     Powered by Vultr AgentBeta

   Save and close the file.

6. Test the automatic renewal process.

   CONSOLE

   Copy

   $ sudo certbot renew --dry-run

   Explain Code

   Powered by Vultr AgentBeta

   Output:

   ...
   Congratulations, all simulated renewals succeeded
   ...

Configure AdGuard Home’s Initial Setup

Access the AdGuard Home web interface to complete the initial configuration.

1. Open your web browser and navigate to the setup interface.

   http://YOUR_SERVER_IP:3000

2. Click Get Started on the welcome page.

   

3. Set Up the Admin Web Interface:

   • Listen Interface: Select All interfaces
   • Port: Enter 80

4. Configure the DNS Server:

   • Listen Interface: Select All interfaces
   • Port: Keep 53

5. Click Next and create an administrator account with a username and a strong password.

6. Click Next. You'll land on the Configure your devices page, where you'll see the configuration settings for various types of devices. Click Next.

7. Click Open Dashboard to access the main interface.

8. Remove port 3000 from the firewall after completing initial configuration.

   CONSOLE

   Copy

   $ sudo ufw delete allow 3000/tcp
   $ sudo ufw reload

   Explain Code

   Powered by Vultr AgentBeta

Enable TLS Encryption

Configure HTTPS access using your TLS certificates for secure dashboard access.

1. Access the AdGuard Home dashboard and log in to the dashboard with the credentials you set earlier.

   http://YOUR_SERVER_IP

   

2. Click the Settings button on the top navigation menu, and click Encryption settings.

   

3. Configure the following encryption settings:

   • Enable Encryption: Check to enable.

   • Server name: Enter your domain name.

   • Redirect to HTTPS automatically: Enable.

   • HTTPS port: 443

   • DNS-over-HTTPS port: 443

   • DNS-over-TLS port: 853

   • DNS-over-QUIC port: 853

     

4. Configure certificate paths:

   • Select Set a certificates file path option.

   • For Docker installation:

     • Certificates path: /opt/adguardhome/certs/cert.pem
     • Private key path: /opt/adguardhome/certs/key.pem

   • For Script installation:

     • Certificates path: /opt/AdGuardHome/certs/cert.pem
     • Private key path: /opt/AdGuardHome/certs/key.pem

5. Click Save to apply the encryption settings. After enabling encryption, access AdGuard Home using https://adguard.example.com.

Configure DNS Privacy Settings

AdGuard Home supports encrypted DNS protocols to prevent ISPs and third parties from monitoring your DNS queries. Configure upstream DNS servers that support DNS-over-HTTPS (DoH) or DNS-over-TLS (DoT) for enhanced privacy.

1. Click the Settings button on the top navigation menu, and click DNS Settings.

2. In the Upstream DNS servers field, add encrypted DNS providers of your choice, such as:

   https://dns.cloudflare.com/dns-query
   https://dns.google/dns-query
   https://dns.quad9.net/dns-query
   tls://1.1.1.1
   tls://8.8.8.8

   These upstream servers use HTTPS or TLS encryption to secure DNS queries between AdGuard Home and the upstream providers. The encrypted protocols prevent your ISP from seeing which domains you're resolving.

3. Configure Fallback DNS servers for redundancy. These servers are used when encrypted upstream servers are unavailable. Add DNS servers of your choice, such as:

   1.1.1.1
   8.8.8.8
   9.9.9.9

   Note

   Fallback servers typically use standard unencrypted DNS (port 53) because they serve as emergency backups when encrypted connections fail. During normal operation, AdGuard Home uses only the encrypted upstream servers.

4. Configure Bootstrap DNS servers. These servers resolve the domain names of your encrypted upstream servers (like dns.cloudflare.com). You can add:

   1.1.1.1
   8.8.8.8
   9.9.9.9

5. Enable the following DNS features:

   • Parallel requests: Enable to query multiple servers simultaneously for faster responses
   • Enable DNSSEC: Validate DNS responses for authenticity
   • Enable EDNS client subnet: Improve CDN performance
   • Disable IPv6: Enable only if your network doesn't support IPv6

6. Click Save to apply the DNS configuration.

Set Up Blocklist

AdGuard has a built-in DNS filter, but you can expand its capabilities by adding additional blocklists. These publicly maintained lists contain tens of thousands of known ad, tracker, malware, and telemetry domains.

1. From the top navigation menu, click Filters and select DNS blocklists.

   

2. Click Add blocklist and click Choose from the list.

3. Select the options in the image below, then click Save.

   

4. Browse the internet for a while, then check your AdGuard Home dashboard on your browser.

   http://SERVER-IP

   You would see all the sites, trackers, and ads that have been blocked.

Custom DNS Rewrites

DNS rewrites are rules that override standard DNS resolution by mapping specific domain names to custom IP addresses. AdGuard supports DNS rewrites, which allow you to map domain names to specific IP addresses within your network. This acts like a mini local DNS server for internal use. For example, you can map adguard.home to SERVER-IP, to access your AdGuard dashboard. Follow the steps below to access your AdGuard Home dashboard with adguard.home instead of your server IP address.

1. From the top navigation menu, click Filters and select DNS rewrites.
2. Click Add DNS rewrites.
3. Input the domain and your server IP address, then click Save.

Configure Client Devices

You can configure your devices to use AdGuard Home as their DNS server. The configuration varies between different types of devices. The section below covers setting up your router to use your AdGuard Home server as a DNS server.

Router Configuration

Configure your router to apply AdGuard Home DNS to all connected devices automatically.

1. Access your router's admin webpage (typically http://192.168.1.1 or http://192.168.0.1).
2. Navigate to the DHCP or DNS settings section.
3. Enable custom DNS and add your AdGuard Home server's IP address, or replace the existing DNS server addresses with your AdGuard Home server's IP address.
4. Save and apply the settings.

You can find configuration settings for most device types from the Setup Guide option on the top navigation menu of AdGuard Home dashboard.

Monitor and Maintain

AdGuard Home shows statistics about DNS queries on its dashboard.

View Statistics

Access the dashboard at https://adguard.example.com. You should see logs of DNS queries that reached your AdGuard Home DNS server.

Conclusion

You have successfully deployed AdGuard Home on Ubuntu 24.04 with automatic TLS certificate renewal and encrypted DNS protocols using the official installation script and Docker. To learn more about using it, refer to the AdGuard Home Wiki page.