IBM Support

Instructions for Enabling TLS Communications to MS SQLServer 2016 Databases in Information Server v11.7.1

How To


Summary

This document covers the steps required to enable TLS communications on connections to MS SQL Server XMETA, DSODB, QSSRDDB and IADB databases used by Information Server. It does not cover the database connections that are defined when using products like DataStage, IMAM, etc.

Steps

  1. Introduction and Conventions
  2. Supported Platforms
  3. Before you Begin
  4. Stop Services
  5. Configure TLS Support in MS SQL SERVER
  6. Configure WebSphere JDBC Data Sources
    1. Import the MS SQL SERVER Certificate into the Java Trust Store
    2. Configure the WebSphere JDBC Data Sources to Use SSL
  7. Configure the Information Server Services Tier
    1. Import the MS SQL SERVER Certificate into the Java Trust Store
    2. Update the database.properties Files
    3. Update the imam_staging_repository.properties File
    4. Update com.ibm.iis.xmeta.repo.conn.POJO_STAGING property
  8. Configure DSODB
    1. Configure MS SQL SERVER to Support SSL Connections
    2. Configure the Information Server Engine Tier
  9. Configure QSSRDDB
  10. Re-start the Services 

1. Introduction and Conventions

The procedure documented here supports enablement of MS SQLServer 2016 to support TLS connections and the changes that need to be made in Information Server to support TLS connections to XMETA, DSODB, QSSRDDB and IADB  databases.

In this document,

  • IS install path refers to the location where IBM Information Server is installed on your machine. By default, /opt/IBM/InformationServer on UNIX or C:\IBM\InformationServer on Windows.
  • Services tier refers to the machine where the IBM Information Server services tier is installed.
  • Engine tier refers to the machine(s) where the IBM Information Server engine tier is installed.

The command examples in this document are for Unix environments and will be adjusted appropriately to run in a Windows environment.

2. Supported Platforms

For details on supported Operating systems and Database Servers see the below link.

https://www.ibm.com/support/pages/infosphere-information-server-v117-detailed-system-requirements

3. Before you Begin

Before you begin this process, you should back up your complete Information Server installation. Instructions for backup and restore can be found at

https://www.ibm.com/support/knowledgecenter/SSZJPZ_11.7.0/com.ibm.swg.im.iis.found.admin.burest.doc/topics/t_admin_backup_restore_super.html

4 . Stop Services

Stop all the Information Server services on each Engine and the Services Tier. Follow the steps found at:

Linux/Unix

https://www.ibm.com/support/knowledgecenter/SSZJPZ_11.7.0/com.ibm.swg.im.iis.found.admin.common.doc/topics/t_wsadmin_shutting_down_services_linux_unix.html

Windows

https://www.ibm.com/support/knowledgecenter/SSZJPZ_11.7.0/com.ibm.swg.im.iis.found.admin.common.doc/topics/t_wsadmin_shutting_down_services_windows.html

5. Configure TLS Support in MS SQL SERVER

Enable SSL/TLSv1.2 on MS SQL Server with the help of your DBA. This procedure is outside the scope of this document. Information Server needs the SSL certificate file from this step to be used in next steps.

6. Configure WebSphere JDBC Data Sources

6.1    Import the MS SQL SERVER Certificate into the Java Trust Store

This step is for importing the MS SQL Server certificate into the trust store of the Java that is used to run the WebSphere Application Server.  If a WebSphere cluster is being used, then the following steps will need to be repeated for each server in the cluster.

  1. Determine the directory location of the Java that is being used to run the server.  The location can be found in the Java SDKs section of the server configuration in the WebSphere administration console.  It can also be found in the header of the WebSphere SystemOut.log file.
  2. The Java trust store is located at {Java location}/ jre/lib/security/cacerts (e.g. /opt/IBM/WebSphere/AppServer/java/8.0/jre/lib/security/cacerts).
  3. Run the following command to import the SQL Server certificate that was generated in the previous section into the Java trust store:

    {Java location}/jre/bin/keytool -import -file {certificate file} -alias SQLCert -keystore {Java location}/ jre/lib/security/cacerts -storepass changeit

