SSL Communication for Introscope Enterprise Manager

This page summarizes steps to enable full SSL/TLS communication for Introscope in combination with SAP Solution Manager. The steps are mainly organized by the two communication ports opened by the Enterprise Manager:

  • HTTP port (default = 8081): This port is served by the embedded Jetty server. Converting this port from HTTP to HTTPS mainly involves adapting the file em-jetty-config.xml. This port is typically used when accessing Introscope Webview (e.g. dashboards), the UI5 applications sapdashboard and emergency monitoring, and also by SAP Solution Manager when accessing Introscope. In the picture below the green arrows represent the http access.
  • RMI port (default = 6001): This port is used for incoming agent connections and for Workstation connections. The RMI communication can be done via multiple "channels" - more than one channel can be active at a time, thus opening multiple TCP ports. Adjusting the RMI ports requires changes on Enterprise Manager side and on agent side. As a result, SSL-enabling RMI is substantially more complex than the HTTP → HTTPS conversion.
    In the picture below the red arrows represent the RMI access. 

  • SSL Communication for Enterprise Managers in a cluster (MoM and Collectors).
    Communication between Enterprise Managers in a cluster (collectors and MoM) uses RMI. Introscope does not support using SSL communication between collectors and MoM. In the picture below this is represented by black arrows.

Strictly speaking even more combinations are possible: Agents and Workstations can also use HTTP and HTTPS. These options are not explained here.

HTTPS Access to the Enterprise Manager (Webview, Webstart, sapdashboard etc)

Configuration of HTTPS access to the Enterprise Manager is described on a dedicated page.

RMI via SSL: Communication between Enterprise Manager and Introscope Agents

Prerequisites

It may be necessary to explicitly enable TLSv1 on Enterprise Manager side since potentially not all components support TLSv1.2. In particular the following components lack TLSv1.2 support:

  • Introscope agent versions 9.7 and lower 
  • Introscope agent runtime in diagnostics agent (=Introscope Host Adapter / "wilyhost"): Up to SAP Solution Manager 7.2 SP11 the Introscope agent runtime 9.7 is used, thus no TLSv1.2 is possible. Starting with SAP Solution Manager 7.2 SP12 the Introscope agent runtime 10.7 is used for wilyhost and thus TLSv1.2 is supported.
  • Earlier patch levels of SAP JVM 6 (see SAP Note 2346928)

To enable TLSv1 put the following property into config/IntroscopeEnterpriseManager.properties:

Enable TLSv1 
introscope.enterprisemanager.protocols.channel2=TLSv1.2,TLSv1.1,TLSv1


Procedure

  1. Enable RMI port for SSL in the Enterprise Manager (see  section below)
  2. Edit the configuration of the Agents so the correct socket factory is used to connect to the Enterprise Manager(see sections below)


Enable RMI Port for SSL in the Enterprise Manager

1  Under the EM installation directory, open the file IntroscopeEnterpriseManager.properties which is located under the folder /config. Most of the properties mentioned below exist already in the file, but are commented out.

2  In this file, edit the propertyintroscope.enterprisemanager.enabled.channels to define which channels will be enabled and accept connections for the EM. Each "channel" refers to a set of properties that configure a TCP port for incoming connections.
By default, the 'channel1' is the default RMI port (6001) and the 'channel2' is the SSL RMI port (6443).
It is possible to activate just one channel or both channels like the following:

Enable RMI 
# SSL channel only


introscope.enterprisemanager.enabled.channels=channel2




# or activate both channels: default and SSL


introscope.enterprisemanager.enabled.channels=channel1,channel2

Recommendation

When you activate only channel 2 for SSL and restart the EM all existing agents cannot connect anymore. To avoid this it is recommend to activate temporarily both channels and if required remove channel1 later when all agents are reconfigured.

Collectors only

For collectors you must activate both channels. 

3  Modify the property introscope.enterprisemanager.workstation.connection.channel to define which channel will be used by SAP Solution Manager. If you set this property with the value 'channel2' , when configuring agents in the future, the port set for channel2 will then be used by the agent to connect to the Enterprise Manager. The property will look like following:

MoM and Standalone Only

For Collectors the property introscope.enterprisemanager.workstation.connection.channel must not be changed. 

# This property is used for Workstations launched via Java Web Start, to set


