If you use HTTPS connections in a production (split host) EUM Server installation, use a custom RSA security certificate for the EUM server. This page describes how to create an RSA security certificate, change the password for the credential keystore, and how to obfuscate a password for the security certificate keystore.   

Set Up a Custom Keystore for Production

In demo mode, the EUM Server uses a default self-signed certificate named ssugg.keystore. This certificate is intended for demonstration and light testing only. Do not use self-signed certificates for production systems since they are less secure than Certificate Authority (CA) signed certificates.  EUM requires that certificates use RSA as the key algorithm whether they are self-signed or CA-signed.  

For Mobile Real User Monitoring, if you use the default or another self-signed certificate on your EUM Server for testing, you may receive the following error: "The certificate for this server is invalid". Ensure that your self-signed certificate is trusted by the simulator or device you use for testing. In real-world scenarios, a CA signed certificate should be used since a self-signed certificate needs to be explicitly trusted by every device that reports to your EUM processor. 

To secure the EUM server with a custom certificate and keystore, generate a new JKS keystore and configure the EUM Server to use it.

The following instructions describe how to create a JKS keystore for the EUM Server with a new key-pair or an existing key-pair.  Alternatively, you can also configure the EUM server to use an existing JKS keystore.

The instructions demonstrate the steps with the Linux command line, but the commands are similar to the commands used for Windows. Make sure to adjust the paths for your operating system. 

Overview of the Steps

The procedure is made up of three parts:

  1. Create a new certificate and keystore (1a) or import an existing certificate into a keystore (1b).  
  2. Configure the EUM Server to use the keystore.
  3. Restart and test the new keystore.

Step 1a: Create a New Certificate and Keystore

  1. At a command prompt, navigate to the eum-processor directory:

    cd <appdynamics_home>/EUM/eum-processor
    CODE

  2. Create a new keystore with a new unique key pair that uses RSA encryption:

    ../jre/bin/keytool -genkey -keyalg RSA -validity <validity_in_days> -alias 'eum-processor' -keystore bin/mycustom.keystore
    CODE

    This creates a new public-private key pair with an alias of 'eum-processor'. You can use any value you like for the alias. 

    The "first and last name" required during the installation process becomes the common name (CN) of the certificate. Use the name of the server.

  3. Configure the keystore.
  4. Specify a password for the keystore. You need to configure this password in the EUM configuration file later.  

  5. Generate a certificate signing request (CSR):

    ../jre/bin/keytool -certreq -keystore bin/mycustom.keystore -file /tmp/eum.csr -alias 'eum-processor'
    CODE

    This generates a certificate signing request based on the contents of the alias, in the example 'eum-processor'. You should send the output file (/tmp/eum.csr, in the example) to a Certificate Authority for signing. After you receive the signed certificate, proceed as follows.

  6. Install the certificate for the Certificate Authority used to sign the .csr file:

    ../jre/bin/keytool -import -trustcacerts -alias myorg-rootca -keystore bin/mycustom.keystore -file /path/to/CA-cert.txt
    CODE

    This command imports your CA's root certificate into the keystore and stores it in an alias called myorg-rootca.

  7. Install the signed server certificate as follows:

    ../jre/bin/keytool -import -keystore bin/mycustom.keystore -file /path/to/signed-cert.txt  -alias 'eum-processor'
    CODE

    This command imports your signed certificate over the top of the self-signed certificate in the existing alias, in the example, 'eum-processor'.

  8. Import the root certificate from step 6 to the Controller truststore:

    keytool -import -trustcacerts -alias <alias_name> -file mycert.cer -keystore <complete_path_to_cacerts.jks>

Step 1b: Import an Existing Certificate into a JKS Keystore

If you have an existing public-private key pair that uses RSA, you must import them into a JKS keystore to use it for EUM.

  1. At a command prompt, navigate to the eum-processor directory:

    cd <appdynamics_home>/EUM/eum-processor
    CODE

  2. Stop the EUM process.

    Run the following command:

    bin/eum.sh stop
    CODE

  3. If there is an existing custom JKS keystore, back it up:

    mv <keystore>.jks <keystore>.jks.old
    CODE

  4. Import the private and public key for your certificate into a PKCS12 keystore:

    openssl pkcs12 -inkey <private_key_file> -in <certificate_file> -export -out keystore.p12
    CODE

  5. Convert the PKCS12 keystore to JKS format:

    keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12 -destkeystore <JKS_keystore> -deststoretype JKS
    CODE

    This command creates a JKS keystore with the name specified in the -destkeystore property.

  6. Specify a password for the keystore. Use this password when you configure EUM to use the new keystore.