6.2   Configure the WebSphere JDBC Data Sources to Use SSL

Configure the WebSphere JDBC data sources to use SSL:

  1. Open the WebSphere Application Server administrative console.
  2. Go to Resources > JDBC > Data sources.
  3. Select ASB JDBC DataSource in the data source list.
  4. In the Additional Properties section, select Custom properties.
  5. Click New.
  6. Enter encryptionMethod in the Name field and enter SSL in the Value field.
  7. Click OK and then Save to save the configurations.
  8. Click New again.
  9. Enter cryptoProtocolVersion in the Name field and enter TLSv1.2 in the Value field.
  10. Click OK and then Save to save the configurations.

Perform the same configuration for the ASB JDBC Staging XA DataSource, ASB JDBC XA DataSource, IADB DataSource and any other data source that connects to the DB2 instance.

Note: If you can not login to WAS Admin console after SSL/TLSv1.2 is enabled on SQL Server, turn the encryption off temporarily at SQL Server side to allow the WAS Admin console log in.

7. Configure the Information Server Services Tier

7.1 Import the MS SQL SERVER Certificate into the Java Trust Store

This step is for importing the MS SQL Server certificate into the trust stores of the Java instances that are used when running Information Server tools and installation upgrades.

  1. Determine the directory locations of the Java instances.  The following Java trust store locations need to be updated, if they exist in your installation. Search for cacerts under IS install path to get all the cacerts locations.
    1. {IS install path}/jdk/jre/lib/security/cacerts
    2. {IS install path}/jdk32/jre\lib/security/cacerts
    3. {IS install path}/_uninstall/_jvm/lib/security/cacerts
    4. {IS install path}/Updates/_jvm/lib/security/cacerts
2. Run the following command for each Java trust store instance to import the SQL Server certificate that was generated in the section 5:

{IS install path}/jdk/jre/bin/keytool -import -file {certificate file} -alias SQLCert -keystore {Java trust store} -storepass changeit

7.2   Update the database.properties Files

Update the database.properties files:

  1. Make a backup copy of the current file {IS install path}/ASBServer/conf/database.properties.
  2. Edit the database.properties file and make the following changes:
    1. Append EncryptionMethod=SSL;CryptoProtocolVersion=TLSv1.2; to the end of the url property after the database name.
  3. Perform the same steps on file {IS install path}/ASBServer/apps/lib/iis/classes/database.properties.
  4. Run the following command to propagate the changes to WebSphere:

    {IS install path}/ASBServer/bin/AppServerAdmin.sh -db -user {xmeta user Id} -password {xmeta user password}

7.3    Update the imam_staging_repository.properties File

Update the imam_staging_repository.properties file:

  1. Make a backup copy of the current file {IS install path}/ASBServer/conf/imam_staging_repository.properties.
  2. Edit the imam_staging_repository.properties file and make the following changes:
    1. Append EncryptionMethod=SSL;CryptoProtocolVersion=TLSv1.2; to the end of the url property after the database name

7.4   Update com.ibm.iis.xmeta.repo.conn.POJO_STAGING property

Run the following command on the services tier to update com.ibm.iis.xmeta.repo.conn.POJO_STAGING property:

{IS install path}/ASBServer/bin/xmetaAdmin.sh setProperty -file {IS install path}/ASBServer/conf/imam_staging_repository.properties -dbfile {IS install path}/ASBServer/conf/database.properties com.ibm.iis.xmeta.repo.conn.POJO_STAGING

8     Configure DSODB

These steps are for configuring TLS support for the DSODB MS SQL SERVER database connections.

8.1    Configure MS SQL SERVER to Support SSL Connections

If the DSODB database is co-located with the repository database, then the MS SQL SERVER instance was already configured to support SSL connections in the previous steps.

If the DSODB data is not co-located with the repository database, then perform the same steps on the DSODB database instance that were performed on the XMeta repository database instance.

8.2    Configure the Information Server Engine Tier

Import the MS SQL SERVER Certificate into the Java Trust Store

This step can be skipped if the engine tier is co-located with the services tier.

