Using the Syracuse server migration tool

The Syracuse server migration tool allows you to duplicate a Syracuse environment from a server to another, and to modify it on the fly. It can be executed from anywhere on the network (on the source environment, the destination environment, or on a third party machine).

Two things happen when the tool is run:

• The source server database is duplicated using the mongodump and mongorestore commands.
• Several entries are modified in the destination MongoDB database (X3 solutions configuration, endpoints, hosts entries, and deletion of certificates).

Note: This tools never modifies the source server database. It can be used safely to duplicate a stable environment to a target server.

Prerequisites

• Stop the destination Syracuse server before running this tool.
• Use the standard certificate generation tool provided with Syracuse to generate the certificates. This can be done before or after using this tool on the destination server.
• Re-enter the passphrase of the host certificate on the destination environment after running this tool. This can be done using the shell script provided with Syracuse.

Running the tool

To run the tool:

1. (On Linux Systems) Run the following command inside the bin directory of the Syracuse folder:

   linux_x64/node node_modules/tools/syracuse-migration

2. (On Windows Systems) Run the following command inside the bin directory of the Syracuse folder:

   win32_x64\node.exe node_modules\tools\syracuse-migration

3. Modify the configuration file with the following command:

    node node_modules/tools/syracuse-migration [param]param can be:`--config` to specify yaml configuration file path

Configuration file

A configuration file template (config-template.yml) is delivered in node_modules/tools/syracuse-migration.

The file format is YAML. Refer to the official YAML specifications for more information.

Logs definition section

This section contains only one entry that allows you to define where the output of the mongodump and mongorestore commands is stored.

 # logsDir defines where dump and restore logs files will be stored. It can be relative or absolute pathlogsDir: ..\..\..\logs

MongoDB section

This section is mostly used for the mongodump and mongorestore commands. The final connection used to modify entries is also based on the destination server parameters.

• All parameters that can be used with the mongodump command can be set in the source sub-section.
• All parameters that can be used with the mongorestore command can be set in the destination sub-section.

Example: It is possible to define SSL parameters for the destination server but not for the source server:

 # mongodb section defines parameters use for dump and restore operationsmongodb:# This `path` property is mandatory and indicates where mongodb client software is installedpath: C:\mongodb-win32-x86_64-2008plus-2.6.0# This `out` property indicates where the dumps will be storedout: C:\dumps# The `dump` section accepts all mongodump standard parameters# See https://docs.mongodb.com/manual/reference/program/mongodump/source:host: my-source-serverport: 27017db: syracuse# The `restore` section accepts all mongorestore standard parameters# See https://docs.mongodb.com/manual/reference/program/mongorestore/destination:host: my-destination-serverport: 27017db: syracuse# the following ssl properties are mandatory only if your mongodb server is secured with ssl (same thing can be applied to source server)ssl: truesslCAFile: D:\keystore\ca.cacrtsslPEMKeyFile: D:\keystore\client.pemsslPEMKeyPassword: MyPassphrase#sslAllowInvalidCertificates: true

X3 solution section

• This section can be omitted if the destination environment is identical to the source server in terms of X3 solutions and runtimes.
• If any adjustment is necessary, you can redefine the X3 solutions configurations that are set on the source environment, entirely or partially.
• If a new solution is defined, you have to redefine all X3 runtimes explicitly for this solution.

Caution: The "-" symbol is used to define arrays of entries. Be careful when using it.

 # x3solutions section defines the new X3 configuration solutionx3solutions:# `-` character allows to declare multiple solutions- solutionToModify: SRC_X3SOLUTION # The solution `code` configured on source server you want to modify on destination servernewSolution:code: NEW_CODE_FOR_SOLUTIONdescription: SRC_X3SOLUTION modified with the migration toolsolutionName: DEST_SOLUTIONserverHost: my-destination-x3-serverserverPort: 17000serverTimeout: 60000webServer: '' # let empty if same as serverHostwebServerPort: 80proxy: falseruntimes:# `-` character allows to declare multiple runtimes# only serverHost and serverPort are mandatory !- serverHost: my-destination-x3-server.mydomain.comserverPort: 17000tag: MAINexclusive: falsebanTimeout: 60banned: falsedisabled: false- serverHost: my-destination-x3-server-2.mydomain.comserverPort: 17001disabled: true

Endpoints section

Similarly to X3 solutions, it is possible to redefine endpoints configuration, for example if you want to change the name of the target X3 folder. Only the dataset, x3ServerFolder, and description properties can be modified.

 # endpoints section defines the new endpointsendpoints:# `-` character allows to declare multiple endpoints- endpointToModify: SEED # The endpoint `dataset` (name) configured on source server you want to modify on destination servernewEndpoint:dataset: SEEDTESTx3ServerFolder: MYSEEDdescription: SEED modified with the migration tool

Hosts section

This section defines the new destination server hostname used by the Syracuse application. It is essential to get the correct behavior.

 # hosts section defines new host instances configuration changes. It will be also used to rename certificates.# 'hostnameToModify' and 'hostname' are mandatory !# WARNING about certificate: the new certificates on destination server have to be generated using the standard certificate tool.hosts:- hostnameToModify: my-source-server # The source server hostname will be used to find and replace host informationhostname: my-destination-server # This is the destination server hostnamechildren: 2 # Number of children processeswsChildren: 1 # Number of children processes dedicated for SOAP web services