Skip to content

Commit 4648901

Browse files
renaudallardrenaudallard
committed
updated README
1 parent 8cd3345 commit 4648901

1 file changed

Lines changed: 161 additions & 145 deletions

File tree

‎README.md‎

Lines changed: 161 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,220 +1,236 @@
1-
# PowerDNS dnsdist Integration for Home Assistant
1+
# 🛡️ PowerDNS dnsdist — Home Assistant Integration
22

3-
[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://hacs.xyz)
4-
![GitHub Release](https://img.shields.io/github/v/release/renaudallard/homeassistant_dnsdist)
5-
![GitHub License](https://img.shields.io/github/license/renaudallard/homeassistant_dnsdist)
6-
![Home Assistant](https://img.shields.io/badge/Home%20Assistant-2025.1+-blue)
3+
![HACS Badge](https://img.shields.io/badge/HACS-Custom-blue.svg)
4+
![Home Assistant](https://img.shields.io/badge/Requires-2025.1%2B-blue)
5+
![Version](https://img.shields.io/badge/Version-1.0.1-green)
6+
![License](https://img.shields.io/github/license/renaudallard/homeassistant_dnsdist)
77

8-
---
9-
10-
## Overview
11-
12-
This custom integration allows **Home Assistant** to connect to one or more
13-
[PowerDNS dnsdist 2.0.0](https://dnsdist.org/) servers through the REST API.
8+
A fully featured **Home Assistant custom integration** for [PowerDNS dnsdist](https://dnsdist.org) — the intelligent DNS load balancer.
149

15-
It provides:
16-
17-
- Real-time metrics such as queries, cache hits, CPU usage, security status, etc.
18-
- Support for multiple dnsdist hosts
19-
- Group aggregation across multiple servers
20-
- SSL / HTTPS support
21-
- Diagnostics for troubleshooting ("Download diagnostics")
22-
- UI-based configuration — no YAML required
23-
- Full support for Home Assistant 2025+
10+
Monitor one or more dnsdist servers, group them for aggregated metrics, and control them directly from Home Assistant via HTTPS, all configured entirely through the UI.
2411

2512
---
2613

27-
## Features
28-
29-
| Feature | Description |
30-
|----------|-------------|
31-
| 🔍 Auto-discovery | Add multiple dnsdist hosts through the UI |
32-
| 🧠 Aggregated Groups | Combine multiple servers into a single logical group |
33-
| 📊 Sensors | Total queries, responses, drops, cache stats, CPU usage, uptime |
34-
| 🛡️ Security Status | Shows OK / Upgrade recommended / Upgrade required |
35-
| 🔐 HTTPS + SSL | Connect securely using API key authentication |
36-
| 🧰 Diagnostics | Download runtime diagnostics via the HA UI |
37-
| ⚙️ Options Flow | Edit groups and hosts directly from the UI |
14+
## ✨ Features
15+
16+
| Category | Description |
17+
|-----------|-------------|
18+
| 🧩 Integration Type | Hub-style (`integration_type: "hub"`) |
19+
| 🔑 Configuration Flow | 100 % UI-based setup (no YAML) |
20+
| ⚙️ Options Flow | Edit hosts, groups, and polling intervals from the UI |
21+
| 👥 Group Aggregation | Combine metrics from multiple hosts |
22+
| 📊 Sensors | Queries, responses, drops, cache, CPU, uptime, security status |
23+
| 🔒 HTTPS + SSL | Full TLS + optional certificate verification |
24+
| 🧰 Diagnostics | “Download diagnostics” directly in the HA UI |
25+
| 🧾 HACS Integration | Fully HACS-compliant structure |
26+
| 🚀 CI/CD | Automated validation and release via GitHub Actions |
27+
| 🌍 Localization | English translations included |
28+
| 🧑‍💻 Compatibility | Home Assistant 2025.1 +, Python 3.13 + |
3829

3930
---
4031

41-
## Installation
42-
43-
### Via HACS (Recommended)
32+
## 📦 Installation
4433

34+
### 🔹 HACS (Recommended)
4535
1. Open **HACS → Integrations → Custom Repositories**
46-
2. Add this repository:
36+
2. Add repository:
4737
```
4838
https://github.com/renaudallard/homeassistant_dnsdist
4939
```
50-
Category: **Integration**
51-
3. Install the integration **PowerDNS dnsdist**
40+
→ **Type:** Integration
41+
3. Search for **PowerDNS dnsdist** and click **Install**
5242
4. Restart Home Assistant
5343

54-
### Manual installation
55-
56-
1. Copy the `custom_components/dnsdist/` folder into your
57-
`<config>/custom_components/` directory.
58-
2. Restart Home Assistant.
44+
### 🔹 Manual
45+
1. Copy the folder:
46+
```
47+
custom_components/dnsdist/
48+
```
49+
into your Home Assistant configuration directory:
50+
```
51+
config/custom_components/dnsdist/
52+
```
53+
2. Restart Home Assistant
5954

6055
---
6156

62-
## Configuration
63-
64-
### Step 1 — Add integration
65-
66-
Go to:
67-
68-
**Settings → Devices & Services → Add Integration → PowerDNS dnsdist**
69-
70-
Then choose one of:
71-
72-
- **Add dnsdist Host** — connect to a single dnsdist instance
73-
- **Add dnsdist Group** — aggregate multiple dnsdist hosts into one logical group
57+
## ⚙️ Configuration
7458

75-
### Step 2 — Fill in connection details
59+
1. Go to **Settings → Devices & Services**
60+
2. Click **“+ Add Integration”**
61+
3. Search for **PowerDNS dnsdist**
7662

77-
| Field | Description |
78-
|--------|-------------|
79-
| Name | Friendly name for this dnsdist server |
80-
| Host address | IP or hostname of the dnsdist API |
81-
| Port | Port of the API (default: 8083) |
82-
| API Key | Optional API key if authentication is enabled |
83-
| Use HTTPS | Enable if dnsdist API runs over HTTPS |
84-
| Verify SSL certificate | Disable if using self-signed certificates |
85-
| Update interval (seconds) | Polling interval for statistics (default: 30) |
63+
### Options
8664

87-
### Step 3 — Add groups (optional)
65+
| Field | Description | Example |
66+
|--------|--------------|----------|
67+
| **Name** | Friendly name for this dnsdist instance | `dnsdist1` |
68+
| **Host address** | IP or hostname of the dnsdist API | `172.20.0.248` |
69+
| **Port** | API port | `8083` |
70+
| **API Key** | Optional X-API-Key for authentication | `supersecretapikey` |
71+
| **Use HTTPS** | Connect over TLS | `true` |
72+
| **Verify SSL** | Validate certificates | `false` |
73+
| **Update interval (s)** | Polling frequency | `30` |
8874

89-
After adding at least one host, you can create a group:
90-
91-
1. Go to **Settings → Devices & Services → Add Integration → PowerDNS dnsdist**
92-
2. Choose **Add dnsdist Group**
93-
3. Select which hosts belong to the group (a host can be part of multiple groups)
94-
4. Choose the update interval
95-
96-
You can edit groups later via the ⚙️ “Configure” button.
75+
Groups can be created once you have at least one host configured.
9776

9877
---
9978

100-
## Available Sensors
79+
## 📊 Sensors
80+
81+
Each dnsdist host or group provides:
10182

10283
| Sensor | Description |
10384
|---------|-------------|
104-
| Total Queries | Number of queries processed |
105-
| Responses | Number of responses sent |
106-
| Dropped Queries | Total dropped queries |
107-
| Rule Drops | Queries dropped due to rules |
108-
| Downstream Send Errors | Errors while sending to downstream servers |
109-
| Cache Hits | Cache hits count |
110-
| Cache Misses | Cache misses count |
111-
| Cache Hit Rate | Percent of queries served from cache |
112-
| CPU Usage | Current dnsdist CPU usage (%) |
113-
| Uptime | Time since dnsdist started |
114-
| Security Status | One of: OK / Upgrade recommended / Upgrade required |
85+
| `queries` | Total DNS queries handled |
86+
| `responses` | Responses sent |
87+
| `drops` | Dropped queries |
88+
| `rule_drop` | Rule-based drops |
89+
| `downstream_errors` | Downstream send errors |
90+
| `cache_hits` / `cache_misses` | Cache efficiency |
91+
| `cacheHit` | Cache hit rate (%) |
92+
| `cpu` | CPU usage (%) |
93+
| `uptime` | Uptime (seconds) |
94+
| `security_status` | OK / Warning / Critical |
95+
96+
Sensors include readable uptime and security labels as attributes.
11597

11698
---
11799

118-
## Example UI
119-
120-
*(Replace with screenshots once published)*
121-
122-
| Example | Description |
123-
|----------|-------------|
124-
| ![dnsdist sensors](https://user-images.githubusercontent.com/placeholder/sensors.png) | dnsdist sensors for a single host |
125-
| ![dnsdist group](https://user-images.githubusercontent.com/placeholder/group.png) | Aggregated group combining multiple servers |
126-
127-
---
100+
## 🧰 Built-In Services
128101

129-
## Services
102+
All services are available under **Developer Tools → Actions**
103+
(HA 2025+ replaced “Services” with this tab).
130104

131105
| Service | Description |
132106
|----------|-------------|
107+
| `dnsdist.clear_cache` | Clear dnsdist cache |
133108
| `dnsdist.enable_server` | Enable a backend server |
134109
| `dnsdist.disable_server` | Disable a backend server |
135-
| `dnsdist.clear_cache` | Clear dnsdist cache |
136-
| `dnsdist.reload_config` | Reload configuration |
110+
| `dnsdist.reload_config` | Reload dnsdist configuration |
111+
| `dnsdist.get_backends` | Retrieve list and state of backends |
112+
| `dnsdist.runtime_command` | Execute any console command via REST API |
137113

138-
*(These appear automatically under “Developer Tools → Services”)*
114+
### Examples
139115

140-
---
116+
**Clear cache**
117+
```yaml
118+
service: dnsdist.clear_cache
119+
data:
120+
host: dnsdist1
121+
```
141122
142-
## SSL & Authentication
123+
**Reload configuration**
124+
```yaml
125+
service: dnsdist.reload_config
126+
data:
127+
host: dnsdist1
128+
```
143129
144-
This integration supports both **HTTP** and **HTTPS** endpoints.
145-
If your dnsdist API uses self-signed certificates, you can disable certificate validation
146-
during setup (uncheck “Verify SSL certificate”).
130+
**Run console command**
131+
```yaml
132+
service: dnsdist.runtime_command
133+
data:
134+
host: dnsdist1
135+
command: showServers()
136+
```
147137
148138
---
149139
150-
## Diagnostics
151-
152-
In Home Assistant, open the integration page → click “⋮ → Download Diagnostics”
153-
to retrieve a JSON diagnostic bundle containing connection details, API response data,
154-
and any recent errors for troubleshooting.
155-
156-
---
140+
## 👥 Group Aggregation
157141
158-
## Requirements
142+
Group entries automatically:
143+
* Sum counters (queries, responses, drops)
144+
* Average percentages (CPU, uptime)
145+
* Report the highest security level among members
159146
160-
- Home Assistant 2025.1 or later
161-
- Python ≥ 3.13
162-
- PowerDNS dnsdist 2.0.0+ (uses `/api/v1/servers/localhost/statistics`)
147+
Each group appears as its own device in Home Assistant.
163148
164149
---
165150
166-
## Development
167-
168-
```bash
169-
git clone https://github.com/renaudallard/homeassistant_dnsdist.git
170-
cd homeassistant_dnsdist
171-
```
172-
173-
To run inside a Home Assistant dev environment:
151+
## 🧾 Diagnostics
174152
175-
```bash
176-
hass --script check_config
177-
```
153+
From the dnsdist device page:
154+
* Open menu → **Download Diagnostics**
155+
Exports a JSON snapshot of configuration (with API keys redacted) and current stats.
178156
179157
---
180158
181-
## Folder structure
159+
## 🧱 Folder Layout
182160
183161
```
184162
custom_components/dnsdist/
163+
│
185164
├── __init__.py
186165
├── config_flow.py
187166
├── coordinator.py
188167
├── group_coordinator.py
189168
├── sensor.py
169+
├── diagnostics.py
190170
├── const.py
191-
├── manifest.json
171+
├── services.yaml
192172
├── strings.json
193-
└── translations/
194-
└── en.json
173+
├── translations/en.json
174+
└── manifest.json
195175
```
196176

197177
---
198178

199-
## Troubleshooting
200-
201-
| Symptom | Cause / Fix |
202-
|----------|-------------|
203-
| `not_implemented` when adding integration | Outdated config_flow → ensure latest version |
204-
| “Unknown error occurred” adding group | No hosts available → add at least one host first |
205-
| All group sensors show “unavailable” | Delete and re-add group (data schema changed) |
206-
| Uptime shows as “unavailable” | dnsdist API uptime not returned — check version |
207-
| Security Status incorrect | dnsdist not reporting proper `security-status` metric |
179+
## 🧩 Manifest (excerpt)
180+
181+
```json
182+
{
183+
"domain": "dnsdist",
184+
"name": "PowerDNS dnsdist",
185+
"version": "1.0.1",
186+
"documentation": "https://github.com/renaudallard/homeassistant_dnsdist",
187+
"issue_tracker": "https://github.com/renaudallard/homeassistant_dnsdist/issues",
188+
"after_dependencies": ["http"],
189+
"config_flow": true,
190+
"iot_class": "local_polling",
191+
"integration_type": "hub",
192+
"services": ["services.yaml"],
193+
"quality_scale": "beta",
194+
"homeassistant": "2025.1.0",
195+
"requirements": [],
196+
"codeowners": ["@renaudallard"],
197+
"supported_brands": ["PowerDNS"],
198+
"diagnostics": true
199+
}
200+
```
208201

209202
---
210203

211-
## License
212-
213-
MIT © [Renaud Allard](https://github.com/renaudallard)
204+
## 🧠 Example Automation
205+
206+
Notify if any backend is down:
207+
208+
```yaml
209+
alias: Notify if dnsdist backend is down
210+
trigger:
211+
- platform: time_pattern
212+
minutes: "/10"
213+
action:
214+
- service: dnsdist.get_backends
215+
data:
216+
host: dnsdist1
217+
- delay: "00:00:02"
218+
- condition: template
219+
value_template: >
220+
{% set s = states('sensor.dnsdist1_security_status') %}
221+
{{ s not in ['ok', 'secure'] }}
222+
- service: notify.persistent_notification
223+
data:
224+
title: "dnsdist Alert"
225+
message: "One or more dnsdist backends are down or degraded."
226+
```
214227
215228
---
216229
217-
## Feedback
230+
## 🧾 License
231+
232+
Licensed under the **MIT License**
233+
© 2025 [Renaud Allard](https://github.com/renaudallard)
218234
219-
- Report bugs or feature requests via [GitHub Issues](https://github.com/renaudallard/homeassistant_dnsdist/issues)
220-
- Contributions welcome via Pull Requests 🎉
235+
Repository:
236+
[https://github.com/renaudallard/homeassistant_dnsdist](https://github.com/renaudallard/homeassistant_dnsdist)

0 commit comments

Comments
 (0)