IBM Support

IBM Planning Analytics Custom SSL - Quick Start and Troubleshooting

Troubleshooting


Problem

The purpose of this document is to compliment the existing product documentation and provide extra guidance to those implementing custom SSL with IBM Planning Analytics Local.  

Resolving The Problem

BEFORE PROCEEDING WITH A CUSTOM SSL CONFIGURATION, BE AWARE THAT
  1. You are responsible for ensuring that encryption methods or ciphers meet your organization standards
    • This guide is to be used as reference/example only
  2. Implementing custom certificates requires either:
    • Using an existing keystore, provided to you by your certificate authority in PFX/PKCS12 format
    • Creating sign requests in Planning Analytics, to be signed and returned to you by your certificate authority
      *This is not yet covered by this guide
  3. IBM Planning Analytics Workspace requires a certificate in the following format:
    See: https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=servers-configure-tls-planning-analytics-workspace-local
    image-20220413124720-1
  4. Once secured using custom certificates, any application or service that communications with PA requires the new certificates to be included in their own keystore or trust store
    • Example: Cognos Command Center, Cognos Analytics
RECOMMENDATIONS
  1. Plan your configuration.  Which components do you plan to secure with custom certificates?
    • TM1 Admin Server and TM1 Server
    • TM1 Application Server (PMPSVC)
    • Planning Analytics Administration Agent
    • Planning Analytics Spreadsheet Service (TM1Web)
    • Planning Analytics Workspace
  2. Make sure you understand how you are going to update the PA client tools with the new keystore (Architect, Perspectives, Performance Modeler)
    • Files need to be manually copied to the ssl directories of the client installation folders
  3. Work with your certificate team and request a PFX/PKCS12 certificate for your server/hostname
    • Once a PFX/PKCS12 certificate file and password is available, you can convert to the formats required as needed
  4. Avoid using a custom keystore name.  Using ibmtm1.* allows for a simplified configuration.
    • Updating certificate filenames and labels to match the steps in the document helps to simplify further.
  5. Assuming that all services use the same certificate authority, configure all intended services at once
  6. Make note of any external certificates that are also required (for example, Cognos Dispatcher)
  7. Final configuration and certificate files should be stored in a separate path outside of the PA installation directories
    • This helps preserve custom certificates during product updates
DEFAULT CERTIFICATE FILE LOCATIONS
  • TM1 Admin Server and TM1 Server: PA_INSTALL_DIR\bin64\ssl\
  • TM1 Application Server (PMPSVC): PA_INSTALL_DIR\webapps\pmpsvc\WEB-INF\bin64\ssl\
  • Planning Analytics Administration Agent: PA_INSTALL_DIR\paa_agent\bin64\ssl\
  • Planning Analytics Spreadsheet Service (TM1Web): PASS_INSTALL_DIR\bin64\ssl\
  • Planning Analytics Workspace:
    • PAW_INSTALL_DIR\config\certs\
    • PAW_INSTALL_DIR\config\ (or PAW_INSTALL_DIR\config\ssl on Windows)

PRODUCT DOCUMENTATION
This technote provides only a high-level example of a custom SSL implementation.  It is important to review the product documentation before proceeding.

COMPONENT GUIDES
  1. How to Configure Planning Analytics Data Tier with Custom SSL (using Existing Keystore)
  2. How to Configure IBM Planning Analytics Administration Agent with Custom SSL (using Existing Keystore)
  3. How to Configure IBM Planning Analytics Application Web (TM1 Contributor/PMPSVC) with Custom SSL (using Existing Keystore)
  4. How to Configure IBM Planning Analytics Spreadsheet Service with Custom SSL (using Existing Keystore)
  5. How to Configure IBM Planning Analytics Workspace with Custom SSL (using Existing Keystore)
  6. How to Configure IBM Planning Analytics Performance Modeler with Custom SSL (using Existing Keystore)

GENERIC TROUBLESHOOTING
  • The most common problem with custom SSL configuration is not updating the correct keystore with the required certificates
    • Every keystore must trust the certificates used to secure any server it communicates with (think of it like a locked door, and you need a key)
  • Use list or detail commands to review your keystore contents
    • List Example: ​​​​​gsk8capicmd_64 -cert -list -db "PA_INSTALL_DIR\bin64\ssl\ibmtm1.kdb" -stashed
    • Detail Example: ​​​​​gsk8capicmd_64 -cert ​​​​​-details -db "PA_INSTALL_DIR\bin64\ssl\ibmtm1.kdb" -stashed -label "ibmtm1_server"
APPLICATION TROUBLESHOOTING
  1. TM1 Admin Server and TM1 Server:
    • Confirm TM1 Admin Server works as expected first.  If not, enable DEBUG logging on the TM1 Admin Server
    • Add log4j.logger.TM1.Comm.SSL=DEBUG to the PA_INSTALL_DIR\bin64\tm1admsrv-log.properties file
    • Review the tm1admsrv.log files in the PA_INSTALL_DIR\bin64\ directory
    • If TM1 Admin Server is working correctly, add log4j.logger.TM1.Comm.SSL=DEBUG to the tm1s-log.properties file (in your data directory)
    • Review the tm1server.log file
    • Some certificates require different NIST or FIPS settings for the TM1 Admin Host and TM1 Server.  TM1 Admin Server is configured by using Cognos Configuration, TM1 Server is configured used tm1s.cfg file.  See:
  2. TM1 Application Server (PMPSVC):
    • If you are able to open the page however cannot log in or see any TM1 Servers, you are missing the certificates required to communicate with TM1
      • Ensure PA_INSTALL_DIR\webapps\pmpsvc\WEB-INF\bin64\ssl\ has been updated correctly
    • If unable to access the web page, this indicates a problem with the application server or CAMKeystore
      • Review the PA_INSTALL_DIR\logs\tm1_messages.log file for details
  3. Planning Analytics Administration Agent:
    • If unable to access the web page, this indicates a problem with the keystore specified in the server.xml file
      • Review the PA_INSTALL_DIR\paa_agent\wlp\usr\servers\kate-agent\logs file for details
  4. Planning Analytics Spreadsheet Service (TM1Web):
    • If you are able to open the page however cannot log in or see any TM1 Servers, you are missing the certificates required to communicate with TM1
      • Ensure PASS_INSTALL_DIR\bin64\ssl\ has been updated correctly
    • If unable to access the web page, this indicates a problem with the application server or the keystore specified in the server.xml file
      • Review the PASS_INSTALL_DIR\wlp\usr\servers\tm1web\logs\messages.log file for details
  5. Planning Analytics Workspace:
    • If you are unable to access the Planning Analytics Workspace web page, there is likely a problem with the pa-workspace.pem file
      • Review the permissions of the PAW_INSTALL_DIR\config\pa-workspace.pem file
      • Ensure proper certificate order in the PAW_INSTALL_DIR\config\pa-workspace.pem file
      • Review the PAW_INSTALL_DIR\log\pa-gateway\error.log file for details
    • If you can connect to Workspace however cannot log in or access certain content (TM1 Server content, TM1 Web content), there is likely a required certificate missing in the PAW_INSTALL_DIR\config\certs\ folder.

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB10","label":"Data and AI"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSD29G","label":"IBM Planning Analytics"},"ARM Category":[{"code":"a8m50000000KzK7AAK","label":"Planning Analytics-\u003ESecurity-\u003ESSL"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
04 May 2022

UID

ibm16571941

Page Feedback