Add Service-Reference

2025-09-28 12:46:27 +00:00
parent 4a8a61612c
commit 6c3d14fd60

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!