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  Controller, you must create an agent truststore that contains the root certificate for the authority that signed the Controller's certificate.

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

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

      • • • • DigiCert Global Root CA
            • DigiCert Global Root G2
            • DigiCert Global Root G3
            • IdenTrust Commercial Root CA 1
   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

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 controller-info.xml: <db_agent_home>/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  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>/conf. Required if you use a truststore other than the default <db_agent_home>/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>

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

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

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

   • 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

     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.

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

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

   <db_agent_home>/conf/

Enable SSH for the Database Agent

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. 

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

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

   or

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

   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:

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

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: 

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

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

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

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:

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

   or 

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

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,  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.