# the communication port used for communicating with the Enterprise Manager.


introscope.enterprisemanager.workstation.connection.channel=channel2


4  Restart the Enterprise Manager so the changes take action

5  In the SAP Solution Manager system, access the Infrastructure Preparation under section 'Define CA Introscope". Here, use the discover button to reload the EM information.

6  If you have set both channels as active, you should then see two Enterprise Manager entries here for MoM and Standalone EM.


Collectors should appear only once with the 'old' port.

7  If you have already performed the steps on section 'Procedure to Enable HTTPS Port for EM WebView', ensure to check the HTTPS flag here for the new EM entry.

Updating Agents Settings to Use Correct Socket Factory

Updating the Agent Profile Templates

With SAP Solution Manager 7.2, it is possible to adjust the profile templates directly so the newly configured agents use the SSL Socket Factory and Port. You can upload templates for the agent profiles via diagnostics agent administration.

There is one template for wilyhost and one template for each byte code agent version. These templates can be customized on two different scopes:

  • Scope <Global>: If you switch the template on this scope to SSL then all managed system configurations for BCA and wilyhost will always use SSL!
  • Scope for individual hosts: The changes will affect only the hosts for which the templates are customized. This scope overrides customizing on scope <Global>.

Agent profile template for Introscope Host Adapter (wilyhost)

1  In Diagnostics Agent Administration select the tab 'Application Configuration' and navigate through 'com.sap.smd.agent.application.wilyhost / Application Resources / IntroscopeSapAgent.profile.template.'

2  Download the default resource and save it locally as text file (.txt).

3  Rename the downloaded file to IntroscopeSapAgent.profile.template (replace the underscore with dot and remove the file extension .txt)

4  Edit the local file and change introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.SSLSocketFactory. Save it again.

5  In agent administration, select the correct scope for the file(Global or specific host). Then browse to the modified file and press Upload.


Here it is important to note that the template for wilyhost will only be considered if the setup has not yet been executed before( if the resource 'IntroscopeSapAgent.profile' is not yet customized in the relevant scope). To force the use of the newly uploaded template, remove the customizing of 'IntroscopeSapAgent.profile' in the relevant scope(host for which the configurations have been done in the past). This can be done by accessing the file 'IntroscopeSapAgent.profile' in the same path, selecting the relevant host in the scope and then removing the customized file.


6  In the Managed System Configuration for the relevant hosts, ensure the correct EM entry is selected. This is important to ensure the correct port will be pushed into the agent configuration.


7  Execute the step Introscope Host Adapter in Managed System configuration.


8  If the Wilyhost was active before, a complete restart of the diagnostics agent is needed.

It is possible to check if the agent is connecting correctly to the Enterprise Manager by checking the file 'jvm_smdagent.out' under the work folder inside the agent installation path. Entries like the following will be present:

[INFO] [IntroscopeAgent.IsengardServerConnectionManager] Connected Agent to the Introscope Enterprise Manager at <HOST>:<SSL PORT 6443>,com.wily.isengard.postofficehub.link.net.SSLSocketFactory. Host = "<HOST>", Process = "SAP HostAgent Process", Agent Name = "SAP HostAgent SMDA98".

Agent profile template for Byte code adapter (wilybcaj5)

1  In Diagnostics Agent Administration select the tab 'Application Configuration' and select the application relevant for your Introscope agent:

  • com.sap.smd.agent.application.wilybcaj5 for Introscope agent 9.x and higher

2  Under the selected application node select Application Resources and the agent profile, e.g. 'WilyResources/ISAGENT.9.1.5.3-2014-10-22/IntroscopeAgent.profile'

3  Download the default resource and save it locally.

4  Edit the local file and change introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.SSLSocketFactory. Save it again.

5  In agent administration, select the correct scope for the file(Global or specific host). Then browse to the modified file and press Upload.


6  In the Managed System Configuration for the relevant hosts, ensure the correct EM entry is selected. This is important to ensure the correct port will be pushed into the agent configuration.


7  Execute the step 'Byte Code Adapter Installation' in Managed System configuration.


8  Restart the managed system to activate the changes.

Optional: Configuration of Certificates for Enterprise Manager and Agents

Default Behavior

By default the initial key stores are used and no additional configuration is needed. This means, however, that certificates are not validated for SSL communication.

