Background

If you run Simplifier Instances using self signed certificates, or certificates issued by a Certification Authority which is not part of the usual trusted ones, you will get an error when you try to transport a package from one environment to another.

For connectors, there is a certificate management implemented in the user interface. You can use this to upload certificates of REST, SOAP or OData V2 services you want to connect to using Simplifier connectors.

These certificates cannot be used for the transport system. To make the transport system work with certificates of a custom CA, you need to manually import the necessary certificates in a so-called trust store. This needs to be done on the server CLI, as described in this article.

Overview

The following steps need to be done:

1. Set up custom trust store on permanent storage
2. Import neccessary certificates (root and intermediates)
3. Change JVM arguments to use custom trust store
4. Restart Simplifier

1. Set up custom trust store on permanent storage

Basis for the custom trust store is the default one, which already includes a wide set of trusted authorities.

Log in to the terminal of the host Simplifier is running on. Figure out the container name of the Simplifier instance you want to change. It must be a container based on the image simplifierag/simplifier.

Open an interactive terminal within the container:

docker exec -it simplifier /bin/bash

All of the following commands need to be issued within this container, not on the host.

Let’s make a new folder for the trust store:

mkdir /opt/simplifier/data/conf/certs

Copy the default trust store to the newly created folder.

For Simplifier 8:

cp /usr/lib/jvm/temurin-8-jdk-amd64/jre/lib/security/cacerts /opt/simplifier/data/conf/certs

For Simplifier 8 EHP 1 or newer:

cp /usr/lib/jvm/graalvm-community-openjdk-20.0.1+9.1/lib/security/cacerts /opt/simplifier/data/conf/certs

2. Import neccessary certificates

First, the certificates need to be copied to the host. Please use scp, FileZilla or any tool of your choice to connect to the host Simplifier is running on and copy the certificates there, e.g. to the folder /home/myUser (please adapt this path to your environment). Please keep in mind that you need the root certificate as well as all intermediates.

Now all certificates should be placed in /home/myUser.

With the next step, the certificates are copied to the folder created in step 1. The folder /opt/simplifer/data/conf/certs was created from within the container. The corresponding path on the host depends on your setup. If you followed our recommendations during setup, this corresponding path is /var/lib/simplifier/data/conf/certs (for Simplifier 8) or /var/lib/simplifier/simplifier/conf/certs (for Simplifier 8 EHP 2).

Simplifier 8:

cp /home/myUser/*.crt /var/lib/simplifier/data/conf/certs/

Simplifier 8 EHP 1 or newer

cp /home/myUser/*.crt /var/lib/simplifier/simplifier/conf/certs/

Now the import is prepared. The import needs to be done from within the container. Connect to the container (container name depends on your setup):

docker exec -it simplifier /bin/bash

For importing certificates, a tool called keytool is used. Go to the folder you placed the certificates and the copied trust store to:

cd /opt/simplifier/data/conf/certs

Check if all expected files are there:

ls -l

This command should show cacerts and one or more certificate files. Now the actual import can be done:

keytool -import -trustcacerts -alias [name in keystore] -file [file name] -keystore ./cacerts

Repeat this command for every certificate you want to import.

3. Change JVM arguments to use custom trust store

To inform Simplifier to use the new trust store, it has to be added to the arguments which are passed to the JVM. There are several options to achive this. Which one to use depends on your setup.

docker compose default setup

Most settings can be changed in .env. In this case it is not possible but the docker compose YAML file has to be adapted. Open simplifer-standalone.yml (Simplifier 8) or docker-compose.yml (Simplifier 8 EHP 2) in a text editor.

Look for the line:

- JVM_PARAMETER=-Xmx${SIMPLIFIER_JVM_HEAP_GB}g -Xms2g -XX:MaxMetaspaceSize=512m -XX:+UseG1GC -XX:+UseStringDeduplication -XX:-UseGCOverheadLimit -Xss256m

By default, this is line 50.

Add the following to the end of the line:

-Djavax.net.ssl.trustStore=/opt/simplifier/data/conf/certs/cacerts

Environment Variable

You can define a environment variable called

JVM_PARAMETER

If you already have this variable defined, just add

-Djavax.net.ssl.trustStore=/opt/simplifier/data/conf/certs/cacerts

at the end.

If you define this variable for the first time, you have to initialize it with the default value and the path to the trust store:

-Xmx8g -Xms2g -XX:MaxMetaspaceSize=512m -XX:+UseG1GC -XX:+UseStringDeduplication -XX:-UseGCOverheadLimit -Xss256m -Djavax.net.ssl.trustStore=/opt/simplifier/data/conf/certs/cacerts

jvm.arg file

If you already use a jvm.arg file, edit it and add at the end of the current content:

 -Djavax.net.ssl.trustStore=/opt/simplifier/data/conf/certs/cacerts

If you are not already using a jvm.arg file, please implement this using one of the two other possibilities.

4. Restart Simplifier

To bring these changes in action, Simplifier has to be stopped and restarted.

For docker compose:

docker compose -f [...] down
docker compose -f [...] up -d

If you used jvm.arg file, a restart is enough:

docker restart simplifier

Please adapt the container name to your setup.

For any other deployment / orchestration, restart or recreate the Simplifier container. Make sure you choose a method that ensures changes made in step 3 are considered.