Automating DNS Management: Infrastructure as Code with Technitium DNS Server

Automating Technitium DNS Management with Ansible

DNS Automation • Technitium API • Ansible Playbooks

Automate DNS zone management and server maintenance using Technitium DNS Server’s REST API with Ansible playbooks.

The DNS Management Problem

When you’re constantly deploying new services, containers, and lab infrastructure, manually editing DNS zones becomes a bottleneck. Whether it’s clicking through web GUIs or SSH sessions with text editors, manual DNS management doesn’t scale.

Technitium DNS Server offers a robust REST API that enables Infrastructure as Code principles for DNS management. Here’s one way to automate your DNS management.

Ansible Automation Approach

Three Core Playbooks

Export zones for backup → Import zones for deployment → Update DNS servers for maintenance

Export Playbook

Backup current DNS zones from Technitium to local directory structure via API

Import Playbook

Deploy zone file changes from local directory to Technitium with atomic operations

Update Automation

Automated DNS server updates and system maintenance via API checks

Getting Started: API Access

Generate API Tokens

Each Technitium DNS server needs its own API token. Log into the web interface and generate tokens for automation.

Access Technitium web interface: https://dns-server-ip/
Navigate to Administration → Sessions
Create new token with Zone permissions and Administration permissions
Copy the generated token – you won’t see it again
Repeat for each DNS server (tokens are server-specific)

Store Tokens Securely

Use Ansible Vault to encrypt tokens in your host_vars files. Never commit plain-text API tokens.

# Encrypt API token
ansible-vault encrypt_string 'your-api-token-here' --name 'technitium_api_token'

# Store in host_vars/dns1.example.local.yml
---
ansible_user: automation
technitium_api_token: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66386439653231653637643637373039633263633762383536363330316264376132633533346637
          ...encrypted token...

DNS Server Maintenance

Automated Updates via API

Before managing DNS zones, ensure your servers are up to date. Technitium provides an update check endpoint that integrates with automation.

---
- name: Update DNS servers
  hosts: dns_servers
  become: yes
  tasks:
    - name: Update apt cache
      apt:
        update_cache: yes
    
    - name: Upgrade all packages
      apt:
        upgrade: dist
    
    - name: Remove unused packages
      apt:
        autoremove: yes
    
    - name: Check for Technitium DNS updates
      uri:
        url: "https://{{ inventory_hostname }}/api/user/checkForUpdate?token={{ technitium_api_token }}"
        method: GET
        validate_certs: no
        return_content: yes
      register: dns_update_check
    
    - name: Parse update response
      set_fact:
        update_available: "{{ dns_update_check.json.response.updateAvailable }}"
        update_version: "{{ dns_update_check.json.response.updateVersion }}"
        current_version: "{{ dns_update_check.json.response.currentVersion }}"
    
    - name: Display update info
      debug:
        msg: "Technitium DNS - Current: {{ current_version }}, Available: {{ update_version }}, Update needed: {{ update_available }}"
    
    - name: Upgrade Technitium DNS if update available
      shell: curl -sSL https://download.technitium.com/dns/install.sh | sudo bash
      when: update_available | bool
      register: dns_upgrade
    
    - name: Display upgrade result
      debug:
        var: dns_upgrade.stdout_lines
      when: update_available | bool

The API returns detailed version information, enabling conditional upgrades. Combined with system updates, this maintains both OS and DNS server currency automatically. Run this weekly or monthly as scheduled maintenance.

DNS Zone Export Automation

Backup Current State

Export existing DNS zones to local directory structure to establish baseline for automation.

---
- name: Pull and save Technitium DNS records
  hosts: primary_dns
  gather_facts: false
  vars:
    dns_api_url: "https://dns1.example.local/api"
    api_token: "{{ technitium_api_token }}"
    domain: "example.local"
    output_file: "{{ playbook_dir }}/dns/records/dns_records_example.zone"
  tasks:
    - name: Export DNS zone from Technitium
      uri:
        url: "{{ dns_api_url }}/zones/export?token={{ api_token }}&zone={{ domain }}"
        method: GET
        return_content: yes
        status_code: 200
      register: dns_response
      
    - name: Save DNS zone file
      copy:
        dest: "{{ output_file }}"
        content: "{{ dns_response.content }}"
      delegate_to: localhost
      
    - name: Show saved zone file location
      debug:
        msg: "DNS zone saved to {{ output_file }}"

This creates BIND-format zone files in your local dns/records directory. Run this periodically as a backup or before making changes to capture current state.

DNS Zone Deployment

API Limitation Workaround

Technitium’s zone import doesn’t fully replace existing records. The solution: delete and recreate the zone for clean deployments.

