Manage AdGuard Blocked services with Home Assistant

As a parent I want to limit entertainment and game time for my kid. Fortunately, AdGuard has presets to block a bunch of services like:

  • Minecraft
  • Roblox
  • Mail.ru
  • OK.ru
  • VK.com
  • Youtube
  • etc.

But AdGuard integration with Home Assistant provides an ability to switch ON/OFF filtering completely but not a specific service.

In this article, you will find guidance on how to disable/enable filtering for a service with Home Assistant.

The main idea is using AdGuard API and command line switch in HA.

Configurations

Script to switch ON/OFF blocking services

Unfortunately, AdGuard API doesn’t provide any possibility to switch ON/OFF blocking services one by one. A list of active blocking services must be uploaded with REST API, other services will be deactivated.  

So, the most useful way is to have a bunch of text files with services lists to activate them.

For example, I provide two sets: 

  • with blocked  Minecraft and Rolblox
  • Without them.

Hence, those online games will be blocked or allowed by applying a proper list.

You will need “File editor” add-on for the following configuration.

Please find guidance on how to install it in the “INSTALL “FILE EDITOR” PLUGIN IN HOME ASSISTANT” chapter of the article.

Open “File editor” and create “AdGuard_API” folder for placing files with filters and script:

 

Create filter with games “filter_games” in the new folder:

minecraft
roblox
tiktok
mail_ru
zhihu
vk
ok

The last row of your file must be empty because of parsing with script.

Create filter without games “filter_wo_games” in the new folder:

tiktok
mail_ru
zhihu
vk
ok

As the result you will have two files in the new folder:

Now create the script file “AdGuard_block_services.sh” in the new folder:

#!/bin/bash

#Variables
AdGuard_URL='http://Your_AdGuard_IP:3000/control/blocked_services/set'
AdGuard_URL_GET='http://Your_AdGuard_IP:3000/control/blocked_services/list'

#Login_password generated echo -n 'login:password' | base64
Login_password="Encoded_Login_&_Password"

#Get bloked services set from file
csv_string=$(<$1)
csv_string=${csv_string//$'\n'/\",\"}
str_b="[\""
str_e="\"]"
filter="$str_b$csv_string$str_e"

#for debuging the list of filters 
#echo "$filter $AdGuard_URL"

curl  -X POST -m 10000 -H "Authorization: Basic $Login_password" -H "Content-Type: application/json" -d "$filter" "$AdGuard_URL"

#curl  -X GET -m 10000 -H "Authorization: Basic $Login_password" -H "Content-Type: application/json" "$AdGuard_URL_GET"

This script must be a bit updated for your reality:

  • Replace Your_AdGuard_IP with the actual IP address of your AdGuard, the port 3000 must be changed as well if you configure another one.
  • AdGuard  API allows authentication with base64 encoded credentials only.
    So, you have to replace Encoded_Login_&_Password with a generated string by following Linux command:
echo -n 'login:password' | base64

Home Assistant configuration

Now you have to create a command line switch to call AdGuard API and apply the filters.

Open /config/configuration.yaml file in “File editor” and add the following config:

switch:
 - platform: command_line
   switches:
    game_mode_filters:
     command_off: 'bash /config/AdGuard_API/AdGuard_block_services.sh /config/AdGuard_API/filter_games'
     command_on: 'bash /config/AdGuard_API/AdGuard_block_services.sh /config/AdGuard_API/filter_wo_games'
     unique_id: game_mode_filters

By default command line switcher is in OFF state after Home Assistant restart.

Hence, I created “Game_mode_switch” which allows Minecraft and Roblox when it’s activated.

Now, restart your Home Assistant to apply changes in the configuration file. 

After reboot add a button to your dashboard for checking the new configuration:

 

Now open “Blocked Services” menu on your AdGuard:

And check the results after clicking “game_mode_filters” button on the Home Assistant dashboard.

Remember! You have to reload AdGuard page after pressing Home Assistant button to see the actual state!

AdGuard doesn’t update  UI if states are changed with API!

Games are disabled:

And check the results after clicking “game_mode_filters” button on the Home Assistant dashboard.

Remember! You have to reload AdGuard page after pressing Home Assistant button to see the actual state!

AdGuard doesn’t update  UI if states are changed with API!

Games are disabled:

Games are enabled:

Now you can create your own sets of filters and command line switches to manage AdGuard blocking services from Home Assistant.

Feel free to ask any questions in the comments.

7 thoughts on “Manage AdGuard Blocked services with Home Assistant

  1. for the life of me i can't get this to run, to test i tried to run bash /config/AdGuard_API/AdGuard_block_services.sh /config/AdGuard_API/filter_all in via an ssh terminal and i get "curl: (3) URL using bad/illegal format or missing URL"

    for the adguard ip am i using the LAN side ip of my HA instance or another ?

    1. It looks like you missed or added extra quotes in the URL of Login_Password strings in the script.
      Check the syntax carefully.

      Regarding IP and port of AdGuard, you should use the same as for accessing AgGusrd's web-panel.

  2. I was similarly struggling to get the scripts to work but realised that SSL was switched on within my Adguard addon conifigration, whereas the instructions above assume no SSL (hence http rather than https reference within the script). Once I had switched off SSL, it worked. I also set a custom port for the web interface within the addon config and updated references to port 3000 within the script to my custom port accordingly. Thank you for posting these instructions.

  3. I can't get the entity to show up when creating a button on my dashboard. Any tips?
    This is what my configuration.yaml has:

    switch:
    - platform: command_line
    switches:
    entertainment_mode_filters:
    command_off: 'bash /config/AdGuard_API/AdGuard_block_services.sh /config/AdGuard_API/filter_all'
    command_on: 'bash /config/AdGuard_API/AdGuard_block_services.sh /config/AdGuard_API/filter_wo_entertainment'
    unique_id: entertainment_mode_filters

  4. I am getting 127 errors trying to follow this process. Heres my output

    Logger: homeassistant.components.command_line
    Source: components/command_line/switch.py:183
    Integration: Command Line (documentation, issues)
    First occurred: 20:16:47 (1 occurrences)
    Last logged: 20:16:47

    Command failed: bash config/AdGuard_API/AdGuard_block_services.sh config/AdGuard_API/filter_nothing

    Logger: homeassistant.components.command_line.utils
    Source: components/command_line/utils.py:29
    Integration: Command Line (documentation, issues)
    First occurred: 20:16:47 (1 occurrences)
    Last logged: 20:16:47

    Command failed (with return code 127): bash config/AdGuard_API/AdGuard_block_services.sh config/AdGuard_API/filter_nothing

    1. Unfortunately, AdGuard team changes names of their filter, it could cause the errors.
      So, I switch on all possible filters and run following command to check names in case of errors:
      curl -X GET -m 10000 -H "Authorization: Basic $Login_password" -H "Content-Type: application/json" "$AdGuard_URL_GET"

Leave a Reply

Your email address will not be published. Required fields are marked *