effectivelywild.technitium_dns.technitium_dns_init_join_cluster module – Join a DNS server to an existing cluster as a Secondary node

Note

This module is part of the effectivelywild.technitium_dns collection (version 1.1.2).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install effectivelywild.technitium_dns. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: effectivelywild.technitium_dns.technitium_dns_init_join_cluster.

New in effectivelywild.technitium_dns 1.0.0

Synopsis

  • Join this DNS server to an existing cluster as a Secondary node.

  • This process will overwrite configuration on this server for Allowed, Blocked, Apps, Settings and Administration sections.

  • The server will automatically synchronize its configuration with the Primary node.

  • If HTTPS is not enabled, it will be enabled automatically with a self-signed certificate.

  • This can only be called on a Secondary node (not yet joined to a cluster).

Requirements

The below requirements are needed on the host that executes this module.

  • Technitium DNS Server v14.0 or later

Parameters

Parameter

Comments

api_port

integer

Port for the Technitium DNS API. Defaults to 5380

Default: 5380

api_token

string / required

API token for authenticating with the Technitium DNS API

api_url

string / required

Base URL for the Technitium DNS API

ignore_certificate_errors

boolean

Set to true only when you know the Primary node uses a self-signed TLS certificate and is on a private network.

Choices:

  • false ← (default)

  • true

primary_node_ip_address

string

The IP address of the Primary node in the cluster.

When unspecified, the domain name in the Primary node URL will be resolved and used.

primary_node_password

string / required

The password of the administrator user.

primary_node_totp

string

The 6-digit code from your authenticator app for the administrator user.

Only required if the user has 2FA enabled.

primary_node_url

string / required

The web service HTTPS URL of the Primary node in the cluster.

primary_node_username

string / required

The username of an administrator on the Primary node in the cluster.

secondary_node_ip_addresses

list / elements=string / required

The static IP address(es) of this DNS server that will be accessible by all other nodes in the cluster.

Accepts a list of IP addresses for nodes with multiple network interfaces.

When multiple IPs are provided, they will be used for cluster communication.

validate_certs

boolean

Whether to validate SSL certificates when making API requests.

Choices:

  • false

  • true ← (default)

Notes

Note

  • This operation requires Administration Delete permission.

  • The process may take a while depending on the amount of config data to sync.

  • It’s recommended to manually configure HTTPS with a valid certificate before joining.

See Also

See also

effectivelywild.technitium_dns.technitium_dns_init_cluster

Initialize a new cluster (Primary node)

effectivelywild.technitium_dns.technitium_dns_leave_cluster

Leave a cluster

effectivelywild.technitium_dns.technitium_dns_get_cluster_state

Get cluster state information

Examples

- name: Join DNS server to cluster as Secondary node with single IP
  effectivelywild.technitium_dns.technitium_dns_init_join_cluster:
    api_url: "http://localhost"
    api_token: "myapitoken"
    secondary_node_ip_addresses:
      - "192.168.10.101"
    primary_node_url: "https://server1.example.com:53443/"
    primary_node_username: "admin"
    primary_node_password: "adminpassword"
  register: result

- name: Join cluster with multiple IP addresses
  effectivelywild.technitium_dns.technitium_dns_init_join_cluster:
    api_url: "http://localhost"
    api_token: "myapitoken"
    secondary_node_ip_addresses:
      - "192.168.10.101"
      - "10.0.1.101"
    primary_node_url: "https://server1.example.com:53443/"
    primary_node_username: "admin"
    primary_node_password: "adminpassword"

- name: Join cluster with self-signed certificate on primary
  effectivelywild.technitium_dns.technitium_dns_init_join_cluster:
    api_url: "http://localhost"
    api_token: "myapitoken"
    secondary_node_ip_addresses:
      - "192.168.10.102"
    primary_node_url: "https://server1.example.com:53443/"
    primary_node_ip_address: "192.168.10.5"
    ignore_certificate_errors: true
    primary_node_username: "admin"
    primary_node_password: "adminpassword"

- name: Join cluster with 2FA enabled
  effectivelywild.technitium_dns.technitium_dns_init_join_cluster:
    api_url: "http://localhost"
    api_token: "myapitoken"
    secondary_node_ip_addresses:
      - "192.168.10.103"
    primary_node_url: "https://server1.example.com:53443/"
    primary_node_username: "admin"
    primary_node_password: "adminpassword"
    primary_node_totp: "123456"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Whether the module made changes

Returned: always

Sample: true

cluster_state

dictionary

Complete cluster state after joining

Returned: always

clusterDomain

string

The cluster domain name

Returned: always

Sample: "example.com"

clusterInitialized

boolean

Whether the cluster is initialized

Returned: always

Sample: true

clusterNodes

list / elements=dictionary

List of nodes in the cluster

Returned: always

id

integer

Node ID

Returned: success

Sample: 811905692

ipAddress

string

Node IP address

Returned: success

Sample: "192.168.10.101"

name

string

Node domain name

Returned: success

Sample: "server2.example.com"

state

string

Node state (Self, Connected, Unreachable)

Returned: success

Sample: "Self"

type

string

Node type (Primary or Secondary)

Returned: success

Sample: "Secondary"

upSince

string

Node up since timestamp

Returned: success

Sample: "2025-09-27T13:19:54.6215569Z"

url

string

Node API URL

Returned: success

Sample: "https://server2.example.com:53443/"

configLastSynced

string

When the configuration was last synced

Returned: always

Sample: "2025-09-27T13:19:55Z"

configRefreshIntervalSeconds

integer

Interval in seconds for config refresh

Returned: always

Sample: 900

configRetryIntervalSeconds

integer

Interval in seconds for config retry

Returned: always

Sample: 60

dnsServerDomain

string

The DNS server domain name

Returned: always

Sample: "server2.example.com"

heartbeatRefreshIntervalSeconds

integer

Interval in seconds for heartbeat refresh

Returned: always

Sample: 30

heartbeatRetryIntervalSeconds

integer

Interval in seconds for heartbeat retry

Returned: always

Sample: 10

version

string

Technitium DNS Server version

Returned: always

Sample: "14.0"

failed

boolean

Whether the module failed

Returned: always

Sample: false

msg

string

Status message

Returned: always

Sample: "Successfully joined cluster"

Authors

  • Frank Muise (@effectivelywild)