AdGuard Home

Videos

Overview: AdGuard Home on Ubuntu 24.04 LTS on Azure: overview (watch on YouTube)

Launch and log in: AdGuard Home on Ubuntu 24.04 LTS on Azure: launch and log in (watch on YouTube)

Deep Dive: AdGuard Home on Ubuntu 24.04 LTS on Azure: deep dive (watch on YouTube)

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting size.

Configure the network security group (NSG) to allow these inbound rules: 22/tcp from your management network for SSH, 80/tcp for the web admin, and 53/udp and 53/tcp so devices can use the server for DNS.

AdGuard serves the admin over plain HTTP on port 80. For production, terminate TLS in front of it with your own domain (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for AdGuard Home by SecureAnyCloud, and select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80).

Review the dedicated data disk on the Disks tab, then select Review + create and Create. After deployment, add inbound rules for DNS on UDP 53 and TCP 53 so your devices can query the server.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:adguardhome-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name adguardhome \
  --image sac1647283583153:adguardhome-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name adguardhome --port 80 --priority 1010
az network nsg rule create --resource-group <your-rg> --nsg-name <your-nsg> \
  --name allow-dns-udp --priority 1020 --protocol Udp --destination-port-ranges 53 --access Allow
az network nsg rule create --resource-group <your-rg> --nsg-name <your-nsg> \
  --name allow-dns-tcp --priority 1030 --protocol Tcp --destination-port-ranges 53 --access Allow

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active AdGuardHome.service nginx.service

Both services report active. AdGuard Home serves DNS on port 53 (UDP and TCP) and its web admin on the loopback address 127.0.0.1:3000. nginx fronts the admin on port 80.

All configuration, query logs and statistics live on the dedicated Azure data disk mounted at /var/lib/adguardhome.

Step 5 - Retrieve your admin login

The AdGuard admin user is admin. Its password is generated uniquely on the first boot of your VM and written to a root-only file:

sudo cat /root/adguardhome-credentials.txt

This file contains ADGUARD_USERNAME, ADGUARD_PASSWORD and ADGUARD_URL. Store them somewhere safe.

With a Standard SKU public IP (the Azure default, and --public-ip-sku Standard in Step 2), ADGUARD_URL shows the VM's private address, because the public address is not visible from inside the VM. Open the dashboard at http://<vm-public-ip>/ as in Step 8.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes. Request it from the VM:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so you can use it for an Azure Load Balancer health probe.

Step 7 - Verify DNS filtering and authentication from the command line

Confirm that the DNS server resolves a normal domain and blocks a known ad domain:

dig @127.0.0.1 example.com +short dig @127.0.0.1 ad.doubleclick.net +short

example.com returns a normal address, while the ad domain returns 0.0.0.0 because the AdGuard DNS filter blocks it.

AdGuard also rejects a wrong admin password and issues a session cookie for the correct one. Read the password from Step 5, then post it to the login endpoint. The command embeds your unique password, so run it interactively rather than from a script. Substitute the value of ADGUARD_PASSWORD for <ADGUARD_PASSWORD>:

curl -s -o /dev/null -w '%{http_code}\n' -c cookies.txt -H 'Content-Type: application/json' -X POST --data '{"name":"admin","password":"<ADGUARD_PASSWORD>"}' http://127.0.0.1/control/login; grep -o 'agh_session' cookies.txt

A correct password returns 200 and prints agh_session, which shows the session cookie was set. A wrong password returns 403 and sets no session cookie.

Step 8 - Sign in to the dashboard

Browse to http://<vm-public-ip>/. AdGuard Home shows its sign-in page. Enter the username and password from Step 5.

After you sign in, the dashboard shows live query statistics: total DNS queries, how many filters blocked, the busiest clients and the average processing time.

Step 9 - Point your devices at the server and watch the query log

On a device or your router, set the DNS server to the VM public IP. Every lookup from that device now flows through AdGuard.

Open Query Log to see, per client and in real time, which domains were processed and which were blocked.

Step 10 - Manage blocklists

Open Filters -> DNS blocklists to review the enabled blocklists. The image ships with the AdGuard DNS filter enabled (over 150,000 rules).

Add more blocklists with Add blocklist. Write your own rules under Custom filtering rules, and allow specific domains with an allowlist.

Step 11 - Confirm state lives on the dedicated disk

AdGuard's configuration, query logs and statistics are stored under /var/lib/adguardhome on the dedicated Azure data disk. They survive OS changes, and you can resize the disk independently. Confirm the mount:

findmnt /var/lib/adguardhome

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Maintenance

• Admin login: the per-VM credentials live in /root/adguardhome-credentials.txt. AdGuard Home has no password change in its web interface, so follow Changing the admin password below.
• Blocklists: add and enable blocklists under Filters -> DNS blocklists. They update automatically on a schedule.
• Upstream DNS: set your preferred upstream resolvers under Settings -> DNS settings.
• Storage: all runtime state lives under /var/lib/adguardhome on the data disk. Back up that volume to protect your configuration and history.
• Service: the unit is AdGuardHome.service. After any change, run sudo systemctl restart AdGuardHome.
• TLS: the admin is served over plain HTTP on port 80. Front it with TLS (for example certbot with your own domain) before running it in production. AdGuard Home can also serve DNS over HTTPS and DNS over TLS once you add a certificate under Settings -> Encryption settings.
• Security patches: unattended-upgrades remains enabled, so the OS continues to receive security updates automatically.

Changing the admin password

AdGuard Home keeps the admin password as a bcrypt hash in the users: section of /var/lib/adguardhome/AdGuardHome.yaml. To change it, generate a new hash and put it there, as AdGuard documents:

sudo apt-get install -y apache2-utils htpasswd -B -C 10 -n admin

htpasswd asks for the new password twice and prints admin:<hash>. Stop the service, set password: under users: to the <hash> part, and start the service again:

sudo systemctl stop AdGuardHome
sudo nano /var/lib/adguardhome/AdGuardHome.yaml
sudo systemctl start AdGuardHome

Sign in with the new password. If you keep a copy of the credentials, update /root/adguardhome-credentials.txt too.

Support

SecureAnyCloud provides 24/7 expert support for this image. To reach the team, email sales@secureanycloud.com.

Deploy on Azure

Launch AdGuard Home on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com