Learn how to setup AdGuard Home on Raspberry Pi for custom DNS, ad blocking, and VPN in one bundle. Perfect for tech enthusiasts.
AdGuard Home has been gaining in popularity as a viable alternative to Pi-Hole. In fact, we did a detailed comparison of AdGuard Home vs Pi-Hole and gave AdGuard Home a slight edge.
In addition, of the nearly 1,700 readers who took our poll, 67% of them picked AdGuard Home as their choice.
Loading ...
We have covered Pi-Hole setup on Raspberry Pi in great detail. We think AdGuard Home Raspberry Pi setup deserves similar attention. So here is our ultimate Raspberry Pi AdGuard home guide.
We debated a lot before writing this guide. Ad blockers are detrimental to content creators (including this website) as typically all ad revenue will be wiped out. Therefore, if you decide to install PiHole on Raspberry Pi for Ad Blocking, please consider supporting us by becoming a member for as low as $2 per month.
AdGuard offers various ad-blocking and privacy solutions. The number of options can be overwhelming, so we broke down the major AdGuard products for you. AdGuard Home is just one of them.
How does AdGuard work?
AdGuard Home provides free custom DNS for ad-blocking on your server. In essence, it is similar to Pi-Hole in offering private whole-home/network DNS level adblocking (all DNS requests that point to known ad servers are dropped).
It uses DNS filtering to block entire domains. When DNS requests match filter list rules, they're directed to a "blackhole," preventing unwanted data packets. AdGuard encrypts DNS requests, protecting against eavesdropping and hijacking, while also identifying and redirecting device requests to ad-related domains.
Adguard Home Dashboard
Once you have AdGuard Home running, there's no need to purchase a AdGuard DNS privacy subscription, as you can achieve the same level of protection. This AdGuard Home Raspberry Pi tutorial will help you set up an AdGuard ad-blocking DNS server and explore remote connections to AdGuard Home.
AdGuard Home Alternatives
If you only want alternative DNS privacy, there are many options you could choose over AdGuard Home.
To setup AdGuard Home on Raspberry Pi, you must install it to a device such as the Raspberry Pi and configure for your devices either individually or on the router for network-wide protection.
This guide is tailored for Raspi OS or Ubuntu/Debian-based Linux distros. In addition, we will also cover an alternate installation method using AdGuard Ubuntu appliance for Raspberry Pi.
The Raspberry Pi is ideal for many things, and AdGuard Home was designed to be installed on Pi and other singleboard computers. There are many other singleboard computers similar to the Pi also capable of running AdGuard. So, don't feel bad if your device is not a Pi, you can still follow this guide.
AdGuard Raspberry Pi Alternative - Linux mini-PC
The Raspberry Pi excels for smart homes and IoT due to its extensive hardware and software support. However, if your Pi primarily serves as a DNS server, you might underutilize its potential.
A powerful Pi can run additional software alongside AdGuard for DNS filtering without resource conflicts. If you're not into tinkering or IoT, consider a mini-PC running Linux as an alternative to a Raspberry Pi.
Atopnuc Ubuntu Mini Pc For Under $100
ATOPNUC is a good option for less than 100 USD. Just disable booting desktop and turn of sleeping, and you have yourself a lost-cost, low-power, unit.
Now that we have covered AdGuard Home alternative options and hardware let us get started with the Raspberry Pi AdGuard tutorial.
Loading ...
Adguard Home Raspberry Pi Setup Using the Commandline Installer
Step 1: What is needed to run AdGuard Home?
Here is what you will need to follow this AdGuard Raspberry Pi tutorial successfully.
Raspberry Pi 4 - 2 GB version is the best Raspberry Pi for PiHole. Any version of Raspberry Pi, including older models, should work quite well for AdGuard purposes. We recommend this Raspberry Pi 4 kit, which comes with a power adapter, case, and heat sinks. A kit is cheaper than getting the items separately.
Raspberry Pi 4 Power Supply (USB-C) - This is already included in the kits listed above. Don't skimp on the power adapter. A bad one can ruin SD cards, causing other problems.
Ethernet Cable - Although you can use Wi-Fi, we strongly recommend a wired connection for reliability since all your network DNS requests will depend on this.
Once you have Raspberry Pi and accessories, move on to setup the base operating system for AdGuard. There are several that you can use, but we recommend Raspberry Pi OS Lite, which is headless and uses little resources.
Do not worry, although the OS is headless (no GUI desktop environment), you can still manage AdGuard using its web interface.
Windows and MacOS installation of the Imager is straight forward. You download the installer and run it as any other package.
On Ubuntu, as of release 20.04 double-clicking no longer opens the .deb installer package with Software Center. You can either right-click on the .deb file, select Open with… and Software Install.
You can also use the command line, which is what I recommend. In this way, you can see what the issue is if it does not install. For me, it failed because of a dependency issue, but I was able to use the APT package manager to fix the issue.
To install Raspberry Pi Imager on Ubuntu on the command line, use the dpkg command in the terminal app. If you are not logged in as user root, run sudo su and enter your password.
dpkg -i Downloads/imager_1.7.4_amd64.deb
To change into the Downloads/ directory use the cd command. This works on any Linux, Ubuntu, Debian and derivative distros as well. If you encounter an error that software dependencies are not installed, you can fix that using the APT package manager.
apt install -y -f --fix-broken
The -y option is to say "yes" to install the dependencies, -f is to "force" installation, and --fix-broken is to fix packages broken by the error. Then you can rerun dpkg -i to ensure it is fully installed, but the apt command should handle the rest.
Write Raspberry Pi OS Image to SD Card
Once installed, launch Imager. The screen will initially look like this.
Rasbperry Pi Imager Start Screen
Choose the recommended OS, Raspberry Pi OS (32-bit ARM) Bullseye.
Choose An Operating System
Here I choose Raspi OS Lite because I do not want a pre-innstalled desktop.
Choose An Operating System From Raspi Os
Configuring Raspberry Pi Imager Advanced Options
If you do not configure advanced settings, you will need a keyboard and monitor connected to Raspberry Pi to finish the setup. Configuring advanced settings allows you to login to Pi remotely using SSH.
For me, on a Debian-based computer (Deepin or Depth OS), the gear icon normally in the bottom right-hand corner is not there (pictured above). On Ubuntu Studio it works normally. On a Windows computer, you can see the advanced settings option as shown below.
Advanced Settings Option In Imager
On some Linux distros (and older versions of macOS using newer versions of Imager), you might need to use CTRL+Shift+X to make advanced settings appear.
Enable SSH
For Raspberry Pi OS Lite, the advanced options allow you to boot and SSH in as the default user over Wi-Fi. This eliminates the need for a keyboard/mouse, monitor, and ethernet cable (still urged over Wi-Fi). Here we can set the hostname to "adguard" as well.
Setting The Host Name For Raspberry Pi
In the past, you could login to the Raspberry Pi OS using SSH once booted as user "pi" and the password "raspberry", after creating the ssh.txt file. But this was disabled for security reasons.
So, now creating an ssh.txt text file in the /boot directory only works if you have created a default user using Imager Advanced Settings (described below) or another way manually (not described in this guide).
Creating A Default User
You can enable user pi with a unique password in Imager at the same time you enable SSH, but it is NOT RECOMMENDED!
In an update to Raspberry Pi OS Bullseye the Raspberry Pi Foundation recommends you create a new default username and password, especially when enabling SSH on boot. This is what I am going to do.
Raspberry Pi Imager Advanced Options For User
Finish Writing the Image
You can also configure Wi-Fi and locale in advanced options, but we will skip that part and use ethernet instead.
Next, choose the storage to install on. In this case, the microSD card.
Choosing Storage On The Raspberry Pi Imager
Continue to erase all data and write the Raspberry PI OS to external USB thumb drive.
Raspberry Pi Imager Warns Erasing Data
Imager will tell you when it is done.
Raspberry Pi Imager Write Successful
Now you can remove the SD card, pop it into the Pi, and boot it.
Be the 1 in 200,000. Help us sustain what we do.
125/150 by Dec 31, 2024
You will gain benefits such as Deployarr access, discord roles, exclusive content, ad-free browsing, and more.
To start Raspberry Pi OS, insert the SD card into RPi, connect the Ethernet cable, and power it up. If you did not enable SSH and create a new user, then connect the Pi to a monitor and keyboard, create a new user when prompted, and continue with this AdGuard Home tutorial.
Even though you may have enabled Wi-Fi in the Advanced Options previously, we highly recommended using Ethernet as a DNS server is essential for the reliability of your network.
Step 3a: Enable SSH in raspi-config
Note that this method replaces the previous method of enabling SSH access by creating an ssh.txt file.
You can now enable SSH by running:
sudo raspi-config
Choose Interface Options from the menu.
Raspberry Pi Os - Raspi-Config Start Screen
Choose SSH from the next menu screen.
Raspi-Config - Interface Options
The next screen will prompt you to confirm with "yes".
Login to your Wi-Fi router administration page, look through your list of connected clients and note down the IP address of your Raspberry Pi. In my case, it is 192.168.12.223.
While you are there, set up a static IP for your AdGuard Raspberry Pi (this is required).
Most modern routers rarely change the IP addresses of connected clients. However, when it does happen your AdGuard instance will not be available and there is a good chance you may not have internet access as well.
The procedure to set static/fixed IP for clients vary by the router. Consult your Router documentation on how to set static IP for clients. The screenshot below shows how to do this on the UniFi controller.
Set Static Ip For Pi-Hole
Step 3c: Connect to AdGuard Through SSH
Once you have the AdGuard Home's IP address, use an SSH Client such as MobaXterm and connect to your Raspberry Pi through SSH using:
IP Address / Host, which in this AdGuard Home guide is 192.168.12.223
Port 22
Now you can use the new default username and password to login.
Run the installer to install AdGuard Home on Raspberry Pi.
./AdGuardHome -s install
Once installation is completed you can access the setup wizard through AdGuard Home setup wizard's port 3000 using the IP address for the Raspberry Pi.
Ubuntu AdGuard Home Appliance (Alternate Installation Method)
Using the Ubuntu AdGuard Home Appliance on Raspberry Pi offers several benefits, including enhanced security and software support. Installation is straightforward: write the image to an SD card using Raspberry Pi Imager.
Ensure you configure advanced settings like login, SSH, Wi-Fi, locale, and time zone within the Imager since raspi-config is not available.
Download and Decompress AGH Ubuntu
First, we must download and decompress the AGH image from the Ubuntu appliances index using our old friend wget and the unxz command to decompress the .xz tarball.
Now we will launch Imager. Though I am using Imager on Ubuntu here, the process is virtually the same on Windows and macOS.
Only differences the methods to uncompress the down (e.g. using a utility such as 7zip on Windows) and the file browser for each operating system.
Burn Ubuntu AGH to SD
Open the downloaded image with Raspberry Pi Imager application, as a custom image (the last option).
Choosing A Custom Image In Imager
Navigate to the folder where the image is stored.
Navigating To The Image In Dolphin File Browser
Select it and then choose the storage to install the image on as described above. In this case, I used an SD card, so it sees this as internal storage.
Ubuntu Agh Image To Burn To Sd On Imager
Hit the Advanced Settings gear icon.
Configure locale and time zone in Imager
We covered login, SSH and Wi-Fi already, but here we also set locale, time zone and keyboard layout. For me, the locale and keyboard layout need to be US. The time zone needs to be EST.
Setting Locale, Time Zone And Keyboard Layout In Imager
Then we hit Write and get the warning that all data will be erased as above. When it is though we get the write successful prompt the same as above. Now all you have to do is insert the SD into the Pi and boot to AGH on Ubuntu.
AdGuard Home Setup Wizard
To get to the AGH setup wizard navigate to 192.168.12.223:3000, where 192.168.12.223 is the IP address of my Pi.
This is not the admin dashboard but the setup wizard for first run only. After the initial setup, port 3000 is not used anymore.
Here we begin the setup process, which was also previously covered in our AdGuard Ubuntu guide.
Adguard Home Raspberry Pi Setup - Step 1
Configuring Default Ports for AGH
Next, we set up the web interface port for administration, which is 80 by default.
Adguard Home Raspberry Pi Setup - Step 2: Port 80
But, in my case port 80 is already in use by another application, so I can change the default from 80 to 8080.
Adguard Home Raspberry Pi Setup - Step 2: Port 8080
The DNS server uses port 53 by default. This is what you should always use.
Adguard Home Raspberry Pi Setup - Step 2: Port 53
Creating a Username and Password
Now we create a username and password.
Agh Setup Wizard Step 3: Creating A Username And Password
Private IPs and Setup Instructions
Now we are shown our private IP addresses and links to setup instructions for various platforms.
Agh Setup Wizard Step 4: Private Ips And Setup Guides
Congratulations! Open Dashboard
Now we receive congratulations and are prompted to Open Dashboard.
Agh Setup Wizard Step 5: Open Dashboard
AGH Admin Web UI Dashboard Login
Then we see the dashboard login screen.
Agh Admin Ui Dashboard Login Screen
AGH Admin Web UI Dashboard
Here is a screenshot of the AGH Admin Web UI dashboard on first run.
Agh Web Ui Dashboard First-Run Screenshot
AdGuard Home Initial Configuration
From the web interface, you now perform the initial configuration. We have already covered this in great detail:
Individual device or router-level AGH ad blocking: Router-level may affect some free content (e.g., TubiTV), so enable a guest network for such apps on streaming devices. Access router settings (varies by manufacturer) and forward port 53 to Pi's IP address (use ip addr show to find it). Works for both IPv4 and IPv6.
Important Note
We debated a lot before writing this guide. Ad blockers are detrimental to content creators (including this website) as typically all ad revenue will be wiped out. Therefore, if you decide to install PiHole on Raspberry Pi for Ad Blocking, please consider supporting us by becoming a member for as low as $2 per month.
Method 1: Configuring The Router for Whole-home Ad Blocking (Recommended)
To block ads on a network level (all network devices use Pi-hole as DNS) manually change or add your Pi-hole DNS server IP on your router as a DNS IP address.
Most routers allow manually setting DNS servers, but some do not make this advanced option available. You can try using custom router firmware to resolve this issue permanently.
Custom Router Firmware
Custom router firmware such as DD-WRT, OpenWRT, and Tomato, open up this option among several others. So if you do not see an option to change DNS name servers, consider switching to one of the supported free alternate router firmware.
The advantage to configuring your router to use Pi-hole for DNS is that there is only one place you will need to update your DNS server IP instead of each and every device. Another reason you might need to block DNS ads at the network level is that some devices do not even offer the option to change DNS settings.
Disadvantages of using AdGuard for DNS only
DNS ads are not all ads. For full ad-blocking you need a standard ad blocker as well. For instance, you can stream from your browser using an AdGuard ad blocking extension to a device capable of only using DNS. This allows you to use both because the ads are blocked by the browser by AdGuard extension app and DNS blocking is enabled on the device where you cannot install the app.
Solutions for per-host tracking or resolving hostnames
You may let your AdGuard Home handle DHCP instead of your router to overcome the limitations above: 1) visualize requests by host (per-host tracking) and 2) reach devices using their hostname.
Method 2: Configuring your devices (not recommended)
The procedure to manually set DNS servers will depend on the device and the operating system. This process is tedious and not recommended.
In addition, if your device leaves home (eg. mobile phones), you may not be able to connect to your AdGuard Raspberry Pi IP and therefore your internet won't work.
Typically, you will have to open the network connection and find the place to put in DNS server IP manually. Covering this is beyond the scope of this guide. Below are some external references for examples, where you can substitute your AdGuard Home Raspberry Pi IP address in place of public DNS IPs.
To configure AdGuard Home, you will have to access the web interface/dashboard.
How do I access AdGuard admin dashboard?
The AdGuard Admin dashboard or web interface can be accessed using a web browser with the URLs http://IP-ADDRESS:80 or http://agh.local. IP-ADDRESS is the Pi-hole server's local IP address (eg. 192.168.12.223 in this guide). Login using the password you created through the initial configuration wizard.
Configuring AdGuard
How to configure AdGuard? After initial configuration, there is not much more to configure.
One good customization to make is expanding or editing your blocklists. You can add blocklists from various online sources to enhance adblocking. These blocklists are trusted and you would rarely have any false positives.
Most AdGuard users may want to expand on blocklists (eg. for known malware/ransomware hosts). The AdGuard community is an excellent source of new information, and several users have created and continued to maintain custom expanded blocklists. Firebog Big Blocklist Collection is a notable one.
The Big Blocklist Collection For Adguard
Caution: Do not add every blocklist you can find. This can break your internet experience and cause trouble (eg. shopping sites, referral/cashback sites, CNN app, GitHub webpage, etc. may not work). The basic/default lists are a great starting point and already block most ad domains.
AdGuard has services check page to tell you what you are running, if anything. If you are not running their apps, you will see an Install button for each app you don't have installed.
Adguard Services Check-Page Shows
Another way to test how well your ad blocker is performing is with Toolz, which tests how many ads you are blocking. You can host Toolz yourself, if you are tech savvy. However, Toolz is also hosted online, if you want to test the apps you are currently using.
AdGuardHome -s uninstall #Uninstalls the AdGuard Home service
AdGuardHome -s start #Start the service
AdGuardHome -s stop #Stop the service
AdGuardHome -s restart #Restart the service
AdGuardHome -s status #Show the current service status
Installing AdGuard Home is just the beginning when it comes to establishing privacy. You can take more measures to further secure your setup. If your AdGuard Home server does more than provide private DNS, you may also want to take measures to improve the life and performance of your server device.
AdGuard Tweaks
Here are some AdGuard tweaks that can make your AdGuard setup even better.
1. Improving AdGuard Performance and Life
AdGuard Home cannot easily slow down the Pi, but a slow physical server can certainly affect AGH.
While a DNS server really does not have a great need for speed, the Raspberry Pi will decrease the longevity of a MicroSD card the more it writes to it. An ad blocker will assuredly write more often to the SD card than other applications.
In order to minimize this, you can either install the operating system on a USB jump drive instead or use Log2RAM to write to memory.
Log2RAM works on every Linux distro. If your Raspberry Pi is doing more than acting as a DNS server for AdGuard, you may have other reasons to increase performance. You can do this by installing Rsync and enabling it for Log2RAM by uncommenting the line USE_RSYNC=true in /etc/log2ram.conf.
You must install rsync as well.
apt install -y rsync
If Rsync is not enabled, Log2RAM will use the cp command to copy logs to RAM instead.
USB Boot AdGuard Home Raspberry Pi
For optimal performance when running an operating system on a Raspberry Pi, utilize a small-sized USB jump drive, preferably 32GB or less, as smaller drives read data faster due to reduced data volume. This speed advantage is particularly noticeable with standard hard drives featuring rotating spindles.
USB jump drives also boast higher durability compared to MicroSD cards, with the option of further increasing their lifespan using Log2RAM. My setup employs a flash drive as the primary hard drive, while the 8GB internal SD card serves as a configured swap partition, delivering even better results when combined with Raspberry Pi cases designed for solid-state drives.
AdGuard Home is great for what it does, blocking ads. But your DNS servers (e.g. your ISP, Google, etc.) can and do sniff to find out what websites you are visiting (even the HTTPS sites). This is because DNS name resolutions (eg. google.com refers to this IP) are done as plain texts. In addition, this also poses some level of security risk.
DNS Over HTTPS
The solution here is to send even your DNS lookup through HTTPS protocol (encrypted). Not all DNS providers offer this (because they won't be able to track your activity). Cloudflare does provide DNS over HTTPS.
Setting up DNS over HTTPS with AdGuard is quite easy, if you follow the instructions in the AdGuard wiki by the AdGuard Team.
Cloudflare has a test page that will provide information on your connection. Visit this page and it will tell you where you are connecting from, which DNS resolvers you are using, and whether the connection is secure or not.
Combine AdGuard with Unbound
I have AdGuard and DNS Over HTTPS, can I improve my privacy even more?
Yes, in the same manner as you would Pi-Hole. Take a look at configuring Unbound with Pi-Hole. Instead of trusting your upstream DNS (eg. Cloudflare's 1.1.1.1 or 1.0.0.1), Unbound, a recursive DNS resolver that will run locally, will connect to the responsible server directly.
This will avoid the exact path you are visiting from being logged anywhere.
Troubleshooting
Yandex browser and Samsung Internet mobile browser
Using AdGuard for Android on your smartphone, but still seeing ads? The AdGuard Content Blocker was developed for Yandex browser and Samsung Internet mobile browser to block ads without root permissions.
Hardcoded DNS
If you see ads on some devices and not on some then try rebooting your router first to renew DHCP leases. If you still continue to see ads, then the DNS server IP may be hard coded on the device (eg. Chromecast).
Some allow you to change it and some do not. Look through your device's network or DNS settings to check if you can change your DNS IP to your AdGuard's IP, or even better your internet gateway's IP (since you have already configured this to run through AdGuard).
No Internet
This happened when my SD cards failed. If you have no internet, make sure AdGuard is up and running by trying to SSH into it or opening the AdGuard admin dashboard. If not, try restarting Raspberry Pi by pulling the power.
Another option is to restore your DNS server IPs on the router/device back to the upstream DNS IP (1.1.1.1 and 1.0.0.1 for Cloudflare or leave them blank to use your ISP's DNS). If the internet works, then the problem is with the AdGuard setup. You may try to reconfigure using the AdGuardHome -s restart command.
FAQs
How do I set up AdGuard Home on Raspberry Pi?
The easiest AdGuard Home Raspberry Pi installer to use is the official Raspberry Pi Imager. Imager allows you to easily install Raspberry Pi OS and run the AdGuard Home installation script. [Read:AdGuard Home Docker Compose: No Ads + Privacy in 5 min]
Which Raspberry Pi is best for AdGuard Home?
Any Raspberry Pi is capable of running AdGuard Home because a DNS server uses very little hardware to respond to queries. By way of comparison, on an OpenWrt router AGH hardware requirements are a minimum of 50MB free RAM and 100MB free disk/flash space.
What should I run AdGuard Home on?
Using AGH on a Raspberry Pi Zero is one suggestion, because it only requires minimal hardware. A home DNS server does not need to be a robust, high-end server. Any dev board or old mini-PC should work.
Is AdGuard a Russian company?
AdGuard was founded in 2009 in Moscow. Later they moved their headquarters to Cyprus as a "conscious decision", in order to operate under the EU law.
AdGuard Tutorial - Closing Thoughts
AdGuard proves to be an excellent choice for maintaining an ad-free online experience while safeguarding against invasive content from advertisers infiltrating your data stream, requiring minimal effort to set up and maintain.
The real reward becomes evident as tailored ads recede, offering a fresh perspective on product discovery and alleviating the monotony of being inundated with the same targeted offerings.
I strongly recommend trying AdGuard Home on Raspberry Pi to improve your internet experience.
I am a backend dev. I have done tech support for frontend devs. I have also done container development of every kind. I am an avid Linux user. Ask me anything about Linux or GNU open-source software, and I can tell you. I like to tinker and learn through formal education, and also like to learn things on my own. I have two degrees in web development and system administration. I have also done a lot of network admin, and have been a network technician before too. You know, getting on all fours and barking at Ethernet cords like a dog!
