Cluster deployment and high availability
An Axiom cluster is a Management-controlled group of nodes with the same data-plane role. An SMB cluster contains one source SMB node and one or more SMB replic
Cluster deployment and high availability
What an Axiom cluster does
An Axiom cluster is a Management-controlled group of nodes with the same data-plane role. An SMB cluster contains one source SMB node and one or more SMB replicas. A DNS cluster contains one source DNS node and one or more DNS replicas.
Management synchronizes the shared service template, centrally managed policy, reputation data, node identity, health, and delivery acknowledgements. The source node seeds the service template when the group is created; replicas do not depend on the source node to process traffic after enrollment.
Cluster membership does not create a floating IP, configure VRRP, change DHCP, or operate an external load balancer. Traffic high availability is a separate network design described below.
Before creating a cluster
Complete these checks first:
- Install and validate the Management Server.
- Install at least one healthy SMB or DNS node normally.
- Confirm the source node appears online under Nodes and uses the intended service configuration.
- Confirm the customer license has capacity for the additional SMB or DNS nodes.
- Require HTTPS on the Management URL for production enrollment.
- Allow replicas to reach Management on TCP 8443 and allow Management to reach each replica on TCP 9443.
- Assign every replica a unique Node ID, static IP, and hostname.
Create the group in Management
- Sign in to Management and open Clusters.
- Enter a unique name containing 3 to 64 letters, numbers, hyphens, or underscores, such as
smb-productionordns-production. - Select
SMB ProxyorDNS Security. - Select an online source node of the same role.
- Set a unique join password with at least 12 characters.
- Record the intended traffic mode and, when applicable, the external VIP or DNS service name.
- Select Create cluster.
The join password is stored as an Argon2 hash. It authorizes new enrollment only; existing replicas use unique node credentials and remain connected when the join password is rotated.
Install an SMB replica
Run the normal installer on a fresh Ubuntu or Debian server:
chmod +x axiom-installer.sh
sudo ./axiom-installer.sh
Choose smb_proxy, then select Join this node to an existing Axiom cluster. Enter the HTTPS Management URL, cluster name, join password, and a unique Node ID.
The installer imports backend SMB targets, ports, VLAN metadata, and listener backlog from the source template. It still asks for this replica's local listener NIC and IP because those values belong to the Linux host. After installation, verify TCP 445 on the client-facing address and TCP 9443 on the node control address.
Install a DNS replica
Run the same installer, choose dns, and select the cluster enrollment path. Enter the Management URL, cluster name, join password, and a unique Node ID.
The installer imports upstream resolvers, DNS ports, cache limits, timeout values, and threat-feed refresh timing. It asks for the replica's local DNS listener NIC/IP and upstream egress NIC. After installation, verify UDP/TCP 53 on the service address and TCP 9443 on the node control address.
Shared and local settings
| Area | Synchronized by Management | Configured per replica |
|---|---|---|
| SMB | Backend targets, ports, VLAN metadata, backlog, policy, reputation | NIC name, listener IP, node control IP |
| DNS | Upstreams, ports, cache and timeout settings, local DNS policy, threat-feed timing | Listener NIC/IP, upstream egress NIC, node control IP |
| Identity | Cluster name, role, unique node credential | Unique Node ID and hostname |
Never clone /etc/axiom/axiom.toml from one replica to another. Duplicate Node IDs or credentials make revocation and health reporting unreliable.
Verify enrollment and synchronization
Open Clusters and confirm:
- The source node and every replica are
online. - Configuration state is
Synced. - The replica also appears under Nodes.
- Sync now completes and reachable members acknowledge the policy push.
- A policy change reaches every member of the matching role.
- SMB byte counters or DNS query counters increase on the replica receiving test traffic.
Management uses active push on TCP 9443. Periodic pull over TCP 8443 remains a recovery path. If a node is online but does not acknowledge a push, test both directions rather than assuming enrollment is complete.
Design client traffic high availability
DNS
Publish two or more Axiom DNS node addresses through DHCP, endpoint DNS settings, or the internal DNS/DC forwarding configuration. Test actual client retry and failover behavior; address publication alone does not prove that every operating system or application fails over within the required time.
SMB
Place SMB replicas behind an external Layer 4 load balancer or TCP 445 VIP with source or session affinity. SMB sessions are stateful, so a connection must remain on one proxy for its lifetime. The load balancer must perform TCP health checks and stop sending new sessions to an unhealthy node.
Do not assign the same service IP directly to multiple Linux nodes unless an approved VRRP or load-balancing design owns address failover. Axiom records the intended mode and endpoint but does not control the external VIP.
Restricted and air-gapped networks
Cluster operation requires no internet access. Replicas need only the Management control flows and their normal SMB backend or DNS upstream connectivity. In an air-gapped environment, use the same installer and local Management URL.
If Management is temporarily unavailable, enrolled data-plane nodes continue using their last installed local configuration and policy. New enrollment, credential changes, policy changes, and centralized health updates wait until Management connectivity returns.
Credential and membership operations
- Rotate the join password after a deployment window or suspected disclosure.
- Remove a retired replica from Clusters to revoke its unique control-plane credential.
- Re-enrollment is required after removal.
- The source node cannot be removed while it remains the source of an active group.
- Do not delete a cluster until reporting replicas have been removed or re-enrolled appropriately.
Acceptance test
- Create one SMB and one DNS cluster from validated source nodes.
- Enroll one fresh replica for each role without re-entering backend or upstream settings.
- Confirm every member is online and synchronized.
- Push an SMB policy and a DNS policy and verify acknowledgement from all reachable members.
- Send representative traffic to every replica and verify telemetry.
- Remove a test replica and confirm its next authenticated report is rejected.
- Rotate the join password and confirm existing replicas stay online.
- Temporarily stop Management and confirm existing data-plane traffic continues with the last policy.
- Validate DNS client failover or the external SMB VIP separately.
Troubleshooting
Join is rejected: verify the cluster name, role, join password, unique Node ID, HTTPS trust, TCP 8443 reachability, and license node limit. Repeated invalid attempts are rate limited.
Replica is online but configuration drifts: select Sync now, compare the applied generation, and review TCP 9443 from Management to the node. Confirm local host fields were not mistaken for shared template fields.
Policy is current but traffic does not fail over: diagnose DHCP/client DNS behavior or the external SMB load balancer. Axiom cluster synchronization does not move client sessions or own a floating service IP.
Source node is unavailable: replicas can continue serving traffic. Restore or replace the source deliberately before refreshing the service template; do not assume source health controls replica traffic.