Renaming the Syracuse Server

This document explains how to rename the Syracuse server (including the load balancer). When doing so, you also need to change a few parameters in the configuration because some of them depend on the current host name.

Note: If the cluster consists in more than one host, we recommend that you stop the cluster before performing the following steps.

Prerequisites

1. Make sure Use local database settings is selected for the "Syracuse Administration" endpoint.
   This option will load the MongoDB settings from nodelocal.js instead of the database itself. No further modification will be required if the database server is renamed.
2. Stop the load balancer service at the operating system level, and execute delete_host.cmd or delete_host.sh in the Syracuse directory of the installation.
   It deletes the instance of the host entity.
3. In the certificate directory, locate the subdirectory named after the old host.
   Rename it with the new host name (in lowercase letters).

Renaming the server

1. Rename the server at the operating system level.
2. Adjust the server names in nodelocal.js, if necessary.
3. Run init_host.cmd or init_host.sh in the Syracuse directory of the installation.
   It creates the new host entity instance.
4. Start the load balancer service to start the server.
5. Invoke the certificate generation tool, and generate a certificate for the new server name.
   Transfer it to the port the server is listening to. You can find this port in init_host.cmd.
6. Log in, and fill in the information requested for the new instance of the host entity.
   Caution: Do not try to log in via SAML2/Oauth2 at this point.
7. If you use SAML2 authentication, the SAML2 identity provider needs the new host name to connect to the server. You can either:
   • Update the configuration of the SAML2 identity provider.
   • Generate a new SAML2 metadata file and load it on the SAML2 identity provider.
   Note: Make sure you also update the OAuth2 server configurations if they still contain the old host name.
8. Set the passphrases for the certificates again.
   This step does not apply to the certificate you just transferred.
   Caution: All server certificates for SSL connections should be renewed once the server name has changed.
9. If the X3 server (or any other server) contains a public key named after the old server, copy the .pem file that was just generated to that server.
10. Delete the old server certificate from MongoDB by running the following command in the MongoDB prompt: in lower case letters):

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

    Where OLDNAME must be replaced with the old server name (in lowercase letters).
    You will get the following response:

    WriteResult({ "nRemoved" : 1 })

Special case: Using a different X3 solution

If you use a different X3 solution, the "application servers" entity needs to be modified as well. Base your code on the following sample to match your X3 servers settings (old and new), and copy the javascript code into a file with .js extension.

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

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

 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
});