Self-signed certificates

Edit online

You might need to use self-signed certificates to enable the monitoring of certain technologies or to gain access to an internal maven mirror. This topic describes how to configure self-signed certificates at the agent level for Instana host agents on both Linux and Windows environments.

Note: For backend-level certificate configuration (for external services that the Instana backend connects to), see Using a custom CA certificate.

To provide self-signed certificates for different agent installations, see the following contents:

Adding a self-signed certificate to the Java truststore file

Edit online

The keytool command works identically on both Linux and Windows environments. The following steps apply to both operating systems.

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. Then, save the file in a safe place outside the agent installation path.
  - For HotSpot JVMs (Azul Zulu 11) 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
  - For HotSpot JVMs (Azul Zulu 11) on Windows®: C:\Program Files\Instana\instana-agent\jvm\lib\security\cacerts
  - For J9 JVMs (IBM J9 11) on Windows: C:\Program Files\Instana\instana-agent\jvm\lib\security\cacerts
  Or you can extract the Java truststore file from a container image as follows:
  - For HotSpot (Azul Zulu 11) based Instana agent, run the following command:
```
id=$(docker create icr.io/instana/agent:latest); 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.
  - 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 the host agent as in the using a custom Java truststore for your Instana host agent section. 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.
On Windows (use Command Prompt or PowerShell), the command is identical:
```
keytool -import -alias <provided_alias> -keystore <java_truststore> -storepass <password> -file <path_to_self-signed_certificate>
```
Note: The keytool command is included with the Java installation and works the same way on both Linux and Windows. On Windows, if keytool is not in your PATH, you can find it in the bin directory of your Java installation (for example, C:\Program Files\Instana\instana-agent\jvm\bin\keytool.exe).

Using a custom Java truststore file for the Instana agent

Edit online

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

Edit online

If your Instana agent is installed on Linux, use one of the following methods:

systemd
Environment variable

systemd

Edit online

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

Edit online

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

Note: If you want to start the Instana host agent directly, make sure that you add 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.

Windows host

Edit online

If your Instana agent is installed on Windows, configure the Java truststore by using environment variables or the Windows service configuration.

Using environment variables

Edit online

Set the JAVA_OPTS environment variable with the Java truststore parameters.

You can set this variable at the system level or user level:
- Open System Properties > Advanced > Environment Variables.
- Under System variables or User variables, click New.
- Set the variable name to JAVA_OPTS.
- Set the variable value to:
```
-Djavax.net.ssl.trustStore=<path_to_java_truststore> -Djavax.net.ssl.trustStoreType=jks
```
- Replace <path_to_java_truststore> with the full path to your custom Java truststore file (for example, C:\certs\cacerts ).
- You do not need to specify a password for reading the custom Java truststore.
Restart the Instana agent service for the changes to take effect.

Open Services (services.msc), find the Instana Agent service, and restart it.

Using Windows service configuration

Edit online

Open the Windows Registry Editor (regedit).

Navigate to the Instana agent service registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\instana-agent

Locate or create the Environment multi-string value.
Add the following line to the Environment value:
```
JAVA_OPTS=-Djavax.net.ssl.trustStore=<path_to_java_truststore> -Djavax.net.ssl.trustStoreType=jks
```
- Replace <path_to_java_truststore> with the full path to your custom Java truststore file.
- You do not need to specify a password for reading the custom Java truststore.
Restart the Instana agent service for the changes to take effect.

Important: Modifying the Windows Registry can affect system stability. Make sure to back up the registry before making changes.

When to use agent-level vs backend-level certificate configuration

Edit online

Understanding when to use agent-level versus backend-level certificate configuration helps you properly secure your Instana deployment:

Agent-level certificate configuration (this topic): Use the keytool command to import certificates into the agent's Java truststore when the Instana agent needs to connect to monitored technologies or services that use self-signed certificates. This configuration affects how the agent communicates with the systems it monitors.

Examples: Monitoring databases, application servers, or internal services that use self-signed certificates.
Backend-level certificate configuration: Use the stanctl backend apply --core-custom-ca-crt command to import certificates into the Instana backend when the backend needs to connect to external services that use custom certificate authorities. This configuration affects how the backend communicates with external systems.

Examples: Connecting to external LDAP servers, SMTP servers, or other external services. For more information, see Using a custom CA certificate.

Troubleshooting

Edit online

SSLException in Instana agent logs

Edit online

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.