DNS Resolver - hapara.fail Docs

Overview

This guide walks you through setting up a private, secure DNS server using AdGuard Home (for ad-blocking and management) backed by Unbound (for recursive DNS resolution). This configuration enhances privacy by querying root DNS servers directly instead of relying on third-party providers.

Why this setup?

Privacy: No single DNS provider sees your entire query history
Security: Direct DNSSEC validation from root servers
Control: Custom blocklists and filtering rules
Performance: Intelligent caching and prefetching

Prerequisites

Server Setup

Use any hosting provider. This guide requires Debian 13 x64.

Firewall Rules

In your provider’s networking or firewall settings, add the following Inbound Rules and attach them to your server:

Core DNS & Web Traffic

Add these inbound rules using the preset types where available:

Type	Protocol	Port Range	Sources
SSH	TCP	22	All IPv4, All IPv6
DNS TCP	TCP	53	All IPv4, All IPv6
HTTP	TCP	80	All IPv4, All IPv6
HTTPS	TCP	443	All IPv4, All IPv6
Custom	TCP	853	All IPv4, All IPv6
DNS UDP	UDP	53	All IPv4, All IPv6
Custom	UDP	853	All IPv4, All IPv6

Temporary Setup Access (delete-later)

Add one more Custom TCP inbound rule for the AdGuard Home setup wizard — remove this rule after setup is complete:

Type	Protocol	Port Range	Sources
Custom	TCP	3000	Your home IP only

Label or tag this rule as delete-later so you remember to remove it once the setup wizard is finished.

Update Your Server

SSH into your server using its public IP address and prepare the system:

# Update system packages
sudo apt update
sudo apt upgrade -y

Press Y when prompted to confirm package upgrades. This may take a few minutes.

Step 1: Install AdGuard Home

AdGuard Home provides the web interface, ad-blocking, and DNS query logging.

wget --no-verbose -O - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v

Initial Configuration

Navigate to http://[YOUR_EXTERNAL_IP]:3000 in your browser
Proceed through the setup wizard to Step 3

Port 53 conflict? If you see bind: address already in use, run these commands to disable systemd-resolved:

sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved
sudo rm -f /etc/resolv.conf && echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf

Then restart AdGuard Home: sudo service AdGuardHome restart

DNS Settings Configuration

Configure Settings → DNS Settings with these values:

Setting	Value	Why?
Upstream DNS servers	`https://dns.cloudflare.com/dns-query`	Temporary until Unbound is installed
Mode	☑ Parallel requests	Best stability even with one upstream
Fallback DNS servers	`https://dns.cloudflare.com/dns-query`	Backup if primary fails
Rate limit	`15`	Limits queries per second per client (DoS protection)
Subnet prefix length (IPv4)	`32`	Tracks individual devices, not subnets
DNSSEC	☑ Enable DNSSEC	Validates DNS responses aren’t tampered
IPv6 addresses	☑ Disable resolving	Prevents timeouts if IPv6 isn’t configured

Blocking & Cache Settings:

Setting	Value	Why?
Blocked response TTL	`86400` (24 hours)	How long clients cache blocked domains
Cache size	`20000000` bytes (≈19MB)	Initial cache; we’ll optimize later with Unbound
Override minimum TTL	`300` (5 minutes)	Prevents too-frequent re-queries
Override maximum TTL	`86400` (24 hours)	Limits stale data
Optimistic Caching	☑ Enable	Serves cached data while refreshing in background

We’ll reconfigure caching in Step 3 after installing Unbound for optimal performance.

Add Blocklists

Go to Filters → DNS Blocklists and add these lists:

hapara.fail Blocklist
HaGeZi Normal

Name: hapara.fail Blocklist
URL: https://cdn.jsdelivr.net/gh/hapara-fail/blocklist@main/blocklist.txt

Our custom blocklist targeting surveillance and tracking domains.

Name: HaGeZi Normal
URL: https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/adblock/multi.txt

Comprehensive multi-category blocklist (ads, trackers, malware).

Click Save after adding each list. AdGuard will download and compile them.

Step 2: Set Up Unbound (Recursive Resolver)

Unbound replaces third-party DNS providers by querying root servers directly, enhancing privacy and control.

Install Unbound

sudo apt update
sudo apt install unbound -y

Configure Unbound

