57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
# Pi-hole DNS to Home Assistant Connector
|
|
|
|
This application acts as a middleman between a Pi-hole instance and a Home Assistant instance. It periodically queries Pi-hole for blocked DNS queries that match a user-defined list of strings. When a certain threshold of matches is met within a time frame, it triggers a specific Home Assistant automation.
|
|
|
|
## Features
|
|
|
|
- Polls Pi-hole for DNS queries.
|
|
- Filters queries based on a list of strings.
|
|
- Implements a "point" system for matched queries with a 5-minute expiration.
|
|
- Triggers a Home Assistant automation when a point threshold is reached.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js (v14 or higher)
|
|
- A running Pi-hole instance
|
|
- A running Home Assistant instance
|
|
|
|
## Installation
|
|
|
|
1. Clone this repository or download the source code.
|
|
2. Navigate to the project directory.
|
|
3. Install the dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
1. Rename `config.json.example` to `config.json`.
|
|
2. Edit `config.json` with your specific settings:
|
|
|
|
- `pihole.host`: The IP address of your Pi-hole.
|
|
- `pihole.password`: Your Pi-hole web interface password. This is required for Pi-hole v6 and newer. If your Pi-hole has no password, you can leave this as an empty string (`""`).
|
|
- `homeAssistant.host`: The IP address and port of your Home Assistant instance (e.g., `192.168.1.200:8123`).
|
|
- `homeAssistant.apiToken`: Your Home Assistant Long-Lived Access Token.
|
|
- `homeAssistant.automation`: The entity ID of the Home Assistant automation to trigger.
|
|
- `filter.strings`: An array of strings to match against blocked DNS queries.
|
|
- `pollingIntervalSeconds`: The interval in seconds to poll Pi-hole.
|
|
- `pointsThreshold`: The number of points required to trigger the Home Assistant automation.
|
|
|
|
- `notifications.discordWebhookUrl`: (Optional) A Discord webhook URL to send messages to when a point is added. Leave empty or omit if not using Discord notifications.
|
|
|
|
## Usage
|
|
|
|
To run the application:
|
|
|
|
```bash
|
|
node src/app.js
|
|
```
|
|
|
|
## Logging
|
|
|
|
The application generates two log files:
|
|
|
|
- `error.log`: Contains only error messages.
|
|
- `combined.log`: Contains all log messages.
|