This guide walks you through renaming the virtual machines in a live SmarterMail High Availability (HA) cluster: the hubs, nodes, and standbys. Cluster membership, certificates, and hub consensus data are all tied to each machine's hostname, so the order you do things in really matters. Work through each section in sequence and you'll avoid having to rebuild the cluster from scratch.
Throughout this guide, replace anything in angle brackets (for example, <new-hostname>) with your own values.
Before You Begin
A little prep goes a long way here. Make sure you have the following ready:
• A maintenance window. Every VM in the cluster gets shut down, so mail service will be unavailable until you're finished.
• The new hostnames for every hub, node, and standby.
• Access to DNS so you can update the records for each VM.
• Console or SSH access to every VM, plus an admin login for the cluster.
Shut Down and Snapshot the VMs
Your first step is to shut down every VM in this order:
1. Standbys
2. Nodes
3. Hubs
4. Load balancer
Once everything is off, take a snapshot of each VM or a backup of pertinent data on each. That way, if something goes sideways, you'll be able to roll back.
Order of Operations
Here's the big picture before we dig into the details:
1. Hubs first. Rename each hub, update the cluster settings, update DNS, and confirm the hubs reconnect to each other.
2. Nodes next. Remove each node from the cluster, rename it, and add it back.
3. Standbys last. Follow the same steps you used for the hubs and nodes.
Step 1: Rename the Hubs
Complete steps 1–4 on every hub before you start the hub service on any of them. (In the steps below we'll note commands via a CLI for Linux. Windows renames are handled via the Windows interface.)
1. Power on the hubs only (leave the nodes, standbys, and load balancer off). Then stop the hub service:
sudo service smartermail.hub stop
2. Change the VM's hostname:
sudo hostnamectl set-hostname <new-hub-hostname>
Note: If the old hostname appears in /etc/hosts, update it there too. Otherwise you may see "unable to resolve host" warnings every time you use sudo.
3. Open the cluster settings file and replace each old hub hostname with its new name:
sudo nano /opt/smartermail/cluster/ha-settings.json
4. Delete the pki and raft folders. The hubs will rebuild them under the new hostnames when the service starts:
sudo rm -r /opt/smartermail/cluster/pki
sudo rm -r /opt/smartermail/cluster/raft
Warning: rm -r deletes permanently, with no confirmation and no recycle bin. Double-check each path before you press Enter. This is exactly why you took snapshots.
5. Update the DNS records for the hubs so they point to the new hostnames.
6. Start the hub service on each hub:
sudo service smartermail.hub start
7. Confirm that every hub shows its new hostname and that all the hubs are connected to each other. Don't move on to the nodes until they are.
Step 2: Rename the Nodes
1. Log in to the cluster and disable failover on the nodes.
2. Delete the node entries from the cluster.
3. Power on the nodes and stop the SmarterMail service on each one:
sudo service smartermail stop
4. Remove the node's cluster settings file and its ClusterPki folder:
sudo rm /etc/smartermail/ha-settings.json
sudo rm -r /opt/smartermail/ClusterPki
5. Change the node's hostname (and update /etc/hosts if needed, just like you did for the hubs):
sudo hostnamectl set-hostname <new-node-hostname>
6. Reboot the node so everything picks up the new hostname:
sudo reboot
7. Once the node is back online, make sure the SmarterMail service is running again:
sudo service smartermail status
8. Add the nodes back to the cluster.
9. Update the DNS records for the nodes.
10. Re-enable failover on the nodes.
Step 3: Rename the Standbys
Standbys follow the exact same process as nodes. Repeat every step in Step 2: Rename the Nodes for each standby.
Wrap Up
1. Power on the load balancer. If its configuration references any VMs by hostname, update those entries.
2. Send a few test messages and confirm that mail is flowing normally through the cluster.
3. Once you're confident everything is healthy, delete the snapshots you took at the start.