If you are running OPNsense at home, and also want to run local DNS filtering, then the AdGuard Home plugin is the easiest way to run every thing on the same box.

My OPNsense Hardware

Recently I purchased a Topton mini PC from AliExpress to replace my aging Netgear router which had decided to start rebooting itself every hour or so. I chose the Intel N100 processor and the option to include 8GB of RAM and a 256GB NVME and the device arrived with the latest version of OPNsense installed.

Enable SSH

The first thing to do is enable SSH, as this is needed to add the community repository to your device.

  1. Navigate to System | Settings | Administration and then find the Secure Shell section, as shown in the image below.
  1. Set the following options:
    • Check Enable Secure Shell
    • Check Permit password login
    • Check Permit root user login (only needed if using a root account)
  2. Scroll to the bottom of the page and click Save.

Add the Community Repository

AdGuard Home is not included as an available plugin, so the next step is to add the OPNsense repo by mimugmail which includes quite a few useful packages.

  1. SSH into the OPNsense machine
  2. Add the new repository and update:
fetch -o /usr/local/etc/pkg/repos/mimugmail.conf https://www.routerperformance.net/mimugmail.conf
pkg update

Install the AdGuard Home package

Next we switch over to the OPNsense UI to install the Adguard Home.

  1. Open the OPNsense portal, and navigate to System | Firmware | Plugins.
  2. Search for adguardhome:
  1. Press the + symbol at the right side to start the installation.
  2. This should only take a few seconds and you will see output similar to the following:
***GOT REQUEST TO INSTALL***
Currently running OPNsense 23.7.9 at Sun Dec  3 20:26:31 PST 2023
Updating OPNsense repository catalogue...
OPNsense repository is up to date.
Updating mimugmail repository catalogue...
mimugmail repository is up to date.
All repositories are up to date.
The following 1 package(s) will be affected (of 0 checked):

New packages to be INSTALLED:
	os-adguardhome-maxit: 1.10 [mimugmail]

Number of packages to be installed: 1

The process will require 27 MiB more space.
6 MiB to be downloaded.
[1/1] Fetching os-adguardhome-maxit-1.10.pkg: .......... done
Checking integrity... done (0 conflicting)
[1/1] Installing os-adguardhome-maxit-1.10...
[1/1] Extracting os-adguardhome-maxit-1.10: .......... done
Stopping configd...done
Starting configd.
Migrated OPNsense\Adguardhome\General from 0.0.0 to 0.0.1
Reloading plugin configuration
Configuring system logging...done.
Reloading template OPNsense/Adguardhome: OK
Checking integrity... done (0 conflicting)
Nothing to do.
***DONE***
  1. Navigate to Services | Adguardhome | General and Enable the service and press Save.

Configure AdGuard Home

The next steps will move across to the AdGuard Home UI.

  1. Browse to http port 3000 on at your OPNsense machine. This will look something like http://192.168.1.1:3000 or http://10.0.0.1:3000 depending on your network setup.
  2. Change the following settings in the setup wizard:
    • Admin Listen interface: Set this to the LAN interface (you don't want this exposed on a WAN port).
    • Admin Port: Set this to port 3000 so this doesnt conflict with OPNsense.
    • DNS server Listen interface: Again set this to the LAN interface.
    • DNS server Port: If you are using unbound or dnsmasq, then set this to a different port so that it doesn't interfere, such as port 5353.
  3. The settings will look something like below:
  1. Follow through the rest of the wizard entering a username and password.

Configure OPNsense to use AdGuard Home

The final step is to configure OPNsenses unbound service to use AdGuard home.

  1. Back in the OPNsense UI, navigate to Services | Unbound DNS | Query Forwarding.
  2. Press the + button to add a new server
    • Enabled: check this box
    • Domain: leave blank so all requests are forwarded
    • Server IP: the address of your OPNsense machine, in my case this is 10.0.0.1 .
    • Server Port: the DNS server port set in the previous step, which in this case is 5353.
  1. Press Save and then Apply to save the query forward.

Conclusion

And you're done! DNS requests will be processed by unbound running on OPNsense, which will redirect all queries to the underlying AdGuard Home service. Another configuration option would be to disable unbound and run AdGuard directly on port 53, however unbound does have some additional features that might come in useful 🙂