Troubleshooting SSL Errors While Adding a DB2 Monitor

Troubleshooting SSL Errors While Adding a DB2 Monitor

Troubleshooting guide for DB2 monitoring in ManageEngine Applications Manager.

Applications Manager connects to DB2 over SSL when SSL is enabled in the monitor credentials. It uses its own truststore, apm.keystore, located at:

<AppManager_Home>/working/Cert/apm.keystore

Import certificates through the Applications Manager certificate screen. Use Trust certificates to import a certificate and List certificates to verify the certificates already present. Accepted formats are .crt, .cer, .pfx, .der, .jks, .keystore and .truststore.

1. Before you start

  1. Confirm the SSL port. DB2 listens for SSL on SSL_SVCENAME, normally a different port from plain SVCENAME. Run:
    db2 get dbm cfg | grep -i svcename
  2. Confirm SSL is enabled. DB2COMM must include SSL:
    db2set -all | grep -i DB2COMM
    If it reads TCPIP only, set DB2COMM=TCPIP,SSL and restart the instance using db2stop and db2start.
  3. Confirm the certificate is trusted. In Applications Manager, open List certificates and look for the DB2 server certificate or its issuing CA.

2. Unable to connect to the DB2 server. Please provide proper SSL certificates used to make SSL connection.

Certificate not trusted by Applications Manager

What it means: Applications Manager reached the DB2 server and started an SSL handshake, but does not trust the certificate presented by the server.

  1. Obtain the DB2 server certificate from the DB2 administrator. If an internal CA issued it, obtain the CA root certificate as well.
  2. In Applications Manager, open the certificate screen, select Trust certificates, upload the certificate, assign an alias and import it.
  3. Open List certificates and confirm the alias is listed.
  4. Edit and save the DB2 monitor, or wait for the next poll.

If intermediate CAs are present, import the intermediate and root certificates too. Every link in the chain must be trusted.

For detailed import instructions, refer to How to import certificates for monitoring DB2 Server with SSL authentication.

3. Unable to connect to the DB2 server. The SSL trust store configured for this connection is invalid or inaccessible. Please re-import the SSL certificate and try again.

What it means: Applications Manager could not open its own truststore. The file may be damaged, unreadable by Java, or have a password that no longer matches the password maintained by the product. This can happen if the file was copied manually, restored from backup or replaced outside the product.

  1. Open the certificate screen and select List certificates. If the list cannot be displayed, the truststore itself is likely the issue.
  2. Re-import the DB2 server certificate using Trust certificates.
  3. If the screen still cannot read the truststore, use Regenerate password on the certificate screen, then import the certificate again.
  4. Restart Applications Manager and add the monitor again.
Do not replace apm.keystore by copying a file over it. Always import certificates through Applications Manager.

4. Unable to connect to the DB2 server. If the SSL option is enabled for this monitor, check that the DB2 server is listening for SSL connections on the port given. Otherwise check the host name and port.

What it means: The connection did not reach the certificate stage. Applications Manager could not reach the port or reached a port that is not serving SSL.

  1. Check the SSL port:
    db2 get dbm cfg | grep -i ssl_svcename
    Use this port in the monitor, not the plain SVCENAME port.
  2. Confirm that DB2COMM includes SSL:
    db2set -all | grep -i DB2COMM
    After changing it, restart the instance with db2stop and db2start.
  3. Confirm SSL_SVR_KEYDB and SSL_SVR_STASH are configured in db2 get dbm cfg.
  4. From the Applications Manager host, test the port:
    telnet <db2-host> <ssl-port>
  5. If SSL is not used on the server, disable the SSL option in the monitor and use the plain port.

5. Unable to connect to the DB2 server. The connection was dropped by the server or the network. If SSL is enabled, the server and Applications Manager may not share a TLS version or cipher.

What it means: Both sides began SSL negotiation, but the server closed the connection during the handshake. The TLS versions or cipher suites may not overlap. Applications Manager runs on Java 17, which does not support TLS 1.0 or TLS 1.1.

  1. Check the DB2 TLS versions and cipher suites:
    db2 get dbm cfg | grep -i ssl_versions
    db2 get dbm cfg | grep -i ssl_cipherspecs
  2. If SSL_VERSIONS is set to TLSV1 or TLSV11, configure TLS 1.2:
    db2 update dbm cfg using SSL_VERSIONS TLSV12
    db2stop
    db2start
  3. If SSL_CIPHERSPECS contains only older cipher suites, clear the setting to use the DB2 default set:
    db2 update dbm cfg using SSL_CIPHERSPECS NULL
    db2stop
    db2start
  4. If DB2 settings are correct, test directly against the DB2 host to rule out a firewall or load balancer terminating or inspecting the connection.

6. What Applications Manager does not check

Certificate host name: Applications Manager connects with host name validation turned off. The certificate CN or SAN does not have to match the host name or IP entered in the monitor. If an error mentions a host name mismatch, it originates elsewhere.

Client certificates: Applications Manager does not present a client certificate to DB2. A DB2 instance configured to require client authentication will reject the connection.

7. If it still does not work

Collect the following before contacting support:

  • The exact error shown when adding the monitor.
  • The DB2 host name and port configured in the monitor.
  • Output of db2 get dbm cfg, especially SVCENAME, SSL_SVCENAME, SSL_VERSIONS, SSL_CIPHERSPECS, SSL_SVR_KEYDB and SSL_SVR_STASH.
  • Output of db2set -all.
  • A screenshot of List certificates.
  • <AppManager_Home>/logs/AMErrorLog*.txt and stdout.txt covering the time the monitor was added.