Add Service-Reference
503
Service-Reference.-.md
Normal file
503
Service-Reference.-.md
Normal file
@@ -0,0 +1,503 @@
|
||||
# 🔧 Service Reference
|
||||
|
||||
Complete documentation for all AdGuard Control Hub services. Use these services in automations and scripts to control your network programmatically.
|
||||
|
||||
## 📋 Service Overview
|
||||
|
||||
| Service | Description | Use Case |
|
||||
|---------|-------------|----------|
|
||||
| `add_client` | Add new client to AdGuard Home | Programmatically register new devices |
|
||||
| `update_client` | Modify existing client settings | Change client configuration |
|
||||
| `remove_client` | Remove client from AdGuard Home | Clean up old devices |
|
||||
| `block_services` | Block specific services for clients | Implement parental controls |
|
||||
| `unblock_services` | Unblock services for clients | Grant access to specific services |
|
||||
| `bulk_update_clients` | Update multiple clients simultaneously | Apply rules to device groups |
|
||||
| `emergency_unblock` | Temporary emergency access override | Urgent internet access needs |
|
||||
|
||||
## 🛡️ Client Management Services
|
||||
|
||||
### `adguard_hub.add_client`
|
||||
|
||||
Add a new client device to AdGuard Home with full configuration options.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `name` | string | ✅ | - | Friendly name for the client |
|
||||
| `ids` | list | ❌ | `[]` | IP addresses, MAC addresses, or Client IDs |
|
||||
| `use_global_settings` | boolean | ❌ | `true` | Whether to use global protection settings |
|
||||
| `use_global_blocked_services` | boolean | ❌ | `true` | Whether to use global service blocking |
|
||||
| `blocked_services` | list | ❌ | `[]` | Services to block for this client |
|
||||
| `filtering_enabled` | boolean | ❌ | `true` | Enable DNS filtering |
|
||||
| `parental_enabled` | boolean | ❌ | `false` | Enable parental controls |
|
||||
| `safebrowsing_enabled` | boolean | ❌ | `false` | Enable safe browsing |
|
||||
| `safesearch_enabled` | boolean | ❌ | `false` | Enable safe search |
|
||||
| `upstream_dns` | list | ❌ | `[]` | Custom DNS servers |
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```yaml
|
||||
# Basic client addition
|
||||
service: adguard_hub.add_client
|
||||
data:
|
||||
name: "Kids iPad"
|
||||
ids:
|
||||
- "192.168.1.150"
|
||||
- "aa:bb:cc:dd:ee:ff"
|
||||
|
||||
# Advanced client with custom settings
|
||||
service: adguard_hub.add_client
|
||||
data:
|
||||
name: "Kids Laptop"
|
||||
ids: ["192.168.1.151"]
|
||||
use_global_settings: false
|
||||
use_global_blocked_services: false
|
||||
blocked_services:
|
||||
- "youtube"
|
||||
- "gaming"
|
||||
- "social"
|
||||
filtering_enabled: true
|
||||
parental_enabled: true
|
||||
safebrowsing_enabled: true
|
||||
safesearch_enabled: true
|
||||
upstream_dns:
|
||||
- "1.1.1.3" # Cloudflare for Families
|
||||
- "1.0.0.3"
|
||||
```
|
||||
|
||||
### `adguard_hub.update_client`
|
||||
|
||||
Modify settings for an existing client.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `name` | string | ✅ | - | Name of the client to update |
|
||||
| `ids` | list | ❌ | - | New device identifiers |
|
||||
| `use_global_settings` | boolean | ❌ | - | Use global protection settings |
|
||||
| `use_global_blocked_services` | boolean | ❌ | - | Use global service blocking |
|
||||
| `blocked_services` | list | ❌ | - | Update blocked services list |
|
||||
| `filtering_enabled` | boolean | ❌ | - | Enable/disable filtering |
|
||||
| `parental_enabled` | boolean | ❌ | - | Enable/disable parental controls |
|
||||
| `safebrowsing_enabled` | boolean | ❌ | - | Enable/disable safe browsing |
|
||||
| `safesearch_enabled` | boolean | ❌ | - | Enable/disable safe search |
|
||||
| `upstream_dns` | list | ❌ | - | Update DNS servers |
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```yaml
|
||||
# Enable parental controls for existing client
|
||||
service: adguard_hub.update_client
|
||||
data:
|
||||
name: "Kids iPad"
|
||||
parental_enabled: true
|
||||
safesearch_enabled: true
|
||||
|
||||
# Change blocked services
|
||||
service: adguard_hub.update_client
|
||||
data:
|
||||
name: "Work Laptop"
|
||||
blocked_services: ["social", "entertainment"]
|
||||
|
||||
# Add new device identifier
|
||||
service: adguard_hub.update_client
|
||||
data:
|
||||
name: "Kids Phone"
|
||||
ids:
|
||||
- "192.168.1.160"
|
||||
- "ff:ee:dd:cc:bb:aa"
|
||||
```
|
||||
|
||||
### `adguard_hub.remove_client`
|
||||
|
||||
Remove a client from AdGuard Home.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `name` | string | ✅ | - | Name of the client to remove |
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```yaml
|
||||
# Remove old device
|
||||
service: adguard_hub.remove_client
|
||||
data:
|
||||
name: "Old Laptop"
|
||||
```
|
||||
|
||||
## 🎛️ Service Blocking Services
|
||||
|
||||
### `adguard_hub.block_services`
|
||||
|
||||
Block specific services for a client device.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `client_name` | string | ✅ | - | Name of the client |
|
||||
| `services` | list | ✅ | - | List of services to block |
|
||||
| `schedule` | dict | ❌ | - | Optional blocking schedule |
|
||||
|
||||
#### Available Services
|
||||
|
||||
Common service identifiers you can use:
|
||||
|
||||
| Service ID | Description |
|
||||
|------------|-------------|
|
||||
| `youtube` | YouTube video platform |
|
||||
| `netflix` | Netflix streaming |
|
||||
| `disney_plus` | Disney+ streaming |
|
||||
| `facebook` | Facebook social network |
|
||||
| `instagram` | Instagram social media |
|
||||
| `tiktok` | TikTok short videos |
|
||||
| `twitter` | Twitter/X social media |
|
||||
| `snapchat` | Snapchat messaging |
|
||||
| `reddit` | Reddit forums |
|
||||
| `gaming` | General gaming services |
|
||||
| `steam` | Steam gaming platform |
|
||||
| `roblox` | Roblox gaming |
|
||||
| `adult` | Adult content |
|
||||
| `gambling` | Gambling sites |
|
||||
| `torrents` | Torrent sites |
|
||||
| `social` | All social media |
|
||||
| `entertainment` | All entertainment |
|
||||
|
||||
#### Schedule Format
|
||||
|
||||
```yaml
|
||||
schedule:
|
||||
enabled: true
|
||||
time_zone: "Local"
|
||||
mon: { start: "09:00", end: "17:00" }
|
||||
tue: { start: "09:00", end: "17:00" }
|
||||
wed: { start: "09:00", end: "17:00" }
|
||||
thu: { start: "09:00", end: "17:00" }
|
||||
fri: { start: "09:00", end: "17:00" }
|
||||
sat: { start: "10:00", end: "14:00" }
|
||||
sun: { start: "10:00", end: "14:00" }
|
||||
```
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```yaml
|
||||
# Block social media for kids
|
||||
service: adguard_hub.block_services
|
||||
data:
|
||||
client_name: "Kids iPad"
|
||||
services:
|
||||
- "social"
|
||||
- "tiktok"
|
||||
- "snapchat"
|
||||
|
||||
# Block gaming during school hours
|
||||
service: adguard_hub.block_services
|
||||
data:
|
||||
client_name: "Kids Laptop"
|
||||
services: ["gaming", "steam", "roblox"]
|
||||
schedule:
|
||||
enabled: true
|
||||
time_zone: "Local"
|
||||
mon: { start: "08:00", end: "15:00" }
|
||||
tue: { start: "08:00", end: "15:00" }
|
||||
wed: { start: "08:00", end: "15:00" }
|
||||
thu: { start: "08:00", end: "15:00" }
|
||||
fri: { start: "08:00", end: "15:00" }
|
||||
|
||||
# Block distracting sites during work
|
||||
service: adguard_hub.block_services
|
||||
data:
|
||||
client_name: "Work Laptop"
|
||||
services: ["facebook", "twitter", "youtube", "reddit"]
|
||||
```
|
||||
|
||||
### `adguard_hub.unblock_services`
|
||||
|
||||
Remove service blocks from a client device.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `client_name` | string | ✅ | - | Name of the client |
|
||||
| `services` | list | ✅ | - | List of services to unblock |
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```yaml
|
||||
# Allow entertainment after homework
|
||||
service: adguard_hub.unblock_services
|
||||
data:
|
||||
client_name: "Kids iPad"
|
||||
services: ["youtube", "netflix"]
|
||||
|
||||
# Allow social media during break
|
||||
service: adguard_hub.unblock_services
|
||||
data:
|
||||
client_name: "Work Laptop"
|
||||
services: ["facebook", "twitter"]
|
||||
|
||||
# Unblock gaming on weekends
|
||||
service: adguard_hub.unblock_services
|
||||
data:
|
||||
client_name: "Kids PlayStation"
|
||||
services: ["gaming", "steam", "playstation"]
|
||||
```
|
||||
|
||||
## 📦 Bulk Operations
|
||||
|
||||
### `adguard_hub.bulk_update_clients`
|
||||
|
||||
Update multiple clients simultaneously using pattern matching or explicit lists.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `client_pattern` | string | ❌ | `"*"` | Wildcard pattern to match clients |
|
||||
| `clients` | list | ❌ | - | Explicit list of client names |
|
||||
| `settings` | dict | ✅ | - | Settings to apply to matched clients |
|
||||
|
||||
#### Pattern Matching
|
||||
|
||||
Use shell-style wildcards:
|
||||
|
||||
- `*` - Matches anything
|
||||
- `?` - Matches any single character
|
||||
- `Kids*` - Matches clients starting with "Kids"
|
||||
- `*Phone*` - Matches clients containing "Phone"
|
||||
- `Work_*` - Matches clients starting with "Work_"
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```yaml
|
||||
# Apply parental controls to all kids' devices
|
||||
service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Kids*"
|
||||
settings:
|
||||
parental_enabled: true
|
||||
safesearch_enabled: true
|
||||
blocked_services: ["adult", "gambling"]
|
||||
|
||||
# Update specific clients by name
|
||||
service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
clients:
|
||||
- "iPad Pro"
|
||||
- "MacBook Air"
|
||||
- "iPhone 12"
|
||||
settings:
|
||||
safebrowsing_enabled: true
|
||||
|
||||
# Apply work restrictions to all work devices
|
||||
service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Work*"
|
||||
settings:
|
||||
blocked_services: ["social", "entertainment"]
|
||||
filtering_enabled: true
|
||||
|
||||
# Emergency: Remove all blocks from all devices
|
||||
service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "*"
|
||||
settings:
|
||||
blocked_services: []
|
||||
parental_enabled: false
|
||||
```
|
||||
|
||||
## 🚨 Emergency Services
|
||||
|
||||
### `adguard_hub.emergency_unblock`
|
||||
|
||||
Temporarily disable blocking for emergency internet access.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| `duration` | integer | ❌ | `300` | Duration in seconds |
|
||||
| `clients` | list | ❌ | `["all"]` | Clients to unblock |
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```yaml
|
||||
# Emergency unblock for all devices (10 minutes)
|
||||
service: adguard_hub.emergency_unblock
|
||||
data:
|
||||
duration: 600
|
||||
clients: ["all"]
|
||||
|
||||
# Unblock specific client for 5 minutes
|
||||
service: adguard_hub.emergency_unblock
|
||||
data:
|
||||
duration: 300
|
||||
clients: ["Work Laptop"]
|
||||
|
||||
# Quick 2-minute unblock for urgent access
|
||||
service: adguard_hub.emergency_unblock
|
||||
data:
|
||||
duration: 120
|
||||
clients: ["Kids iPad"]
|
||||
|
||||
# Long emergency unblock (1 hour) for special circumstances
|
||||
service: adguard_hub.emergency_unblock
|
||||
data:
|
||||
duration: 3600
|
||||
clients: ["all"]
|
||||
```
|
||||
|
||||
## 🔄 Service Combinations
|
||||
|
||||
### Complex Automation Examples
|
||||
|
||||
Combine multiple services for sophisticated network management:
|
||||
|
||||
#### Study Time Automation
|
||||
|
||||
```yaml
|
||||
# Complete study time setup
|
||||
script:
|
||||
study_time_enable:
|
||||
sequence:
|
||||
# Block distractions on all kids' devices
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Kids*"
|
||||
settings:
|
||||
blocked_services: ["social", "entertainment", "gaming"]
|
||||
|
||||
# Allow educational content
|
||||
- service: adguard_hub.unblock_services
|
||||
data:
|
||||
client_name: "Kids Laptop"
|
||||
services: ["educational"]
|
||||
|
||||
# Enable parental controls
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Kids*"
|
||||
settings:
|
||||
parental_enabled: true
|
||||
safesearch_enabled: true
|
||||
```
|
||||
|
||||
#### Family Movie Night
|
||||
|
||||
```yaml
|
||||
# Movie night setup
|
||||
script:
|
||||
movie_night_setup:
|
||||
sequence:
|
||||
# Unblock streaming for TV
|
||||
- service: adguard_hub.unblock_services
|
||||
data:
|
||||
client_name: "Living Room TV"
|
||||
services: ["netflix", "disney_plus", "youtube"]
|
||||
|
||||
# Block bandwidth-heavy services on other devices
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "*"
|
||||
settings:
|
||||
blocked_services: ["torrents", "gaming"]
|
||||
|
||||
# Allow kids to access streaming but block social
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Kids*"
|
||||
settings:
|
||||
blocked_services: ["social", "gaming"]
|
||||
```
|
||||
|
||||
#### Work Focus Session
|
||||
|
||||
```yaml
|
||||
# Deep work focus
|
||||
script:
|
||||
work_focus_enable:
|
||||
sequence:
|
||||
# Block all distractions on work devices
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Work*"
|
||||
settings:
|
||||
blocked_services: ["social", "entertainment", "news", "shopping"]
|
||||
|
||||
# Ensure kids can't distract with bandwidth usage
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Kids*"
|
||||
settings:
|
||||
blocked_services: ["gaming", "streaming", "youtube"]
|
||||
```
|
||||
|
||||
## ⚠️ Service Usage Tips
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Test First**: Test service calls manually before using in automations
|
||||
2. **Error Handling**: Wrap service calls in try-catch blocks for reliability
|
||||
3. **Client Names**: Use consistent, descriptive client names
|
||||
4. **Scheduling**: Use schedules for predictable time-based restrictions
|
||||
5. **Emergency Access**: Always have an emergency unblock method available
|
||||
|
||||
### Common Patterns
|
||||
|
||||
#### Time-Based Restrictions
|
||||
|
||||
```yaml
|
||||
# Bedtime routine
|
||||
automation:
|
||||
- trigger:
|
||||
platform: time
|
||||
at: "20:00:00"
|
||||
action:
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "Kids*"
|
||||
settings:
|
||||
blocked_services: ["entertainment", "social", "gaming"]
|
||||
```
|
||||
|
||||
#### Presence-Based Rules
|
||||
|
||||
```yaml
|
||||
# Away from home
|
||||
automation:
|
||||
- trigger:
|
||||
platform: state
|
||||
entity_id: group.family
|
||||
to: 'not_home'
|
||||
action:
|
||||
- service: adguard_hub.bulk_update_clients
|
||||
data:
|
||||
client_pattern: "*"
|
||||
settings:
|
||||
parental_enabled: true
|
||||
safebrowsing_enabled: true
|
||||
```
|
||||
|
||||
#### Device-Specific Controls
|
||||
|
||||
```yaml
|
||||
# Gaming console management
|
||||
automation:
|
||||
- trigger:
|
||||
platform: time
|
||||
at: "21:00:00"
|
||||
action:
|
||||
- service: adguard_hub.block_services
|
||||
data:
|
||||
client_name: "PlayStation 5"
|
||||
services: ["gaming", "playstation", "steam"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Next**: Check out [Troubleshooting](Troubleshooting) if you need help, or explore the [API Reference](API-Reference) for technical details!
|
Reference in New Issue
Block a user