technitiumDNS Integration for Home Assistant

This custom integration allows you to integrate technitiumDNS with Home Assistant, providing sensors for various DNS statistics.

Installation

Manual Installation

1. Download the repository:
   • Clone the repository or download the ZIP file.

   git clone https://github.com/Amateur-God/home-assistant-technitiumdns.git

2. Copy to Home Assistant:
   • Copy the custom_components directory into your Home Assistant configuration directory.

   cp -r home-assistant-technitiumdns/custom_components/technitiumdns /path/to/your/home-assistant/config/custom_components/

HACS Installation

1. Add Custom Repository:

   • Go to HACS in your Home Assistant.
   • Click on "Integrations".
   • Click on the three dots in the upper right corner and select "Custom repositories".
   • Add the URL to this repository: https://github.com/Amateur-God/home-assistant-technitiumdns and select the category "Integration".

2. Install the Integration:

   • Find technitiumDNS in HACS and click "Install".

Configuration

Add the Integration:

• Go to Home Assistant Configuration > Integrations.
• Click on the "+" button to add a new integration.
• Search for technitiumDNS and follow the configuration steps.

Usage

This integration provides

Sensors for:

• Total Queries
• Blocked Queries
• Clients
• Top Clients
• Top Domains
• Top Blocked Domains
• Total No Error
• Total Server Failure
• Total NX Domain
• Total Refused
• Total Authoritative
• Total Recursive
• Total Cached
• Total Dropped
• Zones
• Cached Entries
• Allowed Zones
• Blocked Zones
• Allow List Zones
• Block List Zones
• Update Available

Switches for:

• Enable/disable Ad Blocking (will check current ad blocking state on initialization and set the switch to the correct position)

Buttons for:

• Temporarily disable ad blocking for:
  • 5 mins
  • 10 mins
  • 30 mins
  • 60 mins
  • 1 day

Device Trackers (Optional):

• DHCP Device Tracking: Monitor devices connected to your Technitium DHCP server

  • MAC-Based Identification: Devices are primarily identified by MAC address for consistency
  • Shows connected/disconnected status based on DHCP lease status and activity
  • Displays IP addresses, MAC addresses, and hostnames
  • Tracks lease information and expiration times
  • Can be enabled/disabled in integration options
  • Configurable update interval (30s, 1min, 5min, 10min)
  • IP Address Filtering: Control which devices are tracked based on IP addresses
    • Disabled: Track all devices (default)
    • Include Mode: Only track devices in specified IP ranges
    • Exclude Mode: Track all devices except those in specified IP ranges
    • Supports single IPs, CIDR notation, and IP ranges
    • Examples: 192.168.1.100, 192.168.1.0/24, 192.168.1.1-192.168.1.50

• Device Diagnostic Sensors: Each tracked device automatically gets dedicated diagnostic sensors:

  • IP Address Sensor: Current IP address of the device
  • MAC Address Sensor: Hardware MAC address identifier
  • Hostname Sensor: Device hostname if available from DHCP
  • Lease Obtained Sensor: Timestamp when the DHCP lease was first obtained
  • Lease Expires Sensor: Timestamp when the current DHCP lease expires
  • Last Seen Sensor: Last DNS activity timestamp (requires DNS logging app)
  • Is Stale Sensor: Whether device has been inactive for too long (requires DNS logging)
  • Minutes Since Seen Sensor: How many minutes since last DNS activity (requires DNS logging)
  • Activity Score Sensor: Intelligent activity score (0-100) distinguishing user activity from background traffic
  • Is Actively Used Sensor: Smart determination if device is genuinely being used (eliminates false positives)
  • Activity Summary Sensor: Human-readable analysis of device activity patterns
  • All sensors are marked as diagnostic entities for better organization in Home Assistant
  • Dynamic Creation: Sensors are automatically created/removed as devices join/leave the network

• Smart Activity Analysis: Advanced feature that solves the "dormant device problem":

  • Problem: Devices with only background traffic (NTP, updates, telemetry) were incorrectly shown as active
  • Solution: Multi-factor scoring analyzes protocol mix, domain diversity, timing patterns, and background traffic ratio
  • Background Detection: Automatically identifies automated traffic vs genuine user activity
  • Configurable Threshold: Adjustable sensitivity (10-100 points, default: 55) for different network environments
  • Analysis Window: Configurable time window (15 minutes to 4 hours, default: 2 hours) for activity pattern analysis
  • Rich Diagnostics: Detailed scoring breakdown for troubleshooting device activity patterns
  • Score Categories: Very Low (10), Low (33), Medium (55), High (76), Very High (100)

