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

Skip to end of metadata
Go to start of metadata

On this page:

The Controller comes with a preconfigured HTTPS port (port 8181 by default), secured with a self-signed certificate.  

For production use, AppDynamics strongly recommends that you replace the self-signed certificate with a certificate signed by a third-party CA or your own internal CA. If you are deploying .NET Agents, you must replace the self-signed certificate with one signed by a CA, since the .NET agents do not work with self-signed certificates. 

This page describes how to replace the existing key in the default keystore. Replacing the entire keystore is not recommended, unless you first export the existing artifacts from the default keystore and import them into your own keystore. 

The default Controller keystore includes the following artifacts:

  • glassfish-instance: A self-signed private key provided the Glassfish application server.
  • s1as: A self-signed private key provided with the Glassfish application server used by the Controller for secure communication on port 8181.

The keystore may also contain eum_client and agg_appdynamics. These are the private key and keychain used by the AppDynamics End User Monitoring product. Do not attempt to modify or remove them. 

You can view the contents of the keystore yourself using the keytool utility. To do so, from the <Controller_home>/jre/bin directory, run the following command, entering that password changeit when prompted: 

keytool -list -v -keystore ../../appserver/glassfish/domains/domain1/config/keystore.jks 

The exact steps to implement security typically vary depending on the security policies for the organization. For example, if your organization already has a certificate to use, such as a wildcard certificate used for your organization's domain, you can import the existing certificate into the Controller keystore. Otherwise, you'll need to generate a new one along with a certificate signing request. The following sections take you through these scenarios. 

Before Starting

The following instructions describe how to configure SSL using the Java keytool utility bundled with the Controller installation. You can find the keytool utility in the following location:

  • <Controller_Installation_Directory>/jre/bin

The steps assume that the keytool is in the operating system's path variable. To run the commands as shown, you first need to put the keytool utility in your system's path. Use the method appropriate for your operating system to add the keytool to your path.

While the directory paths in this topic use forward slashes, the instructions apply to both Linux and Windows Operating System environments. The steps note where there are differences in the use of commands between operating systems. 

Create a Certificate and Generate a CSR

If you don't have a certificate to use for the Controller, create it as follows. In these steps, you generate a new certificate within the Controller's active keystore, so it has immediate effect.

The steps are intended to be used in a staging environment, and require the Controller to be shut down and restarted. Alternatively, you can generate the key as described here but in a temporary keystore rather than the Controller's active keystore. After the certificate is signed, you can import the key from the temporary keystore to the Controller's keystore.

  1. At a command prompt, change directories to the following location:

  2. Create a backup of the keystore file. For example, on Linux, you can run: 

    cp keystore.jks keystore.jks.backup

    On Windows, you can use the copy command in a similar manner.  

  3. If it's still running, stop the Controller.
  4. Delete the existing certificate with the alias s1as from the keystore:

    keytool -delete -alias s1as -keystore keystore.jks
  5. Create a new key pair in the keystore:

    keytool -genkeypair -alias s1as -keyalg RSA -keystore keystore.jks -keysize 2048

    Follow the onscreen instructions to configure the certificate. Note that:

    • For the first and last name, enter the domain name where the Controller is running, for example,
    • Enter the default password for the key, changeit.
    This generates a self-signed certificate in the keystore. We'll generate a signing request for the certificate next. You can now restart the Controller and continue to use it. Since it still has a temporary self-signed keystore, browsers attempting to connect to the Controller UI will get a warning to the effect that its certificate could not be verified.
  6. Generate a certificate signing request for the certificate you created as follows:

    keytool -certreq -alias s1as -keystore keystore.jks -file AppDynamics.csr
  7. Submit the certificate signing request file generated by the command (AppDynamics.csr in our example command) to your Certificate Authority of choice.
    When it's ready, the CA will return the signed certificate and any root and intermediary certificates required for the trust chain. The response from the Certificate Authority should include any special instructions for importing the certificate, if needed. If the CA supplies the certificate in text format, just copy and paste the text into a text file.
  8. Import the signed certificate:

    keytool -import -trustcacerts -alias s1as -file mycert.cer -keystore keystore.jks

    This command assumes the certificate is located in a file named mycert.cer.

  9. If you get the error "Failed to establish chain from reply", install the issuing Certificate Authority's root and any intermediate certificates into the keystore. The root CA chain establishes the validity of the CA signature on your certificate. Although most common root CA chains are included in the cacerts.jks truststore, you may need to import additional root certificates. To do so:

    keytool -import -alias [Any_alias] -file <Path_to_Root_or_Intermediate_Cert> -keystore <Controller_Install_Directory>/appserver/glassfish/domains/domain1/config/keystore.jks

When done importing the certificate chain, try importing the signed certificate again.

Import an Existing Keypair into the Keystore

These steps describe how to import an existing public and private key into the Controller keystore. We'll step through this scenario assuming that the existing public and private keys need to be converted to a format compatible with Java Keystore, say from DER format to PKCS#12. You'll need to use OpenSSL to combine the public and private keys, and then keytool to import the combined keys into the Controller's keystore.

