Skip to main content

Technitium

@thomas/technitiumv2026.10.25.1· MIT(was none)· 28d agoBEHAVIORS
01README

Management of a Technitium DNS Server through its HTTP API: built-in ad blocking (enable/disable, temporary disable, allow/block list URLs), authoritative zone and record lifecycle, allowed/blocked custom domains, dashboard stats, DNS client and query-log debugging, cache flush, settings backup/restore, and security settings (admin web-service TLS certificate and DNSSEC validation).

02Release Notes

Adds record_ensure: a rerun-safe upsert for zone records (fixes GitHub issue #2). Takes a list; each entry adds the record if missing, updates it if its TTL differs, or reports it unchanged. A required mode decides what happens to other records of the type at the name: replace makes it the only one (removed records are stored as deleted), add leaves them alone. The manifest now declares the MIT licence, and the README stores the API token through the prompting form of swamp vault put.

03Behaviors1
@thomas/technitiumv2026.10.25.1technitium.ts

Global Arguments

ArgumentTypeDescription
baseUrlstringTechnitium base URL including port, e.g. https://dns.example:5380
apiTokenstringPermanent Technitium API token. Supply via vault: ${{ vault.get(technitium, api_token) }}
skipTlsVerify?booleanTurn off TLS certificate verification entirely (default false). This
fn blocking_get_settings()
Get the stored subset of the server settings (blocking, web-service TLS, DNSSEC validation, DNS-over-TLS).
fn blocking_set_state(enable: boolean)
Enable or disable DNS blocking permanently (writes only `enableBlocking`).
ArgumentTypeDescription
enableboolean
fn blocking_temporary_disable(minutes: number)
Temporarily disable blocking for N minutes; it re-enables automatically afterwards.
ArgumentTypeDescription
minutesnumberMinutes to disable blocking (e.g. 5, 15, 30, 60, 1440)
fn blocking_set_lists(blockListUrls?: array, allowListUrls?: array)
Set the block-list and/or allow-list URLs; only the lists you provide are changed, and an
ArgumentTypeDescription
blockListUrls?array
allowListUrls?array
fn blocking_force_update_lists()
Force an immediate refresh of all configured block-list URLs.
fn web_service_set_tls(certificatePath?: string, certificatePassword?: string, useSelfSignedCertificate?: boolean, enableTls?: boolean, tlsPort?: number, httpToTlsRedirect?: boolean)
Configure the admin web service TLS (HTTPS) listener: install a
ArgumentTypeDescription
certificatePath?stringPKCS#12 (.pfx/.p12) cert path on the server. Relative paths resolve
certificatePassword?stringExport password for the PKCS#12 file. Supply via vault expression.
useSelfSignedCertificate?booleanSet false when installing a real cert via certificatePath.
enableTls?booleanEnable/disable the HTTPS listener (webServiceTlsPort).
tlsPort?numberHTTPS listener port (Technitium default 53443).
httpToTlsRedirect?booleanRedirect plaintext HTTP to HTTPS. Enable only AFTER verifying the cert.
fn dnssec_validation_set(enable: boolean)
Enable or disable DNSSEC validation of upstream answers
ArgumentTypeDescription
enablebooleanWhether the resolver validates DNSSEC on upstream answers.
fn zone_list()
List all zones (factory: one `zone` per entry, keyed by zone name).
fn zone_create(zone: string, catalog?: string)
Create an authoritative zone. If a zone of the same type, in the `catalog` given if any, already exists it is left as it is (`unchanged`); any other existing zone is an error.
ArgumentTypeDescription
zonestringZone name, e.g. lab.example.com
catalog?stringName of an existing catalog zone to join as a member zone, so secondaries
fn zone_delete(zone: string)
Delete a zone. A zone that does not exist is reported as deleted.
ArgumentTypeDescription
zonestring
fn zone_enable(zone: string)
Enable a previously disabled zone.
ArgumentTypeDescription
zonestring
fn zone_disable(zone: string)
Disable a zone without deleting it.
ArgumentTypeDescription
zonestring
fn record_list(zone: string)
List all records in a zone (factory: one `zoneRecord` per record).
ArgumentTypeDescription
zonestring
fn record_get(zone?: string, domain: string)
Read the live records at a single domain straight from Technitium (factory: one `zoneRecord` each). Ground-truth read-back for one name — unlike `record_list` it queries a single domain rather than the whole zone.
ArgumentTypeDescription
zone?stringZone name; inferred by Technitium if omitted
domainstringRecord owner FQDN to read live
fn record_add(zone?: string, domain: string, type: string, ttl?: number)
Add a record. `rData` carries the type-specific fields (e.g. { ipAddress } for A, { cname } for CNAME, { exchange, preference } for MX).
ArgumentTypeDescription
zone?stringZone name; inferred from domain if omitted
domainstringRecord owner FQDN
typestringA | AAAA | CNAME | TXT | MX | SRV | NS | PTR | ...
ttl?number
fn record_update(zone?: string, domain: string, type: string, ttl?: number, disable?: boolean, comments?: string, expiryTtl?: number, newDomain?: string)
Update a record. `rData` identifies the existing record; `newRData` carries the new values (mapped to Technitium's new* params, except for APP, CNAME and DNAME, which take the new values as they are).
ArgumentTypeDescription
zone?string
domainstring
typestring
ttl?numberNew TTL; the record's current TTL is kept when omitted
disable?booleanDisable or enable the record; its current state is kept when omitted
comments?stringNew comment; the current comment is kept when omitted
expiryTtl?numberSeconds after last modification to auto-delete (0 = never); kept when omitted
newDomain?stringRename the record owner, if set
fn record_ensure(records: array)
Make records match the given data and TTL, safe to rerun: adds a record that is missing, updates one whose TTL differs, and leaves one that already matches (action `unchanged`). Each entry's `mode` decides what happens to other records of its type at its name: `replace` makes it the only one (the others are removed and stored as `deleted`); `add` leaves them as they are. Fans out over `records` in one run.
ArgumentTypeDescription
recordsarray
fn record_delete(zone?: string, domain: string, type: string)
Delete a record. `rData` identifies which record (e.g. { ipAddress }).
ArgumentTypeDescription
zone?string
domainstring
typestring
fn allowed_add(domain: string)
Add a domain to the built-in Allowed zone.
ArgumentTypeDescription
domainstring
fn allowed_delete(domain: string)
Remove a domain from the built-in Allowed zone.
ArgumentTypeDescription
domainstring
fn allowed_list(domain?: string)
List every domain in the built-in Allowed zone, or under `domain` (factory: one `listEntry` per domain). Walks the zone's label tree, one API call per branching node.
ArgumentTypeDescription
domain?stringList only this domain and the domains under it; the whole zone if omitted
fn allowed_flush()
Remove all domains from the built-in Allowed zone.
fn blocked_add(domain: string)
Add a domain to the built-in Blocked zone.
ArgumentTypeDescription
domainstring
fn blocked_delete(domain: string)
Remove a domain from the built-in Blocked zone.
ArgumentTypeDescription
domainstring
fn blocked_list(domain?: string)
List every domain in the built-in Blocked zone, or under `domain` (factory: one `listEntry` per domain). Walks the zone's label tree, one API call per branching node.
ArgumentTypeDescription
domain?stringList only this domain and the domains under it; the whole zone if omitted
fn blocked_flush()
Remove all domains from the built-in Blocked zone.
fn client_resolve(domain: string, type?: string, server?: string, protocol?: enum, dnssecValidation?: boolean)
Resolve a domain via the server's DNS client, for debugging. Output is ephemeral.
ArgumentTypeDescription
domainstring
type?string
server?stringthis-server | recursive-resolver | system-dns | <ip/hostname>
protocol?enum
dnssecValidation?boolean
fn logs_query(appName?: string, classPath?: string, pageNumber?: number, entriesPerPage?: number, descendingOrder?: boolean, start?: string, end?: string, clientIpAddress?: string, protocol?: string, responseType?: string, rcode?: string, qname?: string, qtype?: string, qclass?: string)
Query recent DNS query logs, one page per call (factory: one `queryLog` per entry, keyed on its content, plus a `queryLogPage` with the page and the totals). Requires the Query Logs (Sqlite) DNS app to be installed.
ArgumentTypeDescription
appName?stringDNS app providing query logs (override if your install differs)
classPath?stringApp class path (override if your install differs)
pageNumber?number
entriesPerPage?number
descendingOrder?boolean
start?stringISO 8601 start time
end?stringISO 8601 end time
clientIpAddress?string
protocol?string
responseType?string
rcode?stringDNS response code, e.g. NxDomain
qname?string
qtype?string
qclass?string
fn cache_flush()
Flush the entire DNS cache.
fn cache_list(domain?: string)
List cached zones/records under a domain (factory: one `cacheEntry` per name).
ArgumentTypeDescription
domain?stringSub-tree to list; root if omitted
fn cache_delete(domain: string)
Delete a cached domain entry.
ArgumentTypeDescription
domainstring
fn dashboard_stats(start?: string, end?: string)
Get dashboard query statistics for a time range.
ArgumentTypeDescription
start?stringISO 8601 start (when type=Custom)
end?stringISO 8601 end (when type=Custom)
fn settings_backup(options?: record)
Download a full settings backup (zip) and store it as a `backup` file. May contain secrets.
ArgumentTypeDescription
options?record
fn settings_restore(filePath: string, options?: record, deleteExistingFiles?: boolean)
Restore settings from a local backup zip (multipart upload). Verify the file before running this.
ArgumentTypeDescription
filePathstringAbsolute path to the backup zip on the swamp host
options?record
deleteExistingFiles?booleanDelete the server's existing files for each section being restored

Resources

zone(30d)— An authoritative DNS zone
zoneRecord(30d)— A resource record within a zone
settings(infinite)— Selected server settings: blocking, web-service TLS, DNSSEC validation and DNS-over-TLS
stats(1d)— Dashboard query statistics for a time range
listEntry(30d)— A domain in the built-in Allowed or Blocked zone
dnsResponse(ephemeral)— Result of a DNS client resolve (debugging — ephemeral)
queryLog(7d)— A query-log entry (requires the Query Logs (Sqlite) app)
queryLogPage(7d)— Which page the last logs_query read, and how many entries and pages its query matched
cacheEntry(1h)— A cached zone or record name
operationResult(infinite)— Result of a one-shot operation (flush, temp-disable, restore, ...)

Files

backup(application/zip)— A full Technitium settings backup (zip). May contain secrets — short-lived.
04Previous Versions5
2026.10.11.1

Added 1 behaviors

2026.09.01.1
2026.06.24.1

Removed 1 behaviors

2026.05.24.1

Modified 1 behaviors

2026.05.23.1
05Stats
A
100 / 100
Downloads
40
Archive size
49.4 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels