Importing reports into a secure Maximo application server: where do I need to add my digital certificates?

Body

After upgrading a Maximo application, one of the last steps you will need to perform is importing your reports.  This is done using the importreports script file on windows or Unix.  If your application server hosting Maximo is secured using digital certificates, the importreports script may fail to perform the import of your reports, if the root certificates are missing from the keystore that the command will use to connect to the application server.

How do you determine where they go?

The importreports.cmd and importreports.sh script files contain the JAVA_HOME environment variable which points to the path of the instance of Java that will be used.  Any root certificates needed for validation of the Maximo applications server's personal certificate during the SSL handshake will be stored in, and accessed from the keystore location in this Java runtime location.

The importreports script files are found in the following location on Windows:

C:\IBM\SMP\maximo\reports\birt\tools

Typically, the JAVA_HOME environment variable will point to the JRE that is included within the Maximo installation, and will look similar to the following:

set JAVA_HOME=..\..\..\tools\java\jre

The JRE provided with Maximo is not necessarily the version you are required to use to run this command - you can choose to use a newer version installed in any location as long as you set the path to the JRE correctly in the importreports script file, within the JAVA_HOME environment variable.

The certificate store used by Java is called "cacerts" and is located under the Java run time environment in the following location within the Maximo installation folder:

C:\IBM\SMP\maximo\tools\java\jre\lib\security

If you choose to use a different version and location for the JRE, ensure you update the cacerts keystore file under the corresponding Java installation.

The default password associated with the Java cacerts keystore is "changeit" unless you had previously changed it to something else.

Typically, this keystore will already contain the most commonly used certificate authority root certificates, such as Verisign, Entrust, etc.  However, if this keystore does not contain the correct root certificate associated with your Maximo application server's personal certificate, the root certificate will need to be added and trust enabled in order to successfully verify the personal certificate and allow the connection to proceed.  You can typically use any tool that can add certificates to the cacerts keystore, which is in JKS format.  This includes ikeyman, GSKit, keytool, OpenSSL, and many others that are common.  Since Java includes the keytool command for managing digital certificates, I have included a sample of the keytool command you can use below.  This command assumes you have extracted a copy of the root certificate and placed it in a file called myrootcafile.cer, and is accessible to the keytool command:

C:\IBM\SMP\maximo\tools\java\jre\bin\keytool  -import -trustcacerts -alias "CA Root" -file myrootcafile.cer -keystore cacerts -storepass changeit

When prompted whether or not you should trust this certificate, select "Yes" to proceed.  The certificate will be stored successfully in the cacerts keystore.

For troubleshooting of SSL related issues, you can also edit the importreports script file and locate the ANT_OPT line as shown below:

set ANT_OPTS=%ANT_OPTS% -Xmx256m
 

then add the ssl debug option -Djavax.net.debug=ssl as shown in the following example:

set ANT_OPTS=%ANT_OPTS% -Xmx256m -Djavax.net.debug=ssl
 

When running the importreports script file, redirect the output to a log file to capture all of the debug information that will be written for later review:

importreports > birt.log

The birt.log will contain the output results after running the imporreports command, as well SSL related debug information which you can submit to IBM for further assistance if necessary.