Configure Enterprise Manager Communications
Default keyStore with yourBy default, the Enterprise Manager (EM) communicates with agents, Workstation, WebView, and a cluster of Enterprise Managers on port 5001. The default EM communication channel for this port is non-secure. In addition to the default communication channel, you can enable a secure Enterprise Manager communications channel by configuring an SSL server socket. All socket communication to the Enterprise Manager is protected and passwords are encrypted by a secure communications channel.
apmdevops106
Default keyStore with yourBy default, the Enterprise Manager (EM) communicates with agents, Workstation, WebView, and a cluster of Enterprise Managers on port 5001. The default EM communication channel for this port is non-secure. In addition to the default communication channel, you can enable a secure Enterprise Manager communications channel by configuring an SSL server socket. All socket communication to the Enterprise Manager is protected and passwords are encrypted by a secure communications channel.
As an administrator, perform the following tasks to configure Enterprise Manager communications for your environment:
3
Configure the Default Enterprise Manager Communication Channel
The
IntroscopeEnterpriseManager.properties
file specifies the communication channel properties for each agent that communicates with the Enterprise Manager.Follow these steps:
- Navigate to the<EM_Home>/configdirectory.
- Open theIntroscopeEnterpriseManager.propertiesfile in a text editor.
- Modify the following communication channel properties to the values you want:
- introscope.enterprisemanager.serversocketfactory.<ChannelName>Identifies the classname of the Server Socket Factory that the Enterprise Manager uses for encrypted communication with Workstations and agents.
- introscope.enterprisemanager.port.<ChannelName>Identifies the listener port that the Enterprise Manager uses for encrypted communication with Workstations and agents.The
file specifies the Enterprise Manager port in theIntroscopeWebView.properties
property.introscope.webview.enterprisemanager.tcp.port - introscope.enterprisemanager.enabled.channelsSpecifies the communication channels that the Enterprise Manager can use.
- Save and close the file.
- Restart the Enterprise Manager.
Note: For information about configuring agent properties, see the Java Agent or the Microsoft .NET Agent.
Rebind a Communication Channel
To encounter an inactive socket state while memory is still in use, rebind the communication channel to a port that is in use. Examples of inactive states are
FIN_WAIT
and TIME_WAIT
. Do not enable this property by default. Use it only when a socket is in an unusable state. Disable the property only after the Enterprise Manager starts because the port may still be in use. For example, the port is in use if a collector on the same machine is already bound to the port.
Follow these steps:
- Navigate to the<EM_Home>/configdirectory.
- Open theIntroscopeEnterpriseManager.propertiesfile in a text editor.
- Set the following property to true.introscope.enterprisemanager.serversockets.reuseaddrDefault: false
- Save and close the file.
- Restart the Enterprise Manager.
Enable SSL for Enterprise Manager Communications
In addition to the default communication channel, you can enable a secure Enterprise Manager communications channel by configuring an SSL server socket.
Note:
For more information about setting up SSL communications for an APM cluster and components, see TEC1308495.Follow these steps:
- Navigate to the<EM_Home>/configdirectory.
- Open theIntroscopeEnterpriseManager.propertiesfile in a text editor.
- Navigate to the Enterprise Manager communication channel properties.
- Uncomment the second occurrence of theintroscope.enterprisemanager.enabled.channelsproperty to enable channel 2:# Use this to enable both the default channel and secure channel. introscope.enterprisemanager.enabled.channels=channel1,channel2
- Modify any other SSL properties to the values that you want. For more information, see SSL Property Rules.
- Save and close the file.
- Restart the Enterprise Manager.
SSL Property Rules
When configuring SSL communication channel properties in the
IntroscopeEnterpriseManager.properties
file, follow these rules:- The keyStore property is the location of a keyStore, which contains a certificate for the Enterprise Manager to authenticate itself to the client. The default keyStore of the Enterprise Manager contains a self-signed certificate that is not secure. However, the Workstation and agent do not validate server certificates by default.
- The keyStore property is either an absolute path or a path relative to theconfigdirectory.
- If theneedclientauthproperty is set totrue, the Enterprise Manager requires the client to authenticate.
- The Enterprise Manager must be configured with a trustStore.
- Agents and Workstations must be configured with a keyStore containing a certificate that is trusted by the Enterprise Manager.
- Ifneedclientauthproperty is set totrue, and a trustStore is not configured, the Enterprise Manager does not start. This action requires setting the trustStore property.
- The trustStore property is the location of a trustStore, which contains the certificates of trusted clients. This property is needed if clients are required to authenticate. If no trustStore is specified, all client certificates are trusted.
- The ciphersuites property is used to set the enabled cipher suites. This property can be used to enable an anonymous authentication or avoid data encryption.
- For an anonymous authentication, set the cipher suites to:
for agents running with Java 6 and 7 JRETLS_ECDH_anon_WITH_AES_128_CBC_SHA
for Java 8+ JRE as a replacementTLS_DH_anon_WITH_AES_128_GCM_SHA256Example:introscope.enterprisemanager.ciphersuites.channel2=SSL_DH_anon_WITH_RC4_128_MD5 - A specific JSSE implementation can have several cipher suites available that permit an anonymous authentication. The cipher suites for anonymous authentications contain "anon"
- Specify a cipher suite that does not encrypt data.Example:introscope.enterprisemanager.ciphersuites.channel2=SSL_RSA_WITH_NULL_SHA
Example: Enable Both a Secure and Nonsecure Communications Channel
Configuring the Enterprise Manager for SSL is done in
IntroscopeEnterpriseManager.properties
by enabling a secure communications channel. This secure channel can be configured in addition to the default nonsecure channel. Configuring
MOM-collector
or MOM-WebView
communication over SSL is not supported.The following configuration example sets up the default nonsecure listener on port 5001, and a secure listener on port 5443:
# The enabled communication channels. introscope.enterprisemanager.enabled.channels=channel1, channel2 # The default communication channel. introscope.enterprisemanager.serversocketfactory.channel1=com.wily.isengard.postofficehub.link.net.server.DefaultServerSocketFactory introscope.enterprisemanager.port.channel1=5001 # The secure communication channel. introscope.enterprisemanager.serversocketfactory.channel2=com.wily.isengard.postofficehub.link.net.server.SSLServerSocketFactory introscope.enterprisemanager.port.channel2=5443 # Location of a keystore containing certificates for authenticating the Enterprise Manager to clients. # Either an absolute path or a path relative to the config directory. # On Windows, backslashes must be escaped. For example: # introscope.enterprisemanager.keystore.channel1=C:\\Introscope\\config\\internal\\server\\keystore introscope.enterprisemanager.keystore.channel2=internal/server/keystore # The password for the KeyStore. # Set the following property to true to enable encryption. introscope.enterprisemanager.keypassword.channel2 # Once introscope.enterprisemanager.keypassword.channel2 is encrypted, # this property is automatically set to false. # 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.keypassword.channel2.plaintextpassword=true introscope.enterprisemanager.keypassword.channel2=password # Location of a TrustStore containing trusted client certificates. # Either an absolute path or a path relative to the config directory. # On Windows, backslashes must be escaped. For example: # introscope.enterprisemanager.truststore.channel1=C:\\Introscope\\config\\internal\\server\\keystore # A TrustStore is only needed if client authentication is required. # Set this property to true to enable encryption of introscope.enterprisemanager.trustpassword.channel2 # Once introscope.enterprisemanager.trustpassword.channel2 is encrypted, # this property is automatically set to false. # 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=false # The password for the TrustStore #introscope.enterprisemanager.trustpassword.channel2=password # If no TrustStore is specified, the Enterprise Manager trusts all client certificates.
Connect to the Enterprise Manager Across a Firewall
HTTP tunneling is enabled by default. The tunneling technology enables one network to send its data through connections of another network.
Follow these steps:
- In the Workstation, use the tunneling transport to connect to the port for the embedded web server of the Enterprise Manager.Default: 8081
- Navigate to the<EM_Home>/configdirectory.
- Open theIntroscopeEnterpriseManager.propertiesfile in a text editor.
- Modify theintroscope.enterprisemanager.webserver.portproperty to the value you want for the web server port.
- Save and close the file.
- Restart the web server.
Configure Enterprise Manager to WebView Communications (SSL)
The Enterprise Manager web server supports HTTP tunneling over SSL. This security measure is implemented through the
em-jetty-config.xml
file that is accessed from the Jetty web server. This web server is embedded in the Enterprise Manager. To configure Jetty web server with custom configuration file, uncomment following property in IntroscopeEnterpriseManager.properties
file: introscope.enterprisemanager.webserver.jetty.configurationFile=em-jetty-config.xml.
At startup, the Enterprise Manager loads the default
em-jetty-config.xml
file from the <EM_Home>/config
directory, which sets up a secure listener on port 8444. This secure listener allows the Workstation, WebView, and agent to access the Enterprise Manager using HTTPS tunneling through the Enterprise Manager web server.The Enterprise Manager does not create the unsecured listener that is defined in the
introscope.enterprisemanager.webserver.port
property when the Enterprise Manager loads the Jetty configuration file. However, you can configure the unsecured listener in the Jetty configuration file.Modify the
introscope.webview.enterprisemanager.webserver.tcp.port
and introscope.webview.enterprisemanager.rest.base
(from http to https) in the IntroscopeWebView.properties
file.Warning!
If you uncomment both the
property and the unsecured listener port in theintroscope.enterprisemanager.webserver.jetty.configurationFile
file, CA APM security can be compromised. Notify the application security personnel at your organization before making these configurations together.em-jetty-config.xml
Follow these steps:
- Navigate to the<EM_Home>/configdirectory.
- Open theem-jetty-config.xmlfile in a text editor.
- Activate the file by uncommenting theintroscope.enterprisemanager.webserver.jetty.configurationFileproperty.
- Modify the web server properties in the Jetty file to the values you want.
- Verify that HTTPS is enabled in theem-jetty-config.xmlfile. Ensure that the port attribute is set as follows:<Set name="port">8444</Set>
- (Optional) Specify the HTTPS protocol in the URL in the
file. Set theIntroscopeWebview.properties
to your hostname or IP address of the MOM, for example:EM_HOSTintroscope.webview.enterprisemanager.rest.base=https://{EM_HOST}:8444/apm/appmapWhen you use HTTPS, ensure that Enterprise Manager uses a trusted certificate and that WebView recognizes that certificate as trusted. For more information, see KB Article: Team Center - Blank Page after Login, Status code 503, SSLHandshakeException. - Save and close the file.
- Restart the web server.
: To configure the name and location of the
em-jetty-config.xml
file, use the introscope.enterprisemanager.webserver.jetty.configurationFile
property in the IntroscopeEnterpriseManager.properties
file.Jetty Configuration Options for SSL
Important:
A default Jetty configuration file (
em-jetty-config.xml
) in the <EM_Home>/config
directory lets you modify many components of SSL. For example:- Change the HTTPS port from the default 8444, by changing the value of the port attribute.Example: <Set name="port">8444</Set>
- By default, the SSL listener is configured to use the/internal/server/keystoreKeystore path. This path is relative to the/configdirectory. This keyStore contains a self-signed certificate that is untrustworthy. You can substitute your own keyStore with a keyStore containing a certificate from a recognized Certificate Authority (CA).
- The default keystorePassword ispassword. Clear text passwords inem-jetty-config.xmlandwebview-jetty-config.xmlare obfuscated by default. The obfuscated passwords start withOBF:. The plain text passwords can be provided by removingOBF:. For more information about configuring SSL, see https://wiki.eclipse.org/Jetty/Howto/Configure_SSL.
- By default, SSL is configured to accept self-signed certificates. The SSL does not verify that the host name in the client URL matches the host name in the digital certificate. This configuration is sufficient for testing standalone Enterprise Managers only. This configuration ensures that SSL works by default with the untrusted certificate in the default keyStore. If you require highly secure authentication, create a keystore containing a trusted certificate.The Enterprise Managers are also clients when communicating over SSL. The Enterprise Managers require a valid certificate or a trusted self-signed certificate with the correct hostname in the Java trustStore. You must use a valid certificate. For testing purposes, you can use a self-signed certificate, but you must generate a certificate for your hostname and domain. Add the certificate to the global Java trustStore. The Enterprise Manager as a client uses the global Java trustStore to verify trusted servers.For production environments, a valid certificate from a recognized Certificate Authority is required.Then set these attributes in the XML and replacing the default keyStore with your own:<Set name="KeyStorePath"> <SystemProperty name="introscope.config" default="./config" />/internal/server/keystore </Set> <Set name="KeyStorePassword">password</Set> <Set name="validateCerts">false</Set>
- You can also create a trustStore that contains client certificates to require client authentication, as follows:<Set name="TrustStorePath"> <SystemProperty name="introscope.config" default="./config" />/internal/server/keystore </Set> <Set name="TrustStorePassword">password</Set> <Set name="needClientAuth">true</Set>
- If
is set tovalidateCerts
, employ the following configuration:true- Use a separate keyStore and a trustStore.KeyStorePathandTrustStorePathsettings point to different files.
- Only certificates which can be validated (other than the root CA certificate) should be put into the keyStore. Usually, it is a host machine certificate + private key and their intermediate CA certificate.
- The root CA certificate or an intermediate CA certificate that cannot be validated has to be put in the trustStore.
- Modifyem-jetty-config.xmland enable appropriate validation methods. This modification means that either both or the appropriate one of these following settings have to be enabled:<Set name="enableCRLDP">true</Set>- the validation uses Certificate Revocation List file URL that is specified as an extension of X.509 certificate.<Set name="enableOCSP">true</Set>- the validation uses OCSP responder. This OCSP responder URL can also be specified in X.509 certificate as an extension. If the certificate does not define this OCSP responder URL, it can be specified with<Set name="ocspResponderURL">http://example.com/ocsp</Set>.For more information, see Jetty 9.4 SslContextFactory class documentation.
- If you require client authentication, configure the agents and Workstations with a keyStore that contains a certificate. The Enterprise Manager web server must trust this certificate.To set excluded cipher suites, set theexcludeCipherSuitesattribute to the list of cipher suites:
<Set name="excludeCipherSuites"> <Array type="java.lang.String"> <Item>SSL_DH_anon_WITH_RC4_128_MD5</Item> </Array> </Set>
The agents and Workstations must have an enabled cipher suite in common with the Enterprise Manager to use SSL. You can restrict the enabled cipher suites to these actions:
- Prevent vulnerability in weak cipher suites.
- Allow anonymous connections.
- Not encrypt data.
- If you require to customize the list of accepted protocols, define the protocols for the<Item>tag in theem-jetty-config.xmlandwebview-jetty-config.xmlfiles as shown in the following example:<Set name="includeProtocols"><Array type="java.lang.String"><Item>TLSv1.2</Item><Item>TLSv1.1</Item></Array></Set>
- The Enterprise Manager uses themaxThreadsproperty to limit the number of HTTPS agent connections that the Enterprise Manager can service. If there are not enough threads, the Enterprise Manager does not recognize the connected agents or process metrics from them.
- When using HTTPS, the Enterprise Manager services only the number of agents that are configured in themaxThreadsproperty. The number of allowed agent connections is configured in theintroscope.enterprisemanager.agent.connection.limitproperty in theapm-events-thresholds-config.xmlfile. Be sure that themaxThreadsvalue is greater than or equal to theintroscope.enterprisemanager.agent.connection.limit value. Some agents do not appear in clients or report any metrics when there are not enough threads to connect over HTTPS.
Reset the Default Request Header Size for CEM Console
If you occasionally see blank pages when you access the CEM console, reset the default request header size limit of 8 kB. Reset the header size limit in the Jetty configuration file.
Follow these steps:
- Navigate to the<EM_Home>/configdirectory on the MOM and open theem-jetty-config.xmlfile in a text editor.
- Locate the section with the following line:<New class="org.eclipse.jetty.server.HttpConfiguration">
- Modify theHttpConfigurationproperty with this value:<Set name="requestHeaderSize">16384</Set>
- Save and close the file.
- Navigate to theIntroscopeEnterpriseManager.propertiesfile on each MOM and Collector.
- Uncomment the line in this property:introscope.enterprisemanager.webserver.jetty.configurationFile=em-jetty-config.xml
- Save and close the file.
- Restart the web server.