Stambia DI Runtime can be accessed from several software and tools such as Designer, Analytics, Command line scripts or Process Actions, which offer the possibility to perform operations, consult executed sessions, execute or schedule new deliveries, ...
Communication with Runtime can be performed through different protocols such as RMI or HTTP.
This article summarizes how to use and configure them on the clients.
About configuration
This article will explain how to communicate with a Runtime from the various clients, and how to configure them.
It does not explain how to configure the various services of a Runtime.
As an example, this article explains how to communicate with a secured Runtime, but now how to configure this Runtime to be secured.
There are dedicated articles for this that you can find on the website.
You can refer to those security articles to learn how to configure the Runtime:
- Securing RMI, HTTP, and web services endpoints with TLS in Stambia DI Runtime 2020 (S20.0.0) or higher
- Securing RMI, HTTP, and web services endpoints with TLS in Stambia DI Runtime S17.x.x
- Securing the Runtime with user / password and roles
Supported protocols and syntaxes
You can find below the supported protocols and syntaxes which can be used to communicate with a Runtime.
| Protocol | Hostname Syntax | Default port | Example | Description | Supported from |
| auto | <hostname> | 42000 | localhost |
When no protocol is specified in the hostname, the client will try to connect with RMI / RMIS automatically. This supports connecting both from RMI and RMIS.
We advise to prefer specifying the protocol explicitly to have more control on your connections. |
RMI
RMIS
|
| RMI | rmi://<hostname> | 42000 | rmi://localhost | Connect and communicate with a Runtime through plain RMI |
|
| RMIS | rmis://<hostname> | 42000 | rmis://localhost | Connect and communicate with a Runtime through RMIS (TLS secured RMI) |
|
| HTTP | http://<hostname> | 42200 | http://localhost | Connect and communicate with a Runtime through plain HTTP |
|
| HTTPS | https://<hostname> | 42200 | https://localhost | Connect and communicate with a Runtime through HTTPS (TLS secured HTTP) |
|
When communicating with TLS secured Runtime, through RMIS or HTTPS, you may need to configure the clients with the certificate to be used for communicating.
Refer to the clients usage and configuration below for further information.
Important Note about RMIS:
Stambia DI Runtime 2020 (S20.0.0) or higher forces the specification of your own certificate when you want to use RMIS, for security and customization purposes.
- When trying to connect through RMIS to such Runtime, you will therefore need to configure your clients to know the certificate.
Stambia DI Runtime S17.x.x was including an internal Stambia certificate for RMIS which was working out of the box without any configuration.
- This certificate is still included internally in the following clients which therefore do not need any additional configuration when you want to connect through RMIS to Runtime S17.x.x:
- Stambia DI Designer S19.x.x, Stambia DI Runtime S17.x.x, Stambia DI Production Analytics versions prior to 2.3.3.
- This certificate has been removed starting from the following clients versions, in which you therefore have to manually specify the internal certificate which can be downloaded here when you want to connect from them on a TLS secured Runtime S17.x.x
- Stambia DI Designer 2020 or higher, Stambia DI Runtime 2020 or higher, Stambia DI Production Analytics 2.3.3 or higher / Stambia DI Production Analytics 3.1.1 or higher
Client usage and configuration
You can find below how to connect and configure the various clients.
There will be examples and help about how to configure the clients when additional configuration is required.
Additional configuration may be required when connecting to TLS secured Runtimes (through RMIS / HTTPS).
About certificates
Introduction
When trying to access to a Runtime through RMIS / HTTPS, there will be certificates involved for securing exchanges.
When securing the Runtime itself, or securing the Proxy used to access the Runtime, administrators are using certificates, which will be used to validate and secure exchanges.
All clients which will connect to the Runtime will have to know the public certificate to be able to communicate with it.
If you are using certificates provided from an official authority, this will most of the time work without having to configure the certificate on the clients.
If you are using self-signed certificates, you will have to configure the clients to know this certificate.
You'll therefore need to ask first your administrator for this public certificate before configuring your clients.
Keystore
In Java programs certificates are stored in files called 'keystores'.
When you need to configure a public certificate, you have to create a keystore and add inside this certificate.
Clients will then be configured to use this keystore file, as explained in the next sections of this article.
You can refer to the following article to learn how to create a keystore and import certificates in.
Clients configuration
When needed, there are two mains solutions to configure clients to use the certificate and therefore be able to communicate with secured Runtime.
Importing the given certificate directly into your JVM, so that every application running with this JVM will benefit of it.
Or configuring directly the clients such as the Designer to import the certificate inside.
Both solutions are good and you can use one or another depending on your preference.
First one is global and avoid configuring each client with the certificate, as they will all benefit of it if they are using the same JVM.
Second solution is good if you want to avoid changing your JVM settings and simply configure the clients themselves.
As a reminder, this configuration is required most of the time only when you want to connect to Runtime using a self-signed certificate.
When using certificates provided from an official authority, this configuration is most of the time not necessary, as Java certification checks and validation should be able to validate the certificate automatically.
Stambia DI Designer
When you want to connect from Stambia DI Designer to a Runtime, you will define the Runtime to connect to.
You can do it from a Runtime Metadata, or from the Runtime configuration file which is on a default installation in global project (conf.egc).
In both cases, you will have the different connection properties to define.
Example to connect to a Runtime with automatic protocol detection (RMI / RMIS)
Example to connect to a Runtime with protocol specification:
Importing certificate in Designer
When you want to communicate with TLS secured Runtimes through RMIS / HTTPS, the Designer need to know your certificate.
If the Runtime you are connecting to is using certificates provided from an official authority, this will most of the time work without having to configure the certificate on the Designer.
If you are using self-signed certificates, you will have to configure the Designer to know this certificate, as described below.
To configure the Designer, you'll first have to create a keystore and import your certificate inside
The idea is then to configure the Designer to use the keystore containing the given certificate.
After having created your keystore, you can configure it in Designer.
Lead to Designer's installation folder, and open "stambia.ini" or "stambia32.ini" file depending on the launcher you are using.
Then add the following options at the end of the file:
-Djavax.net.ssl.trustStore=<keystore file path>
-Djavax.net.ssl.trustStoreType=<keystore_type>
-Djavax.net.ssl.trustStorePassword=<keystore and key password>
Example:
-Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks
-Djavax.net.ssl.trustStoreType=jks
-Djavax.net.ssl.trustStorePassword=keystorepass
Note that if you defined a password for protecting the certificate key when adding it in the keystore, this must be the same as the password of the keystore itself.
Note that you can refer to this article to learn how to create a keystore and import your certificates in.
Note about RMIS: As indicated at the beginning of this article, you may not have to configure manually the certificate for RMIS depending on the version you are using, please refer to the "Note About RMIS" section which is at the beginning of this article.
Ignoring certification checks
An alternative option for debugging or convenient purposes is to disable certificate checks for HTTPS Runtime communications.
This will allow to avoid having certificates errors if you want to connect to an HTTPS secured Runtime and you have not created and configured your keystore.
Communication will still be secured, this is only for the checks performed by Java to find if the certificate used for communicating is known.
For ignoring this check, use the following options instead of the keystore options:
-Dcom.stambia.runtime.https.ignoreCertCheck=true
-Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL
Stambia DI Production Analytics
When you want to connect from Stambia DI Production Analytics to a Runtime, you will define the Runtime to connect to.
You can do it from Administration, in which you will have the different connection properties to define.
Example to connect to a Runtime with automatic protocol detection (RMI / RMIS)
Example to connect to a Runtime with protocol specification:
Importing certificate in Analytics
When you want to communicate with TLS secured Runtimes through RMIS / HTTPS, Analytics needs to know your certificate.
If the Runtime you are connecting to is using certificates provided from an official authority, this will most of the time work without having to configure the certificate on Analytics.
If you are using self-signed certificates, you will have to configure Analytics to know this certificate, as described below.
To configure Analytics, you'll have first to create a keystore and import your certificate inside.
The idea is then to configure Analytics to use the keystore containing the given certificate.
After having created your keystore, you can configure it in Analytics application server.
Refer to your application server documentation, such as Apache Tomcat, to know how to add additional Java options.
The idea is to add the following Java options to the application:
-Djavax.net.ssl.trustStore=<keystore file path>
-Djavax.net.ssl.trustStoreType=<keystore_type>
-Djavax.net.ssl.trustStorePassword=<keystore and key password>
Example:
-Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks
-Djavax.net.ssl.trustStoreType=jks
-Djavax.net.ssl.trustStorePassword=keystorepass
Note that if you defined a password for protecting the certificate key when adding it in the keystore, this must be the same as the password of the keystore itself.
Note that you can refer to this article to learn how to create a keystore and import your certificates in.
Note about RMIS: As indicated at the beginning of this article, you may not have to configure manually the certificate for RMIS depending on the version you are using, please refer to the "Note About RMIS" section which is at the beginning of this article.
Ignoring certification checks
An alternative option for debugging or convenient purposes is to disable certificate checks for HTTPS Runtime communications.
This will allow to avoid having certificates errors if you want to connect to an HTTPS secured Runtime and you have not created and configured your keystore.
Communication will still be secured, this is only for the checks performed by Java to find if the certificate used for communicating is known.
For ignoring this check, use the following options instead of the keystore options:
-Dcom.stambia.runtime.https.ignoreCertCheck=true
-Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL
Command Line Scripts
When you want to connect from command line scripts to a Runtime, you will define the Runtime to connect to.
You can do it from the connect command in which you will have the different connection properties to define.
As a reminder, command line scripts are starcommand.bat / startcommand.sh scripts which allow to connect and send commands to Runtimes.
Example of startcommand.bat / startcommand.sh script with automatic protocol detection (RMI / RMIS)
> connect to localhost port 42000
Connecting to localhost on port 42000
Connected
Example of startcommand.bat / startcommand.sh script with protocol specification:
> connect to https://localhost port 42200
Connecting to https://localhost on port 42200
Connected
Importing certificate in command line scripts
When you want to communicate with TLS secured Runtimes through RMIS / HTTPS, command line scripts need to know your certificate.
If the Runtime you are connecting to is using certificates provided from an official authority, this will most of the time work without having to configure the certificate on command line scripts.
If you are using self-signed certificates, you will have to configure command line scripts to know this certificate, as described below.
To configure command line scripts, you'll have to create a keystore and import your certificate inside.
The idea is then to configure the command line scripts to use the keystore containing the given certificate.
After having created your keystore, you can configure it in the scripts.
Lead to Runtime's installation folder, and open "initvariables.bat" or "initvariables.sh" depending on your system.
Then add the following options in the "STAMBIA_STARTCOMMAND_VM_PROPERTIES" variable:
-Djavax.net.ssl.trustStore=<keystore file path> -Djavax.net.ssl.trustStoreType=<keystore_type>-Djavax.net.ssl.trustStorePassword=<keystore and key password>
Example for initvariables.bat:
set STAMBIA_STARTCOMMAND_VM_PROPERTIES=-Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass
Example for initvariable.sh:
STAMBIA_STARTCOMMAND_VM_PROPERTIES= -Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass
Note that if already have some properties defined in this variable, simply add them at the end of the line, such as:
set STAMBIA_STARTCOMMAND_VM_PROPERTIES=-Dstambia.client.configuration="%STAMBIA_PROPERTIES_LOCATION%\client.xml" -Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass
Note that if you defined a password for protecting the certificate key when adding it in the keystore, this must be the same as the password of the keystore itself.
Note that you can refer to this article to learn how to create a keystore and import your certificates in.
Note about RMIS: As indicated at the beginning of this article, you may not have to configure manually the certificate for RMIS depending on the version you are using, please refer to the "Note About RMIS" section which is at the beginning of this article.
Ignoring certification checks
An alternative option for debugging or convenient purposes is to disable certificate checks for HTTPS Runtime communications.
This will allow to avoid having certificates errors if you want to connect to an HTTPS secured Runtime and you have not created and configured your keystore.
Communication will still be secured, this is only for the checks performed by Java to find if the certificate used for communicating is known.
For ignoring this check, add instead the following options:
-Dcom.stambia.runtime.https.ignoreCertCheck=true -Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL
Example:
set STAMBIA_STARTCOMMAND_VM_PROPERTIES=-Dstambia.client.configuration="%STAMBIA_PROPERTIES_LOCATION%\client.xml" -Dcom.stambia.runtime.https.ignoreCertCheck=true -Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL
Process Action
When you want to connect from Execute Delivery Process Action, you will define the Runtime to connect to.
You can do it from the Properties of the Process Action.
Example to connect to a Runtime with automatic protocol detection (RMI / RMIS)
Example to connect to a Runtime with protocol specification:
Importing certificate for Process Action
When you want to communicate with TLS secured Runtimes through RMIS / HTTPS, the Runtime executing the Process Action need to know the certificate to be used.
If the Runtime you are connecting to is using certificates provided from an official authority, this will most of the time work without having to configure the certificate on the Runtime executing the Process Action.
If you are using self-signed certificates, you will have to configure the Runtime executing the Process Action to know this certificate, as described below.
For this, you'll first have to create a keystore and import your certificate inside.
The idea is then to configure the Runtime which executes the Process Action to use the keystore containing the given certificate.
After having created your keystore, you can configure it in the scripts.
Lead to Runtime's installation folder, and open "initvariables.bat" or "initvariables.sh" depending on your system.
Then add the following options in the "STAMBIA_STARTENGINE_VM_PROPERTIES" variable:
-Djavax.net.ssl.trustStore=<keystore file path> -Djavax.net.ssl.trustStoreType=<keystore_type>-Djavax.net.ssl.trustStorePassword=<keystore and key password>
Example for initvariables.bat:
set STAMBIA_STARTENGINE_VM_PROPERTIES=-Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass
Example for initvariable.sh:
STAMBIA_STARTENGINE_VM_PROPERTIES= -Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass
Note that if already have some properties defined in this variable, simply add them at the end of the line, such as:
set STAMBIA_STARTENGINE_VM_PROPERTIES=-Dstambia.client.configuration="%STAMBIA_PROPERTIES_LOCATION%\client.xml" -Djavax.net.ssl.trustStore=D:/certificates/mykeystore.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=keystorepass
Note that if you defined a password for protecting the certificate key when adding it in the keystore, this must be the same as the password of the keystore itself.
Note that you can refer to this article to learn how to create a keystore and import your certificates in.
Note about RMIS: As indicated at the beginning of this article, you may not have to configure manually the certificate for RMIS depending on the version you are using, please refer to the "Note About RMIS" section which is at the beginning of this article.
Ignoring certification checks
An alternative option for debugging or convenient purposes is to disable certificate checks for HTTPS Runtime communications.
This will allow to avoid having certificates errors if you want to connect to an HTTPS secured Runtime and you have not created and configured your keystore.
Communication will still be secured, this is only for the checks performed by Java to find if the certificate used for communicating is known.
For ignoring this check, add instead the following options:
-Dcom.stambia.runtime.https.ignoreCertCheck=true -Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL
Example:
set STAMBIA_STARTCOMMAND_VM_PROPERTIES=-Dstambia.client.configuration="%STAMBIA_PROPERTIES_LOCATION%\client.xml" -Dcom.stambia.runtime.https.ignoreCertCheck=true -Dcom.stambia.runtime.https.ignoreCertCheckProtocol=SSL