Connect:Direct® Web Services Troubleshooting

Use the following table to help troubleshoot problems with Connect:Direct Web Services:
Note: With Fixpack 7 (6.1.0.7), ChangeDatabasePassword-0.1.jar and ./startWebserviceZLinux.sh have changed to ChangeDatabasePassword.jar and ./startWebservice.sh respectively.
Problem Possible Cause Solution
Connect:Direct Web Console fails to load Cookies disabled in your browser settings and/or browser's local storage is persistent. Enable browser cookie, local storage, clear the cache, and reload the page.
Upgrade fails

A previous attempt to uninstall Connect:Direct version was unsuccessful.

Cleanup the registry settings in the .com.zero.registry.xml:
  • Backup your installation data located in your <CDWSInstallDirecory>
  • This file is located in /var/ for Root users and $HOME/for non-root users
  • It is recommended to create a back up of Zero G registry file before you proceed.
  • Edit the Zero G registry file to remove entries that begin with MFTWebServices product name.
  • Delete any entries beginning with tag
    <product name="MFTWebServices">...</product>
  • Attempt to re-install or upgrade.
Connect:Direct Web Console fails to load Web Services is not accessible Ensure firewall rules have been added for inbound and outbound connections between Web Services and Connect Direct Server.

Firewall rules must allow inbound connections to the specified Web Services port. Connect Direct server must also have its API port open for web service.
Connect:Direct Web Services is not accessible A network or firewall restriction Ensure firewall rules are added on all the machines hosting Connect:Direct server(s).
Connect:Direct server stops with the following error message: CD server is in stop state.
  • Connect:Direct node in stop state or,
  • Number of API connection reached maximum or,
  • A firewall Restriction
Ensure that the Connect:Direct Server is running and verify:
  • The API address and port number used to establish client sessions with this Connect:Direct Server
  • The Maximum API connections limit has reached. Close an open API connection to continue using the IBM Connect:Direct Web Services
  • If a Firewall restriction is in place and that the machine hosting Connect:Direct Web Services to Connect:Direct server is attached to the network
Web Admin user account is locked.
  • Failed login attempts
  • Lapses in security policies preventing a Web Admin user from retaining the current password.
Execute the Password Reset utility, ResetDefaultCDWSAdminPassword. For more information see, Password Reset for a Web Administrator.
Certificate-based authentication fails This possibly occurred due to domain name and the Subject Alternative Name (SAN) or common name mismatch of the SSL certificate.
  • When using certificate generated at installation, verify if the common-name is configured with the correct hostname value.
  • When using an external certificate, verify if either one of the following two conditions is met:
    • the common-name is configured with the correct hostname value
    • the IP Address/Hostname should match Subject Alternative Names (SAN) as defined in SSL certificate
Reference to PostgreSQL database may remain in the Registry after Connect:Direct Web Services for Windows is successfully uninstalled.  
  • Start the Registry editor (regedit.exe)
  • Locate the current control set and delete the related values HKEY_LOCAL_MACHINE > Control Set > Services and delete >PostGreSQL -MFTWebServices
  • Quit the Registry editor
  • Restart your system
All services were up and running but unable to access Connect:Direct Web Console. This possibly occurred due to firewall settings. The settings are blocking connection attempts to Web services application. Contact your system administrator.
Connect:Direct Web Services fails to start after installation/upgrade is complete.

Upon inspecting the RESTful APIs logs the following error is displayed:

org.postgresql.util
.PSQLException: FATAL: password authentication: failed for user "postgres"
This issue possibly occurs when you're executing PostgreSQL password reset procedures for Connect:Direct Web Services running zLinux and AIX platforms.
  1. Stop MFTWebservices
  2. Go to <Installation_Directory>/mftws/BOOT-INF/classes and invoke the following command to apply password changes to Web services:
    java -jar ChangeDatabasePassword.jar
    Enter New Postgres Password>:
    Confirm Password>:
    Password Updated Successfully.
  3. Launch Connect:Direct Web Services using the following utility:
    ./startWebservice.sh
The default PostGreSQL password is changed in the Connect:Direct Web Services configuration settings. The modified password must also be updated for this user in PostgreSQL. See, Reset PostgreSQL Database connection password procedure using default password described here, PostgreSQL database Password management.
Reset PostgreSQL Database using old password.   Follow Reset PostgreSQL Database connection password procedure using old password described here, PostgreSQL database Password management.
Change PostgreSQL Database in case of forgotten password   Follow Reset PostgreSQL database connection in case of forgotten password described here, PostgreSQL database Password management.

Unable to import Connect:Direct z/OS certificates through Web Services.

  • To complete Connect:Direct Secure Plus configuration environment, only base64 encoded pem certificates of Connect:Direct z/OS can be imported into Connect:Direct Web Services' Truststore through the Web Console.

  • Importing Connect:Direct z/OS key certificate through Connect:Direct Web Console supports base64-encoded PKCS12 ASCII key certificate.

  • Importing trust certificates into Connect:Direct z/OS Keystore supports base64 encoded certificates through the Web Console.

For a binary key certificate in Base64 ASN.1 DER format, follow the steps below convert the binary certificate into a base64 encoded PKCS12 ASCII key certificate:
  • Convert PKCS12 to base64 and save output into a pem file
    cat cert.p12 | base64 >> cert.pem
  • Add -----BEGIN CERTIFICATE----- in the beginning and -----END CERTIFICATE----- at the end of file cert.pem.

    The key certificate file is ready to import into Connect:Direct z/OS Keystore via Web Console.

Webservices did not come up after installation/ upgrade and after inspecting RestApi.log you can view the postgres connection refused.

{Install_dir}/PostgreSQL/postgres/12-pgdg/bin/64/postgres -V throws following error:
ld.so.1: postgres: fatal: libxml2.so.2: 
version 'SUNW_1.8' not found (required by file postgres)

Postgres installation failed due to an incompatible libxml.

Postgres12.4 requires a specific version of libxml2.so.2 . You can check the version by executing pvs {lib_name} command.

There are 2 ways to resolve this:
  • Replace the existing libxml2.so.2 at standard path with the compatible one. (Not recommended)
  • Place the compatible library at /usr/postgres/12-pgdg/lib/64/ location.
Once the compatible library is in place, follow these steps:
  1. Execute postgresqlInstallSolaris.sh from the bin directory.
  2. Execute startPostgresqlSolaris.sh and verify if postgres service is up and running.
  3. If this was an upgrade, goto {Install_dir}/PostgreSQL/postgres/12-pgdg/bin/64/ and execute the following command:
    ./psql -p $port_at_which_postgres_
    server_is_running -f data_bkp.sql

Webservices did not come up after an upgrade from 6.0.0.5 to 6.1 or above. Upon inspecting the RestApi.log, you can see Invalid truststore path error.

CDWS uses 'sed' to manipulate the truststore path. If it is not installed, you can witness this error.

Remove the '\' characters from .hidden file and restart the webservices.