Advanced features - certificates, private keys and keystore

Enable logging of keystore operations

To enable verbose output about keystore operations such as new keys and certificates additions, set the following system property into the <DT_HOME>/<component>.ini file:
-Dcom.dynatrace.diagnostics.debugKeyStore=true

Clear stored certificates to force usage of new ones

If a collector does not connect to an AppMon Server because the Server's private key was changed while the Collector was offline, the following message appears in its logfile:

WARNING [DynaTraceSSLSocketFactory] Unable to connect to localhost:6699 probably untrusted certificate: java.security.cert.CertificateException: client declined ssl client certificates with alias [collector_client]

Clear the certificate stored locally on the Collector to force it to accept any when presented by the AppMon Server. Start it with <DT_HOME>/dtcollector -Dclearcerts.

To remove certificates from the backend, frontend or client, the -Dclearkeys option is available on each component and also from the Certificate Overview, when doing a right click on an entry of the certificate chain that should be removed and selecting Delete certificate chain.

Clear stored private key to revert to default

If you changed the AppMon Server process' private key and want to revert to the built in default private key (as it would be in a new AppMon installation), start backend and frontend process with <DT_HOME>/dtserver -Dclearkeys -Dclearcerts and <DT_HOME>/dtfrontendserver -Dclearkeys -Dclearcerts respectively.

Note

If a Collector wants to connect to the Server with the now removed key pair, you must clear Stored Certificates as previously described (for example, <DT_HOME>/dtcollector -Dclearcerts). If you also want to remove the private key at the collector and revert back to the built in default private key, add -Dclearkeys too.

Clear DC-RUM certificates

DC-RUM integration server certificates are stored in the same manner as those for internal communication. In case the certificate of the DC-RUM server has changed, they must be re-accepted by clearing them first by entering <DT_HOME>/dtserver -Dcleardcrum or from the Certificate Overview, when doing a right click on an entry of the certificate chain that should be removed and selecting Delete certificate chain.

Reinitialize passwords

Adding -Dreinitpasswords to any component when starting up (for example <DT_HOME>/dtserver -Dreinitpasswords) reinitializes several passwords such as AES tunnel encryption, keystore masterkey stored within the dt_pwdstore. This generates a dt_pwdstore.zip which has to be copied and extracted to every component's /conf folder (Server, Client, Collector). This overwrites all existing dt_pwdstore files. The migration occurs automatically when the component starts for the first time after the .zip extracts.

Important

Remove the -Dreinitpasswords option for the next startup, otherwise regenerates new passwords and overwrites the .zip file. In case something went wrong and you want to revert back to the default passwords, simply delete all dt_pwdstore.*in the /conf folder.

Disallow private key deployment to client and collector

To avoid deploying a newly imported/generated private key to Client and Collector, set the property -Dcom.dynatrace.diagnostics.ssl.allowprivatekeydeployment=false in dtserver.ini (to avoid deployment to collector) and dtfrontendserver.ini (to avoid deployment to client). Removing the flag afterwards causes the server to redeploy to components that are connecting to it.

Tip

This may be used as a workaround to deploy different private keys and Certificates to the various components.

For example, deploying a new private key and Certificate to all components, then adding the property to dtserver.ini and dtfrontendserver.ini and deploying another private key and Certificate gives you a different private key for Client and Collector than the one at the Server.

Deploy new private key within a potentially insecure environment

This may be only done through a locally connected Client or by placing a customized keystore.jks in <DT_HOME>/server/conf which contains the new private key accompanied by the certificate chain (with alias dtserver) and has it's password defined in the dtserver.ini using -Dcom.dynatrace.diagnostics.communication.sslkeystorepassword=mypassword. Follow these steps carefully.

  1. Define -Dcom.dynatrace.diagnostics.ssl.allowprivatekeydeployment=false in dtserver.ini and dtfrontendserver.ini.
  2. Start Frontend and Backend Server and connect with a local Client.
  3. Go to Settings > Dynatrace Server > Services > General and clear all check boxes except the Allow Agent Connections to Dynatrace Server check box (this one must be enabled) and restart the Server.
  4. Generate/import and deploy new private key and certificates and restart all components.
  5. Shutdown the Backend and Frontend Server.
  6. Define -Dcom.dynatrace.diagnostics.ssl.allowprivatekeydeployment=true in dtserver.ini, but do not modify dtfrontendserver.ini.
  7. Start the Backend Server briefly and immediately shutdown after successful startup.
  8. Define -Dcom.dynatrace.diagnostics.ssl.allowprivatekeydeployment=falseagain in dtserver.ini
  9. Startup the Server and go to Settings > Dynatrace Server > Services > General again and restore all previously selected and cleared check boxes. Then restart the Server.
  10. Copy <DT_HOME>/server/conf/dt_co_keystore.* to an USB stick and import in every <DT_HOME>/collector/conf where you wish to exchange the private key.