Technitium DNS¶

Technitium is a self-hosted DNS server with a REST API. It's the most full-featured provider in dnsweaver with support for all record types.

Requirements¶

Technitium DNS Server v11.0+ (for SRV record support) or v9.0+ (for basic records)
API token with zone management permissions

Basic Configuration¶

environment:
  - DNSWEAVER_INSTANCES=technitium

  - DNSWEAVER_TECHNITIUM_TYPE=technitium
  - DNSWEAVER_TECHNITIUM_URL=http://dns-server:5380
  - DNSWEAVER_TECHNITIUM_TOKEN_FILE=/run/secrets/technitium_token
  - DNSWEAVER_TECHNITIUM_ZONE=home.example.com
  - DNSWEAVER_TECHNITIUM_RECORD_TYPE=A
  - DNSWEAVER_TECHNITIUM_TARGET=192.0.2.100
  - DNSWEAVER_TECHNITIUM_DOMAINS=*.home.example.com

Configuration Reference¶

Variable	Required	Default	Description
`TYPE`	Yes	-	Must be `technitium`
`URL`	Yes	-	Technitium server URL
`TOKEN`	Yes	-	API token
`TOKEN_FILE`	Alt	-	Path to file containing API token
`ZONE`	Yes	-	DNS zone to manage
`RECORD_TYPE`	Yes	-	`A`, `AAAA`, `CNAME`, `SRV`, or `TXT`
`TARGET`	Yes	-	Record value
`DOMAINS`	Yes	-	Glob patterns to match
`EXCLUDE_DOMAINS`	No	-	Patterns to exclude
`TTL`	No	`300`	Record TTL in seconds
`INSECURE_SKIP_VERIFY`	No	`false`	Skip TLS certificate verification
`AUTO_HTTPS_RECORDS`	No	`true`	Auto-create companion HTTPS records (see below)
`AUTO_HTTPS_ALPN`	No	`h2`	ALPN protocol for companion HTTPS records

Getting an API Token¶

Log into Technitium web interface
Navigate to Administration → API Token
Create a new token with appropriate permissions
Copy the token value

Warning

Store the API token securely using Docker secrets. See Docker Secrets.

Record Types¶

A Records¶

Point hostnames to an IPv4 address:

- DNSWEAVER_TECHNITIUM_RECORD_TYPE=A
- DNSWEAVER_TECHNITIUM_TARGET=192.0.2.100

AAAA Records¶

Point hostnames to an IPv6 address:

- DNSWEAVER_TECHNITIUM_RECORD_TYPE=AAAA
- DNSWEAVER_TECHNITIUM_TARGET=2001:db8::1

CNAME Records¶

Point hostnames to another hostname:

- DNSWEAVER_TECHNITIUM_RECORD_TYPE=CNAME
- DNSWEAVER_TECHNITIUM_TARGET=proxy.example.com

SRV Records¶

Create SRV records for service discovery:

- DNSWEAVER_TECHNITIUM_RECORD_TYPE=SRV
- DNSWEAVER_TECHNITIUM_TARGET=192.0.2.100
- DNSWEAVER_TECHNITIUM_SRV_PORT=443
- DNSWEAVER_TECHNITIUM_SRV_PRIORITY=10
- DNSWEAVER_TECHNITIUM_SRV_WEIGHT=100

Multiple Zones Example¶

Manage multiple zones with separate instances:

environment:
  - DNSWEAVER_INSTANCES=internal,dmz

  # Internal zone
  - DNSWEAVER_INTERNAL_TYPE=technitium
  - DNSWEAVER_INTERNAL_URL=http://dns-server:5380
  - DNSWEAVER_INTERNAL_TOKEN_FILE=/run/secrets/technitium_token
  - DNSWEAVER_INTERNAL_ZONE=internal.example.com
  - DNSWEAVER_INTERNAL_RECORD_TYPE=A
  - DNSWEAVER_INTERNAL_TARGET=192.0.2.100
  - DNSWEAVER_INTERNAL_DOMAINS=*.internal.example.com

  # DMZ zone
  - DNSWEAVER_DMZ_TYPE=technitium
  - DNSWEAVER_DMZ_URL=http://dns-server:5380
  - DNSWEAVER_DMZ_TOKEN_FILE=/run/secrets/technitium_token
  - DNSWEAVER_DMZ_ZONE=dmz.example.com
  - DNSWEAVER_DMZ_RECORD_TYPE=A
  - DNSWEAVER_DMZ_TARGET=198.51.100.100
  - DNSWEAVER_DMZ_DOMAINS=*.dmz.example.com

Troubleshooting¶

Connection Refused¶

Ensure Technitium's API is accessible from the dnsweaver container:

docker exec dnsweaver curl -s http://dns-server:5380/api/user/session/get

Invalid Token¶

Verify your token is correct:

curl "http://dns-server:5380/api/zones/list?token=YOUR_TOKEN"

TLS Certificate Errors¶

For self-signed certificates, either:

Add the CA to dnsweaver's trust store
Use INSECURE_SKIP_VERIFY=true (not recommended for production)

- DNSWEAVER_TECHNITIUM_INSECURE_SKIP_VERIFY=true

Companion HTTPS Records¶

By default, dnsweaver automatically creates companion HTTPS (SVCB Type 65) records whenever it creates an A, AAAA, or CNAME record in Technitium. This prevents ECH (Encrypted Client Hello) fallback errors that commonly affect split-horizon DNS environments.

Why This Exists¶

Modern browsers (Firefox 128+, Chrome 131+) use ECH to encrypt the SNI during TLS handshakes. When a public domain has HTTPS records (provided by CDNs like Cloudflare), but your internal DNS zone doesn't, browsers may fail to connect or experience delays trying to use ECH parameters that don't apply internally.

The companion HTTPS record tells browsers "this host speaks HTTP/2 over TLS" without ECH, preventing the fallback error.

What Gets Created¶

For each A/AAAA/CNAME record, dnsweaver creates:

app.example.com  300  IN  HTTPS  1 . alpn="h2"

Priority 1 (ServiceMode) — overrides any inherited ECH parameters
Target . (self) — the record's own hostname, per RFC 9460
ALPN h2 — HTTP/2 over TLS (configurable)

Behavior¶

Enabled by default — no configuration needed
Safe — skips creation if an HTTPS record already exists (won't overwrite manual records)
Lifecycle-managed — companion records are deleted when the parent record is removed
Idempotent — duplicate creation attempts are handled gracefully

Configuration¶

# Disable companion HTTPS records (not recommended for split-horizon setups)
- DNSWEAVER_TECHNITIUM_AUTO_HTTPS_RECORDS=false

# Change the ALPN protocol (default: h2)
- DNSWEAVER_TECHNITIUM_AUTO_HTTPS_ALPN=h2,h3

Tip

If you use Cloudflare for external DNS and Technitium for internal DNS (a common split-horizon setup), companion HTTPS records are essential. Cloudflare provides HTTPS records automatically on their side — Technitium needs them too.

Note

This feature only applies to the Technitium provider. Other providers either handle HTTPS records automatically (Cloudflare) or don't support them (Pi-hole, dnsmasq).