# Admin: Initialize and Join Cluster
## Endpoint
`/api/admin/cluster/initJoin`
## Method
POST (`application/x-www-form-urlencoded`)
## Description
Joins a Cluster by making this DNS server a Secondary node. This process will overwrite configuration on this DNS server for the Allowed, Blocked, Apps, Settings, and Administration sections. The DNS server will automatically synchronize its configuration with the Primary node.
If the web service does not have HTTPS enabled, the joining process will enable it automatically with a self-signed certificate. It is recommended to manually configure HTTPS with a valid certificate before joining.
**Warning: Joining a Cluster will permanently overwrite configuration for Allowed, Blocked, Apps, Settings, and Administration sections.**
This call can only be made at the Secondary node (the node initiating the join).
## Authentication
Required. Token must be provided via the `token` parameter.
## Permissions
Administration: Delete
## Parameters
| `token` | string | Yes | No | The session token generated by the `login` or the `createToken` call. |
| `secondaryNodeIpAddresses` | string | Yes | No | A comma-separated list of IP addresses of this DNS server that will be accessible by all other DNS server nodes in the Cluster. |
| `primaryNodeUrl` | string | Yes | No | The web service HTTPS URL of the Primary node in the Cluster. |
| `primaryNodeIpAddress` | string | No | No | The IP address of the Primary node. When unspecified, the domain name in the Primary node URL will be resolved and used. |
| `ignoreCertificateErrors` | boolean | No | No | Set to `true` only when the Primary node uses a self-signed TLS certificate and is reachable on a private network. |
| `primaryNodeUsername` | string | Yes | No | The username of an administrator on the Primary node. |
| `primaryNodePassword` | string | Yes | No | The password of the administrator user specified above. |
| `primaryNodeTotp` | string | No | Yes | The 6-digit TOTP code from the authenticator app for the administrator user. Only required if the user has 2FA enabled. |
## Response Fields
| `clusterInitialized` | boolean | `true` after successful join. |
| `dnsServerDomain` | string | The FQDN of this DNS server (updated to be under the cluster domain). |
| `version` | string | The DNS server software version. |
| `clusterDomain` | string | The cluster domain name. |
| `heartbeatRefreshIntervalSeconds` | integer | Heartbeat refresh interval synced from Primary. |
| `heartbeatRetryIntervalSeconds` | integer | Heartbeat retry interval synced from Primary. |
| `configRefreshIntervalSeconds` | integer | Config refresh interval synced from Primary. |
| `configRetryIntervalSeconds` | integer | Config retry interval synced from Primary. |
| `configLastSynced` | string (datetime) | Timestamp of the initial config sync. |
| `nodes` | array | List of all cluster node objects. |
| `nodes[].id` | integer | Unique node ID. |
| `nodes[].name` | string | Node FQDN. |
| `nodes[].url` | string | Node HTTPS API URL. |
| `nodes[].ipAddresses` | array of strings | Node IP addresses. |
| `nodes[].type` | string | Node type: `Primary` or `Secondary`. |
| `nodes[].state` | string | Node state: `Self`, `Connected`, or `Unreachable`. |
| `nodes[].lastSeen` | string (datetime) | Timestamp of last contact. |
## Conditional Logic Notes
- This is a **POST** request (unlike most other admin endpoints which are GET). The content type must be `application/x-www-form-urlencoded`.
- The `primaryNodeTotp` is conditionally required: only needed when the specified administrator user has 2FA enabled on the Primary node.
- The `primaryNodeIpAddress` is optional; if omitted, DNS resolution of the Primary node URL's hostname is used.
- The `ignoreCertificateErrors` flag should only be used on private/trusted networks with self-signed certificates.
- This call can only be made at the server that will become the Secondary node, not at the Primary.
- Configuration for Allowed, Blocked, Apps, Settings, and Administration sections will be overwritten from the Primary.
- The join process may take significant time depending on the amount of configuration to synchronize.
## Edge Cases
- If HTTPS is not enabled, it will be auto-enabled with a self-signed certificate, potentially changing the server's URL.
- The process may take a long time for large configurations; the client should be prepared for a slow response.
- If the Primary node credentials are wrong or the TOTP code is invalid, the join will fail.
- After joining, local configuration for the overwritten sections is permanently lost.
- The `dnsServerDomain` will be updated to an FQDN under the cluster domain.