Enable SSL for the Database Agent

This page describes how to configure the Database Agent to connect to the Controller using SSL. It assumes that you use a SaaS Controller or have configured the on-premises Controller to use SSL.

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

Requirements

Gather this information:

  • The Controller SSL port.
    • For SaaS Controllers the SSL port is 443.
    • For on-premises 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 Database 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-premises Controller with a self-signed certificate, see Keystore Certificate Extractor Utility for instructions to create the agent keystore.

  1. Obtain the root certificate for the authority that signed the certificate for the Controller.

    1. For SaaS Controller deployments: You can download the DigiCert root certificates from https://www.digicert.com/digicert-root-certificates.htm. Ensure to include at least the following certificates:

            • DigiCert Global Root CA
            • DigiCert Global Root G2
            • DigiCert Global Root G3
            • DigiCert TLS ECC P384 Root G5
            • DigiCert TLS RSA4096 Root G5
    2. For on-premises Controller deployments: Obtain one of the following root certificates:
            • The root certificate for the publicly known certificate authority (CA) that signed the certificate for your on-premises Controller.
            • The root certificate for the internal CA that signed the Controller certificate for your on-premises Controller.

  2. Run the Java keytool command to create the Database 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 Database Agent.

  3. Install the agent truststore to the Database Agent configuration directory:

    <db_agent_home>/conf/

Secure the Database Agent Truststore

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

  • Secure the truststore file through file system permissions:

    • Make the Database 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 Database Agent configuration files so that they are only readable by the agent runtime user and only writable by a privileged user:

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

Configure SSL System Properties for the Database Agent

  1. Configure the following system properties in the versioned controller-info.xml: <db_agent_home>/<version_number>/conf/controller-info.xml. See "SSL Configuration Properties" on Database Agent Configuration Properties 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 Database Agent truststore.

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

      If you have enabled the Secure Credential Store, encrypt the password you enter here. See Encrypt Agent Credentials.

    • Controller Keystore Filename: path of the Database Agent truststore relative to <db_agent home>/<version>/conf. Required if you use a truststore other than the default <db_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 controller-info.xml file.

  2. Save your change to the controller-info.xml file and restart the Database Agent.

Sample SSL controller-info.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>
CODE

Keystore Certificate Extractor Utility

The Keystore Certificate Extractor Utility exports certificates from the Controller's Java keystore for the Database Agent truststore. It installs to the following location:

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

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

  1. Run the Keystore Certificate Extractor Utility from the Controller: 

    % /<full path to application JRE>/bin/java -jar <controller_home>/appserver/glassfish/domains/domain1/appagent/<controller_version>/utils/keystorereader/kr.jar
    CODE
  2. Enter the following when prompted:

    • The full path to the Controller's keystore:

      Enter input keystore: <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks
      CODE

    • The truststore output file name. By default the Database Agent looks for cacerts.jks.

      Enter output agent truststore file name: <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks
      CODE

      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.

    • Example command to execute kr.jar

      /<full path to application JRE>/bin/java -jar kr.jar <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jks cacerts.jks <controller_certificate_password>
      CODE

  3. Install the agent trust store to the agent configuration directory:

    <db_agent_home>/conf/

Enable SSH for the Database Agent

For Linux hosts only

Applies only when Database Agent is running on a Linux host. 


When the Database Agent is running on Linux and you want to monitor hardware, except to monitor the local host, authentication is required and a password is passed between the Database Agent and the database server. 

SSH port option

The SSH port option does not appear unless the Database Agent is running on Linux.

  1. On the agent machine, generate the rsa or dsa key as follows:

    Generate rsa key

    % ssh-keygen -b 1024 -f id_rsa -t rsa
    CODE

    or

    Generate dsa key

    % ssh-keygen -b 1024 -f id_dsa -t dsa
    CODE

    This will create a rsa or dsa 1024-bit key and put the keys into /home/<user_name>/.ssh/id_rsa and /home/<user_name>/.ssh/id_rsa.pub or /home/<user_name>/.ssh/id_dsa' and /home/<user_name>/.ssh/ida_dsa.pub' files. Do not change the names of these files.

  2. Copy the private key, /home/<user_name>/.ssh/id_rsa or /home/<user_name>/.ssh/id_id_dsa into the <db-agent_home>/keys directory.

  3. On both the monitored machine and the agent machine, verify that you have the correct permissions on the .ssh directory, or set them as follows:

    .ssh directory permissions

    % cd /home/<user_name>
% chmod 755 .ssh
    CODE

  4. On the monitored machine, verify that you have a /home/<user_name>/.ssh/authorized_keys file. If you do not have this file, create the authorized_keys file on the monitored machine as follows: 

    Create authorized_keys file

    % cd /home/<user_name>/.ssh
% touch .ssh/authorized_keys
    CODE

  5. Verify that you have the correct permissions to the /home/<user_name>/.ssh/authorized_keys file, or change the permissions as follows:

    authorized_keys file permissions

    % cd /home/<user_name>/.ssh
% chmod 644 authorized_keys
    CODE

  6. Append (do not copy) the file 'id_rsa.pub' or the file 'id_dsa.pub' to the file,  /home/<user_name>/.ssh/authorized_keys, such as follows:

    Append rsa public key to authorized key

    % echo /home/<user_name>/.ssh/id_rsa.pub >> /home/<user_name>/.ssh/authorized_keys
    CODE

    or 

    Append dsa public key to authorized key

    % echo /home/<user_name>/.ssh/id_dsa.pub >> /home/<user_name>/.ssh/authorized_keys
    CODE

  7. The SSH port of the database Collector is set to 22 by default. You can change it by navigating to the Monitoring Hardware section of the Collector configuration dialog. In the dialog, set the SSH port to the port your require.

  8. Save your change to the Collector configuration and restart the Database Agent.

Enable SSH via PEM certificate

For Linux, AppDynamics also supports certificate-based authentication via Privacy Enhanced Mail (PEM). To implement certificate-based authentication:

  1. Enable the Use certificate option in the Monitoring hardware section of the Collector configuration dialog. 
  2. Copy the PEM file to the <db_agent_home>/keys directory. Note, if the home/<user_home>/.ssh directory exists, the agent will use the certificate found there. 
  3. Restart the agent.