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
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.
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
4 . Stop Services
Stop all the Information Server services on each Engine and the Services Tier. Follow the steps found at:
Linux/Unix
Windows
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.
- 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.
- 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).
- 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:
- Open the WebSphere Application Server administrative console.
- Go to Resources > JDBC > Data sources.
- Select ASB JDBC DataSource in the data source list.
- In the Additional Properties section, select Custom properties.
- Click New.
- Enter encryptionMethod in the Name field and enter SSL in the Value field.
- Click OK and then Save to save the configurations.
- Click New again.
- Enter cryptoProtocolVersion in the Name field and enter TLSv1.2 in the Value field.
- 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.
- 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.
- {IS install path}/jdk/jre/lib/security/cacerts
- {IS install path}/jdk32/jre\lib/security/cacerts
- {IS install path}/_uninstall/_jvm/lib/security/cacerts
- {IS install path}/Updates/_jvm/lib/security/cacerts
- {IS install path}/jdk/jre/lib/security/cacerts
{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:
- Make a backup copy of the current file {IS install path}/ASBServer/conf/database.properties.
- Edit the database.properties file and make the following changes:
- Append EncryptionMethod=SSL;CryptoProtocolVersion=TLSv1.2; to the end of the url property after the database name.
- Append EncryptionMethod=SSL;CryptoProtocolVersion=TLSv1.2; to the end of the url property after the database name.
- Perform the same steps on file {IS install path}/ASBServer/apps/lib/iis/classes/database.properties.
- 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:
- Make a backup copy of the current file {IS install path}/ASBServer/conf/imam_staging_repository.properties.
- Edit the imam_staging_repository.properties file and make the following changes:
- 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.
- Determine the directory locations of the Java instances. The following Java trust store locations need to be updated, if they exist in your installation:
- {IS install path}/jdk/jre/lib/security/cacerts
- {IS install path}/jdk32/jre/lib/security/cacerts
- {IS install path}/_uninstall/_jvm/lib/security/cacerts
- {IS install path}/Updates/_jvm/lib/security/cacerts
- {IS install path}/jdk/jre/lib/security/cacerts
- 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:
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:
Windows systems:
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
Was this topic helpful?
Document Information
Modified date:
01 May 2020
UID
ibm15694141