OpenHAB + AdGuard Home: Taking Local DNS Control to the Next Level

Overview

#

If you read my previous post about NextDNS integration, you’ll know I’m all about keeping my cheeky little internet explorers from wasting their entire day on YouTube. While NextDNS worked brilliantly, the monthly fee (even though modest) for such a basic function was annoying.

Enter AdGuard Home - a self-hosted DNS filtering solution that you can run locally. Combined with some clever OpenHAB automation, I now have instant control over what gets blocked, when it gets blocked, and can even create custom schedules so everything happens with crisp precision.

The best part? Everything happens locally, so there’s no waiting for cloud services to sync when I need to urgently block TikTok because someone’s been watching dance videos for three hours straight.

What You’ll Need

#

Here’s what I’m running this on:

Hardware:

• Any machine that can run Docker
• A network or VLAN that you can point the DNS settings to your AdGuard instance

Software:

• AdGuard Home (recommended: via Docker - it’s the easiest way)
• OpenHAB with JSScripting addon

How It All Works

#

1. AdGuard Home: You’ll first need to ge AdGuard Home up & running. If you’ve used Docker before, this is going to be fairly straight-forward. You’ll just need to ensure the container is always available (even if you turn off your laptop or PC) and it has a static IP address. All your clients are going to use it as a DNS resolver, so if it disappears, it will seem like the internet went down.
2. Network or VLAN Configuration: I have a VLAN that the family TV and kids devices use, with us parents on our own network. For the kids VLAN, I’ve set the DHCP rules to use provide the AdGuard docker container address as the local DNS server. This part might vary for your network, so adjust as you need.
3. Sneaky kids? Block Outbound DNS: Your clever little people might try and route around the DNS Blocklist by changing their DNS servers. I manage this by blocking this at the perimeter with our OPNSense firewall. Again, adjust for your purposes.
4. Integrate with OpenHAB: So I can enable/disable filters and rules, use the scripts I’ve written to connect AdGuard to OpenHAB. This allows you to use OpenHAB’s automation and user interface functions to easily manage the enabled rules.

Automatic Item Creation

#

The script watches for:

• DNS Blocklists with [openhab] prefix - these become switchable items
• Blocked Services (YouTube, Spotify, etc.) - but only after you’ve blocked them once

Every 5 minutes, it checks AdGuard and creates or updates OpenHAB items automatically. No manual configuration needed!

Real-Time Control

#

When you flip a switch in OpenHAB, it immediately updates AdGuard Home. When someone (probably me, accidentally) changes something in the AdGuard interface, it syncs back to OpenHAB within 5 minutes.

Setting It Up

#

Step 1: Get AdGuard Home Running

#

1. I use Docker because it’s dead simple. Follow the instructions on the AdGuard Home Docker Hub page for the full details. When you can access the AdGuard Home web control panel you’re ready for the next step.

2. You should now be able to point the network you want to put control in for to this DNS server. This could be as simple as updating the DNS settings for your whole network, but remember any controls you set here will apply to everyone and every device on that network.

3. Before doing any OpenHAB integration, test your network and AdGuard setup. Can you block services via the AdGuard web UI? Go to Filters / Blocked Services and turn OFF YouTube. Does the blocking start working on a device on the network you set in Step 2? If so, you’re good with AdGuard.

Step 2: Install the OpenHAB Integration

#

Download my whole repo from Github and you’ll need to put a few files in the right places:

1. Script File:

• Place the main JSRule script (e.g., adguard.js containing the rules) into your OpenHAB automation scripts directory: $OPENHAB_CONF/automation/js/.
• Replace ADGUARD_BASE_URL in adguard.js with the URL of your AdGuard instance. Your OpenHAB instance needs to be able to reach this address.

2. Environment File for Credentials (adguard.env):

• Copy the adguard.env file and place it in the same directory as the script ($OPENHAB_CONF/automation/js/).
• Modify the file to include your AdGuard Home credentials:

  ADGUARD_USERNAME=your_adguard_username
  ADGUARD_PASSWORD=your_adguard_password
  