Configure RMI via SSL for Certificates (EM side)

You can optionally configure the SSL port to allow only trusted agent connections. This is achieved by setting introscope.enterprisemanager.needclientauth.channel2=true. This requires the following:

  • Create and configure a trust store on EM side via the properties
    • introscope.enterprisemanager.trustpassword.channel2
    • introscope.enterprisemanager.truststore.channel2
    • introscope.enterprisemanager.trustpassword.channel2.plaintextpassword
  • Configure a key store on agent side (next section)

Edit the following properties in IntroscopeEnterpriseManager.properties. The effect is that all agents not providing a trusted certificate will be blocked from connecting to the Enterprise Manager.

IntroscopeEnterpriseManager.properties 
# The truststore is optional.  It is needed only if client authentication is required.


# If no truststore is specified, the EM trusts all client certificates.


introscope.enterprisemanager.truststore.channel2=myTruststore


# To change the existing password, enter the new password and set this property to true.


# Note: If this property is set to true and the password is not changed, the existing encrypted password will be encrypted again.


# If password field for a new channel is configured, add the corresponding  


# plaintextpassword field and set it to true to enable encryption. 


introscope.enterprisemanager.trustpassword.channel2.plaintextpassword=true


# The password for the truststore


introscope.enterprisemanager.trustpassword.channel2=mySecretPassword


# Set to true to require clients to authenticate.


# If true, clients must be configured with a keystore containing a certificate trusted by the EM.


# Default is false


introscope.enterprisemanager.needclientauth.channel2=true


Configure RMI via SSL for Certificates (Agent side)

Procedure to configure a keystore for the RMI communication via SSL on agent side. Goal: Allow only trusted agents to connect. Agent authenticates via a certificate which is configured as trusted in the EM.

Note that there is no automated transfer of the keystore from SAP Solution Manager or Enterprise Manager to the agent host. You have to explicitly take care for the transfer and specify a path that is available on agent side (d:\isagent\emssl2.jks in the example below).

Edit the following properties in IntroscopeAgent.profile:

IntroscopeAgent.profile 
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.isengard.postofficehub.link.net.SSLSocketFactory


introscope.agent.enterprisemanager.transport.tcp.keystore.DEFAULT=d:\\isagent\\emssl2.jks


introscope.agent.enterprisemanager.transport.tcp.keypassword.DEFAULT=caapm9x

Troubleshooting, References, and Reservations

Troubleshooting with SSL Trace

To get more details on TLS connection negotiation you can activate the standard Java SSL tracing. For this purpose add the Java VM parameter -Djavax.net.debug like below  

-Djavax.net.debug=ssl:handshake:verbose:keymanager:trustmanager

or

-Djavax.net.debug=all:

On Windows add a new line to bin\EMService.conf:

EMService.conf 
wrapper.java.additional.8=-Djavax.net.debug=ssl:handshake:verbose:keymanager:trustmanager

.8 is the next free number for the parameter group wrapper.java.additional. Depending on your configuration you may have to choose a different number.

On Unix change the property lax.nl.java.option.additional in Introscope_Enterprise_Manager.lax.

References

Documentation can be found on every Enterprise Manager where the SAP management module package is deployed. Use the link https://techdocs.broadcom.com/us/en/ca-enterprise-software/it-operations-management/application-performance-management/10-7.html to get to the overview page of all guides.

  1. CA APM Configuration and Administration Guide, Chapter Configuring Enterprise Manager Communications
  2. CA APM Java Agent Implementation Guide, Chapter Installing and Configuring the Java Agent, Configuring the connection to the Enterprise Manager
  3. CA APM Security Guide

Reservations

  • Help links from SAP dashboards to the help content are currently always generates as HTTP links. Change to https manually to get the help content displayed.
  • Only one of the channels for each HTTP and RMI can be used in SAP Solution Manager: either secure or non-secure
  • Currently no support for certificate and keystore handling in SAP Solution Manager setup UIs. You can use the destination service of the J2EE server (via Visual Admin / NWA) to configure certificates.
  • Byte code injection agent and Introscope Host Adapter setup via SAP Solution Manager do not support the protocol types "RMI via SSL", "HTTP", "HTTPS" right now. You have to manually adapt the profiles to switch the protocol.