We’ll run Unbound on port 5335 to avoid conflicts with AdGuard Home (which uses port 53).

Create the configuration file:

sudo nano /etc/unbound/unbound.conf.d/recursive.conf

Paste this optimized configuration:

server:
  # Logging
  verbosity: 0 # Minimal logging (use syslog)

  # Network Configuration
  port: 5335 # Non-standard port (AdGuard forwards here)
  interface: 127.0.0.1 # Listen on localhost only (security)
  do-ip4: yes
  do-udp: yes
  do-tcp: yes
  do-ip6: no # Disable IPv6 if not in use

  # Root Hints (list of root DNS servers)
  root-hints: "/var/lib/unbound/root.hints"

  # Security & Privacy
  harden-glue: yes # Only trust glue in-zone
  harden-dnssec-stripped: yes # Reject responses without DNSSEC
  use-caps-for-id: yes # Randomize query capitalization (security)
  edns-buffer-size: 1232 # Prevent fragmentation
  hide-identity: yes # Don't reveal server identity
  hide-version: yes # Don't reveal software version

  # Performance
  prefetch: yes # Refresh popular cached items before expiry
  num-threads: 1 # 1 for low-power VMs, 2+ for powerful servers
  so-rcvbuf: 1m # Socket receive buffer (performance)

  # Access Control
  access-control: 127.0.0.0/8 allow # Only localhost can query

Save and exit (Ctrl+X, Y, Enter)

What is “prefetching”? Unbound refreshes frequently-used DNS records before they expire, keeping your most-visited sites blazing fast.

Download Root Hints

Root hints tell Unbound where the authoritative root DNS servers are:

sudo wget https://www.internic.net/domain/named.root -O /var/lib/unbound/root.hints

Optional but recommended: Auto-update root hints monthly via cron:

sudo crontab -e

Add this line to the bottom:

0 0 1 * * wget -O /var/lib/unbound/root.hints https://www.internic.net/domain/named.root

This cron job runs at midnight on the 1st of each month.

Start and Test Unbound

Restart the service:
sudo service unbound restart
Check service status:
sudo service unbound status
✅ Success: You should see active (running)
Test DNS resolution:
dig @127.0.0.1 -p 5335 google.com
✅ Success: Look for status: NOERROR and an IP address in the ANSWER SECTION

Troubleshooting: If you see connection timed out or SERVFAIL, check your configuration file for syntax errors:

sudo unbound-checkconf /etc/unbound/unbound.conf.d/recursive.conf

Step 3: Connect AdGuard Home to Unbound

Now we’ll point AdGuard Home to use your local Unbound instance instead of Cloudflare.

Update Upstream DNS

In AdGuard Home, go to Settings → DNS Settings
Upstream DNS servers:
- Delete all existing entries
- Add only: 127.0.0.1:5335
Parallel requests: Select Parallel requests (recommended for stability)
Bootstrap DNS servers: These resolve IPs for DNS-over-HTTPS/TLS hostnames (not needed for our IP-based upstream, but good practice):
9.9.9.9 1.1.1.1
Private Reverse DNS servers: (Optional) Point to your router if you want local hostname resolution (e.g., 192.168.1.1)
DNSSEC: ☑ Enable (Unbound validates, but this provides a second check)
Click Test Upstreams → Should show “Server is working” ✅
Click Apply

Optimize Cache Settings

Since Unbound has superior caching with prefetching, we’ll minimize AdGuard’s cache:

Go to Settings → DNS Settings → DNS Cache Configuration
Configure:

Setting	Value	Why?
Cache size	`4194304` (4MB)	Small cache keeps UI responsive
Override minimum TTL	`0` (empty/default)	Let Unbound control TTL
Override maximum TTL	`0` (empty/default)	Let Unbound control TTL
Optimistic caching	☐ Disable	Unbound’s prefetching is superior

Why disable optimistic caching? Unbound’s prefetch mechanism proactively refreshes popular records before they expire—more intelligent than AdGuard’s optimistic cache.

Step 4: Secure with SSL/TLS (DoH & DoT)

Enable encrypted DNS protocols: DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT).

Prerequisite: You must have an A record pointing from your domain (e.g., dns.hapara.fail) to your VM’s external IP address before proceeding.

Install Certbot

sudo apt update
sudo apt install certbot -y

Obtain SSL Certificate

Let’s Encrypt needs port 80 to verify domain ownership. We’ll temporarily stop AdGuard Home:

# Stop AdGuard Home
sudo service AdGuardHome stop

# Request certificate (replace example.org with your domain)
sudo certbot certonly --standalone -d example.org

# Restart AdGuard Home
sudo service AdGuardHome start

Follow the Certbot prompts to enter your email and agree to the Terms of Service.

Configure Encryption in AdGuard

Go to Settings → Encryption Settings
Configure:

Setting	Value
Enable Encryption	☑ Checked
Server Name	`example.org` (your domain)
HTTPS Port	`443` (DNS-over-HTTPS)
DNS-over-TLS Port	`853` (DNS-over-TLS)
DNS-over-QUIC Port	`853` (DNS-over-QUIC, uses UDP)

Certificate & Key Paths (⚠️ Use file paths, NOT file contents):
- Certificate path: /etc/letsencrypt/live/example.org/fullchain.pem
- Private key path: /etc/letsencrypt/live/example.org/privkey.pem
Click Save Settings

Why use paths instead of pasting contents? When Certbot renews your certificate (every 90 days), AdGuard will automatically use the new files.

Automate Certificate Renewal

Because AdGuard Home occupies port 80, Certbot needs AGH to be stopped before it can complete the HTTP-01 challenge. Create a pre and post hook to handle this automatically:

# Create pre-renewal hook (stops AGH before renewal)
sudo nano /etc/letsencrypt/renewal-hooks/pre/stop-adguard.sh

Paste this content:

#!/bin/bash
systemctl stop AdGuardHome

# Create post-renewal hook (starts AGH after renewal)
sudo nano /etc/letsencrypt/renewal-hooks/post/start-adguard.sh

Paste this content:

#!/bin/bash
systemctl start AdGuardHome

Make both scripts executable:

sudo chmod +x /etc/letsencrypt/renewal-hooks/pre/stop-adguard.sh
sudo chmod +x /etc/letsencrypt/renewal-hooks/post/start-adguard.sh

Verify everything works with a dry run:

sudo certbot renew --dry-run

Certbot automatically renews certificates. These hooks ensure AdGuard reloads the new certificate without manual intervention.

Update Firewall Rules

Delete the temporary delete-later rule (port 3000 is no longer needed)
- In your provider’s firewall settings, find the Custom TCP 3000 inbound rule and remove it.

Security Note: The existing rules allow the entire internet to use your DNS server. Ensure you have strong authentication on the AdGuard web interface.

Setup Complete!

Your DNS server is now fully operational with:

Privacy: Direct recursive resolution via Unbound
Security: DNSSEC validation, encrypted protocols (DoH/DoT/DoQ)
Ad-blocking: Custom blocklists via AdGuard Home
Automation: Auto-renewing SSL certificates

Need help? Check the AdGuard Home documentation or the Unbound documentation.

​Overview

​Prerequisites

​Server Setup

​Firewall Rules

​Update Your Server

​Step 1: Install AdGuard Home

​Initial Configuration

​DNS Settings Configuration

​Add Blocklists

​Step 2: Set Up Unbound (Recursive Resolver)

​Install Unbound

​Configure Unbound

​Download Root Hints

​Start and Test Unbound

​Step 3: Connect AdGuard Home to Unbound

​Update Upstream DNS

​Optimize Cache Settings

​Step 4: Secure with SSL/TLS (DoH & DoT)

​Install Certbot

​Obtain SSL Certificate

​Configure Encryption in AdGuard

​Automate Certificate Renewal

​Update Firewall Rules

​Setup Complete!

Overview

Prerequisites

Server Setup

Firewall Rules

Update Your Server

Step 1: Install AdGuard Home

Initial Configuration

DNS Settings Configuration

Add Blocklists

Step 2: Set Up Unbound (Recursive Resolver)

Install Unbound

Configure Unbound

Download Root Hints

Start and Test Unbound

Step 3: Connect AdGuard Home to Unbound

Update Upstream DNS

Optimize Cache Settings

Step 4: Secure with SSL/TLS (DoH & DoT)

Install Certbot

Obtain SSL Certificate

Configure Encryption in AdGuard

Automate Certificate Renewal

Update Firewall Rules

Setup Complete!