• Replace your_adguard_username and your_adguard_password with your AdGuard Home login credentials.

3. Create the Groups required:

The script relies on specific OpenHAB Item Groups to trigger updates when you change an item’s state. You need to create these groups in OpenHAB.

• Place the file adguard.items in your $OPENHAB_CONF/items/ folder OR create these following groups from the Admin UI
  • AdGuard_Filters - Items controlling DNS filter blocklists.
  • AdGuard_Services - Items controlling blocked services.

4. Running the integration:

With the above completed, the script should automatically load and start running. Check the OpenHAB logs for messages from the adguardhome logger to confirm it’s running and to troubleshoot any issues.

On first run, it will automatically create individual Switch items for each managed AdGuard filter/service and add them to the appropriate group. These items will also be tagged (AdGuard_Filter_Item or AdGuard_Service_Item) and have metadata (adguard_item_type) to differentiate them. You should see this occur in the log after a few minutes.

Step 3: Setting up AdGuard

#

1. For Blocked Services (Filters/Blocked Services - eg. Youtube etc) - Items will ONLY be created when the script detects the service being currently blocked. You’ll need to enable blocking for every service you want to control from OpenHAB for at least a short period to create the relevant Items.

2. For DNS Blocklists (Filters/DNS Blocklists) - Items are created for every blocklist with an [openhab] prefix. So for example, to create a Spotify Video blocklist:

   1. Go to AdGuard Home Admin / Filters / DNS Blocklists
   2. Click Add Blocklist button
   3. Click the Custom Blocklist button
   4. For name, enter: [openhab] Spotify Video (or similar, as long as it starts with [openhab])
   5. For URL/Path, use the blocklist from my repo: https://raw.githubusercontent.com/alackmann/openhab-adguardhome/refs/heads/main/blocklists/spotify_video.txt
   6. On next refresh (by default every 5 mins), Items should be created for this Blocklist you can enable/disable from OpenHAB Rules etc

Just prefix any DNS Blocklist in AdGuard with [openhab] and the script automatically creates an OpenHAB item for it.

Automating from OpenHAB

#

Now for the really clever bit - automation rules that make parenting easier. See the [js/adguard-local.js](https://github.com/alackmann/openhab-adguardhome/blob/main/js/adguard-local.js) file for an example:

// Block YouTube every day until 7pm
rules.JSRule({
  name: "Reset YouTube blocking each day to be enabled",
  description: "",
  triggers: [
    triggers.GenericCronTrigger("10 0 3 * * ?") // 3am
  ],
  tags: [],
  id: "AdGuard_ResetYouTubeEachDay",
  execute: (event) => {
    items.getItem('AdGuard_Service_youtube_Blocked').sendCommand('ON');
  }
});

// Turn on YouTube access each day in the evening at 7pm
rules.JSRule({
  name: "Enable YouTube each day in the evening",
  description: "",
  triggers: [
    triggers.GenericCronTrigger("10 0 19 * * ?") // 7pm
  ],
  tags: [],
  id: "AdGuard_EnableYouTubeEachNight",
  execute: (event) => {
    items.getItem('AdGuard_Service_youtube_Blocked').sendCommand('OFF');
  }
});

Adjust these rules or add your own for Services and Blocklists as you see fit!

Downloads & Resources

#

• Complete OpenHAB Integration (GitHub)
• Custom Blocklists Collection
• Example Automation Rules

Conclusion

#

Moving from NextDNS to AdGuard Home has been totally worth it. The local control, almost instant response times, and endless customization options make managing kids’ internet access way more effective (and FREE!).

If you’re running OpenHAB and want better control over your home network’s DNS filtering, definitely give this setup a try. When screens and socials are dominating the time of parents and children alike, this provides at least a little control within the boundaries of your own home.

I hope you find this helpful too.