Migrate Gateways to Centralised Configuration

The ccmigrate tool will check your Gateway configuration against a list of requirements you can specify with a JSON profile file. A minimal defaults.json is provided. When you run ccmigrate, the tool will guide you through providing any information that is not currently listed in your JSON profile file and will update the file accordingly.

You can also use the tool to migrate your Gateways to centralised configuration by specifying the --migrate option.

The script has the following command-line options:

Multi-Gateway environments

In large environments with multiple Gateways, you must perform a phased migration. On each Gateway host you should validate and then migrate your configuration.

When migrating a Gateway, all its include files are added to Gateway Hub as resources. Each Gateway Hub resource must have a unique name, and you will be prompted to provide a resource name for each Gateway file uploaded.

If a resource with a matching name already exists in your Gateway Hub, then the ccmigrate tool will report if the local copy matches an old version of the Gateway Hub resource or if the local copy is entirely distinct. You may see the following messages in the log file:

• Resource '{res_name}' is in Hub but it has been edited. Please update the version on disk to match the one in Hub

• Resource '{res_name}' in Hub does not match the one used by the gateway. Please update the version on disk to match the one in Hub or update the version in Hub to match the one on disk

In both cases, you must update either the local or the Gateway Hub copy of the resource so that they match exactly.

To update Gateway Hub resources use the Gateway configuration page from your Web Console.

Updating an existing local resource using the Gateway Setup Editor will cause a failure.

To update a local resource, you must:

1. Remove the existing resource.

2. Open your output directory.

3. The ccmigrate tool downloads a copy of each Gateway Hub resource to your output folder when performing a validation. Add the matching resource from the output folder to your Gateway.

{
  "gateways": {
    "Gateway1": {
      "binaries": "/opt/itrs/gateway",
      "local_includes": {
        "local-samplers.xml": "Samplers"
      },
      "aes_file_name": "/opt/itrs/gateway/gateway1/private.aes",
      "setup_file": "/opt/itrs/gateway/gateway1/gateway.setup.xml",
      "working_dir": "/opt/itrs/gateway/gateway1",
      "use_aes_file": "Yes",
      "use_krb5_file": "No"
    },
    "Gateway2": {
      "binaries": "/opt/itrs/gateway",
      "local_includes": {
        "local-samplers.xml": "Samplers",
        "local-Rules.xml": "Rules"
      },
      "aes_file_name": "/opt/itrs/gateway/gateway2/private.aes",
      "setup_file": "/opt/itrs/gateway/gateway2/gateway.setup.xml",
      "working_dir": "/opt/itrs/gateway/gateway2",
      "use_aes_file": "Yes",
      "use_krb5_file": "No"
    }
  },
  "general": {
    "max_validation_accepted": "Warn"
  },
  "hub": {
    "api_port": "8081",
    "auth_method": "BASIC",
    "hostname": "hub.example-bank.com"
  },
  "shared_includes": {
    "http://includes.example-bank.com/hub.xml": "Global/Hub/Location",
    "http://includes.example-bank.com/hub-mappings.xml": "Global/Hub/Mappings",
    "http://includes.example-bank.com/users.xml": "Global/Auth"
  }
}

Validate a Gateway configuration

Validating a Gateway will check the specified Gateway against a list of requirements, including but not limited to:

• Connectivity to Gateway Hub.

• Minimum required versions of Gateway and Gateway Hub.

• Duplicate configurations stored in your Gateway Hub.

• Gateway setup validation.

You will be prompted for user input to provide any additional requirements and to specify how include files should be tagged. The tool will modify the JSON requirements file based on your response. This means that you will not be asked to repeat information when re-running the tool.

For more information about centralised configuration prerequisites, see Centralised Gateways user guide.

To validate a Gateway configuration:

1. Download the ccmigrate package from ITRS Downloads .
2. Copy the downloaded package to the target Gateway host and extract the tool by running:

    tar -xvzf ccmigrate.tar.gz

3. Stop the Gateway.

4. Run the following:

   ./ccmigrate --name <gateway_name> --profile <profile_file.json>

If the validation is successful, then the ccmigrate tool will print the output of your tests and also record a log of all checks to an ./output directory using the ccmigrate-<timestamp> format.

If the test fails, then the ccmigrate tool will print a FAILURE status and indicate the steps to resolve it in the log.

Migrate a Gateway configuration

When migrating a Gateway to centralised configuration, the ccmigrate tool will read your JSON requirements file and perform all validation checks before performing the migration.

No changes are made to the Gateway working directory or resource directories and the migration will create a backup of your configuration before moving it into Gateway Hub.

To migrate your data:

1. Stop the Gateway.

2. Migrate the Gateway configuration:

   ./ccmigrate --name <gateway_name> --profile <profile_file.json> --migrate

3. Restart the Gateway using centralised configuration:

   ./gateway2.linux_64 -gateway-name <gateway_name> -gateway-hub <https://hub.example.com:8080>

   1. To connect to a secure Gateway Hub using Kerberos, use the following command line options:

      -kerberos-principal <user@LDN.ITRS> -kerberos-keytab <user.keytab>

   2. To connect to a secure Gateway Hub using an application key, use the following command line options:

      -app-key <user.app-key-file>

If the migration is successful, then the ccmigrate tool will print the output of your tests and a summary of the steps required to restart your Gateway using centralised configuration.

Gateway not configured with auto reload

Ensure each include file has auto-reload enabled so that Gateways run the latest configuration from Gateway Hub.

Gateway binary has not been uploaded

Upload the required Gateway binary file to Gateway Hub. This can be done from the Gateway configuration page in the Web Console or using the Gateway Hub API.

Unsupported users

Centralised configuration requires using the Gateway Hub SSO agent for authentication. Locally defined Gateway users are not supported once authentication is enabled via Gateway Hub SSO. For more information, see Gateway Hub SSO Agent.

Gateway validation inconsistencies

The ccmigrate tool performs a Gateway schema validation when run using the latest Gateway binary stored in Gateway Hub. This may result in a different output than running a schema validation using the Gateway Setup Editor because the Gateway Setup Editor will also check connected Netprobes for newer schemas.

Mixed Gateway deployments

In deployments where some Gateways use centralised configuration and others do not, it is possible that shared include files may not be synchronised correctly. If a shared include file is available from Gateway Hub then centrally configured Gateways will use that, however, other Gateways will continue to use the version of the include file on disk. These versions may diverge and cause problems.

To avoid this you can lock the copy of the include file outside of Gateway Hub and restrict changes to only the centrally stored file. The file used by Gateways without centralised configuration can then be automatically synchronised with the centralised copy using your preferred tools outside of Gateway.

Gateway setup includes a rest address

If a Gateway setup includes the Publishing > Gateway Hub > Rest addresses field, then the migration process fails. Remove this field to proceed.

Performing migration on a running Gateway

It is possible to run a migration operation on a running Gateway. However, this is not recommended and you should always stop your target Gateway when performing a migration.