Skip to content

README.md

Latest commit

 

History

History
213 lines (147 loc) · 10.8 KB

README.md

File metadata and controls

213 lines (147 loc) · 10.8 KB
Raw

Technitium DNS Companion

A multi-node companion tool for aiding in day-to-day management of Technitium DNS servers. Currently offers additional functionality for:

  • DNS Query Logs (DNS Logs)
  • Advanced Blocking App upkeep (DNS Filtering)
  • Built-in Blocking pause (temporary-disable timer surfaced in the header)
  • Domain Groups (named domain sets that bind to Advanced Blocking groups)
  • DNS Schedules (time-window automation for Advanced Blocking groups)
  • Log Alerts (rule-based SMTP notifications on query log events)
  • DNS Zone Insight (DNS Zones)
  • DHCP Scopes

One primary goal of this project is to provide a more mobile-friendly interface for managing day-to-day DNS functions, enabling administrators to perform common tasks (like domain blocking/unblocking) from smartphones and tablets with ease.

This project is not affiliated with Technitium but is built to complement Technitium DNS server deployments and not to replace functionality.

Authentication (v1.4+)

As of v1.4, interactive UI access uses Technitium DNS-backed session authentication:

  • Users sign in with their Technitium DNS username/password (and 2FA if enabled).
  • The Companion stores Technitium session tokens server-side and the browser receives only an HttpOnly session cookie.
  • This keeps interactive permissions aligned with the Technitium account the user actually logged in with.

Legacy “env-token mode” (configuring the Companion with long-lived API tokens) is intended for legacy/migration use only.

Security posture (v1.4+):

  • Interactive UI access requires session auth (Technitium login/RBAC).
  • TECHNITIUM_CLUSTER_TOKEN support is removed.
  • Background jobs use TECHNITIUM_BACKGROUND_TOKEN (least-privilege) since background tasks do not have a user session.

Docs: docs/features/SESSION_AUTH_AND_TOKEN_MIGRATION.md

Use Cases

  • Mobile Management - Block/unblock domains from your phone
  • Multi-Node Visibility - See query logs from all DNS servers in one place
  • Configuration Comparison - Visualize consistency across DNS nodes
  • Advanced Blocking - Easy management of domain lists
  • DHCP Overview - Compare and sync DHCP scopes across nodes

Web-based User Interface

Features Light & Dark Mode

Requirements

  • Docker, OrbStack, or Podman (or similar) (recommended for easiest deployment)
  • OR Node.js 22+ (for running directly without Docker)
  • Access to one or more Technitium DNS servers (v15.3+ recommended; v14 and earlier are deprecated but remain best-effort compatible throughout Companion 1.x)
  • For session auth (required for interactive UI in v1.4+): a Technitium user account to sign in with (run Companion over HTTPS)
  • For legacy env-token mode: admin API token(s) from your Technitium DNS server(s)

Quick Start with Docker (or similar) [Recommended]

Available image tags (published to GitHub Container Registry):

Tag Description
latest Stable release (default)
1.6, 1.6.9 Pinned version tags
beta Pre-release from the next branch — may include features not yet in stable
next Rolling next branch head (same image as beta, dev-facing alias)

The fastest path is the download-and-run script (no repo clone required). For full options and HTTPS details, see DOCKER.md.

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/Fail-Safe/Technitium-DNS-Companion/main/scripts/docker-quickstart.sh -o docker-quickstart.sh
chmod +x docker-quickstart.sh
./docker-quickstart.sh

Windows PowerShell:

iwr https://raw.githubusercontent.com/Fail-Safe/Technitium-DNS-Companion/main/scripts/docker-quickstart.ps1 -OutFile docker-quickstart.ps1
powershell -ExecutionPolicy Bypass -File .\docker-quickstart.ps1

What the script does:

  • Verifies Docker is running
  • Downloads .env.example into technitium.env if missing
  • Shows (and can run) the docker run command
  • Pulls the selected image first (so :latest stays current)

If technitium.env does not exist yet, the script will create it and exit so you can edit it. After updating technitium.env, rerun the script: it will confirm your desired HTTP/HTTPS ports, show the exact docker run command, and only executes it when you press Enter (any other key cancels).

Note: the script requires HTTP and HTTPS to use different host ports (it will re-prompt if you enter the same port for both).

For manual docker run or compose instructions, head to DOCKER.md.

Configuration

Technitium-DNS-Companion's forward-looking baseline is v15.3+. Technitium DNS v14 and earlier remain functional on a best-effort basis in Companion 1.x, but are deprecated and will be removed in Companion 2.0 no earlier than late October 2026.

Technitium DNS v15.3+ with Clustering (Recommended)

When clustering is enabled in Technitium DNS v15.3+, the recommended setup is session auth for interactive UI access:

TECHNITIUM_NODES=primary,secondary1,secondary2

TECHNITIUM_PRIMARY_BASE_URL=https://primary.home.arpa:53443
TECHNITIUM_SECONDARY1_BASE_URL=https://secondary1.home.arpa:53443
TECHNITIUM_SECONDARY2_BASE_URL=https://secondary2.home.arpa:53443

