This topic describes how to configure the AppDynamics Machine 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 Machine Agent supports extending and enforcing the SSL trust chain when in SSL mode.
Plan SSL Configuration
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 Machine 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.
- 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 agent truststore:
Note the truststore password; you will need this later to configure the Machine Agent.
Install the agent truststore to the agent configuration directory:
Secure the Machine Agent Truststore
AppDynamics recommends you take the following security measures to prevent tampering with the Machine 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 controller-info configuration file so that it is only readable by the agent runtime user and only writable by a privileged user:
Enable SSL for the Machine Agent
- Configure the following system properties in the controller-info.xml:
<machine_agent_home>/conf/controller-info.xml. See "SSL Configuration Properties" on Machine Agent Configuration Properties for full details on each property.
Controller Host: should be the same as either the Common Name or the Subject Alternative Name (SAN) in the certificate configured for the Controller.
Controller Port: the SSL port for the controller. 443 for AppDynamics SaaS.
Controller SSL Enabled: true.
Controller SSL Password: the plain text password for the agent truststore.
If you have enabled the Secure Credential Store, encrypt the password you enter here. See Encrypt Agent Credentials.
Controller Keystore Filename: path of the agent truststore relative to
<machine_agent home>/conf. Required if you use a truststore other than the default
You can specify the Controller port and enable SSL for the Controller in the Machine Agent startup script, but you must specify the truststore password and filename in the
- Restart the Machine Agent.
Sample controller-info.xml with SSL and Secure Credential Store encryption enabled
<?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> <!-- Encrypted Controller keystore / agent trust store password --> <controller-keystore-password>Tw49bd0hdCMBoQ5pfMMuYA/cA5B4pouVPkv48ovRm6c=</controller-keystore-password> <controller-keystore-filename>../../conf/cacerts.jks</controller-keystore-filename> ... <!-- Secure Credential Store configuration --> <!-- Enable the Secure Credential Store --> <use-encrypted-credentials>true</use-encrypted-credentials> <!-- Path to they secure credential keystore --> <credential-store-filename>/opt/appdynamics/secretKeyStore</credential-store-filename> <!-- Obfuscated secure credential keystore password --> <credential-store-password>n/8GvAZsKk4gM3Z6g+XQ1w==</credential-store-password> </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. You can run this utility the agent distribution on the Controller:
kr.jarand pass the following parameters:
The full path to the Controller's keystore:
- The truststore output file name. By default, the Machine Agent looks for
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>CODE
Install the Machine Agent trust store to the agent configuration directory: