APM V8 Server upgrade: SSL error HTTPS communication fails to connect agent

Body

Product

IBM Cloud Application Performance Management, Private ( also known as APM V8)

Environment

Here we will discuss an APM server upgrade scenario (from V8.1.3 to V8.1.4) involving following conditions:
1.  APM server is being upgraded using side by side upgrade, so the APM 8.1.3 server and 8.1.4 server are installed on separate hosts.

2. HTTPS communication is configured for agents and 8.1.3 server, and HTTPS communication needs to be used for communication with 8.1.4 server as well.

Problem

After installing and starting 8.1.4 APM server, when you try directing one of the agents to this new server, you may encounter communication problem described below.

For example, Linux OS agent was directed to the new server as follows:
cd /opt/ibm/apm/agent/bin/
./agent2server.sh -s <ipaddress of 8.1.4 server>

The agent is already using HTTPS communication.

When the agent is restarted , it does not show up in the 8.1.4 dashboard.

The agent status log shows the connection to server failed during SSL certification negotiation with the server:

lz_ServerConnectionStatus.txt

Wed Jan  9 15:11:30 2019 Agent  ASF server connection status is CONNECT-FAILED      Server URL (https://ipaddress:443/ccm/asf/request) HTTP status (SSL session negotiation certificate error detected)

How to fix this so that the agents connect to the new server over HTTPS protocol?

Cause of the problem

When using HTTPS communication between APM agents and server, additional steps are required during side-by-side upgrade. If these steps are missed, the communication with new server will fail.

Explanation of HTTPS certificates in APM server:

When an APM server is installed, a set of default certificate files are created, these are used for agent to server communication if HTTPS communication is enabled. These certificates are created during install so are different from one APM server to another. The agent authenticates the APM server's certificates when it connects so the agent certificates must be the ones created by the APM server.

If the server is upgraded on the same system from APM 8.1.3 to 8.1.4 server then this will not be a problem. When using side-by-side systems for the upgrade, as was done in this case, additional steps are required to install new APM server certificates on the connecting agents, and for enabling HTTPS communication on the new APM Server. This is discussed in the steps below.

Resolving the problem

1) Set HTTPS communication on APM server
It is possible to install the APM server with HTTPS communication enabled as described on the following Knowledge Center topic:

Setting HTTP or HTTPS communications

If you did not install the new server (8.1.4) with APM_SECURE_COMMUNICATION=y environment variable as described on the above doc page, then you need to enable it as follows:
Refer to  Knowledge Center topic below - Review "What to do next" section on above link and carefully follow all the steps.
Upgrading the server side-by-side

NOTE: Steps/bullet points #4 and #5 in "What to do next" section (of Upgrading the server side-by-side link above) are repeated below.

If you installed the default certificates for 8.1.4 server, then following steps will enable HTTPS communication on the server and serveragents.

1.1 If you configured HTTPS communication between the Cloud APM server and agents in your V8.1.3 Cloud APM server, you must change clientAuthentication to true.

Copy the <ssl> xml element that contains the enabledCiphers attribute from the file:

install_dir/wlp/usr/servers/min/server.xml

to the file below, if it does not already exist in the user-exit.xml file

install_dir/wlp/usr/servers/min/user-exit.xml .

1.2 Then add this clientAuthentication="true" line after the enabledCiphers line in the user-exit.xml file.

1.3 Remove the <ssl> xml element from the server.xml file.

The following code example shows you where to add the clientAuthentication="true" line in the user-exit.xml.

<ssl
id="defaultSSLConfig"
sslProtocol="TLSv1.2"
enabledCiphers="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
clientAuthentication="true"
serverKeyAlias="server_key"
clientKeyAlias="IBM_Tivoli_Monitoring_Certificate"
keyStoreRef="defaultKeyStore"/>

- If you configured HTTPS communication between the Cloud APM server and agents in your V8.1.3 Cloud APM server and used the default certificates, change the communication protocol that the Cloud APM server agents use to HTTPS. For instructions, see Configuring the communications protocol for server agents

The HTTPS communication should now be enabled on the server.

2) Update the agents with new server address and certificates:

Refer to Knowledge Center topic:
Connecting agents to a different server

Follow steps 1 through 4 under "Procedure" section on the above link . Copy the agent configuration package from your new APM server to the agent system (step 1) and then run agent2server.sh with the -s and -f options (steps 3, 4).  This will update the certificates that the agent is using to match the certificates used by the new APM server.

References

Setting HTTP or HTTPS communications

Connecting agents to a different server

Configuring the communications protocol for server agents