Step 2: Configure the EUM Server to Use the New Keystore

  1. Place the new keystore file in the following directory:  <appdynamics_home>/EUM/eum-processor/bin.

  2. Edit the eum.properties file in the bin directory.

  3. If the property processorServer.keyStorePassword is set, remove or uncomment it.

  4. Add the keystore filename as the following property:  

    processorServer.keyStoreFileName=mycustom.keystore
  5. Configure the password for the keystore. You can add the password to the file either in plain text or in the obfuscated form:

    • For a plain text password, add the password as the value for this property: 

      processorServer.keyStorePassword=mypassword
    • For an obfuscated password:  

      1. Get the obfuscated password by running the following command in the eum-processor directory in a new command terminal:

        bin/eum-credential-key.<bat|sh> obfuscate -plaintext <newpassword>
      2. Copy the output of the command to your clipboard.

      3. In eum.properties, paste the obfuscated password as the value of the keyStorePassword property: 

        processorServer.keyStorePassword=<obfuscated_key>

      4. Add the useObfuscatedKeyStorePassword with the value set to true, as shown:

        processorServer.useObfuscatedKeyStorePassword=true
  6. Save and close the file.  

Step 3: Restart and Test

  1. Restart the EUM Server. From the eum-processor directory, run the following commands:

    bin/eum.sh stop
bin/eum.sh start
    CODE

  2. Verify the new security certificate works by opening the following page in a browser:

    https://<hostname>:7002/eumcollector/get-version
    CODE

    If you get a successful response, the configuration succeeded. 

Change the Certificate Keystore Password

The previous steps describe how to create a new keystore which is likely to have a new password. To change the keystore password without creating a new keystore, perform the following steps: 

  1. At a command prompt, navigate to the eum-processor directory:

    cd <appdynamics_home>/EUM/eum-processor
    CODE

  2. Run the keytool command for creating a new password: 

    ../jre/bin/keytool -storepasswd -keystore bin/ssugg.keystore
    CODE

    The sample command creates the password for the default demo keystore, ssugg.keystore. In your command, use the name of your own keystore as the value for -keystore. 

  3. Enter the existing password and new password when prompted. 

  4. Get the obfuscated key by running the following command in the eum-proccessor directory:

    bin/eum-credential-key.<bat|sh> obfuscate -plaintext <newpassword>
  5. Copy the output of the previous command to your clipboard.

  6. In the eum.properties file in the eum-processor/bin directory, paste the obfuscated password as the value for the keyStorePassword property:

    processorServer.keyStorePassword=<obfuscated_key>

  7. If you did not previously use an obfuscated password, add the following property: 

    processorServer.useObfuscatedKeyStorePassword=true
  8. Save and close the file. 
  9. Restart the EUM Server. 

Change the Credential Keystore Password for the EUM Database 

When you install the EUM Server, you need to specify a password to use to secure the credential keystore for the EUM Server. After installation, you can change the password for the credential keystore. You may need to do this, for example, to comply with your organization's password rotation policy.

Note that completing these procedures requires a restart of the EUM Server.  

To change the existing EUM server credential keystore password: 

  1. At a command prompt, navigate to the eum-processor directory:

    cd <appdynamics_home>/EUM/eum-processor
    CODE
  2. Generate a credential store with the new key using the following command:

    • On Linux:

      bin/eum-credential-key.sh generate_ks -storepass <new_password>

    • On Windows:

      bin\eum-credential-key.bat generate_ks -storepass <new_password>
    This creates and initializes a new credential file, bin/credential.scs. 
  3. Reencrypt the database password using the new credential store.

    • On Linux: 

      bin/eum-credential-key.sh encrypt -storepass <new_password> -plaintext <DB_password>

    • On Windows:

      bin\eum-credential-key.bat encrypt -storepass <new_password> -plaintext <DB_password>
    The command prints out the encrypted form of the DB_password value you entered. 
  4. Copy the output from the previous command to your clipboard.  
  5. Open bin/eum.properties for editing, and replace the value of the onprem.dbPassword setting with the new encrypted password you copied to your clipboard.
  6. Obfuscate the new credential key as follows:

    • On Linux:

      bin/eum-credential-key.sh obfuscate -plaintext <new_password>

    • On Window:

      bin\eum-credential-key.bat obfuscate -plaintext <new_password>
  7. Copy the output of the previous command to your clipboard and in eum.properties replace the value of onprem.credentialKey with the value from your clipboard. 
  8. Save and close the properties file.

  9. Restart the EUM server. 

Change the EUM Database Password

At EUM Server installation time, you set a password for the EUM database. You can change it later as follows:

  1. At a command prompt, navigate to the eum-processor directory:

    cd <appdynamics_home>/EUM/eum-processor
    CODE
  2. Encrypt the new database password using the credential key which you entered during installation:

    • On Linux:

      bin/eum-credential-key.sh encrypt -storepass <plain_credential_key> -plaintext <New_DB_password>

    • On Windows:

      bin\eum-credential-key.bat encrypt -storepass <plain_credential_key> -plaintext <New_DB_password>

      The command prints out the encrypted form of the DB_password value you entered.

  3. Copy the output from the previous command to your clipboard. 
  4. Edit bin/eum.properties and replace the value of the onprem.dbPassword setting with the new encrypted password you copied to your clipboard. 
  5. Save and close the properties file.
  6. Restart the EUM server.