---
- name: Full clean replace of Technitium DNS zone
  hosts: primary_dns
  connection: local
  gather_facts: false
  vars:
    dns_api: "https://dns1.example.local/api"
    token: "{{ technitium_api_token }}"
    zone: "example.local"
    zone_file: "{{ playbook_dir }}/records/dns_records_example.zone"
  tasks:
    - name: Read zone file
      slurp:
        src: "{{ zone_file }}"
      register: zone_raw
      
    - name: Delete zone (ignore if not exists)
      uri:
        url: "{{ dns_api }}/zones/delete?token={{ token }}&zone={{ zone }}"
        method: POST
        status_code: 200
      ignore_errors: yes
      
    - name: Create empty zone
      uri:
        url: "{{ dns_api }}/zones/create?token={{ token }}&zone={{ zone }}"
        method: POST
        status_code: 200
        
    - name: Delete all records inside fresh zone
      uri:
        url: "{{ dns_api }}/zones/records/delete?token={{ token }}&zone={{ zone }}&domain=@&type=*"
        method: POST
        status_code: 200
      ignore_errors: yes
      
    - name: Import full zone file
      uri:
        url: "{{ dns_api }}/zones/import?token={{ token }}&zone={{ zone }}&overwrite=true"
        method: POST
        headers:
          Content-Type: text/plain
        body: "{{ zone_raw.content | b64decode }}"
        status_code: 200
      register: import_result
      
    - debug:
        var: import_result.json

This approach ensures clean deployments. The delete/create/import sequence handles edge cases where the API’s overwrite function doesn’t remove old records.

Security and Configuration

API Token Management

Store API tokens in Ansible Vault or host_vars with proper encryption. Different servers require different tokens.

# host_vars/dns1.yml
---
ansible_user: automation
technitium_api_token: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66386439653231653637643637373039633263633762383536363330316264376132633533346637
          ...encrypted token...

# host_vars/dns2.yml  
---
ansible_user: automation
technitium_api_token: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          35663434666534336430316665643565636361356437383866303762343733313432623533323061
          ...different encrypted token...

Zone Transfer Configuration

Configure automatic zone transfers between primary and secondary DNS servers. Updates to the primary automatically replicate to secondaries.

# Inventory structure
[dns_servers:children]
primary_dns
secondary_dns

[primary_dns]
dns1.example.local

[secondary_dns]
dns2.example.local
dns3.example.local

# Only deploy to primary - zone transfer handles the rest

DNS Management Workflow

Ansible-Driven Process

Backup current state: Run export playbook to capture existing zones
Edit zone file: Modify DNS records locally
Deploy changes: Run import playbook to update DNS servers
Verify deployment: Test DNS resolution and check logs
Maintain servers: Run update playbook for system and DNS software updates

# Complete workflow example
cd ansible/playbooks

# 1. Backup current state
ansible-playbook dns_export.yml --ask-vault-pass

# 2. Edit zone file
vim dns/records/dns_records_example.zone
# Add: webapp1  3600  IN  A  192.168.10.50

# 3. Deploy changes
ansible-playbook dns_import.yml --ask-vault-pass

# 4. Verify
dig @dns1.example.local webapp1.example.local

# 5. Update servers (weekly maintenance)
ansible-playbook update_dns.yml --ask-vault-pass

Automation Benefits

Consistent Process

Standardized playbooks eliminate manual errors and ensure repeatable deployments.

Automated Backups

Export playbook creates zone backups before changes for easy rollback capability.

API-Driven Updates

Direct API interaction provides programmatic control over DNS infrastructure.

Atomic Operations

Zone replacement ensures consistent state – no partial updates or stale records.

Remote Management

Manage DNS servers without direct SSH access using REST API endpoints.

Maintenance Automation

Automated server updates and DNS software upgrades via scheduled playbooks.

Future Enhancements

Integration Opportunities

AWX/Tower integration: Centralized job scheduling and execution
Multi-zone support: Batch operations across multiple DNS zones
Slack notifications: Change notifications via N8N or direct webhooks

Evolution to GitOps

Once these Ansible playbooks are working reliably, you can evolve toward full GitOps by adding Git integration, CI/CD pipelines, and automated deployments. The foundation established here makes that transition straightforward.

Practical DNS Automation

Technitium DNS Server’s REST API combined with Ansible playbooks transforms DNS management from manual SSH sessions into standardized automation. The three-playbook approach handles the complete lifecycle: backup, deployment, and maintenance.

The delete/create/import workaround for clean zone replacements, combined with zone transfers to secondary servers, provides reliable DNS updates without manual intervention across your infrastructure.

Start with the export playbook to backup your existing zones, then gradually introduce the deployment automation as your confidence builds. The maintenance playbook handles the ongoing server updates automatically.

Technitium DNS Management with Ansible