Features
AdGuard Home
Block banners, pop-ups and video advertisements network-wide
WireGuard
A VPN server accessible from public networks (IPv4 & IPv6)
Unbound
A validating, recursive, caching DNS resolver (DoT)
with
Stubby (simple)
DNS queries are sent to resolvers over an encrypted TLS connection providing increased privacy
or
DNScrypt (advanced)
Modern encrypted DNS protocols such as DNSCrypt v2, DNS-over-HTTPS, Anonymized DNSCrypt and oDoH (Oblivious DoH)
Cloudflare
Better performance & security for websites, APIs, and Internet applications
All software are free, open-source and self-hosted
ABOUT | FAQ | WIKI
🧪
DNS query speed BIND'S dig tool results from google.com servers:
- AdGuard default DNS resolvers -
60-70 msec
- Public Cloudflare/Quad9/Google DNS Resolvers -
50-70 msec
- This setup/configuration -
5-10 msec
🎥 Preview
AdGuard default vs setup/configuration:
vid.mp4
Public Cloudflare/Quad9/Google:
(same results if addresses are added manually on systems)
vid2.mp4
Project Status
Last tested: 17 April 2022
Projects | Status |
---|---|
AdGuard Home | |
Unbound | ✅ |
Cloudflared | |
DNScrypt | ✅ |
Stubby | |
WireGuard |
Table of contents
- Requirements
- Install Raspberry Pi OS
- Install AdGuard Home
- Install Unbound
- Install Cloudflare
- Install WireGuard
- Repository Resources
Requirements
This tutorial is installed with Raspberry Pi. Other Linux operating system(𝟹𝟸/𝟼𝟺bit), hardware or cloud service can be used.
(Raspberry Pi OS is most simple and recommended for Pi. For more experience users, DietPi OS is also recommended)
- A Raspberry Pi 3 or 4 version
- A router that supports port forwarding(most can)
- MicroSD USB card reader
- MicroSD card (8GB or bigger, at least Class 4)
- Ethernet cable
- (Optional if using monitor) MicroHDMI-(RPi 4) or HDMI-(RPi 3)
Install Raspberry Pi OS
Raspberry Pi OS comes in desktop and lite versions(use lite for headless mode). It can be accessed with a monitor/keyboard/mouse or connect via ssh from a terminal.
Raspberry Pi OS cannot be setup through the wizard anymore, the Imager utility is needed to preconfigure an image user account.
-
Install Raspberry Pi Imager: https://www.raspberrypi.com/software/
-
Download Raspberry Pi OS image: https://www.raspberrypi.org/software/operating-systems/
- Open Pi Imager tool and configure settings in advanced options. Choose image, select microSD card and click
Write
.
Place SD card into the Raspberry Pi, plug in Ethernet cable and boot up
Access Pi OS with SSH
-
Wait for a minute for Pi's first boot up
-
Open browser and login router's admin panel(default gateway address)
-
Find list of all devices connected to network and copy the IP address of the Raspberry Pi. It will most likely have the hostname
raspberrypi
-
Open terminal on host machine (Windows powershell or raspcontroller for Android can be used).
Type the following command:
ssh pi@pi's IP address
Use right mouse button to paste text in Windows powerShell.
Type “yes” for fingerprint question, and enter password.
Run in terminal:
sudo apt update -y && sudo apt upgrade -y
Reboot when finished
sudo reboot
Install AdGuard Home
This installation script is from AdGuard Home main project. Follow to keep updated.
Run the following command in terminal:
Stable :
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
Beta - testing version of AdGuard Home. More or less stable versions(recommended for Raspberry Pi) :
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c beta
Edge - newest version of AdGuard Home. New updates are pushed to this channel daily and might not be stable :
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c edge
-
When installation is finished, it will show the
links
to your AdGuard home page(Get Started) in terminal -
IMPORTANT:
In Listen Interfaces option chooseEth0
and select next
-
Set up username&password and then login admin panel
-
IMPORTANT:
In general settings, set "Query logs retention" to24 hours
. (I read that for some people logs fill up which slows down Pi and needing a reboot)
Setup devices to work with AdGuard
- For Android/Apple, go to WiFi advanced settings and select static option. In
DNS 1
field enter "Pi's IP" address
-
For PC/Windows
- IPv4
Go to network settings / change adapter options, right click in properties and select "Internet Protocol Version 4(TCP/IPv4)". Enter Pi's IP address in
Preferred DNS
server.- IPv6 (needed for
DoH
/DoT
/oDoH
to detect if using it)
Go to "Internet Protocol Version 6(TCP/IPv6)" Enter
::1
OPTIONAL:
Add a backup DNS in the alternative fields
BE AWARE:
In Android, adding a public DNS in second field breaks AdGuard ad blocking
Updating AdGuard
AdGuard Home can be updated from its user interface or manually from command line which I recommend for now.
Use script constructed with update commands[click here].
Setting up AdGuard blocklist
In AdGuard homepage under filters, select DNS blocklist section for adding URLs.
Ultimate blocklists sources :
black-mirror - Automatically maintained malicious host blacklists and false-positive whitelists
IMPORTANT:
Some lists can block important web content. To unblock, go to "Query Log" section, hover cursor over that specific query(look for client IP & time) to show unblock option. The links is automatically created in "Custom filtering rules" example: @@||bitly.com^$important
(can add the websites manually as well).
Add/Remove multiple URLs
Only one URL can be added at a time in DNS blocklist with AdGuard for now, but there is a python script to add multiple URLs at once.
Create a new python file(bulkurls.py):
nano bulkurls.py
Then copy and paste script text[click here]. Set your AdGuard credentials
and save (control+x then y then enter).
If using DietPi install sudo apt-get install python3-pip -y && pip install requests
for it is not installed by default.
To run : sudo python3 bulkurls.py
Reboot when finished
To remove change add
in second of last line to remove
in bulkurls.py file.
Go to https://d3ward.github.io/toolz/adblock.html to test if ads are blocking
Or just visit some ad infested sites.
Install SSL certificate
If using AdGuard Home on a VPS(Virtual private server)
, get a SSL certificate to make connection secure and data safe[click here]. In this case your DNS resolver(AdGuard Home) resides outside your network, and your DNS requests have better protection from the third parties.
Install Unbound
RECOMMENDED:
Before installing other DNS resolvers, it is a good idea to turn off systemd-resolved DNSStubListener(issue#27).
Run the following command in terminal:
sudo apt install unbound -y
For recursively querying a host that is not cached as an address, the resolver needs to start at the top of the server tree and query the root servers, to know where to go for the top level domain for the address being queried. Unbound comes with default built-in hints.
wget -O root.hints https://www.internic.net/domain/named.root && sudo mv root.hints /var/lib/unbound/
IMPORTANT:
This needs to update every 6 months using cron job.
Enter in command line crontab -e
, it will ask select an editor(choose 1), paste these lines at the bottom of crontab and save (control+x then y then enter):
1 0 1 */6 * wget -O root.hints https://www.internic.net/domain/named.root
2 0 1 */6 * sudo mv root.hints /var/lib/unbound/
If using DietPi, install resolvconf and restart unbound-resolvconf.service to set default nameserver(127.0.0.1) :
sudo apt-get install resolvconf -y && sudo systemctl restart unbound-resolvconf.service
Install Cloudflare
(DoH/oDoH)
Setup Cloudflare with Option 1 (Simple)
Cloudflare Tunnel[click here]:
(DNS over HTTPS only)
Option 2 (Advanced)
click here]:
- DNS over HTTPS DNScrypt proxy[- Oblivious DNS Over HTTPS (experimental)
- Anonymized DNS
Oblivious DNS Over HTTPS (oDoH) is a newly proposed open-source DNS standard built by engineers from Cloudflare, Apple, and Fastly which is supposed to increase the privacy of already existing DNS Over HTTPS.
Anonymized DNS client encrypts the query for the final server instead of directly reaching a server that is one of the public resolvers, but sends it to a relay.
(DoT)
on Unbound
Configure Cloudflare Create a unbound configuration file with DNS over TLS settings. Enter in terminal:
sudo nano /etc/unbound/unbound.conf.d/unbound.conf
And copy and paste all the text from this unbound.conf file[click here] and save (control+x then y then enter).
Configure Stubby and Unbound
Use Unbound for caching and Stubby as a TLS forwarder(if NOT using DNScrypt).
Install Stubby:
sudo apt install stubby -y
Remove and re-create stubby.yaml file:
cd /etc/stubby/ && sudo rm stubby.yml && sudo nano stubby.yml
And copy and paste all the text from this stubby config file[click here] and save. (cd
to return to home folder when finish).
IMPORTANT:
Forward Stubby address in Unbound upstreams. Open nano /etc/unbound/unbound.conf.d/unbound.conf
and uncomment Stubby address(remove # infront of line):
# forward-addr: 127.0.0.1@8053
# forward-addr: ::1@8053
forward-addr: 127.0.0.1@8053
forward-addr: ::1@8053
IMPORTANT:
Stubby and DNScrypt cannot be used together when both are set to run as a forwarder, else redundant caching will occur.
- Restart unbound & stubby and check status:
sudo systemctl restart unbound stubby ; systemctl status unbound stubby -l
(DoH/DoT/oDoH)
Configure AdGuard with -
In AdGuard homepage under settings, select "DNS settings"
-
Delete everything from both Upstream and Bootstrap DNS server options and add the following for:
-
DNS over TLS(unbound) :
127.0.0.1:53
-
DNS over HTTPS/Oblivious DNS over HTTPS :
127.0.0.1:5053
(cloudflared tunnel)127.0.0.1:5353
(dnscrypt proxy)
-
TLS forwarder(stubby) :
127.0.0.1:8053
-
-
IMPORTANT:
Check "Parallel Request" option for DNS resolvers to work simultaneously.
- Then in DNS setting look for DNS cache configuration section and set cache size to
0
(caching is already handled by Unbound) and click apply.
Click apply and test upstreams
Stable DNS resolving
IMPORTANT:
Help resolve multiple DNS servers on Windows system and Android browsers. Linux works fine(tested on ubuntu)
Windows
-
Install Acrylic DNS Proxy: https://mayakron.altervista.org/support/acrylic/Home.htm
-
Go to
C:\Program Files (x86)\Acrylic DNS Proxy
and openAcrylicConfiguration.ini
file. Delete everything and copy these settings[click here], only change PrimaryServerAddres to your Pi's address. -
In same folder run
RestartAcrylicService.bat
&PurgeAcrylicCacheData.bat
TIP:
Troubleshoot IP/DNS Commands
ipconfig /release
ipconfig /renew
ipconfig /flushdns
Android
-
In whatever browser is used, turn off
Use Secure DNS
option if available. -
Be aware conflicts can occur with custom rooted roms&kernels with build.prop DNS tweaks or apps/magisk module.
https://1.1.1.1/help in browser and these options should output 'Yes'.
Now go to- Connected to 1.1.1.1
- DNS over HTTPS(DoH)
- DNS over TLS(DoT)
- DNS over WARP
Other sites to check security
https://browserleaks.com/dns - should show all connected to "Cloudflare"
https://www.cloudflare.com/ssl/encrypted-sni/ - "Secure DNS / DNSSEC / TLS 1.3" should all be a green tick
https://dnssec.vs.uni-due.de/ - should say "Yes, your DNS resolver validates DNSSEC signatures"
Install WireGuard
Before installing WireGuard, if you do not have a static IP it will change dynamically from your internet service provider or from a router reboot. You will need to setup a dynamic DNS service with a hostname to keep automatically up-to-date with a dynamic IP[click here]. Or else skip this.
You also need to set up port forwarding on your router so you can access WireGuard network anywhere like a coffee shop hotspot and even from mobile data tethering.
TYPE | VALUE |
---|---|
Device | Raspberry Pi's hostname or IP |
Protocol | UDP |
Port range | 51820-51820 |
Outgoing port | 51820 |
Permit Internet access(if have) | yes |
My router port setting:
Other router brands will have a different interface look. Google search it for help. If you cannot connect from a outside network that means your ISP has blocked outcoming connections, call them and ask nicely to unblock.
👊BIG THANKS👊 for this installation script from Nyr. Follow to keep updated.
(PiVPN script can also be used)
Run the following command in terminal:
wget https://git.io/wireguard -O wireguard-install.sh && sudo bash wireguard-install.sh
-
The script is going to ask for a Public IPv4/hostname for the VPN. If you have static IP then continue or else type the dynamic DNS hostname that you created from the instructions. For example:
trinibvpn.freeddns.org
-
For port option
press enter
for default 51820, set client name and for DNS use option 3 (1.1.1.1
) for now.
- Wait until the installation is finished and QR code to show, don't close. But if do, to
regenerate qrcode
, enter in terminal but replacing just the nameyourclientname.conf
file to yours:
sudo cp /root/yourclientname.conf /home/pi && sudo qrencode -t ansiutf8 < yourclientname.conf
IMPORTANT:
You will need to add a new client/user for each device used with the VPN(cannot share 1 client to multiple devices). To add, re-run the script and create another user with different client name.
[click here]
Install OpenVPN as an alternativeConnecting VPN To Android/IOS Phone
Install the WireGuard app from Google Play or App Store:
WireGuard (Google Play): https://play.google.com/store/apps/details?id=com.wireguard.android
WireGuard (App Store): https://apps.apple.com/us/app/wireguard/id1441195209
Scan the QR code shown in the terminal with WireGuard app, select the + button
and use the option Scan from QR code
to install configuration.
IMPORTANT
: Enable kernel module backend in settings
Connecting VPN to Windows
WireGuard for windows: https://download.wireguard.com/windows-client/wireguard-installer.exe
-
Create a
new text document
with any name on PC to copy over the text from WireGuard client configuration file. -
To see text in client config file, type in terminal:
sudo cat /root/yourclientname.conf
-
Highlight all the text, copy and paste it in the txt file on PC and save. Then rename the extension from
txt
toconf
. Now you have config file for that specific WireGuard client/user. -
Import the config file to WireGuard (import from file option).
Configure WireGuard with adblocking & DNS security
ADVICE:
I think it might not make much of a difference to use DoT/DoH/oDoH with WireGuard security protocols. Though from my experience and in forums, it does not seem to cause any issues using them together. Mainly this is to achieve adblocking with a VPN on public networks.
-
In WireGuard app, select your tunnel name and select edit (pencil on top right)
-
Under DNS servers enter
Pi's IP
(IPv4 & IPv6) and save
Limit traffic
WireGuard will lose a fair percentage of internet speed from the process of tunneling through Linux system, to router and to devices. You need send traffic through your local network only for better speeds[click here].
Disable all IPv6
click here]. In result if you have weak internet, disabling IPv6 can speed up dns records and request but have less security.
Disable IPv6 if you don't have it or don't want it[Test VPN
How to know if WireGuard VPN is really working?
For windows download Wireshark: https://www.wireshark.org/#download
Once downloaded, use the application to inspect data packets where the protocol is set to the one used by WireGuard VPN. When a packet traffic is encrypted
, it can be read like this for example:
For android use PCAPdroid: https://play.google.com/store/apps/details?id=com.emanuelef.remote_capture&hl=en&gl=US
You should see all connections closed
and status showing all DNS port 53
and not any TLS port 443 connections from all apps. (open and use apps for PCAPdroid to scan)
ANY ISSUES, FIXES OR TIPS TO MAKE THESE PROJECTS BETTER PLEASE CONTRIBUTE
Repository Resources
https://github.com/AdguardTeam/AdGuardHome/wiki
https://developers.cloudflare.com/
https://unbound.docs.nlnetlabs.nl/en/latest/
https://dnsprivacy.org/dns_privacy_clients/
https://github.com/DNSCrypt/dnscrypt-proxy/wiki
https://github.com/anudeepND/pihole-unbound