How to rename a server

It might sometimes happen that you need to rename a server (when duplicating temporarily a server for instance). If you have to do this, you need to change some parameters in the configuration. This document explains how to do it.

There are some data which are dependent on the current hostname. When the host is renamed, the installation cannot just be used, but some changes must be done before and after renaming. This document describes the steps but only for the Syracuse server (including load balancer) and only what is already possible using the current versions of the code. Some steps may be simplified with future code enhancements.

If the cluster consists of more than 1 host, I strongly advise to stop the cluster before the following steps.

Preparations

Make sure to have "Use local database settings" option checked for "Syracuse Administration" endpoint. This option will load mongodb settings from nodelocal.js instead of the database itself. Therefore no further modification would be required in case of database server renaming.
Stop the load balancer service on operating system level. Then execute delete_host.cmd or delete_host.sh in the Syracuse directory of the installation. This will remove the instance of the Host entity.
rename the subdirectory of the certificate directory whose name is the old host to a directory whose name is the new host (in lowercase letters).

Renaming

Rename the server on operating system level

Work after renaming the server

Look into nodelocal.js and adjust server names where necessary.
Execute init_host.cmd or init_host.sh in the Syracuse directory of the installation. This will create the instance of the Host entity for the new name.
Start the server (i. e. start the load balancer service)
invoke the certificate generation tool. Generate a new certificate for the new server name (option 1) and finally transfer it to the port to which the server listens (and which is mentioned in init_host.cmd).
Log in (but not via SAML2/Oauth2 at this time) and fill in the remaining necessary information for the new instance of the host entity.
Update SAML2 information when there is SAML2 authentication: the SAML2 identity provider needs the new name to connect to the server. So either update the configuration of the SAML2 identity provider or generate a new SAML2 metadata file and load it on the SAML2 identity provider. Also look at OAuth2 servers whether their configurations still contain the old name: this has to be replaced with the new name.
Set the passphrases for the certificates again (except for the just transferred certificate)

Note that server certificates for all SSL connections should be renewed anyway, because the server name has changed (and the server name usually occurs in the server certificate).

When the X3 server or another server contains a public key which has the name of the old server, you have to copy the .pem file just generated to that server.

Finally delete the old server certificate from MongoDB using the following command within MongoDB prompt (here `OLDNAME` must be replaced with the old server name in lower case letters):

db.Certificate.remove({name: 'OLDNAME'});

The answer to this command should be something like

WriteResult({ "nRemoved" : 1 })

Particular case : Use a different X3 solution

The "Application servers" entity need to be modified.

The following sample should be modified to match your X3 servers (old and new) settings. Copy the javascript code into a file with .js extension.

Write a script that invokes : mongo.exe with the name of the file as parameter. Example on Windows :

"C:\mongodb\bin\mongo.exe" rename.js

CODECODE CODE javascript
db = connect("host:port/syracuse");
db.X3server.update({
    serverHost: "_my_old_hostname_",
    serverPort: _old_port_
}, {
    $set:{
        serverHost: "_new_host_name_",
        serverPort: _new_port_
    }
}, {
    multi: true
});

Index Home