Most Linux distributions include OpenSSL. If you are using Windows or your Linux distribution does not include OpenSSL, you may find more information on the OpenSSL website.

This assumes that we have the following files:

  • private key: private.key
  • signed public key: cert.crt
  • CA root chain: ca.crt

The private key you use for the following steps must be in plain text format. Also, when performing the following procedures, do not attempt to associate a password to the private key as you convert it to PKCS12 keystore form. If you do, the following steps can be completed as described, but you will encounter an exception when starting up the Controller, with the error message: " Cannot recover key".

To import an existing keypair into the Controller keystore
  1. Use OpenSSL to combine your existing private key and public key into a compatible Java keystore:

    openssl pkcs12 -inkey private.key -in cert.crt -export -out keystore.p12
  2. If the Controller is still running, stop it.
  3. Change to the keystore directory:

    cd <Controller_Installation_Directory>/appserver/glassfish/domains/domain1/config/
  4. Create a backup of the keystore file. For example, on Linux, you can run:

    cp keystore.jks keystore.jks.backup

    On Windows, you can use the copy command in a similar manner.

  5. Delete the self-signed certificate with alias s1as from the default keystore:

    keytool -delete -alias s1as -keystore keystore.jks
  6. Import the PKCS#12 key into the default keystore:

    keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12 -destkeystore keystore.jks -deststoretype JKS
  7.  If you get the error "Failed to establish chain from reply", install the issuing Certificate Authority's root and any intermediate certificates into the keystore. The root CA chain establishes the validity of the CA signature on your certificate. Although most common root CA chains are included in the cacerts.jks truststore, you may need to import additional root certificates. To do so:

    keytool -import -alias [Any alias] -file <Path to Root/Intermediate Cert> -keystore <Controller Install Directory>/jre/lib/security/cacerts

    When done, try importing the signed certificate again.

  8. Update the alias name on the PKCS12 key you just imported:

    keytool -changealias -alias "1" -destalias "s1as" -keystore keystore.jks
  9. Start the Controller. 

Verify the Controller is secured using SSL

To make sure the configuration works, use a browser to connect to the Controller over the default secure port, port 8181:


Make sure the Controller entry page loads in the browser correctly. Also verify that the browser indicates a secure connection. Most browsers display a lock icon next to the URL to indicate a secure connection.

After changing the certificate on the Controller, you will need to import the public key of the certificate to the agent truststore. For information on how to do this, see the topic specific for the agent type:

When finished, you can turn off the default, non-secure port at 8090. To disable the port, you can use the asadmin Glassfish tool. From <controller_home>/appserver/glassfish/bin, run the following command:

./asadmin delete-http-listener http-listener-1

When prompted, enter admin as the user and for the password, the password for the Controller root user. On Windows, use the asadmin.bat script in a similar manner.  

If there is no proxy configured and the agent is reporting to the Controller itself, then the following changes are also mandatory:

  1. Run the following command:

    <controller_home>/bin/ stop-appserver

    Use .bat on Windows.

  2. Search for the following properties in <controller_home>/appserver/glassfish/domains/domain1/config/domain.xml, and replace the port with the SSL port, as the non-secure port is disabled:

  3. In the following property, change the protocol from HTTP to HTTPS, and change the port to the secure port.


    You can also use REST API to update the deeplink URL:

    curl -k --basic --user root@system --header "Content-Type: application/json" --data '
    { "controllerURL": "https://<controller>:<ssl_port>" }' https://<controller>:<ssl_port>/controller/rest/accounts/<ACCOUNT-NAME>/update-controller-url
  4. Add the following JVM argument anywhere above or below the above JVM arguments to ensure the internal agent connects using SSL.

  5. Run the following command:

    <controller_home>/bin/ start-appserver

    Use .bat on Windows.

You can also use the script to make the changes.

Change Keystore Password

The default password for the keystore used by the Controller is changeit. This is the default password for the Glassfish keystore, and is a well-known (and thus insecure) password. For a secure installation, you need to change it.

Changing the password in this manner does not affect the administration password you use to access the Glassfish administration console. See Administrative Users for information on changing that password.

To change the password you must use the Glassfish administration tool (rather than the keytool utility directly). Using the Glassfish administration tool allows the Glassfish instance to access the keys at runtime.

If you change the keystore password directly using the keytool, the Controller generates the following error message at start up: 

Caused by: java.lang.IllegalStateException: Keystore was tampered with,
or password was incorrect

If you encounter this scenario, change the password using the asadmin utility, as described next.

To change Glassfish passwords
  1. Stop the Controller.
  2. Change the Glassfish master password:

    <Controller_Installation_Directory>/appserver/glassfish/bin/asadmin change-master-password --savemasterpassword=true
  3. Restart the Controller and make sure it starts error free.

Changing the master password with asadmin changes the password for the keystore and for the s1as key. It does not change the password of any additional keys you have added to the keystore, however. If you have added keys to the keystore, you need to change their password to match the new master password. Use the keytool to change their passwords as follows:

keytool -keypasswd -alias myserver -keystore keystore.jks
-storepass <new master password>
  • No labels