# Background jobs (recommended): least-privilege token
# TECHNITIUM_BACKGROUND_TOKEN=your-low-privilege-token

Configuration reference: .env.example contains the current defaults and all supported options.

Cluster Features:

  • Automatic cluster detection
  • Primary/Secondary role awareness
  • Write operations restricted to Primary node
  • Automatic cluster role change detection (every 30 seconds)
  • Sync tab hidden (not needed with native clustering)

Legacy v14 and Earlier Deployments (Deprecated)

For pre-v15 deployments or nodes without clustering, per-node environment tokens remain available for migration compatibility:

# Each node has its OWN unique token
TECHNITIUM_NODES=node1,node2,node3

TECHNITIUM_NODE1_BASE_URL=https://dns1.yourdomain.com:5380
TECHNITIUM_NODE1_TOKEN=unique-token-for-node1

TECHNITIUM_NODE2_BASE_URL=https://dns2.yourdomain.com:5380
TECHNITIUM_NODE2_TOKEN=unique-token-for-node2

TECHNITIUM_NODE3_BASE_URL=https://dns3.yourdomain.com:5380
TECHNITIUM_NODE3_TOKEN=unique-token-for-node3

Legacy configuration: Use the per-node token section in .env.example and review the Technitium version compatibility guide.

Standalone Features:

  • All nodes shown as "Standalone"
  • No write restrictions (all nodes can be modified)
  • Sync tab available for manual synchronization
  • Zone comparison helps identify differences

Production: See DOCKER.md for complete Docker deployment configuration.

Optional storage features

These features write data to disk and are disabled unless explicitly enabled/configured. If you run in Docker, keep a /data volume mount so the data persists across container restarts.

  • SQLite rolling query log store (optional)

    • Improves accuracy for time-window browsing (e.g., “Last 24h”) by continuously ingesting query logs into a local SQLite DB.
    • Key env vars: QUERY_LOG_SQLITE_ENABLED, QUERY_LOG_SQLITE_PATH, QUERY_LOG_SQLITE_RETENTION_HOURS.
    • Session-auth note: the ingester runs as a background task and may require TECHNITIUM_BACKGROUND_TOKEN.
    • Docs: docs/features/query-logs/SQLITE_ROLLING_QUERY_LOG_STORE.md

  • DNS Filtering History snapshots (optional)

    • Stores snapshot JSON files so Built-in Blocking / Advanced Blocking changes can be rolled back.
    • Key env vars: DNS_FILTERING_SNAPSHOT_DIR, DNS_FILTERING_SNAPSHOT_RETENTION.
    • See .env.example for defaults and persistence notes.

  • Domain Groups and Log Alert Rules (SQLite-backed, shared companion.sqlite)

    • Domain Groups are enabled by default. Log Alert Rules are always-on when the companion DB is available.
    • Both features share a single SQLite file (companion.sqlite). Override the path with COMPANION_DB_PATH.
    • Domain Groups optional kill switch: DOMAIN_GROUPS_ENABLED=false.
    • See .env.example for defaults and persistence notes.

Features

Core Functionality

  • Multi-Node Management - Monitor and manage multiple servers from one interface
  • Query Logs - View combined query logs from all configured nodes (optional SQLite stored logs for accurate time-window browsing; see docs/features/query-logs/SQLITE_ROLLING_QUERY_LOG_STORE.md)
  • Advanced Blocking - Manage domain allow/block lists (requires Advanced Blocking App), with optional DNS Filtering History (snapshots) for quick rollback
  • Pause Built-in Blocking - Persistent header pill that surfaces Technitium's temporary-disable timer at the top level; preset durations (1m–4h), a live countdown while paused, and multi-node fan-out so a pause/resume applies across every blocking node at once
  • Domain Groups - SQLite-backed named domain sets that bind to Advanced Blocking groups; drag-and-drop bindings, apply tracking with zero-data-loss semantics, and unified export/import
  • DNS Schedules - Time-window automation that toggles Advanced Blocking groups on a daily/weekly schedule (with timezone and overnight-window support), optional email notifications with templated subjects/bodies, and drift detection
  • Log Alerts - Rule-based SMTP notifications triggered by query log events; configurable domain patterns, debounce, client filters, and outcome modes

Analysis & Comparison

  • Zone Comparison - Compare DNS zones across nodes and identify differences
  • DHCP Management - View and clone DHCP scopes across nodes
  • Auto-Detection - Automatically detects which apps are installed on each node

Monitoring & Operations

  • Health Check API - Built-in health check endpoints for Docker health checks and external monitoring (see docs/features/HEALTH_CHECK_API.md)
  • Performance Optimizations - Caching, deduplication, and throttling for efficient operation

User Experience

  • Responsive UI - Mobile-friendly interface built with React and TailwindCSS
  • Cluster Support - Automatic detection and support for Technitium DNS v15 clustering
  • Touch-Optimized - Designed for easy use on smartphones and tablets

License

MIT License - see LICENSE file for details