Install AdGuard Home on an OPNsense router

📆2022-02-13🍱server

I recently decided to upgrade my old Asus router to something more modern and fun. Since going the self-hosted and open-source path recently, the choice was easy. A small, dedicated hardware running OPNsense.

One of the most important services I host is AdGuard Home, which I've been running on either a dedicated Raspberry Pi or in Proxmox. With this new router I think it's a good idea to combine router and DNS since they should work together as much as possible. So let's install AdGuard Home on the same device as OPNsense.

Make AdGuard Home installable as a plugin

First we need to add mimugmail community repo, so we can install AdGuard Home as a plugin. That is easiest done over ssh. If you don't need to have ssh activated all the time (especially not for root) we can temporarily activate it just for this occasion. If you already have set up SSH you can ignore this.

In OPNsense WebUI, navigate to System: Settings: Administration
Scroll down to Secure Shell and check
- Enable Secure Shell
- Permit root user login
- Permit password login
Save the settings

Now connect to OPNsense over ssh and run this command fetch -o /usr/local/etc/pkg/repos/mimugmail.conf https://www.routerperformance.net/mimugmail.conf pkg update to add the repo.

Reverse the steps above to disable SSH again.

Install and set up AdGuard Home

Head over to System: Firmware: Plugins and search for AdGuard and install it.
Go to Services: Adguardhome: General and enable the plugin, then save.

Since DNS as default is listening on port 53 we also want AdGuard Home to listen on this port to make or life easier. Out of the box OPNsense is already running Unbound on this port. We need to change this so they don't conflict with each other.

Navigate to Services: Unbound DNS: General
Change Listen Port to 5353
Check Register DHCP leases and Register DHCP static mappings, this will resolve hostnames for us in AdGuard Home.
Save the settings.

Now we are ready to configure AdGuard Home itself. I will not go in to all configuration here but some things are needed to make this work optimal with OPNsense.

Navigate to http://*opnsense-ip*:3000/ in your browser and follow the wizard.
Set the Admin interface to listen on your router IP only (often 192.168.1.1), the same you use when configuring OPNsense itself. Also set the port to be 8080.
The DNS Server can listen on all interface and use the default port 53.
In the next step pick a username and password.

When the wizard is complete we can login to AdGuard Home with the credentials you entered.

In AdGuard Home navigate to Settings -> DNS settings and scroll down to Upstream DNS servers -> Private reverse DNS servers.
Here we enter the Unbound server we changed earlier in OPNsense settings, 192.168.1.1:5353, or with other port pointing to you OPNsense instance if you have another one.

Resolve local domains

If you use a domain name to resolve local hosts by name instead of IP you might need to tweak that in AdGuard Home as well. Let's say you've entered a domain under System: Settings: General that is home.mydomain.xyz, and you want that to take precedence over the public DNS, if that also exists, when you are at home.

In AdGuard Home navigate to Settings -> DNS settings and go to top section under Upstream DNS servers.
Add [/home.mydomain.xyz/]192.168.1.1:5353 at the top of that list.
Now you will resolve local machines when connected to your LAN, and if connecting over the internet the public DNS record will be used instead.

That's the only settings you need to do to make this work. You should, of course, tweak the other settings and add some filter rules, but that is standard AdGuard Home configuration.

Under OPNsense you can navigate to System: Settings: General and add backup DNS servers under Networking -> DNS servers, but if you leave them empty only AdGuard Home will be used. I usually leave them empty.

Information gathered from OPNsense forum. Thanks to yeraycito, N0_Klu3 and pmhausen.