Changing the IP address of a cluster node

Your network team renumbers a subnet, or a node moves to another network, and a node of your Syncplify Server! cluster gets a new IP address. From Syncplify Server! 8.12.0 the node stays in the cluster through that change. You do not remove it and you do not join it again: you change the address of the machine, run one command on it, and the other nodes switch to the new address.

WARNING

This page applies to Syncplify Server! 8.12.0 and newer, and needs every node of the cluster to run 8.12.0 or newer. On an older cluster, update the nodes first (one at a time, so the cluster stays up), or use the older procedure: remove the node from the cluster, change its address, and join it again.

The short version

1. Change the IP address of the machine, in the operating system.
2. On that node, from an elevated shell, run:

ss-webrest ha address set 192.168.122.198

Use the node's new address in place of 192.168.122.198. The command shows what it is about to change, asks you to confirm, and then tells you, node by node, that the others reach this node at its new address:

Node node-a now announces 192.168.122.198:6443 (it was 10.0.0.5:6443), as generation 1 of its address claims.
  node-b                       reached this node at the new address and uses it
  node-c                       reached this node at the new address and uses it
2 listener binding(s) moved. Workers restarted: default.

Done. Every peer reaches node node-a at 192.168.122.198:6443.

That is all. The node kept its identity, its license, its configuration and its place in the cluster. ss-webrest cluster address set is the same command under another name.

Why this works

A node is known to its cluster by its node ID and its identity key, never by its IP address. The address is only where the other nodes dial it. When you run the command, the node states its new address in a message signed with its identity key. Each of the other nodes checks the signature, connects to the new address, and starts using it only once the node answers there. Until then it keeps the old address.

Two things follow, and both are in your favor:

• A mistake costs nothing. If you mistype the address, or the firewall on the new network is not open yet, the other nodes simply keep the address they had and tell you why. Run the command again with the right address, or open the firewall: the nodes pick the new address up on their next heartbeat, within seconds, with nothing else to do.
• A node that was away catches up by itself. A node that was switched off during the change learns the new address from the others when it comes back, and can never hand the old address back to them.

What the command moves, and what it leaves alone

It moves the node's listeners. If the SFTP, FTP or HTTPS listeners of a virtual site on this node were bound to the old address, they are moved to the new one and the site's worker on this node is restarted so that it listens there. Listeners bound to every address of the machine need no change and get none.

It lists, and does not touch, settings that still name the old address. The typical ones are the address FTP clients are told to use for passive connections, IP allow lists, trusted proxies, and the safe list of the console Shield. The command prints each of them so that you can decide; whether such an entry meant "this node" or something else is yours to know.

Outside the server, anything that pointed at the old address has to follow: DNS records, load balancer pools, firewall rules for the cluster port (the port of the management console, 6443 unless you changed it), and the configuration of R2FS! agents that reach this node by address.

Your license is not affected. It is tied to the machine, not to its address.

To see everything the command would do without doing it, add --check:

ss-webrest ha address set 192.168.122.198 --check

Doing it with no interruption at all

Sessions connected to the old address end when the machine loses that address; that is the network, and no software can prevent it. If you need the change to be invisible:

1. Add the new address to the machine in addition to the old one.
2. Run ss-webrest ha address set NEW-ADDRESS. The other nodes switch to the new address while the old one still works.
3. Point clients at the new address (DNS record, load balancer pool).
4. Optionally drain the node from the Cluster page, so that sessions still on the old address finish.
5. Remove the old address from the machine.

When every node changes address at once

A node can only tell the others about its new address if it can still reach them. When the whole cluster is renumbered in one go, every node knows only the old, dead addresses of the others, so no node can tell anybody anything.

Write one small text file that lists the new address of every node, using the node IDs shown on the Cluster page (or by ss-webrest ha nodes):

# the cluster after the move to the 192.168.122.0/24 network
node-a=192.168.122.198
node-b=192.168.122.199
node-c=192.168.122.200

Copy the same file to every node and run, on each of them:

ss-webrest ha address apply --file cluster-addresses.txt

On each node, the command announces the address on that node's own line and uses the other lines to find the other nodes. Run it on every node, even when the first one already reports that all the others use its new address: the command is also what moves each node's own listeners, and what makes each node state its own address instead of leaving the others to work it out. For only two nodes, or when just some of them moved, the same can be said on the command line instead of in a file:

ss-webrest ha address set 192.168.122.198 --peer node-b=192.168.122.199

Reading the result

The command exits with 0 when every other node uses the new address. Anything else is explained on screen:

What you see	What it means	What to do
could NOT reach this node at the new address, keeps the old one and keeps trying	That node received the announcement and could not connect to the new address.	Check that the address is right and that the cluster port is open from that node to this one. Nothing has to be repeated once it is.
could not be told: this node cannot reach it	That node is down, or it moved too.	If it is down, it catches up when it returns. If it moved, tell this node where it is with --peer, or use the file.
answered and would NOT take the announcement, with a note about the console Shield	That node's console Shield has banned this node's new address.	On that node, lift the ban, or add the new address to the Shield safe list.
a cluster member runs a release that predates address claims	A node runs a version older than 8.12.0. Nothing was changed.	Update that node, then run the command again.
The service did not pick the order up	The management service of this node is not running.	Start it. The change is carried out as soon as the service runs.

ss-webrest ha address, with nothing after it, shows where the node stands at any time: the address it announces, the address it reaches every other node at, and how the last change went.

Using a host name instead of an address

If your DNS is as dependable as your network, you can give a node a name instead of an address:

ss-webrest ha address set node1.corp.example

The nodes then find each other through DNS, and the next time the IP address changes you update the DNS record and run nothing at all. Listeners are always bound to addresses, so with a host name you say which listeners move with --map OLD-ADDRESS=NEW-ADDRESS.

More

The full reference of the command is in the manual, under Command line reference, and the Cluster page of the manual explains how a change of address is handled. If a node still does not settle, contact our support with the output of ss-webrest ha address from every node.