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 path
   logsDir: ..\..\..\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 operations
  mongodb:
    # This `path` property is mandatory and indicates where mongodb client software is installed
    path: C:\mongodb-win32-x86_64-2008plus-2.6.0
    # This `out` property indicates where the dumps will be stored
    out: C:\dumps
    # The `dump` section accepts all mongodump standard parameters
    # See https://docs.mongodb.com/manual/reference/program/mongodump/
    source:
      host: my-source-server
      port: 27017
      db: syracuse
    # The `restore` section accepts all mongorestore standard parameters
    # See https://docs.mongodb.com/manual/reference/program/mongorestore/
    destination:
      host: my-destination-server
      port: 27017
      db: 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: true
      sslCAFile: D:\keystore\ca.cacrt
      sslPEMKeyFile: D:\keystore\client.pem
      sslPEMKeyPassword: 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 solution
  x3solutions:
    # `-` character allows to declare multiple solutions
    - solutionToModify: SRC_X3SOLUTION # The solution `code` configured on source server you want to modify on destination server
      newSolution:
        code: NEW_CODE_FOR_SOLUTION
        description: SRC_X3SOLUTION modified with the migration tool
        solutionName: DEST_SOLUTION
        serverHost: my-destination-x3-server
        serverPort: 17000
        serverTimeout: 60000
        webServer: '' # let empty if same as serverHost
        webServerPort: 80
        proxy: false
        runtimes:
          # `-` character allows to declare multiple runtimes
          # only serverHost and serverPort are mandatory !
          - serverHost: my-destination-x3-server.mydomain.com
            serverPort: 17000
            tag: MAIN
            exclusive: false
            banTimeout: 60
            banned: false
            disabled: false
          - serverHost: my-destination-x3-server-2.mydomain.com
            serverPort: 17001
            disabled: 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 endpoints
  endpoints:
    # `-` character allows to declare multiple endpoints
    - endpointToModify: SEED # The endpoint `dataset` (name) configured on source server you want to modify on destination server
      newEndpoint:
        dataset: SEEDTEST
        x3ServerFolder: MYSEED
        description: 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 information
      hostname: my-destination-server # This is the destination server hostname
      children: 2 # Number of children processes
      wsChildren: 1 # Number of children processes dedicated for SOAP web services