This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


On this page:

Related pages:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
4 rates

This topic covers how to configure the Java Agent to connect to the Controller using SSL. It assumes that you use a SaaS Controller or have configured the on-premise Controller to use SSL.

The Java Agent supports extending and enforcing the SSL trust chain when in SSL mode.

Requirements

Gather the following information:

  • The Controller SSL port.
    • For SaaS Controllers the SSL port is 443.
    • For on-premise Controllers the default SSL port is 8181, but you may configure the Controller to listen for SSL on another port.
  • The signature method for the Controller's SSL certificate:
    • A publicly known certificate authority (CA) signed the certificate. This applies for DigiCert, Verisign, Thawte, and other commercial CAs.
    • A CA internal to your organization signed the certificate. Some companies maintain internal certificate authorities to manage trust and encryption within their domain.
    • The Controller uses a self-signed certificate.

Establish Trust for the Controller's SSL Certificate

To establish trust between the Java Agent and the AppDynamics Controller, you must create an agent truststore that contains the root certificate for the authority that signed the Controller's certificate.

If you secured your on-premise Controller with a self-signed certificate, see Keystore Certificate Extractor Utility for instructions to create the agent keystore.

  1. Obtain one of the following root certificates:
    • DigiCert Global Root CA for the AppDynamics SaaS Controller
    • the root certificate for the publicly known certificate authority (CA) that signed the certificate for your on-premise Controller
    • the root certificate for the internal CA that signed the Controller certificate for your on-premise Controller

  2. Run the Java keytool command to create the agent truststore:

    keytool -import -alias rootCA -file <root_certificate_file_name> -keystore cacerts.jks -storepass <truststore_password>

    For example:

    keytool -import -alias rootCA -file /usr/home/appdynamics/DigicertGlobalRootCA.pem -keystore cacerts.jks -storepass MySecurePassword

    Make note of the truststore password, you need it to configure the Java Agent.

  3. Install the agent truststore to the versioned agent configuration directory:

    <agent_home>/<version_number>/conf/

Secure the Java Agent Truststore

AppDynamics recommends you take the following security measures to prevent tampering with the Java Agent truststore:

  • Secure the truststore file through filesystem permissions:

    • Make the agent truststore readable by any user.

    • Make the truststore owned by a privileged user.

    • Make the truststore writable only by the specified privileged user.

  • Secure the agent configuration files so that they are only readable by the agent runtime user and only writable by a privileged user:

    • Versioned configuration file: <agent_home>/<version_number>/conf/controller-info.xml.

    • Global configuration file: <agent_home>/conf/controller-info.xml.

Enable SSL for the Java Agent

  1. Configure the following system properties in the versioned controller-info.xml: <agent_home>/<version_number>/conf/controller-info.xml. See "SSL Configuration Properties" here for full details on each property.
    • Controller Port: the SSL port for the controller. 443 for AppDynamics SaaS.

      <controller-port>443</controller-port>

    • Controller SSL Enabled: true. 

      <controller-ssl-enabled>true</controller-ssl-enabled>

    • Controller Keystore Password: the plain text password for the agent truststore.

      <controller-keystore-password>MySecurePassword</controller-keystore-password>

    • Controller Keystore Filename: path of the agent truststore relative to <agent home>/<version>/conf. Required if you use a truststore other than the default <agent_home>/<version_number>/conf/cacerts.jks.

      <controller-keystore-filename>../../conf/cacerts.jks</controller-keystore-filename>

      You can specify the Controller port and enable SSL for the Controller in the JVM startup script, but you must specify the truststore password and filename in the versioned controller-info.xml file.

  2. Restart the JVM.

Sample SSL controller.xml configuration

<?xml version="1.0" encoding="UTF-8"?>
<controller-info>
	<controller-host>mycompany.saas.appdynamics.com</controller-host>
	<controller-port>443</controller-port>
	<controller-ssl-enabled>true</controller-ssl-enabled>
	<controller-keystore-password>MySecurePassword</controller-keystore-password>
	<controller-keystore-filename>../../conf/cacerts.jks</controller-keystore-filename>
	...
</controller-info>


Keystore Certificate Extractor Utility

The Keystore Certificate Extractor Utility exports certificates from the Controller's Java keystore and writes them to an agent truststore. It installs to the following location:

<agent_home>/<version_number>/utils/keystorereader/kr.jar

To avoid copying the Controller keystore to an agent machine, you can run this utility from the Controller server. Access the agent distribution on the Controller at the following location:

<controller_home>/appserver/glassfish/domains/domain1/appagent
  1. Execute kr.jar and pass the following parameters:
    • The full path to the Controller's keystore:

      <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks
    • The truststore output file name. By default the Java Agent looks for cacerts.jks.
    • The password for the Controller's certificate, which defaults to "changeit". If you don't include a password, the extractor applies the password "changeit" to the output truststore.

      java -jar kr.jar <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks cacerts.jks <controller_certificate_password>
  2. Install the agent trust store to the versioned agent configuration directory:

    <agent_home>/<version_number>/conf/

Resolve SSL Issues