This step is for importing the MS SQL Server certificate into the trust stores of the Java instances that are used when running Information Server tools and installation upgrades.

  1. Determine the directory locations of the Java instances.  The following Java trust store locations need to be updated, if they exist in your installation:
    1. {IS install path}/jdk/jre/lib/security/cacerts
    2. {IS install path}/jdk32/jre/lib/security/cacerts
    3. {IS install path}/_uninstall/_jvm/lib/security/cacerts
    4. {IS install path}/Updates/_jvm/lib/security/cacerts
  2. Run the following command for each Java trust store instance to import the SQL Server certificate that was generated in the section 5:

    {IS install path}/jdk/jre/bin/keytool -import -file {certificate file} -alias SQLCert -keystore {Java trust store} -storepass changeit

Update the Registered Database Server

Run the following command on the services tier to list the registered databases:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -listDatabases

For each database in the list that has been configured to use SSL connections, do the following steps.

Run the following command to display the registered database properties, where {database name} is the name of the database that was returned from the -listDatabases command:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -displayDatabase -dbName {database name}

Make sure that the database details are correct. If they need any update, do it by following below.

If the database server port needs to be updated to the security port, then run the following command to update the port, where {database version} and {database server host} are found in the output of the -displayDatabase command and {database server security port} is the security port that was configured previously:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -updateDatabaseServer -databaseType SQLSERVER -databaseVersion {database version} -serverHost {database server host} -serverPort {database server security port}

Update the Registered DSODB Repository

Run the following command on the services tier to list the registered repositories:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -listRepositories

Locate the repository name of the registered DSODB repository (e.g. dsodb) in the command output.

Run the following command to display the registered DSODB repository properties, where {repository name} is the name of the registered DSODB repository that was returned from the -listRepositories command:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -displayRepository -reposName {repository name}

Update the connectionURL by appending EncryptionMethod=SSL;CryptoProtocolVersion=TLSv1.2; to the existing connectionURL. Run the following command to update the connectionURL:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -updateRepositoryConnection -reposName {repository name} -connectionURL "{url}"

Update the DSODBConnect.cfg File

Make a backup of the existing DSODBConnect.cfg file by running the following commands on the engine tier:

cd {IS install path}/Server/DSODB

copy DSODBConnect.cfg DSODBConnect.cfg.orig

Generate a new connection file by running the following command:

{IS install path}/ASBNode/bin/RegistrationCommand.sh -user {admin user} -password {password} -gcf -repository {dsodb repository name} -cf DSODBConnect.tmpl -results DSODBConnect.cfg

9     Configure QSSRDDB

These steps are for configuring TLS support for the QSSRDDB MS SQL SERVER database connections.

Update the Registered QSSRDDB Repository

Run the following command on the services tier to list the registered repositories:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -listRepositories

If the output lists a QSSRDDB repository, then continue with the next steps.

Run the following command to display the registered QSSRDDB repository properties:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -displayRepository -reposName QSSRDDB

Update the connectionURL by appending EncryptionMethod=SSL;CryptoProtocolVersion=TLSv1.2; to the existing connectionURL. Run the following command to update the connectionURL:

{IS install path}/ASBServer/bin/RepositoryAdmin.sh -updateRepositoryConnection -reposName QSSRDDB -connectionURL "{url}"

10      Re-start the Services

Next, the Information Server services need to be started again.  Follow the steps found at:

Unix systems:

https://www.ibm.com/support/knowledgecenter/SSZJPZ_11.7.0/com.ibm.swg.im.iis.found.admin.common.doc/topics/t_wsadmin_starting_services_linux_unix.html 

Windows systems:

https://www.ibm.com/support/knowledgecenter/SSZJPZ_11.7.0/com.ibm.swg.im.iis.found.admin.common.doc/topics/t_wsadmin_starting_services_windows.html

After restarting, it is highly recommended that you run the ISALite General Diagnostic Health Checker on all tiers and check the output for any errors.

Document Location

Worldwide

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSZJPZ","label":"IBM InfoSphere Information Server"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"11.7.1","Edition":"","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

Document Information

Modified date:
01 May 2020

UID

ibm15694141