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)
• Domain Groups (named domain sets that bind to 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 (v13.6 or v14.0+)
• 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.5, 1.5.1	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 supports both v13.6 (standalone) and v14.0+ (clustering) configurations.

Technitium DNS v14.0+ with Clustering (Recommended)

When clustering is enabled in Technitium DNS v14.0+, 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

Example config: See configs/.env.example.v14

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)

Technitium DNS v13.6 (Standalone Nodes)

For v13.6 or nodes without clustering, per-node env tokens are legacy-only (Technitium DNS < v14):

# 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

Example config: See configs/.env.example.v13

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
• 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
• 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 v14+ clustering
• Touch-Optimized - Designed for easy use on smartphones and tablets

License

MIT License - see LICENSE file for details