CA Application Performance Management - 10.7

PDF
20.2 10.7
Japanese English

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:
  1. Navigate to the
    <EM_Home>/config
     directory.
  2. Open the
    IntroscopeEnterpriseManager.properties
     file in a text editor.
  3. 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 
      IntroscopeWebView.properties
      file specifies the Enterprise Manager port in the 
      introscope.webview.enterprisemanager.tcp.port
      property.
    • introscope.enterprisemanager.enabled.channels
      Specifies the communication channels that the Enterprise Manager can use.
  4. Save and close the file.
  5. 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:
  1. Navigate to the
    <EM_Home>/config
     directory.
  2. Open the
    IntroscopeEnterpriseManager.properties
     file in a text editor.
  3. Set the following property to true.
    introscope.enterprisemanager.serversockets.reuseaddr
    Default
    : false
  4. Save and close the file.
  5. 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:
  1. Navigate to the
    <EM_Home>/config
     directory.
  2. Open the
    IntroscopeEnterpriseManager.properties
     file in a text editor.
  3. Navigate to the Enterprise Manager communication channel properties.
  4. Uncomment the second occurrence of the
    introscope.enterprisemanager.enabled.channels
     property to enable channel 2:
    # Use this to enable both the default channel and secure channel.
introscope.enterprisemanager.enabled.channels=channel1,channel2
  5. Modify any other SSL properties to the values that you want. For more information, see SSL Property Rules.
  6. Save and close the file.
  7. 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 the
    config
    directory.
  • If the
    needclientauth
    property is set to
    true
    , 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.
  • If
    needclientauth
     property is set to
    true
    , 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: 
    TLS_ECDH_anon_WITH_AES_128_CBC_SHA
    for agents running with Java 6 and 7 JRE 
    TLS_DH_anon_WITH_AES_128_GCM_SHA256
    for Java 8+ JRE as a replacement
    Example:
     
    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"
    in their names. However, the cipher suite is common to both client and server, and enabled on both.
  • 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:
  1. In the Workstation, use the tunneling transport to connect to the port for the embedded web server of the Enterprise Manager.
    Default
    : 8081
  2. Navigate to the
    <EM_Home>/config
     directory.
  3. Open the
    IntroscopeEnterpriseManager.properties
     file in a text editor.
  4. Modify the
    introscope.enterprisemanager.webserver.port
     property to the value you want for the web server port.
  5. Save and close the file.
  6. 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 
 introscope.enterprisemanager.webserver.jetty.configurationFile
property and the unsecured listener port in the 
em-jetty-config.xml
file, CA APM security can be compromised. Notify the application security personnel at your organization before making these configurations together.
Follow these steps:
  1. Navigate to the
    <EM_Home>/config
     directory.
  2. Open the
    em-jetty-config.xml
     file in a text editor.
  3. Activate the file by uncommenting the
    introscope.enterprisemanager.webserver.jetty.configurationFile
     property.
  4. Modify the web server properties in the Jetty file to the values you want.
  5. Verify that HTTPS is enabled in the
    em-jetty-config.xml
     file. Ensure that the port attribute is set as follows:
    <Set name="port">8444</Set>
  6. (Optional) Specify the HTTPS protocol in the URL in the 
    IntroscopeWebview.properties
    file. Set the 
    EM_HOST
    to your hostname or IP address of the MOM, for example:
    introscope.webview.enterprisemanager.rest.base=https://{EM_HOST}:8444/apm/appmap
    When 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.
  7. Save and close the file.
  8. 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/keystore
     Keystore path. This path is relative to the
    /config
     directory. 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 is
    password
    . Clear text passwords in
    em-jetty-config.xml
     and
    webview-jetty-config.xml
     are obfuscated by default. The obfuscated passwords start with
    OBF:
    . The plain text passwords can be provided by removing
    OBF:
    . 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 
    validateCerts
    is set to 
    true
    , employ the following configuration:
    • Use a separate keyStore and a trustStore.
      KeyStorePath
       and
      TrustStorePath
       settings 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.
    • Modify
      em-jetty-config.xml
       and 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 the
    excludeCipherSuites
     attribute 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 the
    em-jetty-config.xml
    and
    webview-jetty-config.xml
     files 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 the
    maxThreads
     property 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 the
    maxThreads
     property. The number of allowed agent connections is configured in the
    introscope.enterprisemanager.agent.connection.limit
     property in the
    apm-events-thresholds-config.xml
     file. Be sure that the
    maxThreads
     value is greater than or equal to the
    introscope.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:
  1. Navigate to the
    <EM_Home>/config
     directory on the MOM and open the
    em-jetty-config.xml
     file in a text editor.
  2. Locate the section with the following line:
    <New class="org.eclipse.jetty.server.HttpConfiguration">
  3. Modify the
    HttpConfiguration
     property with this value:
    <Set name="requestHeaderSize">16384</Set>
  4. Save and close the file.
  5. Navigate to the
    IntroscopeEnterpriseManager.properties
     file on each MOM and Collector.
  6. Uncomment the line in this property:
    introscope.enterprisemanager.webserver.jetty.configurationFile=em-jetty-config.xml
  7. Save and close the file.
  8. Restart the web server.