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
Using a custom Java TrustStore file for the Instana agent
- Linux host
  - systemd
  - Environment variable
Troubleshooting
- SSLException in Instana agent logs

Adding a self-signed certificate to the Java TrustStore file

Copy the Java TrustStore file, and save it in a safe place.
- If you use the default Java TrustStore of the JVM that the Instana host agent comes with, find the Java TrustStore file on the host machine where the agent is installed, and then save it in a safe place outside the agent installation path.
  - 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
  Or you can 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
```
    Replace <local_path> 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:
```
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
```
    Replace <local_path> in the command with your local host path to store the default Java TrustStore file.
- If you want to use a custom Java TrustStore for your Instana host agent, configure the Java TrustStore of host agent as in the using a custom Java TrustStore for your Instana host agent section, and then save your custom Java TrustStore file to a safe place.
Import a self-signed certificate into the Java TrustStore file by running the following command:
```
keytool -import -alias <provided_alias> -keystore <java_truststore> -storepass <password> -file <path_to_self-signed_certificate>
```
- 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 that you copied in the last step.
- 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

If you don't want to use the default Java TrustStore of the JVM for your Instana agent, you can use a custom Java TrustStore.

Linux host

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

systemd
Environment variable

systemd

Specify the Java TrustStore parameters by using either of the following ways:
- Use the unit file.
  1. To change the current unit file, run the following command:
```
systemctl edit instana-agent
```
    Then, the current unit file is 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"
```
    - Replace <path_to_java_truststore> with the path of your custom Java TrustStore file.
    - You don't need to specify a password for reading the custom Java TrustStore.
- 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"
```
    - Replace <path_to_java_truststore> with the path of your custom Java TrustStore file.
    - You don't need to specify a password for reading the custom Java TrustStore.
Reload the changed unit files by running the following command:
```
systemctl daemon-reload
```
Restart the Instana host agent for the changes to work by running the following command:
```
systemctl restart instana-agent
```

Environment variable

To use a custom Java TrustStore for your host agent, you can also configure the environment variable as follows:

If you want to start the Instana host agent directly, ensure that you have added the following environment variable before you start the host agent.

JAVA_OPTS="-Djavax.net.ssl.trustStore=<path_to_java_truststore> -Djavax.net.ssl.trustStoreType=jks"

You need to replace <path_to_java_truststore> with the path of your custom Java TrustStore file.
You don't need to specify a password for reading the custom Java TrustStore.

Troubleshooting

SSLException in Instana agent logs

You might see the following exceptions in the Instana agent logs:

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.

To resolve this issue, you need to verify your changes, and make sure that the Instana agent can access the provided Java TrustStore file.