Self-signed certificates

Sometimes you might need to use self-signed certificates to enable monitoring of certain technologies or to gain access to an internal maven mirror. To provide self-signed certificates for different agent installations, see the following contents:

Adding a self-signed certificate to the Java TrustStore file

As a starting point, you can use the default Java TrustStore of the JVM that the Instana Agent comes with. Make a copy of the default Java TrustStore file and save it in a safe place outside the Instana agent installation path. You can find the file on the host machine where the Instana agent is installed:

  • For HotSpot JVMs (Azul Zulu 1.8) on Linux®/Unix®: /opt/instana/agent/jvm/jre/lib/security/cacerts
  • For J9 JVMs (IBM J9 11) on Linux®/Unix®: /opt/instana/agent/jvm/lib/security/cacerts

You can also extract the Java TrustStore file from a container image as follows:

For HotSpot (Azul Zulu 1.8) based Instana agent, run the following command:

id=$(docker create icr.io/instana/agent:latest); docker cp $id:/opt/instana/agent/jvm/jre/lib/security/cacerts /<local_path>/cacerts && docker rm -v $id
```**Note:** Replace *&lt;local_path&gt;* in the command with your local host path to store the default Java TrustStore file.

For J9 (IBM J9 11) based Instana agent, run the following command:
```bash {: codeblock}
id=$(docker create icr.io/instana/agent:latest-j9); docker cp $id:/opt/instana/agent/jvm/lib/security/cacerts /<local_path>/cacerts && docker rm -v $id
```**Note:** Replace *&lt;local_path&gt;* in the command with your local host path to store the default Java TrustStore file.

After you copy the Java TrustStore file, you can continue to add the individual certificate.
To import a self-signed certificate into the Java TrustStore file, run the following command:

```bash {: codeblock}
keytool -import -alias <provided_alias> -keystore <java_truststore> -storepass <password> -file <path_to_self-signed_certificate>

Notes:

  • A keystore entry is identified by an alias. Replace <provided_alias> with your chosen value.
  • Replace <java_truststore> with the absolute path to the Java TrustStore file.
  • Replace <password> with your chosen password. The default password for the default Java TrustStore file is changeit.
  • Replace <path_to_self-signed_certificate> with the absolute path to your self-signed certificate that you want to import.

Using a custom Java TrustStore file for the Instana agent

Linux host

If your Instana agent is installed on Linux, use either of the following ways:

systemd

By using systemd, the easiest way to specify the additional parameters is changing the unit file or using a drop-in.

  1. To change the current unit file, run the systemctl edit instana-agent command. Then, the current unit file will be opened in the default editor of the system.

  2. Locate the following lines:

    ### Anything between here and the comment below will become the new contents of the file

### Lines below this comment will be discarded

    Add the contents as follows to the file:

    [Service]
Environment="JAVA_OPTS=-Djavax.net.ssl.trustStore=<path_to_java_truststore> -Djavax.net.ssl.trustStoreType=jks"
```   **Notes:**
 - Replace *&lt;path_to_java_truststore&gt;* with the path of your Java TrustStore file.
 - You don't need to specify a password for reading the Java TrustStore.

Instead of changing the unit file directly, you can use an additional file with the extension .conf in the /etc/systemd/system/instana-agent.service.d/ directory as a drop-in.

  1. Create a new file in the /etc/systemd/system/instana-agent.service.d/ directory with the extension .conf, such as /etc/systemd/system/instana-agent.service.d/environments.conf.
  2. Add the contents as follows to the file:
    [Service]
Environment="JAVA_OPTS=-Djavax.net.ssl.trustStore=<path_to_java_truststore> -Djavax.net.ssl.trustStoreType=jks"
```   **Notes:**
- Replace *&lt;path_to_java_truststore&gt;* with the path of your Java TrustStore file.
- You don't need to specify a password for reading the Java TrustStore.

After you change the unit file or add a drop-in, you must run the systemctl daemon-reload command to reload the changed unit files. Then, restart the Instana agent by running the command systemctl restart instana-agent for the changes to work.

Environment variable

If you want to start Instana agent directly, make sure that you have added the following environment before you start the Instana agent:

JAVA_OPTS="-Djavax.net.ssl.trustStore=<path_to_java_truststore> -Djavax.net.ssl.trustStoreType=jks"
```**Notes:**
- Replace *&lt;path_to_java_truststore&gt;* with the path of your Java TrustStore file.
- You don't need to specify a password for reading the Java TrustStore.

## <a href="#troubleshooting"><img src="../../../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> Troubleshooting {: #troubleshooting}
### <a href="#sslexception-in-instana-agent-logs"><img src="../../../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> SSLException in Instana agent logs {: #sslexception-in-instana-agent-logs}
You might see exceptions as follows in the Instana agent logs:
``` {: codeblock}
Caused by: javax.net.ssl.SSLException: Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty

This exception indicates that you started the Instana agent without a valid Java TrustStore file. You need to verify your changes, and make sure that the Instana agent can access the provided Java TrustStore file.