• DNS Query Logs Tracking (Advanced):

  • Requires DNS App Installation: DNS query logging is only available through DNS apps with logging capability
  • Not Available by Default: The Technitium DNS /api/logs/query endpoint requires specific DNS app parameters
  • Enhanced Device Activity: When available, provides more accurate last-seen timestamps
  • Automatic Detection: Integration automatically detects and uses available logging DNS apps
  • Fallback to DHCP: When DNS logging is unavailable, uses DHCP leases as primary tracking method

Configuration Options

After setting up the integration, you can configure additional options by going to:

1. Home Assistant Configuration > Integrations
2. Find your TechnitiumDNS integration and click "Configure"
3. Available options:
   • Enable DHCP Device Tracking: Turn on device tracking for DHCP clients
   • DHCP Update Interval: How often to check for DHCP lease changes (30-600 seconds)
   • IP Filter Mode: Choose how to filter devices by IP address
   • IP Addresses/Ranges: Specify which IPs to include or exclude (comma or newline separated)
   • Smart Activity Analysis: Enable intelligent activity scoring for devices (default: enabled)
   • Activity Score Threshold: Minimum score to consider a device "actively used" (10-100, default: 55)
   • Activity Analysis Window: Time window for analyzing device activity patterns (15 minutes to 4 hours, default: 2 hours)

IP Filtering Examples

Include Mode - Only track specific devices:

192.168.1.100,192.168.1.101,192.168.1.102

Exclude Mode - Track all except servers:

192.168.1.0/28
10.0.0.1-10.0.0.10

Mixed Format - Flexible configuration:

192.168.1.100
10.0.0.0/30
172.16.1.1-172.16.1.5

Entity Management

Automatic Cleanup

When you change IP filtering settings, the integration automatically removes device tracker entities and their associated diagnostic sensors for devices that no longer match the filter criteria. This happens during the next data update cycle.

Manual Cleanup

If you need to manually clean up orphaned entities:

1. Using the Cleanup Button: Go to your TechnitiumDNS device page and click the "Cleanup Devices" button.

2. Using the Service: Call the technitiumdns.cleanup_devices service:

   service: technitiumdns.cleanup_devices
   data:
     config_entry_id: "your_entry_id"  # Optional - if omitted, cleans all entries

3. Using Developer Tools: Go to Developer Tools > Services and search for "Cleanup Devices".

Available Services

The integration provides these services for advanced control:

1. technitiumdns.cleanup_devices: Remove orphaned device tracker entities and sensors

   • config_entry_id (optional): Target specific integration instance

2. technitiumdns.get_dhcp_leases: Retrieve DHCP lease information programmatically

   • config_entry_id (optional): Target specific integration instance
   • include_inactive (optional): Include expired leases (default: false)
   • filter_scope (optional): Filter by specific DHCP scope (e.g., "192.168.1.0/24")

What Gets Cleaned Up

• Device tracker entities for devices no longer matching IP filters
• All diagnostic sensors associated with removed devices
• Device registry entries for devices with no remaining entities
• Orphaned entity registry entries

Note: Only entities belonging to this integration are affected. Other integrations and their entities remain untouched.

📚 Documentation

For detailed documentation, troubleshooting guides, and implementation details, see the docs/ directory:

• Implementation Guides - DHCP implementation, entity cleanup, and technical summaries
• Feature Documentation - Smart Activity Analysis and diagnostic sensors
• Testing & Troubleshooting - Comprehensive guides for issue resolution
• Migration Guides - Upgrading from older versions

Visit docs/INDEX.md for a complete documentation index.

Contributing

If you want to contribute to this project, feel free to fork the repository and submit a pull request. Issues and feature requests are also welcome.

License

This project is licensed under the GPL 3.0 License. See the LICENSE file for details.

Disclaimer

The non-English translations for this integration were generated by ChatGPT and may not be perfectly accurate. If you find any errors or improvements, please feel free to contribute.

TECHNITIUM API DOCUMENTATION

Technitium DNS Server API Documentation