Skip to content

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)

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.

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

Screenshots

We auto-switch to light/dark variants based on your theme.

Overview (light) Overview (dark)
DNS logs (light) DNS logs (dark)
DNS filtering - advanced lists (light) DNS filtering - advanced lists (dark)
DNS filtering - advanced groups (light) DNS filtering - advanced groups (dark)
DNS filtering - advanced domains (light) DNS filtering - advanced domains (dark)
DNS filtering - built-in flat list (light) DNS filtering - built-in flat list (dark)
DNS filtering - built-in tree view (light) DNS filtering - built-in tree view (dark)
DNS filtering - built-in settings (light) DNS filtering - built-in settings (dark)
DNS lookup - all (light) DNS lookup - all (dark)
DNS lookup - policy (light) DNS lookup - policy (dark)
DHCP scopes (light) DHCP scopes (dark)
DHCP bulk sync (light) DHCP bulk sync (dark)