Download page Enable SSL and SSH for Database Agent Communications.
Enable SSL and SSH for Database Agent Communications
Enable SSL for the Database Agent
This topic covers 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-premise Controller to use SSL.
The Database Agent supports extending and enforcing the SSL trust chain when in SSL mode.
Gather the following 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.
- 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-premises Controller
the root certificate for the internal CA that signed the Controller certificate for your on-premises Controller
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>
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.
Install the agent truststore to the Database Agent configuration directory:
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
- 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 SSL Enabled: true.
Controller Keystore Password: the plain text password for the Database Agent truststore.
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.
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.
- 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:
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:
Run the Keystore Certificate Extractor Utility from the Controller as follows:
% /<full path to application JRE>/bin/java -jar <controller_home>/appserver/glassfish/domains/domain1/appagent/<controller_version>/utils/keystorereader/kr.jarCODE
- Enter the following when prompted:
The full path to the Controller's keystore:
Enter input keystore: <controller_home>/appserver/glassfish/domains/domain1/config/keystore.jksCODE
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.jksCODE
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
Install the agent trust store to the agent configuration directory:
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 optionThe SSH port option does not appear unless the Database Agent is running on Linux.
On the agent machine, generate the rsa or dsa key as follows:
Generate rsa key
% ssh-keygen -b 1024 -f id_rsa -t rsaCODE
Generate dsa key
% ssh-keygen -b 1024 -f id_dsa -t dsaCODE
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.
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.
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 .sshCODE
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_keysCODE
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_keysCODE
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_keysCODE
Append dsa public key to authorized key
% echo /home/<user_name>/.ssh/id_dsa.pub >> /home/<user_name>/.ssh/authorized_keysCODE
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.
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:
- Enable the Use certificate option in the Monitoring hardware section of the Collector configuration dialog.
- 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.
- Restart the agent.